MSBuild Setup

The Sentry CLI has many useful features that can improve your Sentry experience. For .NET, you can use it to upload debug information files, such as .NET PDB symbol files. This allows Sentry to show a more complete stack trace, including file names and line numbers. You can also use it to upload source code, which enables Sentry to display source context when viewing stack traces.

While you can always run sentry-cli from the command line manually, we've made it easier by including it in the Sentry NuGet package, and providing properties to enable it from your build.

Authentication

For this feature to work, you must authenticate to Sentry on the machine that is performing your release builds.

Any of the authentication methods accepted by the Sentry CLI can be used. See Configuration and Authentication. However, we generally recommend the following:

• If building your releases on a developer workstation, install the Sentry CLI and then call sentry-cli login to use the automatic configuration option. This will help you create an auth token and save it to the ~/.sentryclirc file on the workstation.

• If building from a CI/CD server, use the secrets feature of your CI/CD platform to set the SENTRY_AUTH_TOKEN environment variable.

  For example, if using GitHub Actions, first set an encrypted secret and then pass the secret via the SENTRY_AUTH_TOKEN environment variable to the step performing your build action.

  YAML

  Copied

  steps:
    - name: Build
      run: dotnet build -c Release
      env:
        SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  

  You do not need to separately install Sentry CLI on your build server, as it is already provided by the Sentry NuGet package.

• If building inside a Docker container, use a BuildKit secret to pass the auth token securely. See Building with Docker below for a complete example.

Configuration

In addition to authentication, you must configure your Sentry organization and project slugs. You may also want to configure other optional properties.

The slugs can be found in various places from the Sentry UI, such as in the URL after selecting a project. For example, the organization slug is example-org and the project slug is example-project in the following URLs:

• https://example-org.sentry.io/projects/example-project/?project=1234567
• https://sentry.io/organizations/example-org/projects/example-project/?project=1234567

If you are self-hosting Sentry (rather than using sentry.io), then you will also need to provide the URL to your Sentry server.

Setting MSBuild Properties

Sentry's MSBuild properties can be set in any MSBuild project file, such as those that are created by Visual Studio or the dotnet CLI (YourProject.csproj, YourProject.vbproj, Directory.Build.props, etc.). We recommend using a dedicated property group, so that you can control when these features are used.

In the following example, Condition="'$(Configuration)' == 'Release'" ensures that these features are enabled only for release builds. This is the usual recommendation, because sending data to Sentry during debug builds can slow down your development workflow.

Alternatively, you could control this using any MSBuild property or environment variable you like. For example, if you only want these features enabled in a GitHub Actions CI workflow, you could use Condition="'$(GITHUB_ACTIONS)' == 'true'".

<!-- We recommend only using these features for release builds. -->
<PropertyGroup Condition="'$(Configuration)' == 'Release'">

  <!-- Configure Sentry org and project -->
  <SentryOrg>___ORG_SLUG___</SentryOrg>
  <SentryProject>___PROJECT_SLUG___</SentryProject>

  <!--
    Each of the below features are opt-in.
    Enable the features you wish to use.
  -->

  <!-- Automatically creates a release when building your application. -->
  <SentryCreateRelease>true</SentryCreateRelease>

  <!-- Automatically associates commits with the release. -->
  <SentrySetCommits>true</SentrySetCommits>

  <!-- Optionally provide explicit flags to the set-commits command -->
  <SentrySetCommitOptions>--local</SentrySetCommitOptions>

  <!-- Sends symbols to Sentry, enabling symbolication of stack traces. -->
  <SentryUploadSymbols>true</SentryUploadSymbols>

  <!-- Sends sources to Sentry, enabling display of source context. -->
  <SentryUploadSources>true</SentryUploadSources>

  <!-- If you are targeting Android, sends proguard mapping file to Sentry. -->
  <SentryUploadAndroidProGuardMapping
  >true</SentryUploadAndroidProGuardMapping>

</PropertyGroup>

<!-- We recommend only using these features for release builds. -->
<PropertyGroup Condition="'$(Configuration)' == 'Release'">

  <!-- Configure Sentry org and project -->
  <SentryOrg>___ORG_SLUG___</SentryOrg>
  <SentryProject>___PROJECT_SLUG___</SentryProject>

  <!--
    Each of the below features are opt-in.
    Enable the features you wish to use.
  -->

  <!-- Automatically creates a release when building your application. -->
  <SentryCreateRelease>true</SentryCreateRelease>

  <!-- Automatically associates commits with the release. -->
  <SentrySetCommits>true</SentrySetCommits>

  <!-- Optionally provide explicit flags to the set-commits command -->
  <SentrySetCommitOptions>--local</SentrySetCommitOptions>

  <!-- Sends symbols to Sentry, enabling symbolication of stack traces. -->
  <SentryUploadSymbols>true</SentryUploadSymbols>

  <!-- Sends sources to Sentry, enabling display of source context. -->
  <SentryUploadSources>true</SentryUploadSources>

  <!-- If you are targeting Android, sends proguard mapping file to Sentry. -->
  <SentryUploadAndroidProGuardMapping
  >true</SentryUploadAndroidProGuardMapping>

</PropertyGroup>

Alternatively, they could be passed as parameters when building your project. For example:

dotnet build YourProject.csproj -c Release -p:SentryOrg=___ORG_SLUG___ -p:SentryProject=___PROJECT_SLUG___ -p:SentryUploadSymbols=true -p:SentryUploadSources=true

dotnet build YourProject.csproj -c Release -p:SentryOrg=___ORG_SLUG___ -p:SentryProject=___PROJECT_SLUG___ -p:SentryUploadSymbols=true -p:SentryUploadSources=true

Required MSBuild Properties

The following MSBuild properties will pass required information to the Sentry CLI:

Optional MSBuild Properties

There are a few additional properties available to control the Sentry CLI:

Building with Docker

When building inside a Docker container, there are two things to handle: passing the auth token securely, and avoiding errors in multi-stage builds.

Passing the Auth Token

Use Docker BuildKit's --secret flag to pass the auth token at build time. Unlike ARG/ENV, BuildKit secrets are never written to any image layer and do not appear in docker history.

Pass the secret when building the image:

docker build --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN .

docker build --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN .

In your Dockerfile, add a syntax directive at the top, then mount the secret for the RUN instruction that performs the build:

# syntax=docker/dockerfile:1
...
RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
    dotnet build "MyWebApp.csproj" --no-restore -c Release

# syntax=docker/dockerfile:1
...
RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
    dotnet build "MyWebApp.csproj" --no-restore -c Release

The env= option (available since Dockerfile syntax v1.10) exposes the secret as the SENTRY_AUTH_TOKEN environment variable for the duration of that RUN instruction only — exactly what the Sentry CLI needs — without persisting it to a layer. The # syntax= directive ensures Docker uses a frontend that supports env=, regardless of the Docker Engine version.

Multi-Stage Dockerfiles

If your Dockerfile has separate stages for dotnet build and dotnet publish (a common pattern for ASP.NET Core apps), Sentry CLI only needs to run during the build stage, where the auth token is mounted.

By default, dotnet publish runs its own implicit build. That would invoke Sentry CLI again — and because the auth token is deliberately scoped to the build stage's RUN (so it never reaches the publish stage or the final image), the second run would fail. Pass --no-build --no-restore so dotnet publish reuses the build stage's output instead of recompiling, plus -p:UseSentryCLI=false as an extra safeguard:

RUN dotnet publish "MyWebApp.csproj" -c Release -o /app/publish --no-build --no-restore -p:UseAppHost=false -p:UseSentryCLI=false

RUN dotnet publish "MyWebApp.csproj" -c Release -o /app/publish --no-build --no-restore -p:UseAppHost=false -p:UseSentryCLI=false

Complete Example

The following is a complete multi-stage Dockerfile for an ASP.NET Core app. It assumes <SentryOrg>, <SentryProject>, <SentryUploadSymbols>, and <SentryUploadSources> are configured in your .csproj or Directory.Build.props.

# syntax=docker/dockerfile:1
# Build: docker build --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN .
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 8080

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MyWebApp.csproj", "./"]
RUN dotnet restore "MyWebApp.csproj"
COPY . .

# The secret is available only for this RUN instruction and is never written to a layer.
# Sentry CLI runs here and uploads debug symbols as part of the build.
RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
    dotnet build "MyWebApp.csproj" --no-restore -c Release

# Reuse the build output; --no-build avoids recompiling, which would re-run Sentry CLI without the auth token.
FROM build AS publish
RUN dotnet publish "MyWebApp.csproj" -c Release -o /app/publish --no-build --no-restore -p:UseAppHost=false -p:UseSentryCLI=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyWebApp.dll"]

# syntax=docker/dockerfile:1
# Build: docker build --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN .
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 8080

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MyWebApp.csproj", "./"]
RUN dotnet restore "MyWebApp.csproj"
COPY . .

# The secret is available only for this RUN instruction and is never written to a layer.
# Sentry CLI runs here and uploads debug symbols as part of the build.
RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
    dotnet build "MyWebApp.csproj" --no-restore -c Release

# Reuse the build output; --no-build avoids recompiling, which would re-run Sentry CLI without the auth token.
FROM build AS publish
RUN dotnet publish "MyWebApp.csproj" -c Release -o /app/publish --no-build --no-restore -p:UseAppHost=false -p:UseSentryCLI=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyWebApp.dll"]