PublishSymbols@2 - Index sources and publish symbols v2 task

Artikel
02/27/2024

Use this task to index your source code and publish your symbols to a file share or Azure Artifacts symbol server.

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

Symbol servers enable your debugger to automatically retrieve the correct symbol files without knowing product names, build numbers, or package names.

Inputs

SymbolsFolder - Path to symbols folder
string. Default value: $(Build.SourcesDirectory).

Specifies the path to the folder that is searched for with symbol files. The default is $(Build.SourcesDirectory). Otherwise, specify a rooted path, such as $(Build.BinariesDirectory)/MyProject.

Note

UNC paths aren't supported if you select the Azure Artifacts symbol server as the server type.

SearchPattern - Search pattern
string. Required. Default value: **/bin/**/*.pdb.

Specifies the pattern used to discover the PDB files to publish. See File matching patterns reference for more information.

IndexSources - Index sources
boolean. Default value: true.

Specifies whether to inject source server information into the PDB files. This option is only supported on Windows agents.

PublishSymbols - Publish symbols
boolean. Default value: true.

Specifies whether to publish the symbol files.

SymbolServerType - Symbol server type
string. Required when PublishSymbols = true. Allowed values: TeamServices (Symbol Server in this account/collection (requires Package Management)), FileShare (File share).

Specifies 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. See instructions to Publish symbols for debugging to use Symbol Server in Azure Artifacts.

SymbolsPath - Path to publish symbols
string. Optional. Use when PublishSymbols = true && SymbolServerType = FileShare.

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

DetailedLog - Verbose logging
boolean. Default value: true.

Specifies verbose logging.

TreatNotIndexedAsWarning - Warn if not indexed
boolean. Default value: false.

Specifies whether to warn if sources are not indexed for a PDB file. Otherwise, the messages are logged as normal output.

SymbolsMaximumWaitTime - Max wait time (min)
string.

Specifies the number of minutes to wait before failing this task.

SymbolsProduct - Product
string.

Specifies the product parameter to symstore.exe. The default is $(Build.DefinitionName).

SymbolsVersion - Version
string.

Specifies the version parameter to symstore.exe. The default is $(Build.BuildNumber).

SymbolsArtifactName - Artifact name
string. Default value: Symbols_$(BuildConfiguration).

Specifies the artifact name to use for the symbols artifact. This should only be used with the FileShare symbol server type. The default is Symbols_$(BuildConfiguration).

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Use this task to index your source code and publish your symbols to a file share or Azure Artifacts symbol server.

Symbol servers enables your debugger to automatically retrieve the correct symbol files without knowing product names, build numbers, or package names.

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.

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 E.g: 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. 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, but you can use Source Link instead.

How long are Symbols retained?

Symbols are associated with the build that published to Azure Pipelines they are associated with a build. When the build is deleted either manually or using retention policies, the symbols are also deleted. If you want to retain the symbols indefinitely, mark the build as Retain Indefinitely.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	1.95.0 or greater
Task category	Build

Dela via