Publish symbols for debugging

  • Article

TFS 2017

With Azure Pipelines, you can publish your symbols to Azure Artifacts symbol server using the Index sources and publish symbols task. You can use the debugger to connect and automatically retrieve the correct symbol files without knowing product names, build numbers, or package names. Using Azure Pipelines, you can also publish your symbols to files shares and portable PDBs.

Note

The Index sources and publish symbols task is not supported in release pipelines.

Publish symbols to Azure Artifacts symbol server

To publish your symbols to Azure Artifacts symbols server, you can use the Index Sources & Publish Symbols task.

  1. From your pipeline definition, select + to add a new task.

  2. Search for the Index sources and publish symbols task. Select Add to add it to your pipeline.

    Screenshot showing how to add the index sources and publish symbols to the current pipeline

  3. Fill out the required fields as follows:

    Screenshot showing the index sources and publish symbols task to publish symbols to Azure Artifacts symbol server

  • Task version: 1.\*.

  • Display name: task display name.

  • Path to symbols folder: path to the folder hosting the symbol files.

  • Search pattern: the pattern used to find the pdb files in the folder that you specified in Path to symbols folder. Single-folder wildcard (*) and recursive wildcards (**) are supported. Example: *\bin**.pdb searches for all .pdb files in all the bin subdirectories.

  • Index sources: indicates whether to inject source server information into the PDB files.

  • Publish symbols: indicates whether to publish the symbol files.

    • Symbol server type: select Symbol Server in this organization/collection (requires Azure Artifacts) to publish your symbols to Azure Artifacts symbol server.

  • Verbose logging: check to include more information in your logs.

Publish symbols to a file share

Aside from Azure Artifacts symbol server, you can also publish your symbols to a file share using the Index Sources and Publish Symbols task.

  1. From your pipeline definition, select + to add a new task.

  2. Search for the Index sources and publish symbols task. Select Add to add it to your pipeline.

    Screenshot showing how to add the index sources and publish symbols to the current pipeline

  3. Fill out the required fields as follows:

    Screenshot showing the index sources and publish symbols task to publish symbols to a file share

  • Task version: 1.\*.

  • Display name: task display name.

  • Path to symbols folder: path to the folder hosting the symbol files.

  • Search pattern: the pattern used to find the pdb files in the folder that you specified in Path to symbols folder.

  • Index sources: indicates whether to inject source server information into the PDB files.

  • Publish symbols: indicates whether to publish the symbol files.

    • Symbol server type: select File share to publish your symbols to a file share.
    • Path to publish symbols: the file share that will host your symbols.

  • Verbose logging: check to include more information in your logs.

Publish portable PDBs to Azure Artifacts symbol server

Portable PDBs are symbol files that can be created and used on all platforms unlike the traditional PDBs which are used on Windows only. If you're using portable PDBs, you still need to use the Index Sources and Publish Symbols task to publish your symbols. For portable PDBs, the build does the indexing, however you should use SourceLink to index the symbols as part of your pipeline.

Source link is a set of tools that allow developers to debug their source code by mapping from the .NET assemblies back to the source code. Check out the dotnet/sourcelink GitHub repository to learn about the different packages included.

  • For projects hosted on GitHub, add the Microsoft.SourceLink.GitHub package reference to your project file.

    <ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="All"/>
</ItemGroup>

  • For projects hosted on Azure Repos, add the Microsoft.SourceLink.AzureRepos.Git package reference to your project file.

    <ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.AzureRepos.Git" Version="1.0.0" PrivateAssets="All"/>
</ItemGroup>

  • For projects hosted on Azure DevOps Server, add the Microsoft.SourceLink.AzureDevOpsServer.Git package reference to your project file.

    <ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.AzureDevOpsServer.Git" Version="1.0.0" PrivateAssets="All"/>
</ItemGroup>

Set up the build task

The next step is to modify the build task in your pipeline to invoke Source Link during the build process.

  1. From your pipeline definition, select the Build solution task. You can search for and add the Visual Studio build task to your pipeline if you don't have it already.

  2. Add the following snippet to the MSBuild arguments.

    /p:SourceLinkCreate=true

  3. Select Save & queue when you are done.

    MSBuild arguments in the build solution task

Set up the publish task

The Index Sources & Publish Symbols task is used to index your source code and publish your symbols to Azure Artifacts symbols server. Because we are using the Visual Studio build task to index our source, we will disable indexing in the publish task.

  1. From your pipeline definition, select + to add a new task.

  2. Search for the Index sources and publish symbols task. Select Add to add it to your pipeline.

    Screenshot showing how to add the index sources and publish symbols to the current pipeline

  3. Fill out the required fields as follows:

    Screenshot showing how to configure the publish task to publish symbols to Azure Artifacts symbol server

  • Task version: 1.\*.

  • Index sources: Uncheck to disable indexing. Indexing is done during build. See the previous step for more details.

  • Publish symbols: indicates whether to publish the symbol files.

    • Symbol server type: select Symbol Server in this organization/collection (requires Azure Artifacts) to publish your symbols to Azure Artifacts symbol server.

Set up Visual Studio

Before starting to consume our symbols from Azure Artifacts symbol server, let's make sure that Visual Studio is set up properly:

  1. In Visual Studio, select Tools then Options.

  2. Select Symbols from the Debugging menu.

  3. Select the + sign to add a new symbol server location.

    Screenshot showing how to add a new symbol server location

  4. A new dialog box will open, select your account from the dropdown menu, and then select the organization that you wish to connect to. Select Connect when you are done.

  5. Select General from the same Debugging section. Scroll down and check Enable Source Link support to enable support for portable PDBs.

    Enable source link support

Note

Checking the Enable source server support option enables you to use Source Server when there is no source code on the local machine or the symbol file does not match the source code. If you want to enable third-party source code debugging, uncheck the Enable Just My Code checkbox.

Important

To delete symbols that were published using the Index Sources & Publish Symbols task, you must first delete the build that generated those symbols. This can be accomplished by using retention policies or by manually deleting the run.

FAQs

Q: How long symbols are retained for?

A: A symbol file has the same retention period as the build that generated it. When you delete a build either manually or using retention policies, the symbols that were generated by that build will be deleted as well.

Q: Can I use source indexing on a portable PDB generated from a .NET Core assembly?

A: This is not possible at the moment. Source indexing is not currently supported for portable PDBs. The recommended approach is to configure your build to do the indexing.