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.

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

  • Test Variables for Null Values

  • 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

  • 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

  • Get a list of shelvesets

  • TfGet

  • TfResolve

  • TfShelve

  • TfUndo

  • TfUnshelve

  • TfWorkfold

• 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

• ApproveRequestForCheckIn

• AssociateChangesetsAndWorkItems

• CheckInGatedChanges

• ConvertWorkspaceItem

• ConvertWorkspaceItems

• CopyDirectory

• CreateDirectory

• CreateWorkspace

• DeleteDirectory

• DeleteWorkspace

• DownloadFile

• DownloadFiles

• EvaluateCheckInPolicies

• ExpandEnvironmentVariables

• FindMatchingFiles

• GenerateRunSettings

• GetApprovedRequests

• GetBuildAgent

• GetBuildDetail

• GetBuildDirectory

• GetBuildEnvironment

• GetCommonLocalPath

• GetCommonServerPath

• GetImpactedTests

• GetPendingChanges

• GetRejectedRequests

• GetReshelvedShelveset

• GetShelvedChanges

• GetTeamProjectCollection

• GetWorkspace

• IndexSources

• InvokeForReason

• InvokeProcess

• IsNotNull<T>

• IsNull<T>

• LabelSources

• LabelWorkspace

• MSBuild

• MSTest

• OpenWorkItem

• ParseWorkspaceSpec

• PublishSymbols

• QueryShelvesets

• RejectRequestFromCheckIn

• RetryRequest

• RetryRequests

• RevertWorkspace

• RunOnce

• RunTests

• SetBuildProperties

• SharedResourceScope

• SyncWorkspace

• SynchronizeRequests

• TfGet

• TfQueryConflicts

• TfResolve

• TfShelve

• TfUndo

• TfUnshelve

• TfWorkfold

• TfsBuild

• UpdateBuildNumber

• WriteBuildError

• WriteBuildInformation<T>

• WriteBuildMessage

• WriteBuildTestError

• WriteBuildWarning

• WriteCustomSummaryInformation

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

Test variables for null values

IsNotNull&lt;T&gt;

Use the IsNotNull<T> activity to test whether a Visual Basic expression, for example a variable you are using, that you supply in the Value (Object) property is not Null. The result of the test is returned in the ResultBoolean property.

IsNull&lt;T&gt;

Use the IsNull<T> activity to test whether a Visual Basic expression, for example a variable you are using, that you supply in the Value (Object) property is Null. The result of the test is returned in the ResultBoolean property.

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 Build Definition.

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.

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

Manipulate path data

GetCommonLocalPath activity

Use the GetCommonLocalPath activity to get the path to the lowest-level common parent folder of one or more local folders. For example, if you specify LocalItems (IEnumerable<String>) like this:

{“c:\Code\Fabrikam-3\TestScrum\Main\FabrikamFiber.CallCenter”, “c:\Code\Fabrikam-3\TestScrum\Main\lib”}

Then Result (String) will return:

c:\Code\Fabrikam-3\TestScrum\Main

GetCommonServerPath activity

Use the GetCommonServerPath activity to get the path to the lowest-level common parent folder of one or more local folders. For example, if you specify ServerItems (IEnumerable<String>) like this:

{“$/TestScrum/Main/FabrikamFiber.CallCenter”, “$/TestScrum/Main/lib”}

Then Result (String) will return:

$/TestScrum/Main

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.

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.

• 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 DirectoryGetFiles(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

WriteCustomSummaryInformation

Use the WriteCustomSummaryInformation activity to write a message into the build summary, which is displayed to users in the build results window.

WriteCustomSummaryInformation Argument Properties

• Message (String): You must specify the message that you want to display in the build summary.

  You can include hyperlinks in the message using one of following syntaxes:

  [link text](url)
  [link text] (url)
  

  For example:

  For the latest operation status, see [Fabrikam Fiber Ops] (http://intranet.fabrikam.com/ops/status).
  

• SectionDisplayName (String): You must specify the name of the section in which you want the message to be shown. If multiple instances of WriteCustomSummaryInformation with the same SectionKey value specify different SectionDisplayName values, the system uses the SectionDisplayName of the first instance in the build process template.

• SectionKey (String): You must specify an identifier for the name of the section in which you want the message to be shown. The value you specify must comply with the rules described in NameProperty.

  For example, if you implement two instances of WriteCustomSummaryInformation with a SectionKey value of “MySection”, when your build is processed, both messages appear in the same section in the build summary.

• SectionPriority (Int32): You can specify the priority of the section, which in turn determines the relative position of the section in the build summary. The lower the value, the higher in the summary the section will appear. If multiple instances of WriteCustomSummaryInformation with the same SectionKey value specify different SectionPriority values, the system uses the SectionPriority value of the first instance in the build process template.

Back to top

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

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 a build 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.

Errors are always logged, regardless of the verbosity setting. For more information, see Manage Build Information and Control Verbosity.

WriteBuildTestError activity

Use the WriteBuildTestError activity to write a test 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.

Errors are always logged, regardless of the verbosity setting. For more information, see Manage Build Information and Control Verbosity.

WriteBuildInformation&lt;T&gt; 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)

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:

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

2. 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 to ensure that the enclosed segment of your build process 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:

1. Sequence (Sequence) >

2. Run On Agent (AgentScope) >

3. Try Compile, Test, and Associate Changesets and Work Items (TryCatch [Try]) >

4. Sequence (Sequence) >

5. Get Impacted Tests, Index Sources and Publish Symbols (Parallel) >

6. If SourceAndSymbolServerSettings.IndexSources Or SourceAndSymbolServerSettings.HasSymbolStorePath (If [Then]) >

7. Index Sources and Publish Symbols for Triggered Builds (InvokeForReason) >

8. If SourceAndSymbolServerSettings.HasSymbolStorePath (If [Then]) >

9. Try Publish Symbols (TryCatch [Try]) >

10. Synchronize Access to Symbol Store (SharedResourceScope) >

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

• 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

You can run tests using either the RunTests activity or the MSTest activity.

Run tests using the RunTests activity

Use the RunTests activity to use the Agile Test Runner to run tests. If your build compiles and tests binaries with incompatible platforms, you must run this activity separately against the assemblies in each platform.

For more information, such as the advantages and disadvantages of this test runner, see Run Tests in Your Build Process.

Core RunTests Properties

• TestSources (IEnumerable<String>): You must specify a list of the assembly files that contain the tests you want to run.

• ExecutionPlatform (ExecutionPlatformType) You can specify the platform of binaries that you want to test. For more information, see Agile Test Runner.

• ExecutionTimeout (Int32): You can specify the maximum amount of time that the build process waits for the test run to be completed. Specify a value of 0 if you want to give the RunTests activity unlimited time to run the tests.

• KeepAlive (Boolean): You can set this property to True if you want the Agile Test Runner process to continue running on the build agent after the RunTests activity is completed.

• RunSettings (String): Not documented.

• TestCaseFilter (String): You can use this property to run a subset of your test cases. For more information, see Specify criteria for the tests run by Visual Studio Test Runner.

• UpdateFrequency (Int32): Not documented.

• UpdateFrequencyTimeout (Int32): Not documented.

RunTests Publish Properties

You can use the following properties to publish the test results to the team project collection:

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

• Platform (String): You can specify the platform of the build against which you ran the tests whose results you want to publish.

• RunName (String): You can specify the name of the test run. Customers of your build process will see this name in the build results window summary. If you do not provide a name, then the system will automatically generate one.

Delegates

• OnTestCompleted: Not documented.

• OnTestRunCompleted: Not documented.

Back to top

Run tests using the MSTest activity

Use this activity to run tests by using MSTest.exe. For more information, such as the advantages and disadvantages of this test runner, see Run Tests in Your Build Process.

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 team project collection:

• 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 Finding theTests that are Affected by Code Changes.

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:

1. If you specify the BaselineBuildDropLocation property, the build that generated those binaries is identified as the previous build.

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

1. In the InvokeProcess activity, double-click Double-click to view.

2. Drag a WriteBuildMessage activity from the Toolbox so that the activity appears under Handle Standard Output, and set the WriteBuildMessageMessage property to stdOutput.

3. Drag a WriteBuildError activity from the Toolbox so that it appears under Handle Standard Output, and set the WriteBuildMessageMessage 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.

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

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 or Code Analysis 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.

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

Get a list of shelvesets (QueryShelvesets activity)

Use the QueryShelvesets activity to get a list of shelvesets that meet your criteria. You can then use the TfUnshelve activity to retrieve the contents of any of the shelvesets.

QueryShelvesets Result (IList<T><Shelveset>)

QueryShelvesets Argument Properties

• Name (String): You must specify the Name.

• Owner (String): You must specify the Owner.

• VersionControlServer (VersionControlServer): You must specify a VersionControlServer.

TfGet activity

This activity wraps the Get Command.

TfResolve activity

This activity wraps the Resolve Command.

TfShelve activity

This activity wraps the Shelve Command.

TfUndo activity

This activity wraps the Undo Command.

TfUnshelve activity

This activity wraps the Unshelve Command.

TfWorkfold activity

This activity wraps the Workfold Command.

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 Debug Your App by Recording Code Execution 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.

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 you to modify in a custom build process

Some activities are not intended for you to modify in a custom build process.

ApproveRequestForCheckIn

Ignore this activity.

Back to top

CreateWorkspace activity

Ignore this activity.

Back to top

DeleteWorkspace

Ignore this activity.

Back to top

GenerateRunSettings

Ignore this activity.

Back to top

GetApprovedRequests

Ignore this activity.

Back to top

GetPendingChanges

Ignore this activity.

Back to top

GetRejectedRequests

Ignore this activity.

Back to top

GetReshelvedShelveset

Ignore this activity.

Back to top

GetShelvedChanges

Ignore this activity.

Back to top

GetWorkspace

Ignore this activity.

Back to top

ParseWorkspaceSpec

Ignore this activity.

Back to top

RejectRequestFromCheckIn

Ignore this activity.

Back to top

RetryRequest

Ignore this activity.

Back to top

RetryRequests

Ignore this activity.

Back to top

RevertWorkspace

Ignore this activity.

Back to top

RunOnce

Not documented in the current release.

SyncWorkspace

Ignore this activity.

Back to top

SynchronizeRequests

Ignore this activity.

Back to top

TfsBuild activity

Ignore this activity.

Back to top

TfQueryConflicts

Ignore this activity.

Back to top

See Also

Concepts

Navigate in a Complex Windows Workflow

Define a Build Process that is Based on the Default Template

Deploy and Configure a Build Controller

Deploy and Configure Build Agents

Other Resources

Visual Studio 2010 Workflow Designer

Windows Workflow Foundation

MSBuild Reference

View Build Results