Manage Build Information and Control Verbosity

You can get detailed information about a completed build:

• How did the build run? Was the build successful? When did it start? How long did the build take? How did this build perform relative to previous builds?

• What was built? Which solutions, changesets, and bug fixes went into this build?

• What went wrong? What warnings or errors occurred? Which tests failed?

You can systematically control the verbosity of the information that is stored about each completed build when you define your build process. As an alternative, you can control this verbosity for a single run of a build when you queue it manually.

In this topic

• How Build Information is Generated and Flows

  • Define the Build Process

  • Build Process is Queued and Run

  • Build Information is Produced, Filtered, and Stored

  • Retrieve Build Information

• Setting the Build Process Parameter for Logging Verbosity

• Best Practice: Set Verbosity as Low as Possible

  • Use Minimal Verbosity When Running a Build

  • Use Minimal Verbosity When Designing a Custom Build Process Template

• For More Information

How Build Information is Generated and Flows

Define the Build Process

You can systematically control information verbosity when you develop your build process. When you create or edit a build definition that is based on the Default Template or the Upgrade Template, display the Process tab. In the Basic node, you can select a value in the Logging Verbosity list to specify this build process parameter.

In cases where the built-in templates do not meet your needs, you can develop a custom build process template. When you create this kind of template, you should carefully write build information. For more information, see Use Minimal Verbosity When Designing a Custom Build Process Template.

Build Process is Queued and Run

You can manually override the Logging Verbosity setting when you queue a build definition that is based on the Default Template or the Upgrade Template. In the Queue Build dialog box, choose the Parameters tab, expand the Basic node, and then select a value in the Logging Verbosity list to specify this build process parameter. This value is applied to a single run of the build.

Build Information is Produced, Filtered, and Stored

The build system passes the value of the Verbosity build process parameter to Verbosity. This property is used to filter the build information that is logged and stored on your Team Foundation Server via Information from the following sources:

• Workflow activities: Several workflow activities generate a message when an operation succeeds or a warning or error when an operation fails. For example, the SyncWorkspace activity generates Low importance messages when it downloads source code and other files from the server to the build agent. This activity generates errors when it fails to download the files. As another example, the OpenWorkItem activity generates a warning when it fails to create a work item.

  You can use other workflow activities to directly write your own build information. For more information, see Design a Custom Build Process Template that Writes Information with the Minimal Necessary Verbosity.

• Compile code: The build process uses the MSBuild activity to leverage MSBuild to compile the binaries and perform other vital tasks. The Verbosity property of this activity controls the verbosity of the information that this process generates and publishes to the following locations:

  • Your Team Foundation Server stores compilation results, errors, and warnings.

  • A log in the drop folder stores the same information as your Team Foundation Server along with all other messages that MSBuild produces.

• Test code: The build process uses the RunTests or the MSTest activity to run tests. All messages that these activities log are classified with an importance value of High if the build controller is on-premises, or Low if you are using the Hosted Build Controller..

Retrieve Build Information

While the build is running and after it is completed, you can retrieve both summary and detailed information from the build results window. You can copy this information from the window onto the Clipboard. You can also link directly to the drop folder to retrieve logs, binaries, and other data.

The Logging Verbosity Build Process Parameter

In a build process that is based on the Default Template or the Upgrade Template, you can use the Logging Verbosity build process parameter to manage the verbosity of the information that is logged and stored.

The following table lists the Logging Verbosity values and their corresponding effects:

Best Practice: Set Verbosity as Low as Possible

Although build information is important, a build process that logs too much information can cause problems. These problems might include consuming too much storage on your Team Foundation Server, decreasing Visual Studio performance, and overloading your team members with more information than they can handle.

Use Minimal Verbosity When Running a Build

When you are running a build, you should generally follow the best practice of using the lowest verbosity setting that still provides the information that you need to accomplish your goal.

Use Minimal Verbosity When Designing a Custom Build Process Template

Users of your build process rely on verbosity filtering to reduce information overload. You can help make this filtering more effective by taking the following measures:

• Make sure that you select the most appropriate activity to write a message: WriteBuildMessage, WriteBuildWarning, WriteBuildError, or WriteBuildTestError.

• When you use the WriteBuildMessage activity to log information, apply an intentional and consistent approach to setting the Importance property. When you use a higher importance value for your message, be aware that you are potentially increasing the amount of data that is stored and presented to your team members.

For More Information

Diagnose Build Problems describes how to get diagnostic logs.

Team Foundation Build Activities describes the build process workflow activities that this topic mentions.

Define a Build Process that is Based on the Default Template and Use Legacy Build Processes provide guidance about how to create and maintain build definitions that are based on the Default Template and the Upgrade Template

View Build Results provides guidance about how to use the build results window.

IBuildDetail, BuildMessageImportance, and BuildVerbosity describe some key elements of the Team Foundation Build API that provide build information functionality.

MSBuild Command-Line Reference describes MSBuild.

Specify Build Triggers and Reasons and Queue a Build describe how to automatically and manually queue a build.