Index Sources & Publish Symbols task

Artikkeli
12/08/2021

TFS 2017 | TFS 2015

Use this task to index your source code and optionally publish symbols to the Package Management symbol server or a file share.

Indexing source code enables you to use your .pdb symbol files to debug an app on a machine other than the one you used to build the app. For example, you can debug an app built by a build agent from a dev machine that does not have the source code.

Symbol servers enables your debugger to automatically retrieve the correct symbol files without knowing product names, build numbers or package names. To learn more about symbols, read the concept page; to publish symbols, use this task and see the walkthrough.

Demands

None

Arguments

Argument	Description
`SymbolsFolder` Path to symbols folder	(Optional) The path to the folder that is searched for symbol files. The default is $(Build.SourcesDirectory), Otherwise specify a rooted path. Note that UNC paths aren't supported if you select the Azure Artifacts symbol server as the server type. For example: $(Build.BinariesDirectory)/MyProject
`SearchPattern` Search pattern	(Required) File matching pattern(s) The pattern used to discover the pdb files to publish Default value: /bin//*.pdb
`IndexSources` Index sources	(Optional) Indicates whether to inject source server information into the PDB files Default value: true
`PublishSymbols` Publish symbols	(Optional) Indicates whether to publish the symbol files Default value: true
`SymbolServerType` Symbol server type	(Required) Choose where to publish symbols. Symbols published to the Azure Artifacts symbol server are accessible by any user with access to the organization/collection. Azure DevOps Server only supports the "File share" option. Follow these instructions to use Symbol Server in Azure Artifacts. TeamServices: Symbol Server in this organization/collection (requires Azure Artifacts) File share: Select this option to use the file share supplied in the next input.
`SymbolsPath` Path to publish symbols	(Optional) The file share that hosts your symbols. This value will be used in the call to symstore.exe add as the /s parameter. To prepare your SymStore symbol store: Set up a folder on a file-sharing server to store the symbols. For example, set up \fabrikam-share\symbols. Grant full control permission to the build agent service account. If you leave this argument blank, your symbols will be source indexed but not published. (You can also store your symbols with your drops. See Publish Build Artifacts).
`CompressSymbols` Compress symbols	(Required) Only available when File share is selected as the Symbol server type. Compresses your `pdbs` to save space. Default value: false

Advanced options

Argument	Description
`DetailedLog` Verbose logging	(Optional) Enables additional log details. Default value: true
`TreatNotIndexedAsWarning` Warn if not indexed	(Optional) Indicates whether to warn if sources are not indexed for a PDB file. Otherwise the messages are logged as normal output. A common cause of sources to not be indexed are when your solution depends on binaries that it doesn't build. Even if you don't select this option, the messages are written in log. Default value: false
`SymbolsMaximumWaitTime` Max wait time (min)	(Optional) The number of minutes to wait before failing this task. If you leave it blank, limit is 2 hours.
`SymbolsProduct` Product	(Optional) Specify the product parameter to symstore.exe. The default is $(Build.DefinitionName)
`SymbolsVersion` Version	(Optional) Specify the version parameter to symstore.exe. The default is $(Build.BuildNumber).
`SymbolsArtifactName` Artifact name	(Optional) Specify the artifact name to use for the Symbols artifact. The default is Symbols_$(BuildConfiguration). Default value: Symbols_$(BuildConfiguration)

For more information about the different types of tasks and their uses, see Task control options.

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.

Open source

This task is open source on GitHub. Feedback and contributions are welcome.

FAQ

How does indexing work?

By choosing to index the sources, an extra section will be injected into the PDB files. PDB files normally contain references to the local source file paths only. For example, C:\BuildAgent\_work\1\src\MyApp\Program.cs. The extra section injected into the PDB file contains mapping instructions for debuggers. The mapping information indicates how to retrieve the server item corresponding to each local path.

The Visual Studio debugger will use the mapping information to retrieve the source file from the server. An actual command to retrieve the source file is included in the mapping information. You may be prompted by Visual Studio whether to run the command. For example

tf.exe git view /collection:http://SERVER:8080/tfs/DefaultCollection /teamproject:"93fc2e4d-0f0f-4e40-9825-01326191395d" /repository:"647ed0e6-43d2-4e3d-b8bf-2885476e9c44" /commitId:3a9910862e22f442cd56ff280b43dd544d1ee8c9 /path:"/MyApp/Program.cs" /output:"C:\Users\username\AppData\Local\SOURCE~1\TFS_COMMIT\3a991086\MyApp\Program.cs" /applyfilters

Can I use source indexing on a portable PDB created from a .NET Core assembly?

No, Source Link is the equivalent to source indexing for portable PDBs.

Where can I learn more about symbol stores and debugging?

Do I need an agent?

You need at least one agent to run your build or release.

I'm having problems. How can I troubleshoot them?

See Troubleshoot Build and Release.

I can't select a default agent pool and I can't queue my build or release. How do I fix this?

See Agent pools.

My NuGet push task is failing with the following error: "Error: unable to get local issuer certificate". How can I fix this?

This can be fixed by adding a trusted root certificate. You can either add the NODE_EXTRA_CA_CERTS=file environment variable to your build agent, or you can add the NODE.EXTRA.CA.CERTS=file task variable in your pipeline. See Node.js documentation for more details about this variable. See Set variables in a pipeline for instructions on setting a variable in your pipeline.

How long are Symbols retained?

When symbols are published to Azure Pipelines they are associated with a build. When the build is deleted either manually or due to retention policy then the symbols are also deleted. If you want to retain the symbols indefinitely then you should mark the build as Retain Indefinitely.

Jaa