MSBuild Setup

Configure MSBuild properties in your .NET project to automatically use the Sentry CLI.

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.

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.

    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.

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.

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'".

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

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

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

  <!-- 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:

Copied
dotnet build YourProject.csproj -c Release -p:SentryOrg=example-org -p:SentryProject=example-project -p:SentryUploadSymbols=true -p:SentryUploadSources=true

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

SentryOrg

The organization slug for your Sentry account.

SentryProject

The project slug for the specific Sentry project you are using.

SentryUrl

The URL to your Sentry server. Required only if self-hosting Sentry. (Do not use with sentry.io.)

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

SentryUploadSymbols

Controls uploading symbols to Sentry during the build. Defaults to false (disabled).

Set this property to true to opt-in to sending symbols to Sentry as debug information files, which are used to perform symbolication of stack traces. This will allow you to view file names and line numbers within a stack trace, instead of just a function name.

SentryUploadSources

Controls whether source code files are uploaded to Sentry during the build. Defaults to false (disabled).

Set this property to true to opt-in to sending source code to Sentry. This enables the display of source context when viewing stack traces.

If you are already embedding source code in your symbol files using EmbedAllSources, you do not need to upload them to Sentry separately. In other words, use either SentryUploadSources or EmbedAllSources, not both.

UseSentryCLI

Controls whether the Sentry CLI is enabled in your build. Defaults to true if any of the individual features are enabled. Set to false to disable the Sentry CLI completely, ignoring the settings of each feature.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").