Manage Build Information and Control Verbosity

You can get the following kinds of 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 DefaultTemplate.xaml or UpgradeTemplate.xaml, 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 Manage Build Verbosity in Your 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 DefaultTemplate.xaml or UpgradeTemplate.xaml. In the Queue Build dialog box, display 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 in the data warehouse 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.

• MSBuild: 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:

  • The data warehouse stores compilation results, errors, and warnings.

  • A log in the drop folder stores the same information as the data warehouse along with all other messages that MSBuild produces.

• MSTest: The build process uses the MSTest activity to leverage MSTest.exe to run tests. All messages that this process generates are classified with an importance value of High and published to the data warehouse and to a log in the drop folder.

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 DefaultTemplate.xaml or UpgradeTemplate.xaml, 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:

Value	Errors	Warnings	High-Importance Build Messages	Normal-Importance Messages	Low-Importance Messages	Workflow Activity Properties (inputs and outputs)
Minimal	Y	N	N	N	N	N
Normal	Y	Y	Y	N	N	N
Detailed	Y	Y	Y	Y	N	N
Diagnostic (generally should be used only for debugging a build process)	Y	Y	Y	Y	Y	Y

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 space in the data warehouse, 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.

For example, you might run a build to generate binaries that include your most recent code changes. In most cases, a Normal verbosity will likely suffice. However, you may need to use Detailed or Diagnostic verbosity if you are troubleshooting a build process bug or an unusual code compilation failure.

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, or WriteBuildError.

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

Note

The impact of such decisions can be especially dramatic if you use these activities inside a loop structure such as DoWhile, ForEach<T>, or While.

For More Information

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

Define a Build Using the Default Template and Define a Build Using the Upgrade Template provide guidance about how to create a build definition.

View the Build Results Window 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.

Change History

Date	History	Reason
April 2011	Added topic.	Information enhancement.