MSBuild Integration (Windows / MSVC)

The MSVC agent instruments builds by injecting a shared MSBuild targets file, sealights-vcx.targets, into your solution tree through a patched Directory.Build.targets. This adds the /Gh compiler flag to every in-scope project without modifying individual .vcxproj files. After a clean rebuild, the scan command reads PDB files, generates a .slmap sidecar file beside each binary, and uploads the build map to SeaLights.

Follow these steps in order. The final step is optional.

1

Clean and inject SeaLights build targets

Run msbuild /t:Clean before injection. This makes every object file recompile with /Gh during the next build.

The injection creates sealights-vcx.targets and a patched Directory.Build.targets. It does not modify any .vcxproj file.

PowerShell

# Clean first — required so all objects recompile with /Gh
msbuild MySolution.sln /t:Clean /p:Configuration=Release

# Inject SeaLights MSBuild targets
SL.Agent.Cpp.exe integrateMsBuild `
  --dir . `
  --tokenFile ./sltoken.txt `
  --gtest

Azure DevOps

- task: PowerShell@2
  displayName: Clean and inject SeaLights build targets
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      msbuild MySolution.sln /t:Clean /p:Configuration=Release
      SL.Agent.Cpp.exe integrateMsBuild --dir . --token $env:SL_TOKEN --gtest

--gtest enables the GTest event listener shim. It auto-injects into application projects that resolve <gtest/gtest.h>. The --dir flag also accepts --projectsRoot and --solutionRoot.

2

Rebuild the solution

PowerShell

msbuild MySolution.sln /p:Configuration=Release

Azure DevOps

- task: PowerShell@2
  displayName: Rebuild the solution
  inputs:
    targetType: inline
    script: msbuild MySolution.sln /p:Configuration=Release

MSBuild picks up sealights-vcx.targets through Directory.Build.targets. Every in-scope project compiles with /Gh and links the SeaLights tracer libraries.

3

Create a build session

Create a build session to register the build with SeaLights. The command writes a session ID file for all subsequent commands.

PowerShell

SL.Agent.Cpp.exe config `
  --tokenFile          ./sltoken.txt `
  --appName            MyCppApp `
  --buildName          $(git rev-parse --short HEAD) `
  --branchName         main `
  --buildSessionIdFile buildSessionId.txt

Azure DevOps

- task: PowerShell@2
  displayName: Create a SeaLights build session
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      SL.Agent.Cpp.exe config `
        --token              $env:SL_TOKEN `
        --appName            MyCppApp `
        --buildName          $(Build.BuildNumber) `
        --branchName         main `
        --buildSessionIdFile buildSessionId.txt

Use a unique --buildName for each build, such as a CI run number or Git SHA. Make --appName match the name registered in SeaLights exactly.

4

Scan the build and upload the coverage map

Run the scan to read PDB files, write a .slmap sidecar file beside each binary, and upload the build map to SeaLights.

PowerShell

SL.Agent.Cpp.exe scan `
  --tokenFile          ./sltoken.txt `
  --buildSessionIdFile buildSessionId.txt `
  --binDir             .\bin\Release `
  --srcRootDir         .

Azure DevOps

- task: PowerShell@2
  displayName: Scan the build and upload the coverage map
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      SL.Agent.Cpp.exe scan `
        --token              $env:SL_TOKEN `
        --buildSessionIdFile buildSessionId.txt `
        --binDir             .\bin\Release `
        --srcRootDir         .

Confirm --binDir contains the compiled .exe or .dll files and their .pdb files. Copy each .slmap file with its binary to the test environment. The files contain the build-specific RVA-to-function-name map. Generate them again after every rebuild.

5

Undo injection (optional)

Restore Directory.Build.targets from its backup. Skip this step when your pipeline uses a fresh agent for every run.

PowerShell

SL.Agent.Cpp.exe integrateMsBuild --dir . --undo

Azure DevOps

- task: PowerShell@2
  displayName: Undo MSBuild injection (optional)
  inputs:
    targetType: inline
    script: SL.Agent.Cpp.exe integrateMsBuild --dir . --undo

The instrumented binaries from step 2 remain after you undo the injection.

Next step: Application Under Test