Team Foundation Build Activities
The Team Foundation Build activities are the fundamental components of the build process in your Team Foundation Build system. You can use these activities to create a custom build process to meet team requirements such as following custom logic or performing specialized tasks.
In most cases, the best way to create a custom build process template is to base it on the Default Template (DefaultTemplate.xaml). This way, you can take advantage of generally useful functionality that has already been created while customizing specific parts to meet your requirements. Another advantage of this approach is that you can see specific and practical examples of how you can use the activities that this topic describes. For information about how to create your build process template, see Create and Work with a Custom Build Process Template.
Important
You should create a custom build process only if you must meet specialized requirements. You can use DefaultTemplate.xaml to quickly define a build process that meets many typical requirements. For more information, see Define a Build Using the Default Template.
In this topic
Required Permissions
Goal-oriented reference to the activities
Alphabetical reference to the activities
Required Permissions
To perform procedures that use Team Foundation Build activities, you must have the following permissions set to Allow:
Edit build definition
Check out and Check in for the relevant version control directories (such as the BuildProcessTemplates subdirectory of your team project)
Queue builds
For more information, see Team Foundation Server Permissions.
Goal-oriented reference to the activities
Perform Basic Tasks
Get the values of environment variables
Get paths to files in the workspace
Work with directories
Get the path to the build agent working directory
Download files that are not in a workspace
Find files
Write warnings, errors, messages, and other data in the build log
Write build metadata into the data warehouse
Control the Build Process
Run activities on the build agent
Use a named mutex structure to implement a thread safe process
Restrict sections of your build process based on the reason (trigger)
Compile, Test, and Perform Other Tasks
Use MSBuild to compile binaries, run code analysis, and perform other tasks
Use MSTest to run tests
Get a list of tests that the build affects
Start a process
Work with Version Control
Associate changesets and work items with the build
Check in gated changes
Evaluate check-in policies
Label files in version control
Work with Work Items
Associate changesets and work items with the build
Create a work item
Work with Symbol Data
Embed version control paths and versions into the symbol data in your .pdb files
Publish symbols to a SymStore symbol store
Get References to Useful Objects
Get a reference to an object for a team project collection
Get a reference to an object for a build agent
Get a reference to an object for a build detail
Get a reference to an object for a build environment
Alphabetical reference to the activities
AgentScope
AssociateChangesetsAndWorkItems
CheckInGatedChanges
ConvertWorkspaceItem
ConvertWorkspaceItems
CopyDirectory
CreateDirectory
CreateWorkspace
DeleteDirectory
DeleteWorkspace
DownloadFile
DownloadFiles
EvaluateCheckInPolicies
ExpandEnvironmentVariables
FindMatchingFiles
GetBuildAgent
GetBuildDetail
GetBuildDirectory
GetBuildEnvironment
GetImpactedTests
GetTeamProjectCollection
GetWorkspace
IndexSources
InvokeForReason
InvokeProcess
LabelSources
LabelWorkspace
MSBuild
MSTest
OpenWorkItem
PublishSymbols
RevertWorkspace
SetBuildProperties
SharedResourceScope
SyncWorkspace
TfsBuild
UpdateBuildNumber
WriteBuildError
WriteBuildInformation<T>
WriteBuildMessage
WriteBuildWarning
Perform Basic Tasks
You can use Team Foundation Build activities to perform the following tasks:
Get the values of environment variables
Get paths to files in the workspace
Work with directories
Get the path to the build agent working directory
Download files that are not in a workspace
Find files
Write warnings, errors, messages, and other data in the build log
Write metadata about the build
Get the Values of Environment Variables (ExpandEnvironmentVariables Activity)
Use the ExpandEnvironmentVariables activity to resolve one or more environment variables on a build server. The environment variables are read on the build agent if this activity is inside an AgentScope sequence; otherwise, they are read on the build controller.
ExpandEnvironmentVariables Result (String) Property
Returns the result of the operation. For example: The temp directory on machine BLDSERV3 is C:\windows\SERVIC~2\NETWOR~1\AppData\Local\Temp.
ExpandEnvironmentVariables Argument Properties
Input (String): You must specify the string that contains the environment variables that you want to resolve. You must format each environment variable by specifying an MSBuild property instead of by using the Windows percent symbol notation. For example: "The temporary directory on machine $(COMPUTERNAME) is $(TEMP)."
AdditionalVariables (IDictionary<TKey, TValue><String,String>): You can specify an IDictionary object that contains any additional variables (as keys) that you want to resolve to their corresponding values.
Back to top
Get Paths to Files in the Workspace
Each build has a version control workspace that is defined on the Workspace tab of the build definition. The workspace provides the build with access to the source code files and any other files that it needs from the version control system. Team Foundation Build provides two activities that you can use to work with files in the build workspace: ConvertWorkspaceItemand ConvertWorkspaceItems.
For more information about build workspaces, see Create a Basic Build Definition.
Tip
For detailed step-by-step guidance about how to use the ConvertWorkspaceItem activity in a typical scenario, see Control Where the Build System Places Your Binaries.
Get the Path to a File in a Workspace (ConvertWorkspaceItem Activity)
Use the ConvertWorkspaceItem activity to convert a server path to a local path on the build agent or to convert a local path on the build agent to a server path.
ConvertWorkspaceItem Result (String) Property
Returns the converted path.
ConvertWorkspaceItem Argument Properties
Input (String): You must supply the path value that you want to convert.
Workspace (Workspace): You must supply a reference to the Workspace that contains the file. In most cases, you should set this property to the variable that you initialize in the Result property of the CreateWorkspace activity. If you are creating a build process that is based on DefaultTemplate.xaml, you should probably use the Workspace variable.
Direction
Convert a server path to a local path: In the Direction property, select ServerToLocal, and then specify the path to the file on the server in the Input (String) property.
For example, your team might store common utilities in the following directory: $/OurTeam/BuildProcess/Util. You can create a custom build process that runs the ScanBinaries.exe utility after your binaries are compiled. If the $/OurTeam/BuildProcess/Util is mapped on the Workspace tab of your build definition, you can specify $/OurTeam/BuildProcess/Util/ScanBinaries.exe in the Input property to get the local path to the utility from the Result (String) property.
Convert a local path to a server path: In the Direction property, select ServerToLocal, and then specify the local path to the file on the build agent in the Input property.
Get the Paths to Files in a Workspace (ConvertWorkspaceItems Activity)
Use the ConvertWorkspaceItems activity to convert server paths to local paths on the build agent or to convert local paths on the build agent to server paths.
ConvertWorkspaceItems Result (IList<String>) Property
Returns the converted path values.
ConvertWorkspaceItems Argument Properties
Input (IEnumerable<T><String>): You must supply the path values that you want to convert.
Workspace (Workspace): You must supply a reference to Workspace that contains the files. In most cases, you should set this property to the variable that you initialize in the Result property of the CreateWorkspace activity.
Tip
If you are creating a build process that is based on DefaultTemplate.xaml, you should probably use the Workspace variable.
Direction: Select one of the following values:
Select ServerToLocal if you are specifying a collection of server path values in the Input property and you want the Result property to return a list of local path values.
Select LocalToServer if you are specifying a collection of local path values in the Input property and you want the Result property to return a list of server path values.
Work with directories
You can work with directories by using several activities in Team Foundation Build.
Tip
If you must work with directories that are part of the version control workspace of your build, you should instead use the workspace activities. For more information, see Get Paths to Files in the Workspace.
Create a Directory (CreateDirectory Activity)
Use the CreateDirectory activity to create a directory, the name of which you specify in the Directory (String) property.
Copy a Directory (CopyDirectory Activity)
Use the CopyDirectory activity to recursively copy all the content from one directory, which you specify in the Source (String) property, to another directory, which you specify in the Destination (String) property. The directory that you specify in the Destination property must already exist. Empty directories or subdirectories are not copied.
Delete a Directory (DeleteDirectory Activity)
Use the DeleteDirectory activity to delete a directory, the name of which you specify in the Directory (String) property. If the directory that you are deleting contains subdirectories, you must set the Recursive (Boolean) property to True; otherwise, the build will fail.
Get the Path to the Build Agent Working Directory (GetBuildDirectory Activity)
Use the GetBuildDirectory activity to get the literal path to the build agent’s working directory from the Result (String) property. You can use this activity only within an AgentScope activity.
Back to top
Download files that are not in a workspace
Use the DownloadFiles activity to download one or more files. Ignore the DownloadFile activity.
DownloadFiles Activity
Use the DownloadFiles activity to download one or more files from version control.
Tip
If the files that you want to download are in your build workspace, you should probably access them by using the ConvertWorkspaceItem activity.
DownloadFiles Argument Properties
LocalPath (String) You must specify a value:
If you are downloading a single file, specify the local path and the name that you want to give to the local copy of the file that you are downloading; for example, "c:\Docs\readme.txt".
If you are downloading multiple files, specify the local path to the directory into which you want to download the files; for example, "c:\Docs\".
ServerPath (String) You must specify a value:
If you are downloading a single file, specify the server path and the name of the file that you are downloading; for example, "$/Docs/readme.txt".
If you are downloading multiple files, specify the server path to the directory that contains the files that you want to download; for example, "$/Docs/".
Recursion (RecursionType):
OneLevel: Downloads the file or files in the directory that you specify in the ServerPath property.
Full: Downloads the files in the directory that you specify in the ServerPath property and any files in any subdirectories.
Version (String): You can specify a versionspec. To download the current version, leave this property set to Microsoft.TeamFoundation.VersionControl.Client.VersionSpec.Latest.DisplayString. For more information about versionspecs, see Command-Line Syntax (Version Control).
DeletionID (Int32): You must specify this property only if you are downloading a file that has been deleted from version control. You can get this value interactively by typing tf dir /deleted at a command prompt. (For more information, see Dir Command). However, Team Foundation Build does not provide a built-in activity to obtain a DeletionID. To use this property, you must obtain or create a custom activity that provides this functionality.
Back to top
DownloadFile Activity
Ignore the DownloadFile activity. The DownloadFiles activity is the easiest way to download one or more files.
Find Files (FindMatchingFiles Activity)
Use the FindMatchingFiles activity to find files. Specify the search criteria in the MatchPattern (String) property. In this property, you can specify an argument that includes the following elements:
Syntax that is supported by the searchPattern argument of the Directory GetFiles(String, String) method.
** to specify a recursive search. For example:
To search the sources directory for text files, you could specify something that resembles the following value for the MatchPattern property: String.Format("{0}\**\*.txt", SourcesDirectory).
To search the sources directory for text files in one or more subdirectories that are called txtfiles, you could specify something that resembles the following value for the MatchPattern property: String.Format("{0}\**\txtfiles\*.txt", SourcesDirectory).
You collect the outcome of the operation in the Result (IEnumerable<T><String>) property.
Write warnings, errors, messages, and other data in the build log
WriteBuildMessage Activity
Use the WriteBuildMessage activity to write an informational message in the build log. You must specify the message in the Message (String) property. You can also indicate the importance of the message by modifying the value of the Importance property (BuildMessageImportance).
Tip
-
Users of your build process may rely on verbosity filtering to reduce information overload both with regard to what they must view and the data that is stored in the warehouse. You can help make this filtering more effective by using a thoughtful and consistent approach to setting the Importance property of your build messages. For more information, see Manage Build Information and Control Verbosity.
-
If you are using default settings, your message will not be written into the build log. To resolve this issue, perform either of the following steps:
-
Set the WriteBuildMessage Importance property to Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.High.
-
On the Process tab of the build definition, set the Logging Verbosity process parameter to Detailed or Diagnostic.
-
WriteBuildWarning Activity
Use the WriteBuildWarning activity to write a warning message in the build log. Warnings appear with a yellow exclamation point in the build results window. You must specify the message in the Message (String) property.
Your build warnings are logged only when your team sets the verbosity to Minimal or higher. For more information, see Manage Build Information and Control Verbosity.
WriteBuildError Activity
Use the WriteBuildError activity to write an error message in the build log. Errors appear with a red exclamation point in the build results window. When an error is written into the build log, the build is classified as Partially Succeeded at best. You must specify the message in the Message (String) property.
Build errors are always logged, regardless of the verbosity setting. For more information, see Manage Build Information and Control Verbosity.
WriteBuildInformation<T> Activity
Use the WriteBuildInformation<T> activity to put an object into the build log. When a user views the log in the build results window, the object is rendered using reflection.
WriteBuildInformation<T> Argument Properties
Value (Object): You must specify the object that you want to put into the build log. For your object to be rendered in the build results window, the object must implement IBuildInformationNode and set the Type to one of the following InformationTypes values:
ActivityProperties
ActivityTracking
AgentScopeActivityTracking
BuildError
BuildMessage
BuildProject
BuildStep
BuildWarning
ExternalLink
OpenedWorkItem
ParentToBuildDetail: You can specify False to make the parent of this object be the parent of this activity, or you can specify True to make the parent the IBuildDetail object.
One effect of this property is how the information appears in the build result window. If you specify False, the information is indented and aligned with the output from other activities that are before and after the WriteBuildInformation<T> activity and that are at the same level. If you specify True, the information is not indented.
Back to top
Write Metadata into the Data Warehouse
You can write metadata about the build into the data warehouse:
Write the Build Number (UpdateBuildNumber Activity)
Write Key Data Points about the Build (SetBuildProperties Activity)
Tip
If these activities do not support the metadata that you want to write, you can use the GetBuildDetail activity to obtain a reference to the IBuildDetail object and then assign the data directly to the object by using that reference.
Write the Build Number (UpdateBuildNumber Activity)
Use the UpdateBuildNumber activity to set the build number (or name) of the build. This activity performs the following steps:
Constructs a build number that is based on an expression that determines the build number format. Your build process typically accepts this expression from a workflow argument, which is supplied by a parameter on the Process tab of a build definition.
Sets the build number (or name) of the build by writing the resulting value to the BuildNumber property.
UpdateBuildNumber Result (String) Property
Result: Returns the new BuildNumber value.
UpdateBuildNumber Properties
- BuildNumberFormat (String): You must supply an expression that specifies the format of build numbers. For information about the syntax of this expression, see Work with Build Numbers.
Back to top
Write Key Data Points about the Build (SetBuildProperties Activity)
Use SetBuildProperties to write key data points to the IBuildDetail object, which manages the storage of data about each build in the data warehouse. Much of this data appears to the user in the build results window.
SetBuildProperties Properties
PropertiesToSet: You must select the check boxes for the names of the properties that you want to set.
BuildNumber (String): You can set the BuildNumber of the build, which you might think of as the name of the build.
Tip
If you want to set this value based on user-specified settings on the Process tab of the build definition, you should probably use the UpdateBuildNumber activity instead of this property.
CompilationStatus (BuildPhaseStatus): You can set the compilation status (CompilationStatus). (The MSBuild activity also sets this value automatically.)
DropLocation (String): You can record the drop location in the DropLocation property.
Note
If you set this property, you do not actually create the drop location. Instead, you use this property to store, in the data warehouse, the location of the drop folder, which you typically create by using the CreateDirectory activity.
KeepForever (Boolean): You can set the KeepForever property to True if you want to bypass settings on the Retention Policy tab of the build definition and keep the completed build indefinitely.
LabelName (String): You can set the LabelName property to record the label that you used to mark this build on the source code files in version control. You set this property typically to match the value in the Name property of the LabelWorkspace activity.
Important
Team Foundation Build requires this data to associate changeset and work items with builds. If you do not provide this data, the AssociateChangesetsAndWorkItems activity will fail.
LogLocation (String): You can use the LogLocation property record the UNC file path to the folder where your build process puts the log file.
Note
You probably will not need to use this property in your custom build process. This property is primarily intended for use by the UpgradeTemplate.xaml file to support legacy build processes.
Quality (String): You can record the quality of the build in the Quality property.
SourceGetVersion (String): You can use the SourceGetVersion property to record the version specification for which the sources are retrieved for this build.
Status (BuildStatus): You can record the overall status of the build in the Status property. For example, you can use this property to indicate whether the build succeeded or failed.
TestStatus (BuildPhaseStatus): You use the TestStatus property to record the overall status of tests that were run on this build. For example, you can use this property to indicate whether the tests that you ran on this build succeeded or failed.
Back to top
Control the Build Process
You can use Team Foundation Build activities to control the build process in the following ways:
Run activities on the build agent
Use a named mutex structure to implement a thread safe process
Restrict sections of your build process based on the reason (trigger)
Run Activities on the Build Agent (AgentScope Activity)
Use the AgentScope activity to enclose the parts of your build process that you want to run on the build agent.
AgentScope Argument Properties
Agent Selection
MaxWaitTime (TimeSpan): You can specify the maximum amount of time that the build process waits for a build agent to become available. You can type a value in hh:mm:ss format. For example, the build will fail with a time-out error if you specify a value of 01:30:45 and the build has not been assigned to a build agent after 1 hour, 30 minutes, and 45 seconds. Specify a value of 00:00:00 if you want to give the build controller unlimited time to find a build agent to process this build definition.
Important
You can avoid backing up your build queue by specifying a reasonable non-zero value in the MaxWaitTime property
ReservationSpec (AgentReservationSpec): You can constrain the kind of build agent that will process the activities that this activity contains. For example, you can specify that only build agents that have a certain tag are used to process the activities inside the AgentScope activity.
Execution
MaxExecutionTime (TimeSpan): You can specify the maximum amount of time that is allowed for this AgentScope activity to be completed. You can type a value in hh:mm:ss format. For example, the build will fail with a time-out error if you specify a value of 04:30:15 and the build agent has not completed its work after 4 hours, 30 minutes, and 15 seconds. Specify a value of 00:00:00 if you want to give the build agent unlimited time to process the build.
Tip
You can avoid backing up your build queue by specifying a reasonable non-zero value in the MaxExecutionTime property
Scope
- DataToIgnore: Ignore this property.
Back to top
Use a named mutex structure to implement a Thread safe process (SharedResourceScope Activity)
Use the SharedResourceScope activity to implement a named mutex (mutual exclusion) structure. The segment of your build process that you put inside this activity will be “thread safe.”
A typical use of this activity is to enclose the parts of a build process that must access a shared resource that must be accessed by only one process at a time. For example, you might want your builds to write, in sequential order, to a single text file on a file share. To make sure that this kind of process functions correctly, you should implement it inside a SharedResourceScope activity.
You can find another example in DefaultTemplate.xaml, in which the call of the PublishSymbols activity is embedded in a SharedResourceScope activity:
Sequence (Sequence) >
Run On Agent (AgentScope) >
Try Compile, Test, and Associate Changesets and Work Items (TryCatch [Try]) >
Sequence (Sequence) >
Get Impacted Tests, Index Sources and Publish Symbols (Parallel) >
If SourceAndSymbolServerSettings.IndexSources Or SourceAndSymbolServerSettings.HasSymbolStorePath (If [Then]) >
Index Sources and Publish Symbols for Triggered Builds (InvokeForReason) >
If SourceAndSymbolServerSettings.HasSymbolStorePath (If [Then]) >
Try Publish Symbols (TryCatch [Try]) >
Synchronize Access to Symbol Store (SharedResourceScope) >
Publish Symbols (PublishSymbols)
For information about how to navigate this structure, see Navigate in a Complex Windows Workflow.
SharedResourceScope Argument Properties
ResourceName (String): You must specify a value. All instances of SharedResourceScope activities are run one at a time if they have the same ResourceName value in your team project collection (even if they are in different build definition templates).
MaxExecutionTime (TimeSpan): You can specify the maximum amount of time that is allowed for the SharedResourceScope activity to be completed. You can type a value in hh:mm:ss format. For example, the build will fail with a time-out error if you specify a value of 04:30:15 and the SharedResourceScope activity has not been completed after 4 hours, 30 minutes, and 15 seconds. Specify a value of 00:00:00 if you want to allow unlimited time to process the SharedResourceScope activity.
Tip
You can avoid backing up your build queue by specifying a reasonable non-zero value in the MaxExecutionTime property
MaxWaitTime (TimeSpan): You can specify the maximum amount of time that the build process waits in the queue to process the SharedResourceScope activity. You can type a value in hh:mm:ss format. For example, the build will fail with a time-out error if you specify a value of 01:30:45 and the SharedResourceScope activity not been processed after 1 hour, 30 minutes, and 45 seconds. Specify a value of 00:00:00 if you want to allow the build process unlimited time to wait in the queue.
Tip
You can avoid backing up your build queue by specifying a reasonable non-zero value in the MaxWaitTime property
Back to top
Restrict sections of your build process based on the reason (trigger) (InvokeForReason Activity)
Use the InvokeForReason activity to enclose a segment of your build process that you want to run only in builds that have been run for a particular reason. Build reasons are typically set by the trigger that the user selects on the Trigger tab of the build definition. You can specify, in the Reason property, one or more reason values that you want to allow. For more information, see Specify Build Triggers and Reasons.
Back to top
Compile, Test, and Perform Other Tasks
You can use Team Foundation Build activities to compile binaries, run tests, and perform other tasks:
Use MSBuild to compile binaries, run code analysis, and perform other tasks
Use MSTest to run tests
Get a list of tests that this build affects
Use MSBuild to compile binaries, run code analysis, and perform other tasks (MSBuild Activity)
Use the MSBuild activity to compile binaries, run code analysis, and take advantage of any other functionality that MSBuild provides.
MSBuild Result
No property of this activity returns a result. However, this activity sets CompilationStatus to Failed if any compilation errors are logged.
MSBuild Argument Properties
AdditionalVCOverrides (String): If you set GenerateVsPropsFile to True, the content of this property will be embedded into the generated .vsprops file.
CommandLineArguments (String): You can specify command-line arguments that you want to pass to MSBuild.
Configuration (String): You can specify the configuration to be built. For example: “debug” or “release”.
GenerateVSPropsFile (Boolean): If this property is set to True, MSBuild generates a standard .vsprops file to pass to C++ projects. This file will include the output directory for C++ projects and whatever you specify in the AdditionalVCOverrides property.
LogFile (String): You can specify the name of the log file that MSBuild should create.
LogFileDropLocation (String): You can specify the fully qualified UNC path to the directory where you want MSBuild to drop the log file.
MaxProcesses (Int32): You can specify the maximum number of processes that MSBuild creates.
OutDir (String) You can specify the directory where MSBuild drops the compiled binaries. For more information, see Control Where the Build System Places Your Binaries.
Platform (String): You can specify the platform to which MSBuild builds. For example: “Any CPU”, “x86”, or “x64”.
Project (String): You can specify the solution or the code project that MSBuild builds.
ResponseFile (String): You can specify the response file that MSBuild uses.
RunCodeAnalysis (CodeAnalysisOption): You can specify whether code analysis should always be run, should never be run, or should be run according to project settings.
Targets (IEnumerable<T><String>): You can specify the targets to build.
TargetsNotLogged (IEnumerable<T><String>): You can specify the targets for which ProjectStarted events should not be logged.
ToolPath (String): You can specify the path to the tool.
ToolPlatform (ToolPlatform): You can specify the platform for the tool. Specify Microsoft.TeamFoundation.Build.Workflow.Activities.ToolPlatform.Auto to detect the platform based on the current operating system.
Verbosity (BuildVerbosity): You can specify the verbosity of the log that MSBuild generates.
For more information about many MSBuild options that the MSBuild properties affect, see MSBuild Command Line Reference.
Back to top
Run Tests (MSTest Activity)
Use this activity to run tests by using MSTest.exe.
Core MSTest Properties
To start, decide how you want to run the tests, and then specify values for the appropriate properties.
To run tests in test containers (recommended approach), use the following properties:
TestContainers (IEnumerable<String>): You must specify the test containers of the tests that you want to run. This property is equivalent to the /testcontainer option of the MSTest.exe command. For more information, see MSTest.exe Command-Line Options (/testcontainer).
SearchPathRoot (String): You can specify the root of the path to the directory in which to search for test containers and their dependencies. If you do not specify a value, the MSTest activity will attempt to find the files in typical locations.
TestSettings (String): You can specify a test run configuration file to use. This property is equivalent to /testsettings option of the MSTest.exe command. For more information, see MSTest.exe Command-Line Options (/testsettings).
To run tests in test lists, use the following properties:
TestLists (IEnumerable<String>): You must specify the test lists that you want to run. This property is equivalent to the /testlist option of the MSTest.exe command. For more information, see MSTest.exe Command-Line Options (/testlist) and Defining Test Lists to Group Your Tests.
TestMetadata (String): You must specify the metadata file that contains the test lists that you want to run. This property is equivalent to the /testmetadata option of the MSTest.exe command. For more information, see MSTest.exe Command-Line Options (/testmetadata).
MSTest Filtering Properties
You can use the following properties to filter which tests are run:
Category (String): You can filter the tests based on their test categories. This property is equivalent to the /category option of the MSTest.exe command. For more information, see MSTest.exe Command-Line Options (/category) and Defining Test Categories to Group Your Tests.
MaxPriority (Int32): You can specify the maximum priority of tests that you want to run. Only tests whose priority is less than or equal to this value will run. You must specify a positive integer that is equal to or greater than the MinPriority property, or you must specify -1 if you do not want to specify a maximum priority.
Tip
If you have assigned priorities to your tests, the MinPriority and MaxPriority properties can be an important mechanism to help you define a balance between thorough testing and faster builds.
MinPriority (Int32): You can specify the minimum priority of tests that you want to run. Only tests whose priority is greater than or equal to this value will run. You must specify a positive integer that is equal to or less than the MaxPriority property, or you must specify -1 if you do not want to specify a minimum priority.
TestNames (IEnumerable<String>): You can specify the names of the tests that you want to run. This property is equivalent to the /test option of the MSTest.exe command. For more information, see MSTest.exe Command-Line Options (/test).
MSTest Publish Properties
You can use the following properties to publish the test results to the data warehouse:
Publish (Boolean): You must set this property to True if you want to publish test results.
Flavor (String): You can specify the flavor of the build against which you ran the tests whose results you want to publish. This property is equivalent to the /flavor option of the MSTest.exe command. For more information, see Command-Line Options for Publishing Test Results.
Platform (String): You can specify the platform of the build against which you ran the tests whose results you want to publish. This property is equivalent to the /platform option of the MSTest.exe command. For more information, see Command-Line Options for Publishing Test Results.
TestConfigId (Int32): You can specify the ID of an existing test management configuration to associate with the test run whose results you want to publish. This property is equivalent to the /testconfigid option of the MSTest.exe command. For more information, run MSTest /? at the Visual Studio command prompt.
TestConfigName (String): You can specify the name of an existing test management configuration to associate with the test run whose results you want to publish. This property is equivalent to the /testconfigname option of the MSTest.exe command. For more information, run MSTest /? at the Visual Studio command prompt.
MSTest Other Properties
CommandLineArguments (String): For information about the additional command-line options that you can specify, see MSTest.exe Command-Line Options.
PathToResultsFilesRoot (String): You can specify the root of the path to the directory on the build agent where MSTest.exe puts the results files (.trx files).
ToolPath (String): You can specify the path to the directory that contains the version of MSTest.exe that you want to run. If you do not specify a path, Team Foundation Build automatically determines the path based on the data in your tests lists or test containers.
Back to top
Get a list of tests that the build affects (GetImpactedTests Activity)
Use the GetImpactedTests activity to identify code changes in the current build and produce a list of tests that are affected by these changes. The activity writes the list of affected tests into the data warehouse to help members of your test team determine which tests they should run after this build is completed. For more information about how your team can use this data, see Recommending Tests to Run That are Affected by Code Changes.
Note
This activity has no effect in gated check-in builds or private builds.
Required Conditions
The GetImpactedTests activity can function only when the following conditions are true:
The MSTest activity has been run with a test settings file (specified in the TestSettings property) that collects test impact data. You can use the Traceandtestimpact.testsettings file, which is generated automatically, or you can use another test settings file in which the Test Impact check box is selected. For more information, see How to: Collect Data to Check Which Tests Should be Run After Code Changes.
The GetImpactedTests activity has successfully identified the previous build. For more information, see the next section.
How the GetImpactedTests Activity Identifies the Previous Build
The GetImpactedTests activity produces its results by comparing the current build to the previous build. The activity identifies the previous build by using the following process:
If you specify the BaselineBuildDropLocation property, the build that generated those binaries is identified as the previous build.
If you do not specify the BaselineBuildDropLocation property, the activity identifies the previous build by searching in the data warehouse for the most recent build that matches all of the following criteria:
The build has the same BuildDefinitionUri as the current build.
The Status of the build is either Succeeded or PartiallySucceeded.
The build has a DropLocation.
The build is not a gated check-in build or a private build.
GetImpactedTests Result Properties
CodeChanges (CodeChangeList): Returns a list of the changes that were made to each method in your code between this build and the previous build. The methods are analyzed at the Microsoft intermediate language (MSIL) level.
ImpactedTests (TestList): Returns a list of the tests that were affected by the code changes between the previous build and this build.
GetImpactedTests Argument Properties
Misc
- Build: You must supply the IBuildDetail object of the build. You can use the GetBuildDetail activity to get a reference to this object.
Miscellaneous
Assemblies (IEnumerable<String>): You must specify a list of assemblies that you want this activity to examine. Typically you built these assemblies in this build.
AssociatedChangesets (IList<T><Changeset>): You can specify the changesets that you want to associate with the test impact results. Typically you want to specify the changesets that you are building. You can get a reference to these changesets from the AssociateChangesetsAndWorkItems activity.
BinariesRoot (String): You must specify the path to the binaries on which your assemblies depend. You can get this value by using the GetBuildDirectory activity.
Workspace (Workspace): You must supply a reference to the workspace of your build. You can get this reference from the Result property of the CreateWorkspace activity.
BaselineBuildDropLocation (String): You can specify the path to the drop folder that contains the completed build that you want the GetImpactedTests activity to compare to the current build. If you do not specify this property, the activity attempts to query the build system for the previous build. For more information, see “How the GetImpactedTests Activity Identifies the Previous Build” earlier in this section.
Back to top
Start a process (InvokeProcess Activity)
Use the InvokeProcess activity to start a process (run a program) on the build server. This activity is essentially a wrapper over Start.
InvokeProcess Result (Int32) Property
Returns the ExitCode from the process.
InvokeProcess Argument Properties
FileName (String): You must specify the FileName of the process that you want to start (the program that you want to run). For example: %ProgramFiles%\ContosoBuildUtils\MarkBins.exe.
Arguments (String): You can specify command-line arguments (Arguments) that you want to pass to the process.
EnvironmentVariables (IDictionary<TKey, TValue><String,String>): You can specify additional environment variables (EnvironmentVariables) and their values.
OutputEncoding (Encoding): You can specify the encoding that is used to read the output (StandardOutputEncoding) and error (RedirectStandardError) streams. In many cases, the default value is the best value for this property:
System.Text.Encoding.GetEncoding(System.Globalization.CultureInfo.InstalledUICulture.TextInfo.OEMCodePage)WorkingDirectory (String): You can specify the working directory (WorkingDirectory) in which you want to run the process.
For example, you might want to run your MarkBins.exe utility against your compiled binaries. To narrow the scope in which the utility runs, you could call GetBuildDirectory and put the result in this property.
To display the standard output and error output from your process
In the InvokeProcess activity, double-click Double-click to view.
Drag a WriteBuildMessage activity from the Toolbox so that the activity appears under Handle Standard Output, and set the WriteBuildMessage Message property to stdOutput.
Drag a WriteBuildError activity from the Toolbox so that it appears under Handle Standard Output, and set the WriteBuildMessage Message property to errOutput.
Work with Version Control
You can use Team Foundation Build activities to perform the following version control tasks:
Associate changesets and work items with the build
Check in gated changes
Evaluate check-in policies
Label files in version control
Associate Changesets and Work Items with the Build (AssociateChangesetsAndWorkItems Activity)
Use the AssociateChangesetsAndWorkItems activity to link each completed build with all the changesets that went into the code and their associated work items.
Each build definition maintains its own record of which changesets and work items are waiting to be associated with the next completed build. For example, both Build A and Build B might build changeset 382. Build A is queued and successfully completed, but Build B is queued and fails. Changeset 382 is now linked with the successfully completed Build A and the failed Build B. Changeset 382 will not be linked with the next completed build of Build A, but it will be linked with the next successfully completed build of Build B.
AssociateChangesetsAndWorkItems Result (IList<T><Changeset>) Property
Returns the changesets that were associated with the build.
AssociateChangesetsAndWorkItems Argument Properties
CurrentLabel (String): Leave this property empty.
LastLabel (String): Leave this property empty.
UpdateWorkItems (Boolean): You can set the value of this property to True if you want to populate the Fixed In field of the associated work items with the build number. Otherwise, set the value to False.
Back to top
Check in gated changes (CheckInGatedChanges Activity)
Use the CheckInGatedChanges activity to check in to version control the code changes that triggered a gated check-in build. This activity also associates the build with the work items that are associated with the changesets.
Note
To function correctly, this activity must be placed after all implementations of the MSBuild and MSTest activities in your template.
CheckInGatedChanges Result (Changeset) Property
Returns the changeset that contains the changes that are being checked in.
CheckInGatedChanges Argument Properties
IgnoreErrors (Boolean): Set this property to False to allow files to be checked in only if the CompilationStatus and TestStatus properties both have a value of Succeeded. Set this property to True to allow files to be checked in regardless of the values of these properties.
Note
You can use the SetBuildProperties activity to set the CompilationStatus and the TestStatus properties.
UpdateWorkItems (String): Set this value to True if you want to populate the Fixed In field of the associated work items with the build number. Otherwise, set it to False.
Back to top
Evaluate check-in policies (EvaluateCheckInPolicies Activity)
Use the EvaluateCheckInPolicies activity to run check-in policies on the build server. This activity runs the check-in policies that are in force for folders that are specified on the Workspace tab of the build definition. The build fails if the check-in policies fail and the reason for the build is either CheckInShelveset (a gated check-in build) or ValidateShelveset (a private build).
Important
The check-in policies are evaluated on the build server, not on the developer’s client computer.
The most effective use of this activity is to enforce stronger quality gates by using it together with gated check-in builds. If you use the activity in this way, the user is blocked from bypassing the check-in policies. This activity is most useful for the following types of check-in policies:
The built-in Work Items check-in policy
Custom check-in policies that are designed to be evaluated on the build server
This activity is not useful for evaluating the built-in Builds, Code Analysis, or Testing Policy check-in policies because you can more efficiently run those processes in a build directly by using MSBuild and MSTest activities.
For more information, see the following resources:
For information about the built-in check-in policies, see Add Check-In Policies.
For information about custom check-in policies, see How to: Create Custom Check-in Policies in Visual Studio Team Foundation Server.
For information about gated check-in builds, see Define a Gated Check-In Build Process to Validate Changes
For information about private builds, see Queue a Build
EvaluateCheckInPolicies Argument Properties
- Workspace (Workspace): You must specify the workspace that you want to evaluate. In most cases, you should set this property to the variable that you initialize in the Result property of the CreateWorkspace activity. If you are creating a build process that is based on DefaultTemplate.xaml, you should probably use the Workspace variable.
Back to top
Label files in version control
You can label files by using Team Foundation Build activities:
Label the source code that you are building
Label files
Label the source code that you are building (LabelWorkspace Activity)
You should label source code files in version control so that your team can easily identify which version of each file is included in a given completed build. Use the LabelWorkspace activity to include this step in your build process.
LabelWorkspace Argument Properties
Name (String): You must specify the name of the label.
Child (LabelChildOption): You can specify how to handle items that already have labels that match the label that you specified. This property is equivalent to /child option of the tf label command.
Workspace (Workspace): You must supply a reference to the workspace of this build. In most cases, you should set this property to the variable that you initialize in the Result property of the CreateWorkspace activity. If you are creating a build process that is based on DefaultTemplate.xaml, you should probably use the Workspace variable.
Comment (String): You can specify a comment for the label. This property is equivalent to the /comment option of the tf label command.
Scope (String): You can specify a scope for the label. This property is equivalent to the @scope argument of the tf label command.
For more information about tf label parameters, see Label Command (Team Foundation Version Control).
Back to top
Label Files (LabelSources Activity)
Use the LabelSources activity to label files in version control.
Tip
You can frequently label the source code files that you are building more effectively if you use the LabelWorkspace activity.
LabelSources Argument Properties
Items (IEnumerable<String>): You must specify the items that you want to label. Each String is equivalent to an itemspec argument of the tf label command.
Name (String): You must specify the name of the label.
Scope (String): You must specify a scope for the label. This property is equivalent to the @scope argument of the tf label command.
Recursion (RecursionType): You can specify Microsoft.TeamFoundation.VersionControl.Client.RecursionType.Full if you want to label all files in a directory hierarchy. Otherwise, you can specify Microsoft.TeamFoundation.VersionControl.Client.RecursionType.OneLevel.
Version (String): You must supply the version of the items that you want to label. This property is equivalent to the /version option of the tf label command.
Child (LabelChildOption): You can specify how to handle items that already have labels that match the label that you have specified. This property is equivalent to /child option of the tf label command.
Comment (String): You can specify a comment for the label. This property is equivalent to the /comment option of the tf label command.
For more information about tf label parameters, see Label Command (Team Foundation Version Control).
Back to top
Work with Work Items
You can work with work items by using Team Foundation Build activities:
Associate changesets and work items with the build
Create a work item
Create a Work Item (OpenWorkItem Activity)
Use the OpenWorkItem activity to create a work item.
OpenWorkItem Result (WorkItem) Property
Returns the new work item.
OpenWorkItem Argument Properties
AssignedTo (String): You must specify the person to whom you want to assign the work item.
Title (String): You must specify the title of the work item.
Type (String): You must specify the type of the work item. Typical Type values include the following examples: “Bug”, “Issue”, and “Task”.
Comment (String): You can add a comment to the history of the work item.
CustomFields (IDictionary<TKey, TValue><String,String>): You can specify the value of one or more other fields of the work item.
Back to top
Work with Symbol Data
You can work with symbol data by using two Team Foundation Build activities: IndexSources and PublishSymbols.
A typical use of these activities is to enable IntelliTrace debugging. If you want to enable IntelliTrace debugging, you should first call the IndexSources activity to prepare your symbol data, and then you should call the PublishSymbols activity to publish the data to a SymStore symbol store.
For more information about IntelliTrace debugging, see Debugging with IntelliTrace.
Embed version control paths and versions into the symbol data in Your PDB Files (IndexSources Activity)
Use the IndexSources activity to embed version control paths and versions into the symbol data in your .pdb files.
IndexSources Argument Properties
FileList (IEnumerable<String>): You must specify the full path and name to each symbol file. You can use the FindMatchingFiles activity to supply this argument.
You can use ** to specify a recursive search. For example, you could call FindMatchingFiles with the following value in the MatchPattern property: String.Format("{0}\**\*.pdb", BinariesDirectory).
Back to top
Publish symbols to a SymStore symbol store (PublishSymbols Activity)
Use the PublishSymbols activity to publish the symbol data in your PDB files to a SymStore symbol store. This activity is essentially a wrapper over SymStore.exe. For information about SymStore symbol stores and how to prepare one, see Publish Symbol Data.
Important
Data can be corrupted if concurrent builds attempt to publish to the same symbols file share. To reduce this risk, you should call this activity only inside a SharedResourceScope activity.
PublishSymbols Result (String) Property
Returns the transaction ID that SymStore.exe returns.
PublishSymbols Argument Properties
FileList (IEnumerable<String>): You must specify the full path and name of each symbol file. You can use the FindMatchingFiles activity to supply this argument.
For example, you could call FindMatchingFiles with the following value in the MatchPattern property: String.Format("{0}\**\*.pdb", BinariesDirectory).
StorePath (String): You must specify the UNC file path to the root folder of the SymStore symbol store.
CommandLineArguments (String): For information about additional arguments that you can pass to SymStore.exe, see SymStore Command-Line Options.
Comments (String): You can specify transaction comments that are recorded in the transaction history file in the symbol store. This property is equivalent to the /c Comment parameter of the SymStore.exe command. For more information, see SymStore Command-Line Options.
ProductName (String): You can specify the product name, which is recorded in the transaction history file in the symbol store. For example, you could set this property to the build definition name (Name), which you could obtain from the BuildDefinition property by calling GetBuildDetail. This property is equivalent to the /t Product parameter of the SymStore.exe command. For more information, see SymStore Command-Line Options.
StoreCompressed (Boolean): You can set this value to True to store files in the symbol store as compressed files. Otherwise, files will be stored uncompressed. This property is equivalent to the /compress parameter of the SymStore.exe command. For more information, see SymStore Command-Line Options.
Version (String): For example, you could set this property to the build number (BuildNumber) which you can obtain by calling GetBuildDetail. This property is equivalent to the /v Version parameter of the SymStore.exe command. For more information, see SymStore Command-Line Options.
Back to top
Get references to useful objects
You can get references to useful objects by using Team Foundation Build activities.
Get a reference to the object for a team project collection (GetTeamProjectCollection Activity)
Use the GetTeamProjectCollection activity to get, from its Result property, a reference to a TfsTeamProjectCollection object. This starter object is important; for example, you can use it to connect to an application-tier server for Team Foundation.
Get a reference to the IBuildAgent object (GetBuildAgent Activity)
Use the GetBuildAgent activity to get, from its Result property, a reference to the IBuildAgent object. You can use this activity only within an AgentScope activity.
Get a reference to the IBuildDetail object (GetBuildDetail Activity)
Use the GetBuildDetail activity to obtain, from its Result property, a reference to the IBuildDetail object. You can use this object to get, and in some cases set, data about the current build.
Back to top
Get a reference to the BuildEnvironment object (GetBuildEnvironment Activity)
Use the GetBuildEnvironment activity to get, through its Result property, a reference to the BuildEnvironment object. You typically use this property to perform the following tasks:
Use the Environment object to determine whether the current segment of the workflow is running on the build controller or the build agent.
Use the CustomAssemblyPath object to get the path to the assemblies that contain the custom activities on the build agent.
Back to top
Activities that are not intended for reuse in a custom build process
Some activities are not intended for use in a custom build process.
TfsBuild Activity
Ignore this activity. It exists only for use in UpgradeTemplate.xaml. This activity is not intended for re-use in a custom build process.
CreateWorkspace Activity
You will probably never need to create or modify an instance of the CreateWorkspace activity. If you are designing a build process that requires one or more additional workspaces, you must create a custom activity to accomplish this goal.
Other Workspace Activities
Your build process template may use these activities in the same way that the DefaultTemplatate.xaml uses them. But unless you develop a custom activity to create a workspace, you will probably never need to create or modify an instance of a workspace in your custom build process template.
DeleteWorkspace
Back to top
GetWorkspace
Back to top
RevertWorkspace
Back to top
SyncWorkspace
Back to top
See Also
Tasks
Concepts
Define a Build Using the Default Template
Create and Work with a Build Controller
Create and Work with Build Agents