> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/c++-agent-for-windows-beta/msbuild-integration-windows-msvc.md).

# 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.

{% stepper %}
{% step %}

### 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.

{% tabs %}
{% tab title="PowerShell" %}

```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
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- 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
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`--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`.
{% endhint %}
{% endstep %}

{% step %}

### Rebuild the solution

{% tabs %}
{% tab title="PowerShell" %}

```powershell
msbuild MySolution.sln /p:Configuration=Release
```

{% endtab %}

{% tab title="Azure DevOps" %}

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

{% endtab %}
{% endtabs %}

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

{% step %}

### 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.

{% tabs %}
{% tab title="PowerShell" %}

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

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- 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
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

### 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.

{% tabs %}
{% tab title="PowerShell" %}

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

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- 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         .
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

### Undo injection (optional)

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

{% tabs %}
{% tab title="PowerShell" %}

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

{% endtab %}

{% tab title="Azure DevOps" %}

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

{% endtab %}
{% endtabs %}

The instrumented binaries from step 2 remain after you undo the injection.
{% endstep %}
{% endstepper %}

Next step: Application Under Test


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/c++-agent/c++-agent-for-windows-beta/msbuild-integration-windows-msvc.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.