Condividi tramite

Team Build 2008 Property Reference

  • Articolo

There are lots and lots of MSBuild properties available to Team Build 2008 build definitions, most of which are probably unknown to the majority of users.  As such, I've tried to compile a comprehensive list of these properties so that they can (hopefully) be more widely used.  I'll do the same thing at some point here for Team Build 2005.  If I've missed anything here or made any mistakes please let me know and I'll try and get them added/fixed.

Extensibility Properties

These are properties that are designed to be overridden by users, and they are already pretty well documented in MSDN here.  I've included the same properties here for comprehensiveness, along with some others not covered by the linked document:

  • AdditionalVCOverrides.  These values are written to the vsprops file generated by Team Build for each C++ project compiled and passed to the Override property of the VCBuild task.
  • BinariesSubdirectory.  The subdirectory under the build agent's working directory to which binaries are redirected during compilation.  Default value is "Binaries".
  • BuildConfigurationsInParallel.  Boolean property which, if true, enables building configurations (e.g. Debug|Any CPU and Release|Any CPU) in parallel, using MSBuild's multi-process capability.  Defaults to true.  Note that for this property to have an effect, the number of processes used by MSBuild, controlled by the MaxProcesses key in TfsBuildService.exe.config, must be set to a number greater than one.
  • BuildlogText.  The text that points to the build log in the work item created on a compilation failure.
  • BuildNumber.  The number of the build being built.  If you wish to override the default value, make sure to do so in the BuildNumberOverrideTarget so that the standard build process logic will update the various properties that depend on the build number (the drop location, label name, etc.) properly.
  • BuildSolutionsInParallel.  Boolean property which, if true, enables building solutions in parallel, using MSBuild's multi-process capability.  Defaults to true.  Note that for this property to have an effect, the number of processes used by MSBuild, controlled by the MaxProcesses key in TfsBuildService.exe.config, must be set to a number greater than one.
  • CleanCompilationOutputOnly.  Do not use this property directly - use IncrementaBuild and/or IncrementalGet instead.
  • CreateWorkspaceTaskComment.  The comment used when Team Build's workspace is created.  Default value is "Workspace created by Team Build".
  • CustomizableOutDir.  Set this property to true to keep Team Build from overriding the OutDir property for each solution/project in the SolutionToBuild item group. 
  • CustomizablePublishDir.  Set this property to true to keep Team Build from overriding the OutDir property for each solution/project in the SolutionToPublish item group.
  • CustomPropertiesForBuild.  Allows properties to be passed into all solutions/projects compiled during the course of the build.
  • CustomPropertiesForClean.  Allows properties to be passed into all solutions/projects cleaned during the course of the build.  Note that the Clean target of individual solutions/projects is only invoked if IncrementalBuild is true.
  • DescriptionText.  The history comment of the work item created on a compilation failure.
  • ErrorWarningLogText.  The text that points to the errors/warnings log file in the work item created on a compilation failure.
  • IncrementalBuild.  A boolean property that specifies whether the build should be full or incremental.  Defaults to false (i.e. a full build). 
  • IncrementalGet.  A boolean property that specifies whether the get operation should be full or incremental.  Defaults to false (i.e. a full get).
  • MSTestRefPath.  The path to the TestToolsTask (contained in Microsoft.VisualStudio.QualityTools.MSBuildTasks.dll).  Overridable so that the 8.0 version can be used for test assemblies compiled against the 8.0 unit test framework - see V8TestToolsTask.
  • RunCodeAnalysis.  Property that controls whether code analysis is executed according to project settings (Default), all the time (Always), or never (Never).
  • RunTest.  Boolean property that controls whether or not tests are executed.
  • SkipClean.  Do not use this property directly - use IncrementalGet and/or IncrementalBuild instead.
  • SkipDropBuild.  Set this property to true to skip the CoreDropBuild target.
  • SkipGet.  Set this property to true to skip the CoreGet target.
  • SkipGetChangesetsUpdateWorkItems.  Set this property to true to skip the association of changesets and work items for successful builds.
  • SkipInitializeWorkspace.  Do not use this property directly - use IncrementalGet and/or IncrementalBuild instead.
  • SkipInvalidConfigurations.  Set this property to false to generate an error rather than a warning when an invalid configuration is present in the ConfigurationToBuild item group for one or more solutions/projects.
  • SkipLabel.  Set this property to true to skip the CoreLabel target.
  • SkipPostBuild.  Do not use this property - use SkipGetChangesetsUpdateWorkItems instead.
  • SkipWorkItemCreation.  Set this property to true to skip the CoreCreateWorkItem target on a compilation failure.
  • SourcesSubdirectory.  The subdirectory under the build agent's working directory to which sources are retrieved from version control.  Default value is "Sources".
  • StopOnFirstFailure.  Set this property to true to stop cleaning, compiling, and/or testing on the first failure encountered.
  • TestResultsSubdirectory.  The subdirectory under the build agent's working directory to which test results are redirected.  Default value is "TestResults".
  • UpdateAssociatedWorkItems.  A boolean value that controls whether associated work items have their "Fixed In" field updated on a successful build.
  • UpdateAssociatedWorkItemsOnBuildBreak.  A boolean value that controls whether associated work items are updated for broken builds.  Default value is false.
  • V8TestToolsTask.  Boolean property which, if true, causes the 8.0 TestToolsTask syntax to be used (the TestNames property was not supported in the 8.0 version of the task).
  • VCBuildAdditionaLibPaths.  Passed to the AdditionalLibPaths property of the VCBuild task for each C++ project compiled.
  • VCBuildAdditionalOptions.  Passed to the AdditionalOptions property of the VCBuild task for each C++ project compiled.
  • VCBuildToolPath.  Passed to the ToolPath property of the VCBuild task for each C++ project compiled.
  • VCBuildUseEnvironment.  Passed to the UseEnvironment property of the VCBuild task for each C++ project compiled.
  • VCOverridesOpen.  The beginning of the vsprops file used to override VCBuild properties - can be overridden to use a different ProjectType version, a different Name, etc.  Default value is an escaped version of:

<?xml version="1.0"?>
<VisualStudioPropertySheet ProjectType="Visual C++" Version="8.00" Name="Team Build Overrides"

  • VCOverridesClose.  The ending of the vsprops file used to override VCBuild properties.  Default value is an escaped version of:

</VisualStudioPropertySheet>

  • WorkItemFieldValue.  The fields and values of the work item created on a compilation failure.
  • WorkItemTitle.  The title of the work item created on a compilation failure.
  • WorkItemType.  The type of work item created on a compilation failure.

Task Behavior Extensibility Properties

These are properties that are designed to be overridden by users to control the behavior of particular tasks (e.g. the Get task).  They are organized by task.

  • Get (for more info, see the tf get docs here)
    • ForceGet.  Passed to the Force property of the Get task.  Use of this property is discouraged - use the IncrementalGet and/or IncrementalBuild helper properties instead.
    • GetOverwrite.  Passed to the Overwrite property of the Get task.  If true (the default), writable files will be overwritten automatically.
    • RecursiveGet.  Passed to the Recursive property of the Get task.  If true (the default), the get operation will be recursive; otherwise, the get operation will only get top-level files and directories.
    • GetVersion.  Passed to the Version property of the Get task.  Defaults to SourceGetVersion (see below), but can be overridden to retrieve a particular version from source control.
    • GetFileSpec.  Passed to the Filespec property of the Get task.  Defaults to empty, signifying that the entire contents of the workspace should be retrieved.
    • GetPopulateOutput.  Passed to the PopulateOutput property of the Get task - controls whether the Gets, Replaces, and Deletes properties of the Get task are populated (these provide access to the new files retrieved from version control, the files modified during the get, and the files deleted during the get).  Default value is false.
  • Label (for more info, see the tf label docs here)
    • LabelRecursive.  Passed to the Recursive property of the Label task.  If true (the default), the label operation will be recursive; otherwise, the label operation will only label top-level files and directories.
    • LabelChild.  Passed to the Child property of the Label task.  Valid values are Merge or Replace, with the default being Replace. 
    • LabelComment.  Passed to the Comment property of the Label task, this property controls the comment text used by the label operation.  Default value is "Label created by Team Build".
    • LabelName.  Passed to the Name property of the Label task, this property controls the name of the label generated by the label operation.  Default value is the build number.
    • LabelFiles.  Passed to the Files property of the Label task, this property controls the files labeled by the label operation.  Default value is "$/", or every file mapped in the workspace.
    • LabelScope.  Passed to the Scope property of the Label task, this property controls the scope of the label generated by the label operation.  Default value is "$/$(TeamProject)".

Other Useful Properties

These are properties that are used by the build process and should not be modified.  They can, however, be used to execute logic conditionally, to parameterize custom logic in the build process, etc.

  • BinariesRoot.  The root directory for binaries - typically the working directory for the build agent + the BinariesSubdirectory property (see above).
  • BuildAgentName.  The name of the build agent running the build.
  • BuildAgentUri.  The URI of the build agent running the build.
  • BuildBreak.  Set to true when a compilation error occurs, otherwise false.  Can be used in build break targets to determine whether they are executing after a compilation error or executing normally.
  • BuildDefinition.  This property provides the name of the definition being built.
  • BuildDefinitionId.  This property provides the integer ID of the definition being built.
  • BuildDefinitionName.  See BuildDefinition.
  • BuildDefinitionUri.  The URI of the build definition being built.
  • BuildDirectory.  The local directory being used for the build, corresponding to the expanded working directory of the build agent being used.
  • BuildProjectFolderPath.  This property provides the version control path to the TfsBuild.proj file being run, and corresponds to the ConfigurationFolderPath property of the build definition.
  • BuildUri.  The URI of the executing build.
  • ConfigurationFolderUri.  The version control URI of the directory that contains the TfsBuild.proj file being run.
  • DropLocation.  This property provides the "root" drop location for the build - either the DefaultDropLocation of the build definition or the overridden drop location provided when the build was queued.
  • IsDesktopBuild.  True for desktop builds, false for "standard" build machine builds.
  • LastBuildNumber.  The number of the last build, regardless of its status.
  • LastGoodBuildLabel.  The label created by the last "good" build.  This is the label that will be used to associate changesets and work items with the current build.
  • LastGoodBuildNumber.  The number of the last good build.
  • MachineName.  The machine name of the build agent running the build.
  • MaxProcesses.  The maximum number of processes being used by MSBuild.
  • Port.  The port being used by the build agent running the build.
  • NoCICheckinComment.  The comment which must be included in a checkin to prevent continuous integration from triggering a build.  This is critical for CI builds that need to check files in to avoid triggering an infinite loop of builds.
  • Reason.  (SP1 and later only)  The reason the build was started - None indicates the build was manually queued, Individual indicates that a "build every checkin" trigger caused the build, Batch indicates that a "rolling build" trigger caused the build, Schedule indicates that a scheduled trigger caused the build, and ScheduleForced indicates that a scheduled trigger that builds whether or not changes have occurred since the last build caused the build.
  • RequestedBy.  The user that requested the build - for triggered builds, this will typically be a service account.
  • RequestedFor.  The user for whom the build was requested - for CI builds, this will be the user whose checkin triggered the build.
  • SolutionRoot.  The root directory for source files retrieved from version control - typically the working directory for the build agent + the SourcesSubdirectory property (see above).
  • SourceGetVersion.  The version spec that will be used to retrieve sources for the build, unless the GetVersion property is overridden.
  • StartTime.  The time at which the build started.
  • TeamBuildConstants.  Allows projects being compiled to determine whether Team Build is compiling them.  Default value is "_TEAM_BUILD_".
  • TeamBuildOutDir.  The directory Team Build would have set OutDir true if CustomizableOutDir and/or CustomizablePublishDir (see above) were false.  If both are true, this value is equivalent to OutDir. 
  • TeamBuildRefPath.  Provides the path to Team Build binaries (the logger, tasks, etc.).  Typically %ProgramFiles%\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies.
  • TeamBuildVersion.  This property is set to 2.0 in Team Build 2008 and will be incremented in subsequent versions.
  • TeamFoundationServerUrl.  The URL of the team foundation server that owns the executing build.
  • TeamProject.  The team project of the build definition being built.
  • TestResultsRoot.  The root directory for test results - typically the working directory for the build agent + the TestResultsSubdirectory property (see above).
  • WorkspaceName.  The name of the workspace used to retrieve sources from version control. 

Target Dependency Properties

These are the properties used to set up the target dependency hierarchy in Team Build.  The can be modified to insert custom targets into the build process as an alternative to overriding the provided extensibility targets, but this should be done with care.  The standard pattern for overriding a dependency property is something like the following:

   <PropertyGroup>
    <DesktopBuildDependsOn>
      PreDesktopBuildTarget;
      $(DesktopBuildDependsOn);
      PostDesktopBuildTarget;
    </DesktopBuildDependsOn>    
  </PropertyGroup>

Note that the initial value of the property is preserved and new values are simply inserted before and after the existing ones, making sure to include semi-colons in all the appropriate spots.  For more information on these properties, you'll need to comb through the targets file - a full explanation of their functionality is beyond the scope of this blog post!

  • CleanDependsOn.
  • CleanAllDependsOn.
  • CleanCompilationOutputDependsOn.
  • CleanConfigurationDependsOn.
  • CleanSolutionDependsOn.
  • CompileDependsOn.
  • CompileConfigurationDependsOn.
  • CompileSolutionDependsOn.
  • ComputeSolutionListDependsOn.
  • CoreCompileDependsOn.  (This one is for backwards compatibility with TFS 2005 target overrides)
  • _CoreCompileDependsOn.  (This one is the new CoreCompileDependsOn for TFS 2008)
  • CoreCompileConfigurationDependsOn.
  • CoreCleanDependsOn.
  • CoreCleanAllDependsOn.
  • CoreCleanCompilationOutputDependsOn.
  • CoreCleanConfigurationDependsOn.
  • CoreCreateWorkItemDependsOn.
  • CoreDropBuildDependsOn.
  • CoreGetChangesetsAndUpdateWorkItemsDependsOn.
  • CoreGetChangesetsOnBuildBreakDependsOn.
  • CoreGetDependsOn.
  • CoreInitializeWorkspaceDependsOn.
  • CoreLabelDependsOn.
  • CoreOnBuildBreakDependsOn.
  • CoreTestDependsOn.
  • CoreTestConfigurationDependsOn.
  • CreateWorkItemDependsOn.
  • DesktopBuildDependsOn. 
  • DesktopRebuildDependsOn.
  • DropBuildDependsOn.
  • EndToEndIterationDependsOn.
  • GetChangesetsAndUpdateWorkItemsDependsOn.
  • GetChangesetsOnBuildBreakDependsOn.
  • GetDependsOn.
  • InitializeWorkspaceDependsOn.
  • LabelDependsOn.
  • OnBuildBreakDependsOn.
  • PostBuildDependsOn.
  • PreBuildDependsOn.
  • RunTestDependsOn.
  • TeamBuildDependsOn.
  • TestConfigurationDependsOn.
  • TestDependsOn.

Comments

  • Anonymous
    February 13, 2008
    PingBack from http://noocyte.wordpress.com/2008/02/13/aaron-hallberg-team-build-2008-property-reference/
  • Anonymous
    February 15, 2008
    Aaron Hallberg has posted a great reference to the Team Build 2008 built-in properties.&#160; You can
  • Anonymous
    February 17, 2008
    Aaron Hallberg on Team Build 2008 Property Reference. Charles Sterling on Upgrading Team Foundation Server...
  • Anonymous
    April 11, 2008
    For sometime now I have been working on custom MSBuild task. The following links were very useful in
  • Anonymous
    April 17, 2008
    The comment has been removed
  • Anonymous
    June 23, 2008
    Aaron,Any chance you could dump this awesome info to wikipedia under [[msbuild]]?Thanks,Alex
  • Anonymous
    June 26, 2008
    In Team Build 2008 there is a property called GetVersion . Here’s what the description from Aaron Hallberg’s
  • Anonymous
    October 24, 2008
    This post is more for myself than anyone, it is a collection of links difficult to find that are nevertheless
  • Anonymous
    December 24, 2008
    关键字:Label,Changeset,datetime...在TeamBuild的时候我们经常有需求需要编译某个版本，例如某个Label,或者什么时候提交的，而不是最新提交的版本,在T...
  • Anonymous
    March 12, 2009
    Hi Aaron,Great post! Thanks for the insight into the build lifecycle. If you or any of your readers are interested, I have posted the code for a custom build number generator on my blog at:http://www.grahamzero.com/blog/2009/03/team-foundation-server-2008-build-number-generator.htmlThanks again!Graham
  • Anonymous
    May 12, 2009
    Excellent resource, Aaron, but why is this not in the product documentation?
  • Anonymous
    May 15, 2009
    The customizable properties are in MSDN docs here: http://msdn.microsoft.com/en-us/library/aa337598.aspx.  As for why other stuff like this doesn't make it in, it's the same story as anything else: the team responsible for the official documentation has limited time and resources.  We (the product team) try to fill in the gaps a bit with blog content, etc. and very often the doc folks will later roll up such content into the official documentation.
  • Anonymous
    May 26, 2010
    It appears to me that the BuildBreak property does not get set at all if compilation is successful, rather than being set to false as indicated above.
  • Anonymous
    May 27, 2010
    Being new to Team Build, this list is very helpful.  Does anyone know though a way to trace the values of these properties from a particular build attempt?
  • Anonymous
    November 28, 2010
    i'd like get date of changeset, how i could do this?thank you
  • Anonymous
    August 24, 2011
    It would be very helpful to see a TFS 2010 version of this list.
  • Anonymous
    December 15, 2011
    SkipGetChangesetsUpdateWorkItems is a typo.  It is actually SkipGetChangesetsAndUpdateWorkItems