Team Foundation Build 活動
Team Foundation Build 活動是 Team Foundation Build 系統中建置流程的基礎元件。 您可以使用這些活動建立自訂建置流程以符合小組需求，例如下列自訂邏輯或執行特定工作。
在大部分情況下，建立自訂建置流程範本最佳的方式就是以預設範本 (DefaultTemplate.xaml) 為建立基礎。 這樣一來，即可在自訂特定部分以符合需求時利用已建立的一般有用功能。 這種方式的另一個優點是，您可以查看如何使用本主題所述之活動的特定和實用範例。 如需如何建立建置流程範本的詳細資訊，請參閱建立並使用自訂建置流程範本。
.gif "重要事項") 重要事項 |
|---|
只有在必須符合特定需求時才要建立自訂建置流程。 您可以使用 DefaultTemplate.xaml 快速定義符合許多一般需求的建置流程。 如需詳細資訊，請參閱使用預設範本定義組建。 |
本主題內容
必要的使用權限
目標導向的活動參考
依字母順序排列的活動參考
必要的使用權限
若要執行使用 Team Foundation Build 活動的程序，必須將下列權限設定為 [允許]：
編輯組建定義
[簽出] 和 [簽入] 相關的版本控制目錄 (例如 Team 專案的 BuildProcessTemplates 子目錄)
佇列組建
如需詳細資訊，請參閱 Team Foundation Server 使用權限。
目標導向的活動參考
執行基本工作
取得環境變數的值
取得工作區中之檔案的路徑
使用目錄
取得組建代理程式工作目錄的路徑
下載不在工作區中的檔案
尋找檔案
將警告、錯誤和其他資料寫入建置記錄檔中
將建置中繼資料寫入資料倉儲
控制建置流程
在組建代理程式上執行活動
使用具名 Mutex 結構實作執行緒安全的處理序
根據原因 (觸發程序) 限制建置流程的區段
編譯、測試和執行其他工作
使用 MSBuild 編譯二進位碼、執行程式碼分析和執行其他工作
使用 MSTest 執行測試
取得組建所影響的測試清單
啟動處理序
使用版本控制
將變更集和工作項目與組建產生關聯
簽入受管制的變更
評估簽入原則
標示版本控制中的檔案
使用工作項目
將變更集和工作項目與組建產生關聯
建立工作項目
使用符號資料
將版本控制路徑和版本嵌入 .pdb 檔案中的符號資料
將符號發行至 SymStore 符號存放區
取得有用的物件參考
取得 Team 專案集合的物件參考
取得組建代理程式的物件參考
取得組建詳細資料的物件參考
取得建置環境的物件參考
依字母順序排列的活動參考
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
執行基本工作
您可以使用 Team Foundation Build 活動執行下列工作：
取得環境變數的值
取得工作區中之檔案的路徑
使用目錄
取得組建代理程式工作目錄的路徑
下載不在工作區中的檔案
尋找檔案
將警告、錯誤和其他資料寫入建置記錄檔中
寫入有關組建的中繼資料
取得環境變數的值 (ExpandEnvironmentVariables 活動)
使用 ExpandEnvironmentVariables 活動，在組建伺服器上解析一個或多個環境變數。 如果這個活動位於 AgentScope 順序內則會在組建代理程式上讀取環境變數，否則會在組建控制器上讀取環境變數。
ExpandEnvironmentVariables Result (String) 屬性
傳回作業的結果。 例如：The temp directory on machine BLDSERV3 is C:\windows\SERVIC~2\NETWOR~1\AppData\Local\Temp.。
ExpandEnvironmentVariables 引數屬性
Input (String)：您必須指定含有要解析之環境變數的字串。 您必須指定 MSBuild 屬性而不是使用 Windows 百分比符號標記法，格式化每個環境變數。 例如："The temporary directory on machine $(COMPUTERNAME) is $(TEMP)."。
AdditionalVariables (IDictionary<TKey, TValue><String,String>)：您可以指定包含要解析對應值之任何其他變數 (索引鍵形式) 的 IDictionary 物件。
回到頁首
取得工作區中之檔案的路徑
每個組建都有一個版本控制工作區，其定義位於組建定義的 [工作區] 索引標籤。 工作區為組建提供需要從版本控制系統取得的原始程式碼檔和任何其他檔案。 Team Foundation Build 提供兩種可用來與組建工作區中之檔案搭配使用的活動：ConvertWorkspaceItem 和 ConvertWorkspaceItems。
如需組建工作區的詳細資訊，請參閱建立基本組建定義。
.gif "秘訣") 秘訣 |
|---|
如需如何在一般情節中使用 ConvertWorkspaceItem 活動的詳細逐步指示，請參閱控制建置系統放置二進位檔的地方。 |
取得工作區中之檔案的路徑 (ConvertWorkspaceItem 活動)
使用 ConvertWorkspaceItem 活動，將伺服器路徑轉換成組建代理程式上的本機路徑或將組建代理程式上的本機路徑轉換成伺服器路徑。
ConvertWorkspaceItem Result (String) 屬性
傳回轉換後的路徑。
ConvertWorkspaceItem 引數屬性
Input (String)：您必須提供要轉換的路徑值。
Workspace (Workspace)：您必須提供含有檔案之 Workspace 的參考。 在大部分情況下，您應該將這個屬性設定為您會在 CreateWorkspace 活動的 Result 屬性中初始化的變數。 如果建立以 DefaultTemplate.xaml 為基礎的建置流程，可能要使用 Workspace 變數。
Direction
將伺服器路徑轉換成本機路徑：在 Direction 屬性中選取 ServerToLocal，然後在 Input (String) 屬性中指定伺服器上之檔案的路徑。
例如，小組可能在下列目錄中存放一般公用程式：$/OurTeam/BuildProcess/Util。 在編譯二進位碼後，您可以建立一個執行 ScanBinaries.exe 公用程式的自訂建置流程。 如果在組建定義的 [工作區] 索引標籤上已對應 $/OurTeam/BuildProcess/Util，您可以在指定 Input 屬性中指定 $/OurTeam/BuildProcess/Util/ScanBinaries.exe，從 Result (String) 屬性取得公用程式的本機路徑。
將本機路徑轉換成伺服器路徑：在 Direction 屬性中選取 ServerToLocal，然後在 Input 屬性中指定組建代理程式上之檔案的本機路徑。
取得工作區中之檔案的路徑 (ConvertWorkspaceItems 活動)
使用 ConvertWorkspaceItems 活動，將伺服器路徑轉換成組建代理程式上的本機路徑或將組建代理程式上的本機路徑轉換成伺服器路徑。
ConvertWorkspaceItems Result (IList<String>) 屬性
傳回轉換後的路徑值。
ConvertWorkspaceItems 引數屬性
Input (IEnumerable<T><String>)：您必須提供要轉換的路徑值。
Workspace (Workspace)：您必須提供含有檔案之 Workspace 的參考。 在大部分情況下，您應該將這個屬性設定為您會在 CreateWorkspace 活動的 Result 屬性中初始化的變數。
秘訣如果建立以 DefaultTemplate.xaml 為基礎的建置流程，可能要使用 Workspace 變數。
Direction：選取下列其中一個值：
如果在 Input 屬性中指定伺服器路徑值的集合，而且想要 Result 屬性傳回本機路徑值的清單，請選取 ServerToLocal。
如果在 Input 屬性中指定本機路徑值的集合，而且想要 Result 屬性傳回伺服器路徑值的清單，請選取 LocalToServer。
使用目錄
您可以透過 Team Foundation Build 中的數種活動使用目錄。
| 秘訣 |
|---|
如果您要使用的目錄屬於組建的版本控制工作區，就必須改用工作區活動。 如需詳細資訊，請參閱取得工作區中之檔案的路徑。 |
建立目錄 (CreateDirectory 活動)
使用 CreateDirectory 活動建立 Directory (String) 屬性中指名的目錄。
複製目錄 (CopyDirectory 活動)
使用 CopyDirectory 活動，以遞迴方式將所有內容從一個在 Source (String) 屬性中指定的目錄複製到另一個在 Destination (String) 屬性中指定的目錄。 在 Destination 屬性中指定的目錄必須已經存在。 不會複製空的目錄或子目錄。
刪除目錄 (DeleteDirectory 活動)
使用 DeleteDirectory 活動刪除 Directory (String) 屬性中指名的目錄。 如果您要刪除的目錄包含子目錄，則必須將 Recursive (Boolean) 屬性設定為 True，否則建置將會失敗。
取得組建代理程式工作目錄的路徑 (GetBuildDirectory 活動)
使用 GetBuildDirectory 活動，從 Result (String) 屬性取得組建代理程式工作目錄的常值路徑。 這個活動只能用於 AgentScope 活動內。
回到頁首
下載不在工作區中的檔案
使用 DownloadFiles 活動下載一個或多個檔案。 忽略 DownloadFile 活動。
DownloadFiles 活動
使用 DownloadFiles 活動從版本控制下載一個或多個檔案。
| 秘訣 |
|---|
如果您要下載的檔案位於組建工作區，可能要透過 ConvertWorkspaceItem 活動進行存取。 |
DownloadFiles 引數屬性
LocalPath (String)：您必須指定值：
如果要下載單一檔案，請為要下載的本機檔案複本指定本機路徑和名稱，例如 "c:\Docs\readme.txt"。
如果要下載多個檔案，請為要下載的檔案指定目標目錄的本機路徑，例如 "c:\Docs\"。
ServerPath (String)：您必須指定值：
如果要下載單一檔案，請為要下載的本機檔案複本指定伺服器路徑和名稱，例如 "$/Docs/readme.txt"。
如果要下載多個檔案，請指定含有要下載的檔案之目錄的伺服器路徑，例如 "$/Docs/"。
Recursion (RecursionType)：
OneLevel：下載 ServerPath 屬性中指定之目錄內的檔案。
Full：下載 ServerPath 屬性中指定之目錄內的檔案，以及任何子目錄內的檔案。
Version (String)：您可以指定版本規格。 若要下載目前版本，請保留這個屬性的 Microsoft.TeamFoundation.VersionControl.Client.VersionSpec.Latest.DisplayString 設定。 如需版本規格的詳細資訊，請參閱命令列語法 (版本控制)。
DeletionID (Int32)：只有在要下載的檔案已從版本控制中刪除時，您才必須指定這個屬性。 您可以在命令提示字元輸入 tf dir /deleted，以互動方式取得這個值。 (如需詳細資訊，請參閱 Dir 命令)。 但是，Team Foundation Build 不提供可取得 DeletionID 的內建活動。 若要使用這個屬性，您必須取得或建立可提供此功能的自訂活動。
回到頁首
DownloadFile 活動
忽略 DownloadFile 活動。 DownloadFiles 活動是下載一個或多個檔案最簡單的方法。
尋找檔案 (FindMatchingFiles 活動)
使用 FindMatchingFiles 活動尋找檔案。 在 MatchPattern (String) 屬性中指定搜尋準則。 您可以在這個屬性中指定包含下列項目的引數：
Directory GetFiles(String, String) 方法的 searchPattern 引數所支援的語法。
**表示指定遞迴搜尋。 例如：
若要搜尋原始檔目錄以找出文字檔，您可以為 MatchPattern 屬性指定類似如下的值：String.Format("{0}\**\*.txt", SourcesDirectory)。
若要搜尋原始檔目錄以找出一個或多個叫做 txtfiles 的子目錄中的文字檔，您可以為 MatchPattern 屬性指定類似如下的值：String.Format("{0}\**\txtfiles\*.txt", SourcesDirectory)。
您可以在 Result (IEnumerable<T><String>) 屬性中收集作業的結果。
將警告、錯誤和其他資料寫入建置記錄檔中
WriteBuildMessage 活動
使用 WriteBuildMessage 活動將告知性訊息寫入建置記錄檔中。 您必須在 Message (String) 屬性中指定訊息。 您也可以修改 Importance 屬性 (BuildMessageImportance) 的值，以指出訊息的重要性。
| 秘訣 |
|---|
|
WriteBuildWarning 活動
使用 WriteBuildWarning 活動將警告訊息寫入建置記錄檔中。 警告與黃色驚嘆號會一起出現在建置結果視窗中。 您必須在 Message (String) 屬性中指定訊息。
只有在小組將詳細等級設定為最低或最高時，建置訊息才會被記錄下來。 如需詳細資訊，請參閱管理組建資訊和控制詳細資訊。
WriteBuildError 活動
使用 WriteBuildError 活動將錯誤訊息寫入建置記錄檔中。 錯誤與紅色驚嘆號會一起出現在建置結果視窗中。 將錯誤寫入建置記錄檔時，組建至多只會被分類為 Partially Succeeded。 您必須在 Message (String) 屬性中指定訊息。
不論詳細等級設定為何，建置錯誤一定會被記錄下來。 如需詳細資訊，請參閱管理組建資訊和控制詳細資訊。
WriteBuildInformation<T> 活動
使用 WriteBuildInformation<T> 活動將物件放入建置記錄檔。 使用者在建置結果視窗中檢視記錄檔時，物件是以反映呈現的。
WriteBuildInformation<T> 引數屬性
Value (Object)：您必須指定要放入建置記錄檔的物件。 以要在建置結果視窗中呈現的物件來說，物件必須實作 IBuildInformationNode 並將 Type 設定為下列其中一個 InformationTypes 值：
ActivityProperties
ActivityTracking
AgentScopeActivityTracking
BuildError
BuildMessage
BuildProject
BuildStep
BuildWarning
ExternalLink
OpenedWorkItem
ParentToBuildDetail：您可以指定 False 將這個物件的父代設為此活動的父代，或指定 True 將父代設為 IBuildDetail 物件。
這個屬性的其中一個作用是，資訊是如何顯示在建置結果視窗中。 如果指定 False，會將資訊縮排並對齊其他位於 WriteBuildInformation<T> 活動前後或位於相同層級的活動。 如果指定 True，就不會呈現資訊。
回到頁首
將中繼資料寫入資料倉儲
您可以將有關組建的中繼資料寫入資料倉儲：
寫入組建編號 (UpdateBuildNumber 活動)
寫入有關組建的關鍵資料點 (SetBuildProperties 活動)
| 秘訣 |
|---|
如果這些活動不支援您要寫入的中繼資料，您可以使用 GetBuildDetail 活動取得 IBuildDetail 物件的參考，然後使用該參考將資料直接指派至物件。 |
寫入組建編號 (UpdateBuildNumber 活動)
使用 UpdateBuildNumber 活動設定組建的組建編號 (或名稱)。 此活動會執行下列步驟：
依據決定組建編號格式的運算式，建構組建編號。 建置流程通常會從工作流程引數接受此運算式，這個引數由組建定義的 [流程] 索引標籤上的參數提供。
透過將結果值寫入 BuildNumber 屬性，設定組建的組建編號 (或名稱)。
UpdateBuildNumber Result (String) 屬性
Result：傳回新的 BuildNumber 值。
UpdateBuildNumber 屬性
回到頁首
寫入有關組建的關鍵資料點 (SetBuildProperties 活動)
使用 SetBuildProperties 將關鍵資料點寫入 IBuildDetail 物件，這個物件會管理有關每個組建在資料倉儲中的資料儲存。 大部分的資料會在建置結果視窗中顯示給使用者。
SetBuildProperties 屬性
PropertiesToSet：您必須為要設定之屬性的名稱選取核取方塊。
BuildNumber (String)：您可以設定組建的 BuildNumber，將它視為組建的名稱。
秘訣如果要根據組建定義的 [流程] 索引標籤上使用者指定的設定來設定這個值，您可能要使用 UpdateBuildNumber 活動而非這個屬性。
CompilationStatus (BuildPhaseStatus)：您可以設定編譯狀態 (CompilationStatus)。 (MSBuild 活動也會自動設定這個值)
DropLocation (String)：您可以在 DropLocation 屬性中記錄置放位置。
注意事項如果設定這個屬性，您實際上不會建立置放位置， 而是改用這個屬性在資料倉儲中儲存置放資料夾的位置，您通常會使用 CreateDirectory 活動建立置放資料夾。
KeepForever (Boolean)：如果要略過組建定義的 [保留原則] 索引標籤上的設定，並且無限期保留已完成的組建，您可以將 KeepForever 屬性設定為 True。
LabelName (String)：您可以設定 LabelName 屬性，以記錄用來在版本控制中的原始程式碼檔上標示此組建的標籤。 您通常會設定這個屬性，以比對 LabelWorkspace 活動的 Name 屬性中的值。
重要事項Team Foundation Build 必須要有此資料，才能將變更集和工作項目與組建產生關聯。 如果您不提供此資料，AssociateChangesetsAndWorkItems 活動將會失敗。
LogLocation (String)：您可以使用 LogLocation 屬性，記錄建置流程放置記錄檔的資料夾的 UNC 檔案路徑。
注意事項您可能不需要在自訂建置流程中使用這個屬性。 這個屬性主要是供 UpgradeTemplate.xaml 檔案支援舊版建置流程使用。
SourceGetVersion (String)：您可以使用 SourceGetVersion 屬性記錄為此組建擷取原始檔的版本規格。
Status (BuildStatus)：您可以在 Status 屬性中記錄建置的整體狀態。 例如，您可以使用這個屬性來指出建置成功還是失敗。
TestStatus (BuildPhaseStatus)：您可以使用 TestStatus 屬性記錄已在此組建上執行之測試的整體狀態。 例如，您可以使用這個屬性來指出已在此組建上執行的測試成功還是失敗。
回到頁首
控制建置流程
您可以使用 Team Foundation Build 活動，透過下列方式控制建置流程：
在組建代理程式上執行活動
使用具名 Mutex 結構實作執行緒安全的處理序
根據原因 (觸發程序) 限制建置流程的區段
在組建代理程式上執行活動 (AgentScope 活動)
使用 AgentScope 活動封入建置流程要在組建代理程式上執行的部分。
AgentScope 引數屬性
代理程式選取項目
MaxWaitTime (TimeSpan)：您可以指定建置流程等候組建代理程式變成可用的最長時間。 您可以用 hh:mm:ss 格式輸入值。 例如，如果您指定的值為 01:30:45，而組建在 1 小時 30 分 45 秒後仍未指派組建代理程式，則建置將會失敗且具有逾時錯誤。 如果您要提供組建控制器無限制的時間來尋找用以處理此組建定義的組建代理程式，請指定值 00:00:00。
重要事項您可以在 MaxWaitTime 屬性中指定合理的非零值，以避免備份組建佇列。
ReservationSpec (AgentReservationSpec)：您可以限制將處理此活動包含之活動的組建代理程式種類。 例如，您可以指定只有具有特定標記的組建代理程式，才會被用來處理 AgentScope 活動內的活動。
執行
MaxExecutionTime (TimeSpan)：您可以指定允許此 AgentScope 活動完成的最長時間。 您可以用 hh:mm:ss 格式輸入值。 例如，如果您指定的值為 04:30:15，而組建代理程式在 4 小時 30 分 15 秒後未完成其工作，則建置將會失敗且具有逾時錯誤。 如果您要提供組建代理程式無限制的時間來處理組建，請指定值 00:00:00。
秘訣您可以在 MaxExecutionTime 屬性中指定合理的非零值，以避免備份組建佇列。
範圍
- DataToIgnore：忽略這個屬性。
回到頁首
使用具名 Mutex 結構實作執行緒安全的處理序 (SharedResourceScope 活動)
使用 SharedResourceScope 活動實作具名 Mutex (互斥) 結構。 放在此活動內的建置流程區段將會具備「執行緒安全」。
此活動的典型用法是，封入建置流程必須存取一次只能有一個流程存取的共用資源的部分。 例如，您可能會想要組建循序寫入檔案共用上的單一文字檔案。 為確保這種流程運作正常，您應該在 SharedResourceScope 活動內加以實作。
您可以在 DefaultTemplate.xaml 中找到另一個範例，其中 PublishSymbols 活動的呼叫是內嵌在 SharedResourceScope 活動內：
順序 (Sequence) >
在代理程式上執行 (AgentScope) >
嘗試編譯、測試及關聯變更集與工作項目 (TryCatch [Try]) >
順序 (Sequence) >
取得受影響的測試、索引來源和發行符號 (Parallel) >
如果 SourceAndSymbolServerSettings.IndexSources 或 SourceAndSymbolServerSettings.HasSymbolStorePath (If [Then]) >
已觸發之組建的索引來源和發行符號 (InvokeForReason) >
如果 SourceAndSymbolServerSettings.HasSymbolStorePath (If [Then]) >
嘗試發行符號 (TryCatch [Try]) >
同步處理對符號存放區的存取 (SharedResourceScope) >
發行符號 (PublishSymbols)
如需如何巡覽這個結構的詳細資訊，請參閱在複雜的 Windows 工作流程中巡覽。
SharedResourceScope 引數屬性
ResourceName (String)：您必須指定值。 如果 SharedResourceScope 活動的所有執行個體在 Team 專案集合中有相同的 ResourceName 值，則一次只能有一個執行個體執行 (即使它們位於不同的組建定義範本)。
MaxExecutionTime (TimeSpan)：您可以指定允許 SharedResourceScope 活動完成的最長時間。 您可以用 hh:mm:ss 格式輸入值。 例如，如果您指定的值為 04:30:15，而 SharedResourceScope 活動在 4 小時 30 分 15 秒後還未完成處理，則建置將會失敗並發生逾時錯誤。 如果要讓 SharedResourceScope 活動的處理時間無限制，請指定值 00:00:00。
秘訣您可以在 MaxExecutionTime 屬性中指定合理的非零值，以避免備份組建佇列。
MaxWaitTime (TimeSpan)：您可以指定建置流程在佇列中等候處理 SharedResourceScope 活動的最長時間。 您可以用 hh:mm:ss 格式輸入值。 例如，如果您指定的值為 01:30:45，而 SharedResourceScope 活動在 1 小時 30 分 45 秒後還未處理，則建置將會失敗並發生逾時錯誤。 如果您要讓組建流程在佇列中的等候時間無限制，請指定值 00:00:00。
秘訣您可以在 MaxWaitTime 屬性中指定合理的非零值，以避免備份組建佇列。
回到頁首
根據原因 (觸發程序) 限制建置流程的區段 (InvokeForReason 活動)
使用 InvokeForReason 活動封入建置流程的區段，而這個流程只要在因特定原因而執行的組建中執行。 組建原因通常由使用者在組建定義的 [觸發程序] 索引標籤上選取的觸發程序設定。 您可以在 Reason 屬性中指定一個或多個要允許的原因值。 如需詳細資訊，請參閱指定組建觸發程序和原因。
回到頁首
編譯、測試和執行其他工作
您可以使用 Team Foundation Build 活動編譯二進位碼、執行測試和執行其他工作：
使用 MSBuild 編譯二進位碼、執行程式碼分析和執行其他工作
使用 MSTest 執行測試
取得組建所影響的測試清單
使用 MSBuild 編譯二進位碼、執行程式碼分析和執行其他工作 (MSBuild 活動)
使用 MSBuild 活動編譯二進位碼、執行程式碼分析和利用 MSBuild 所提供的任何其他功能。
MSBuild 結果屬性
此活動的屬性不會傳回結果。 不過，如果任何編譯錯誤被記錄，此活動會將 CompilationStatus 設定為 Failed。
MSBuild 引數屬性
AdditionalVCOverrides (String)：如果將 GenerateVsPropsFile 設定為 True，這個屬性的內容會內嵌到產生的 .vsprops 檔案。
CommandLineArguments (String)：您可以指定要傳遞至 MSBuild 的命令列引數。
Configuration (String)：您可以指定要建置的組態。 例如：“debug” 或 “release”。
GenerateVSPropsFile (Boolean)：如果這個屬性設定為 True，MSBuild 會產生標準的 .vsprops 檔案以傳遞至 C++ 專案。 此檔案會包含 C++ 專案的輸出目錄，以及您在 AdditionalVCOverrides 屬性中指定的任何項目。
LogFile (String)：您可以指定 MSBuild 應該建立之記錄檔的名稱。
LogFileDropLocation (String)：您可以指定想要 MSBuild 置放記錄檔之目錄的完整 UNC 路徑。
MaxProcesses (Int32)：您可以指定 MSBuild 建立的最大處理序數目。
OutDir (String)：您可以指定 MSBuild 置放編譯過的二進位檔的目錄。 如需詳細資訊，請參閱控制建置系統放置二進位檔的地方。
Platform (String)：您可以指定 MSBuild 建置的平台。 例如：“Any CPU”、“x86” 或 “x64”。
Project (String)：您可以指定 MSBuild 建置的方案或程式碼專案。
ResponseFile (String)：您可以指定 MSBuild 使用的回應檔。
RunCodeAnalysis (CodeAnalysisOption)：您可以指定程式碼分析應該是永遠執行、絕不執行，還是根據專案設定執行。
Targets (IEnumerable<T><String>)：您可以指定要建置的目標。
TargetsNotLogged (IEnumerable<T><String>)：您可以指定不記錄 ProjectStarted 事件的目標。
ToolPath (String)：您可以指定工具的路徑。
ToolPlatform (ToolPlatform)：您可以指定工具的平台。 指定 Microsoft.TeamFoundation.Build.Workflow.Activities.ToolPlatform.Auto 以根據目前作業系統偵測平台。
Verbosity (BuildVerbosity)：您可以指定 MSBuild 產生之記錄檔的詳細等級。
如需 MSBuild 屬性所影響的許多 MSBuild 選項的詳細資訊，請參閱 MSBuild 命令列參考。
回到頁首
執行測試 (MSTest 活動)
透過 MSTest.exe 使用此活動執行測試。
MSTest 核心屬性
若要開始此活動，請決定您要執行測試的方式，然後為適當的屬性指定值。
若要執行測試容器中的測試 (建議方法)，請使用下列屬性：
TestContainers (IEnumerable<String>)：您必須指定要執行之測試的測試容器。 這個屬性相當於 MSTest.exe 命令的 /testcontainer 選項。 如需詳細資訊，請參閱 /testcontainer。
SearchPathRoot (String)：您可以指定要搜尋測試容器及其相依性所在之目錄路徑的根目錄。 如果不指定值，MSTest 活動會嘗試在一般位置尋找檔案。
TestSettings (String)：您可以指定要使用的測試回合組態檔。 這個屬性相當於 MSTest.exe 命令的 /testsettings 選項。 如需詳細資訊，請參閱 /testsettings。
若要執行測試清單中的測試，請使用下列屬性：
TestLists (IEnumerable<String>)：您必須指定要執行的測試清單。 這個屬性相當於 MSTest.exe 命令的 /testlist 選項。 如需詳細資訊，請參閱 /testlist 和定義測試清單以分組測試。
TestMetadata (String)：您必須指定包含要執行之測試清單的中繼資料檔。 這個屬性相當於 MSTest.exe 命令的 /testmetadata 選項。 如需詳細資訊，請參閱 /testmetadata。
MSTest 篩選屬性
您可以使用下列屬性篩選執行的測試：
Category (String)：您可以根據測試分類篩選測試。 這個屬性相當於 MSTest.exe 命令的 /category 選項。 如需詳細資訊，請參閱 /category 和定義測試分類以分組測試。
MaxPriority (Int32)：您可以指定要執行之測試的最高優先順序。 只有那些優先順序小於或等於這個值的測試才會執行。 您必須指定等於或大於 MinPriority 屬性的正整數，否則指定 -1 表示不指定最高優先順序。
秘訣如果您已將優先順序指派給測試，MinPriority 和 MaxPriority 屬性會是重要的機制，可協助您定義全面性測試與快速組建之間的平衡。
MinPriority (Int32)：您可以指定要執行之測試的最低優先順序。 只有那些優先順序大於或等於這個值的測試才會執行。 您必須指定等於或小於 MaxPriority 屬性的正整數，否則指定 -1 表示不指定最低優先順序。
TestNames (IEnumerable<String>)：您可以指定要執行之測試的名稱。 這個屬性相當於 MSTest.exe 命令的 /test 選項。 如需詳細資訊，請參閱 /test。
MSTest 發行屬性
您可以使用下列屬性將測試結果發行至資料倉儲：
Publish (Boolean)：如果要發行測試結果，就必須將這個屬性設定為 True。
Flavor (String)：您可以為要發行的測試結果指定執行測試之組建的類別。 這個屬性相當於 MSTest.exe 命令的 /flavor 選項。 如需詳細資訊，請參閱發行測試結果的命令列選項。
Platform (String)：如果要發行測試的結果，您可以指定執行測試之組建的平台。 這個屬性相當於 MSTest.exe 命令的 /platform 選項。 如需詳細資訊，請參閱發行測試結果的命令列選項。
TestConfigId (Int32)：您可以指定現有測試管理組態的 ID，與要發行之結果的測試回合產生關聯。 這個屬性相當於 MSTest.exe 命令的 /testconfigid 選項。 如需詳細資訊，請執行在 Visual Studio 命令提示字元執行 MSTest /?。
TestConfigName (String)：您可以指定現有測試管理組態的名稱，與要發行之結果的測試回合產生關聯。 這個屬性相當於 MSTest.exe 命令的 /testconfigname 選項。 如需詳細資訊，請執行在 Visual Studio 命令提示字元執行 MSTest /?。
MSTest 其他屬性
CommandLineArguments (String)：如需可指定的其他命令列選項的詳細資訊，請參閱 MSTest.exe 命令列選項。
PathToResultsFilesRoot (String)：您可以指定組建代理程式上 MSTest.exe 放置結果檔案 (.trx 檔案) 的目錄之路徑的根目錄。
ToolPath (String)：您可以指定包含要執行的 MSTest.exe 版本之目錄的路徑。 如果不指定路徑，Team Foundation Build 會自動根據測試清單或測試容器中的資料來決定路徑。
回到頁首
取得組建所影響的測試清單 (GetImpactedTests 活動)
使用 GetImpactedTests 活動，識別目前組建中的變更並產生受這些變更影響的測試清單。 此活動會將受影響的測試清單寫入資料倉儲，以協助測試小組成員判斷要在此組建完成後執行的測試。 如需小組如何使用此資料的詳細資訊，請參閱執行會受到程式碼變更影響的建議測試。
| 注意事項 |
|---|
此活動對閘道簽入組建或私用組建沒有作用。 |
必要條件
只有在下列條件成立時，GetImpactedTests 活動才會有作用：
MSTest 活動已經以收集測試影響資料的測試設定檔案 (TestSettings 屬性中指定的) 執行。 您可以使用自動產生的 Traceandtestimpact.testsettings 檔案，或使用另一個已選取 [測試影響] 核取方塊的測試設定檔案。 如需詳細資訊，請參閱 HOW TO：收集資料以檢查程式碼變更後應該要執行的測試。
GetImpactedTests 活動已成功識別出前一個組建。 如需詳細資訊，請參閱下一章節。
GetImpactedTests 活動如何識別前一個組建
GetImpactedTests 活動會藉由目前組建與前一個組建的比較來產生結果。 此活動會透過下列程序識別前一個組建：
如果指定 BaselineBuildDropLocation 屬性，則會將已產生二進位檔的組建識別為前一個組建。
如果不指定 BaselineBuildDropLocation 屬性，此活動會藉由搜尋資料倉儲中的資料以找出符合下列準則的最新組建來識別前一個組建。
組建與目前組建有相同的 BuildDefinitionUri。
組建的 Status 不是 Succeeded 就是 PartiallySucceeded。
組建有 DropLocation。
組建並非閘道簽入組建或私用組建。
GetImpactedTests 結果屬性
CodeChanges (CodeChangeList)：傳回對此組建與前一個組建之間的程式碼中之每個方法進行的變更清單。 這些方法會在 Microsoft Intermediate Language (MSIL) 層級進行分析。
ImpactedTests (TestList)：傳回受此組建與前一個組建之間的程式碼變更影響的測試清單。
GetImpactedTests 引數屬性
其他
- Build：您必須提供組建的 IBuildDetail 物件。 您可以使用 GetBuildDetail 活動取得這個物件的參考。
其他
Assemblies (IEnumerable<String>)：您必須指定想要此活動檢查的組件清單。 您通常已在此組建中建置這些組件。
AssociatedChangesets (IList<T><Changeset>)：您可以指定要與測試影響結果產生關聯的變更集。 一般來說，您會想要指定正在建置的變更集。 您可以從 AssociateChangesetsAndWorkItems 活動取得這些變更集的參考。
BinariesRoot (String)：您必須指定組件相依的二進位檔的路徑。 您可以使用 GetBuildDirectory 活動取得這個值。
Workspace (Workspace)：您必須提供組建之工作區的參考。 您可以從 CreateWorkspace 活動的 Result 屬性取得此參考。
BaselineBuildDropLocation (String)：您可以指定含有已完成的組建之置放資料夾的路徑，而您會想要 GetImpactedTests 活動將已完成的組建與目前組建做比較。 如果不指定這個屬性，此活動會嘗試查詢建置系統以找出前一個組建。 如需詳細資訊，請參閱本節前面所述的＜GetImpactedTests 活動如何識別前一個組建＞。
回到頁首
啟動處理序 (InvokeProcess 活動)
使用 InvokeProcess 活動，在組建伺服器上啟動處理序 (執行程式)。 此活動其實是 Start 上的包裝函式。
InvokeProcess Result (Int32) 屬性
從處理序傳回 ExitCode。
InvokeProcess 引數屬性
FileName (String)：您必須指定要啟動之處理序 (要執行之程式) 的 FileName。 例如：%ProgramFiles%\ContosoBuildUtils\MarkBins.exe。
EnvironmentVariables (IDictionary<TKey, TValue><String,String>)：您可以指定其他環境變數 (EnvironmentVariables) 及其值。
OutputEncoding (Encoding)：您可以指定用來讀取輸出 (StandardOutputEncoding) 和錯誤 (RedirectStandardError) 資料流的編碼。 在許多情況下，預設值是這個屬性的最佳值：
System.Text.Encoding.GetEncoding(System.Globalization.CultureInfo.InstalledUICulture.TextInfo.OEMCodePage)WorkingDirectory (String)：您可以指定要在其中執行處理序的工作目錄 (WorkingDirectory)。
例如，您可能會想要對編譯過的二進位檔執行 MarkBins.exe 公用程式。 若要縮小公用程式執行的範圍，您可以呼叫 GetBuildDirectory，並將結果放入這個屬性。
若要從處理序顯示標準輸出和錯誤輸出
在 InvokeProcess 活動中，按兩下 [按兩下以檢視]。
從 [工具箱] 拖曳 WriteBuildMessage 活動讓此活動出現在 [處理標準輸出] 底下，然後將 WriteBuildMessage Message 屬性設定為 stdOutput。
從 [工具箱] 拖曳 WriteBuildError 活動讓此活動出現在 [處理標準輸出] 底下，然後將 WriteBuildMessage Message 屬性設定為 errOutput。
使用版本控制
您可以使用 Team Foundation Build 活動執行下列版本控制工作：
將變更集和工作項目與組建產生關聯
簽入受管制的變更
評估簽入原則
標示版本控制中的檔案
將變更集和工作項目與組建產生關聯 (AssociateChangesetsAndWorkItems 活動)
使用 AssociateChangesetsAndWorkItems 活動，將每個已完成的組建與進入程式碼的所有變更集及其關聯的工作項目連結在一起。
每個組建定義都會自行維護哪些變更集和工作項目正等候與下一個完成組建產生關聯的記錄。 例如，組建 A 和組建 B 可能會建置變更集 382。 組建 A 已排入佇列且成功完成，而組建 B 已排入佇列但失敗。 變更集 382 現在與成功完成的組建 A 和失敗的組建 B 連結在一起。雖然變更集 382 不會與組建 A 的下一個完成組建連結在一起，不過它會與組建 B 的下一個完成組建連結在一起。
AssociateChangesetsAndWorkItems Result (IList<T><Changeset>) 屬性
傳回與組建關聯的變更集。
AssociateChangesetsAndWorkItems 引數屬性
CurrentLabel (String)：讓這個屬性保持空白。
LastLabel (String)：讓這個屬性保持空白。
UpdateWorkItems (Boolean)：如果要將關聯工作項目的 [修正於] 欄位填入組建編號，請將這個屬性的值設定為 True， 否則將這個值設定為 False。
回到頁首
簽入受管制的變更 (CheckInGatedChanges 活動)
使用 CheckInGatedChanges 活動將已觸發閘道簽入組建的程式碼變更簽入版本控制。 此活動也會將該組建和與變更集關聯的工作項目產生關聯。
| 注意事項 |
|---|
為了正常運作，此活動必須放在範本中 MSBuild 和 MSTest 活動的所有實作後面的位置。 |
CheckInGatedChanges Result (Changeset) 屬性
傳回含有所簽入之變更的變更集。
CheckInGatedChanges 引數屬性
IgnoreErrors (Boolean)：將這個屬性設定為 False，表示只有在 CompilationStatus 和 TestStatus 屬性都有 Succeeded 的值時，才允許簽入檔案。 將這個屬性設定為 True，表示允許簽入檔案，不論上述兩個屬性的值為何。
注意事項您可以使用 SetBuildProperties 活動設定 CompilationStatus 和 TestStatus 屬性。
UpdateWorkItems (String)：如果要將關聯工作項目的 [修正於] 欄位填入組建編號，請將這個值設定為 True， 否則請將其設定為 False。
回到頁首
評估簽入原則 (EvaluateCheckInPolicies 活動)
使用 EvaluateCheckInPolicies 活動，在組建伺服器上執行簽入原則。 此活動會執行對組建定義的 [工作區] 索引標籤上指定之資料夾有效的簽入原則。 如果簽入原則失敗而組建原因不是 CheckInShelveset (閘道簽入組建) 就是 ValidateShelveset (私用組建)，則建置會失敗。
| 重要事項 |
|---|
簽入原則是在組建伺服器上評估，而不是在開發人員的用戶端電腦上評估。 |
此活動最有效的用法是與閘道簽入組建搭配使用，實施更堅固的品質閘門。 如果您以這種方式使用此活動，使用者會被阻止略過簽入原則。 此活動對下列簽入原則類型最為有用：
內建 Work Items 簽入原則
專為在組建伺服器上評估的自訂簽入原則。
此活動不適用於內建 Builds、Code Analysis 或 Testing Policy 簽入原則，因為您可以使用 MSBuild 和 MSTest 活動，直接在組建中更有效率地執行那些程序。
如需詳細資訊，請參閱下列資源：
如需內建簽入原則的詳細資訊，請參閱加入簽入原則。
如需自訂簽入原則的詳細資訊，請參閱 HOW TO：在 Visual Studio Team Foundation Server 中建立自訂簽入原則 (英文)。
如需閘道簽入組建的詳細資訊，請參閱定義閘道簽入組建來驗證變更
如需私用組建的詳細資訊，請參閱將組建排入佇列
EvaluateCheckInPolicies 引數屬性
- Workspace (Workspace)：您必須指定要評估的工作區。 在大部分情況下，您應該將這個屬性設定為您會在 CreateWorkspace 活動的 Result 屬性中初始化的變數。 如果建立以 DefaultTemplate.xaml 為基礎的建置流程，可能要使用 Workspace 變數。
回到頁首
標示版本控制中的檔案
您可以透過下列 Team Foundation Build 活動標示檔案：
標示所建置的原始程式碼
標示檔案
標示所建置的原始程式碼 (LabelWorkspace 活動)
您應該標示版本控制中的原始程式碼檔，讓小組可以輕鬆地識別指定的已完成組建中所包含之每個檔案的版本。 使用 LabelWorkspace 活動將這個步驟納入建置流程。
LabelWorkspace 引數屬性
Name (String)：您必須指定標籤的名稱。
Child (LabelChildOption)：您可以指定如何處理已經有與指定的標籤相符之標籤的項目。 這個屬性相當於 tf label 命令的 /child 選項。
Workspace (Workspace)：您必須提供此組建之工作區的參考。 在大部分情況下，您應該將這個屬性設定為您會在 CreateWorkspace 活動的 Result 屬性中初始化的變數。 如果建立以 DefaultTemplate.xaml 為基礎的建置流程，可能要使用 Workspace 變數。
Comment (String)：您可以為標籤指定註解。 這個屬性相當於 tf label 命令的 /comment 選項。
Scope (String)：您可以為標籤指定範圍。 這個屬性相當於 tf label 命令的 @scope 引數。
如需 tf label 參數的詳細資訊，請參閱 Label 命令 (Team Foundation 版本控制)。
回到頁首
標示檔案 (LabelSources 活動)
使用 LabelSources 活動標示檔案版本控制中的檔案。
| 秘訣 |
|---|
如果使用 LabelWorkspace 活動，經常可以更有效地標示正在建置的原始程式碼檔。 |
LabelSources 引數屬性
Items (IEnumerable<String>)：您必須指定要標示的項目。 每個 String 相當於 tf label 命令的 itemspec 引數。
Name (String)：您必須指定標籤的名稱。
Scope (String)：您必須為標籤指定範圍。 這個屬性相當於 tf label 命令的 @scope 引數。
Recursion (RecursionType)：如果要標示目錄階層架構中的所有檔案，您可以指定 Microsoft.TeamFoundation.VersionControl.Client.RecursionType.Full。 否則，您可以指定 Microsoft.TeamFoundation.VersionControl.Client.RecursionType.OneLevel。
Version (String)：您必須提供要標示之項目的版本。 這個屬性相當於 tf label 命令的 /version 選項。
Child (LabelChildOption)：您可以指定如何處理已經有與指定的標籤相符之標籤的項目。 這個屬性相當於 tf label 命令的 /child 選項。
Comment (String)：您可以為標籤指定註解。 這個屬性相當於 tf label 命令的 /comment 選項。
如需 tf label 參數的詳細資訊，請參閱 Label 命令 (Team Foundation 版本控制)。
回到頁首
使用工作項目
您可以透過下列 Team Foundation Build 活動使用工作項目：
將變更集和工作項目與組建產生關聯
建立工作項目
建立工作項目 (OpenWorkItem 活動)
使用 OpenWorkItem 活動建立工作項目。
OpenWorkItem Result (WorkItem) 屬性
傳回新的工作項目。
OpenWorkItem 引數屬性
AssignedTo (String)：您必須指定要將工作項目指派給誰。
Title (String)：您必須指定工作項目的標題。
Type (String)：您必須指定工作項目的類型。 一般 Type 值的範例如下：“Bug”、“Issue” 和 “Task”。
Comment (String)：您可以為工作項目的記錄加上註解。
CustomFields (IDictionary<TKey, TValue><String,String>)：您可以指定一個或多個其他工作項目欄位的值。
回到頁首
使用符號資料
您可以透過兩個 Team Foundation Build 活動使用符號資料：IndexSources 和 PublishSymbols。
這兩個活動的典型用法是啟用 IntelliTrace 偵錯。 如果要啟用 IntelliTrace 偵錯，您應該先呼叫 IndexSources 活動準備符號資料，再呼叫 PublishSymbols 活動將資料發行至 SymStore 符號存放區。
如需 IntelliTrace 偵錯的詳細資訊，請參閱使用 IntelliTrace 進行偵錯。
將版本控制路徑和版本嵌入 PDB 檔案中的符號資料 (IndexSources 活動)
使用 IndexSources 活動將版本控制路徑和版本嵌入 .pdb 檔案中的符號資料。
IndexSources 引數屬性
FileList (IEnumerable<String>)：您必須指定每個符號檔的完整路徑和名稱。 您可以使用 FindMatchingFiles 活動提供這個引數。
您可以使用 ** 指定遞迴搜尋。 例如，您可以透過 MatchPattern 屬性中的下列值呼叫 FindMatchingFiles：String.Format("{0}\**\*.pdb", BinariesDirectory)。
回到頁首
將符號發行至 SymStore 符號存放區 (PublishSymbols 活動)
使用 PublishSymbols 活動將 PDB 檔案中的符號資料發行至 SymStore 符號存放區。 此活動其實是 SymStore.exe 上的包裝函式。 如需 SymStore 符號存放區以及如何加以準備的詳細資訊，請參閱發行符號資料。
| 重要事項 |
|---|
如果並行組建嘗試發行至相同的符號檔案共用，資料可能會損毀。 為降低這個風險，您應該只在 SharedResourceScope 活動內呼叫此活動。 |
PublishSymbols Result (String) 屬性
傳回 SymStore.exe 所傳回的異動 ID。
PublishSymbols 引數屬性
FileList (IEnumerable<String>)：您必須指定每個符號檔的完整路徑和名稱。 您可以使用 FindMatchingFiles 活動提供這個引數。
例如，您可以透過 MatchPattern 屬性中的下列值呼叫 FindMatchingFiles：String.Format("{0}\**\*.pdb", BinariesDirectory)。
StorePath (String)：您必須指定 SymStore 符號存放區之根資料夾的 UNC 檔案路徑。
CommandLineArguments (String)：如需可傳遞至 SymStore.exe 的其他引數的詳細資訊，請參閱 SymStore 命令列選項 (英文)。
Comments (String)：您可以指定符號存放區的異動記錄檔中記錄的異動註解。 這個屬性相當於 SymStore.exe 命令的 /c Comment 參數。 如需詳細資訊，請參閱 SymStore (命令列選項) (英文)。
ProductName (String)：您可以指定符號存放區的異動記錄檔中記錄的產品名稱。 例如，您可以將這個屬性設定為可透過呼叫 GetBuildDetail 從 BuildDefinition 屬性取得的組建定義名稱 (Name)。 這個屬性相當於 SymStore.exe 命令的 /t Product 參數。 如需詳細資訊，請參閱 SymStore (命令列選項) (英文)。
StoreCompressed (Boolean)：您可以將這個值設定為 True 表示在符號存放區中會將檔案壓縮存放。 否則，不會將檔案壓縮存放。 這個屬性相當於 SymStore.exe 命令的 /compress 參數。 如需詳細資訊，請參閱 SymStore (命令列選項) (英文)。
Version (String)：例如，例如，您可以將這個屬性設定為可透過呼叫 GetBuildDetail 取得的組建編號 (BuildNumber)。 這個屬性相當於 SymStore.exe 命令的 /v Version 參數。 如需詳細資訊，請參閱 SymStore (命令列選項) (英文)。
回到頁首
取得有用的物件參考
您可以透過 Team Foundation Build 活動取得有用的物件參考。
取得 Team 專案集合的物件參考 (GetTeamProjectCollection 活動)
使用 GetTeamProjectCollection 活動從它的 Result 屬性取得 TfsTeamProjectCollection 物件的參考。 這個起始物件相當重要，例如可用來連接 Team Foundation 的應用程式層伺服器。
取得 IBuildAgent 物件的參考 (GetBuildAgent 活動)
使用 GetBuildAgent 活動從它的 Result 屬性取得 IBuildAgent 物件的參考。 這個活動只能用於 AgentScope 活動內。
取得 IBuildDetail 物件的參考 (GetBuildDetail 活動)
使用 GetBuildDetail 活動從它的 Result 屬性取得 IBuildDetail 物件的參考。 您可以使用這個物件取得 (以及在某些情況下設定) 有關目前組建的資料。
回到頁首
取得 BuildEnvironment 物件的參考 (GetBuildEnvironment 活動)
使用 GetBuildEnvironment 活動透過它的 Result 屬性取得 BuildEnvironment 物件的參考。 您通常會使用這個屬性執行下列工作：
使用 Environment 物件判斷工作流程的目前區段是在組建控制器上執行還是在組建代理程式上執行。
使用 CustomAssemblyPath 物件取得組建代理程式上包含自訂活動之組件的路徑。
回到頁首
不適合在自訂建置流程中重複使用的活動
某些活動並不適合在自訂建置流程中重複使用。
TfsBuild 活動
忽略這個活動。 它只能用於 UpgradeTemplate.xaml。 此活動並不適合在自訂建置流程中重複使用。
CreateWorkspace 活動
您可能永遠不需要建立或修改 CreateWorkspace 活動的執行個體。 如果設計的建置流程需要一個或多個其他工作區，您必須建立自訂活動來達成此目的。
其他工作區活動
建置流程範本可能以 DefaultTemplatate.xaml 使用這些活動的同樣方式來使用它們。 不過，除非開發建立工作區的自訂活動，否則可能永遠都不需要在自訂建置流程範本中建立或修改工作區的執行個體。
DeleteWorkspace
回到頁首
GetWorkspace
回到頁首
RevertWorkspace
回到頁首
SyncWorkspace
回到頁首