傳統發行和成品變數

  • 發行項

Azure DevOps Services |Azure DevOps Server 2020 |Azure DevOps Server 2019 |TFS 2018

注意

在 Microsoft Team Foundation Server (TFS) 2018 和舊版中，組建和發行管線稱為定義、執行稱為組建、服務連線稱為服務端點、階段稱為環境，而作業稱為階段。

傳統發行和成品變數是在整個管線中交換和傳輸資料的便利方式。 每個變數都會儲存為字串，而且其值可以在管線的執行之間變更。

變數與執行時間 參數 不同，只能在範本剖析時間使用。

注意

這是涵蓋傳統發行和成品變數的參考文章。 若要瞭解 YAML 管線中的變數，請參閱 使用者定義的變數。 當您從發行管線移轉至 YAML 管線時， Release.* 將不會填入變數。

當您撰寫將應用程式部署至DevOps CI/CD 程式中每個階段的工作時，變數將協助您：

  • 定義更一般的部署管線一次，然後輕鬆地為每個階段自訂。 例如，變數可用來代表 Web 部署的連接字串，而且此變數的值可以從一個階段變更為另一個階段。 這些是 自訂變數。

  • 使用執行部署管線之特定發行、 階段、 成品或 代理程式 內容的相關資訊。 例如，您的腳本可能需要存取組建的位置以下載，或存取代理程式上的工作目錄，以建立暫存檔。 這些是 預設變數。

提示

您可以檢視發行 的所有變數目前值 ，並使用預設變數在 偵錯模式中執行發行。

預設變數

執行內容的相關資訊可供透過預設變數執行工作。 您的工作和腳本可以使用這些變數來尋找它們正在執行之系統、發行、階段或代理程式的相關資訊。 除了 System.Debug之外，這些變數是唯讀的，而且系統會自動設定其值。 下表說明一些最重要的變數。 若要檢視完整清單，請參閱 檢視所有變數的目前值。

系統

變數名稱 描述
System.TeamFoundationServerUri TFS 或Azure Pipelines中服務連線的 URL。 請從腳本或工作使用此腳本或工作來呼叫Azure Pipelines REST API。

範例： https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri Team Foundation 集合或Azure Pipelines的 URL。 請從腳本或工作使用此專案，在其他服務上呼叫 REST API，例如建置和版本控制。

範例： https://dev.azure.com/fabrikam/
System.CollectionId 這個組建或發行所屬集合的識別碼。 TFS 2015 中無法使用。

範例： 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId 目前版本所屬發行管線的識別碼。 TFS 2015 中無法使用。

範例： 1
System.TeamProject 此組建或發行所屬專案的名稱。

範例： Fabrikam
System.TeamProjectId 此組建或發行所屬專案的識別碼。 TFS 2015 中無法使用。

範例： 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory 在發行部署期間下載成品的目錄。 如果需要將成品下載到代理程式，則會在每次部署之前清除目錄。 與 Agent.ReleaseDirectory 和 System.DefaultWorkingDirectory 相同。

範例： C:\agent\_work\r1\a
System.DefaultWorkingDirectory 在發行部署期間下載成品的目錄。 如果需要將成品下載到代理程式，則會在每次部署之前清除目錄。 與 Agent.ReleaseDirectory 和 System.ArtifactsDirectory 相同。

範例： C:\agent\_work\r1\a
System.WorkFolder 此代理程式的工作目錄，其中會針對每個組建或發行建立子資料夾。 與 Agent.RootDirectory 和 Agent.WorkFolder 相同。

範例： C:\agent\_work
System.Debug 這是使用者可 設定 的唯一系統變數。 將此設定為 true，以 在偵錯模式中執行版本 ，以協助尋找錯誤。

範例： true

版本

變數名稱 描述
Release.AttemptNumber 此版本在此階段中部署的次數。 TFS 2015 中無法使用。

範例： 1
Release.DefinitionEnvironmentId 對應發行管線中階段的識別碼。 TFS 2015 中無法使用。

範例： 1
Release.DefinitionId 目前版本所屬發行管線的識別碼。 TFS 2015 中無法使用。

範例： 1
Release.DefinitionName 目前版本所屬的版本管線名稱。

範例： fabrikam-cd
Release.Deployment.RequestedFor 在目前進行中的部署) 啟動 (觸發的身分識別顯示名稱。 TFS 2015 中無法使用。

範例： Mateo Escobedo
Release.Deployment.RequestedForEmail 觸發 (的身分識別電子郵件地址已啟動，) 目前正在進行中的部署。 TFS 2015 中無法使用。

範例： mateo@fabrikam.com
Release.Deployment.RequestedForId 在目前進行中的部署) 啟動 (觸發的身分識別識別碼。 TFS 2015 中無法使用。

範例： 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID 部署的識別碼。 每個作業都是唯一的。

範例： 254
Release.DeployPhaseID 部署執行階段的識別碼。

範例： 127
Release.EnvironmentId 部署目前正在進行中的發行階段實例識別碼。

範例： 276
Release.EnvironmentName 目前正在進行部署的階段名稱。

範例： Dev
Release.EnvironmentUri 部署目前正在進行中的發行階段實例 URI。

範例： vstfs://ReleaseManagement/Environment/276
Release.Environment。{stage-name}.status 階段的部署狀態。

範例： InProgress
Release.PrimaryArtifactSourceAlias 主要成品來源的別名

範例： fabrikam\_web
Release.Reason 部署的原因。 支援的值為：
ContinuousIntegration - 在建置完成後，在持續部署中啟動的版本。
Manual - 手動啟動發行。
None - 尚未指定部署原因。
Scheduled - 從排程開始的版本。
Release.ReleaseDescription 發行時所提供的文字描述。

範例： Critical security patch
Release.ReleaseId 目前發行記錄的識別碼。

範例： 118
Release.ReleaseName 目前版本的名稱。

範例： Release-47
Release.ReleaseUri 目前版本的 URI。

範例： vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL 此版本的 URL。

範例： https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor 觸發發行的身分識別顯示名稱。

範例： Mateo Escobedo
Release.RequestedForEmail 觸發發行的身分識別電子郵件地址。

範例： mateo@fabrikam.com
Release.RequestedForId 觸發發行的身分識別識別碼。

範例： 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload 布林值，指定是否要略過將成品下載至代理程式。

範例： FALSE
Release.TriggeringArtifact.Alias 觸發發行之成品的別名。 當發行排程或手動觸發時，這是空的。

範例： fabrikam\_app

發行階段

變數名稱 描述
Release.Environment。{階段名稱}。地位 在指定階段內部署此版本的狀態。 TFS 2015 中無法使用。

範例： NotStarted

代理程式

變數名稱 描述
Agent.Name 向 代理程式組件區註冊的代理程式名稱。 這與電腦名稱稱可能不同。

範例： fabrikam-agent
Agent.MachineName 代理程式設定所在的電腦名稱稱。

範例： fabrikam-agent
Agent.Version 代理程式軟體的版本。

範例： 2.109.1
Agent.JobName 正在執行的作業名稱，例如發行或組建。

範例： Release
Agent.HomeDirectory 安裝代理程式的資料夾。 此資料夾包含代理程式的程式碼和資源。

範例： C:\agent
Agent.ReleaseDirectory 在發行部署期間下載成品的目錄。 如果需要將成品下載到代理程式，則會在每次部署之前清除目錄。 與 System.ArtifactsDirectory 和 System.DefaultWorkingDirectory 相同。

範例： C:\agent\_work\r1\a
Agent.RootDirectory 此代理程式的工作目錄，其中會針對每個組建或發行建立子資料夾。 與 Agent.WorkFolder 和 System.WorkFolder 相同。

範例： C:\agent\_work
Agent.WorkFolder 此代理程式的工作目錄，其中會針對每個組建或發行建立子資料夾。 與 Agent.RootDirectory 和 System.WorkFolder 相同。

範例： C:\agent\_work
Agent.DeploymentGroupId 代理程式註冊的部署群組識別碼。 這僅適用于部署群組作業。 TFS 2018 Update 1 中無法使用。

範例： 1

一般成品

針對版本中所參考的每個成品，您可以使用下列成品變數。 並非所有變數對於每個成品類型都有意義。 下表列出預設成品變數，並提供它們根據成品類型所擁有值的範例。 如果範例是空的，表示變數不會針對該成品類型填入。

將 {alias} 預留位置取代為您為 成品別名 指定的值，或以針對發行管線產生的預設值取代預留位置。

變數名稱 描述
釋放。Artifacts。{alias}。DefinitionId 組建管線或存放庫的識別碼。

Azure Pipelines範例：1
GitHub範例：fabrikam/asp
釋放。Artifacts。{alias}。DefinitionName 組建管線或存放庫的名稱。

Azure Pipelines範例：fabrikam-ci
TFVC 範例： $/fabrikam
Git 範例： fabrikam
GitHub範例：fabrikam/asp (main)
釋放。Artifacts。{alias}。BuildNumber 組建編號或認可識別碼。

Azure Pipelines範例：20170112.1
Jenkins/TeamCity 範例： 20170112.1
TFVC 範例： Changeset 3
Git 範例： 38629c964
GitHub範例：38629c964
釋放。Artifacts。{alias}。BuildId 組建識別碼。

Azure Pipelines範例：130
Jenkins/TeamCity 範例： 130
GitHub範例：38629c964d21fe405ef830b7d0220966b82c9e11
釋放。Artifacts。{alias}。BuildURI 組建的 URL。

Azure Pipelines範例：vstfs://build-release/Build/130
GitHub範例：https://github.com/fabrikam/asp
釋放。Artifacts。{alias}。SourceBranch 來源所建置之分支的完整路徑和名稱。

Azure Pipelines範例：refs/heads/main
釋放。Artifacts。{alias}。SourceBranchName 只有建立來源的來源分支名稱。

Azure Pipelines範例：main
釋放。Artifacts。{alias}。SourceVersion 已建置的認可。

Azure Pipelines範例：bc0044458ba1d9298cdc649cb5dcf013180706f7
釋放。Artifacts。{alias}。Repository.Provider 從中建置來源的存放庫類型。

Azure Pipelines範例：Git
釋放。Artifacts。{alias}。RequestedForID 觸發組建之帳戶的識別碼。

Azure Pipelines範例：2f435d07-769f-4e46-849d-10d1ab9ba6ab
釋放。Artifacts。{alias}。RequestedFor 要求組建的帳戶名稱。

Azure Pipelines範例：Mateo Escobedo
釋放。Artifacts。{alias}。類型 成品來源的類型，例如 Build。

Azure Pipelines範例：Build
Jenkins 範例： Jenkins
TeamCity 範例： TeamCity
TFVC 範例： TFVC
Git 範例： Git
GitHub範例：GitHub
釋放。Artifacts。{alias}。PullRequest.TargetBranch 作為提取要求目標之分支的完整路徑和名稱。 只有在提取要求流程觸發發行時，才會初始化此變數。

Azure Pipelines範例：refs/heads/main
釋放。Artifacts。{alias}。PullRequest.TargetBranchName 只有屬於提取要求目標的分支名稱。 只有在提取要求流程觸發發行時，才會初始化此變數。

Azure Pipelines範例：main

另請參閱 成品來源別名

主要成品

您會在發行管線中將其中一個成品指定為主要成品。 針對指定的主要成品，Azure Pipelines填入下列變數。

變數名稱 同於
Build.DefinitionId 釋放。Artifacts。{主要成品別名}。DefinitionId
Build.DefinitionName 釋放。Artifacts。{主要成品別名}。DefinitionName
Build.BuildNumber 釋放。Artifacts。{主要成品別名}。BuildNumber
Build.BuildId 釋放。Artifacts。{主要成品別名}。BuildId
Build.BuildURI 釋放。Artifacts。{主要成品別名}。BuildURI
Build.SourceBranch 釋放。Artifacts。{主要成品別名}。SourceBranch
Build.SourceBranchName 釋放。Artifacts。{主要成品別名}。SourceBranchName
Build.SourceVersion 釋放。Artifacts。{主要成品別名}。SourceVersion
Build.Repository.Provider 釋放。Artifacts。{主要成品別名}。Repository.Provider
Build.RequestedForID 釋放。Artifacts。{主要成品別名}。RequestedForID
Build.RequestedFor 釋放。Artifacts。{主要成品別名}。RequestedFor
Build.Type 釋放。Artifacts。{主要成品別名}。類型
Build.PullRequest.TargetBranch 釋放。Artifacts。{主要成品別名}。PullRequest.TargetBranch
Build.PullRequest.TargetBranchName 釋放。Artifacts。{主要成品別名}。PullRequest.TargetBranchName

使用預設變數

您可以使用兩種方式使用預設變數-作為發行管線或腳本中工作的參數。

您可以直接使用預設變數做為工作的輸入。 例如，若要將別名 ASPNET4.CI 至工作的成品來源傳遞 Release.Artifacts.{Artifact alias}.DefinitionName ，您可以使用$(Release.Artifacts.ASPNET4.CI.DefinitionName) 。

Using artifact variables in arguments to a PowerShell Script task

若要在腳本中使用預設變數，您必須先將預設變數名稱中的 取代 . 為 _ 。 例如，若要列印成品來源的成品變數 Release.Artifacts.{Artifact alias}.DefinitionName 值，其別名在 PowerShell 腳本中 ASPNET4.CI ，您可以使用 $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME 。

Using artifact variables in an inline PowerShell script

請注意，成品來源別名 ASPNET4.CI 的原始名稱會取代為 ASPNET4_CI 。

檢視所有變數的目前值

  1. 開啟發行摘要的管線檢視，然後選擇您感興趣的階段。 在步驟清單中，選擇 [ 初始化作業]。

    Opening the log for a release

  2. 這會開啟此步驟的記錄。 向下捲動以查看代理程式為此作業所使用的值。

    Viewing the values of the variables in a release

在偵錯模式中執行發行

藉由執行整個版本或在個別發行階段中執行工作，在偵錯模式中顯示發行時執行和記錄檔中的其他資訊。 這可協助您解決問題和失敗。

  • 若要起始整個版本的偵錯模式，請在發行管線的 [變數] 索引標籤中新增名為 System.Debugtrue 的變數。

  • 若要起始單一階段的偵錯模式，請從階段的快捷方式功能表開啟 [ 設定階段 ] 對話方塊，並將名為 System.Debugtrue 的變數新增至 [ 變數 ] 索引標籤。

  • 或者，建立變數 群組 ，其中包含名為 System.Debug 且具有 值的 true 變數，並將此變數群組連結至發行管線。

提示

如果您收到與 Azure RM 服務連線相關的錯誤，請參閱如何：針對 Azure Resource Manager服務連線進行疑難排解。

自訂變數

您可以在各種範圍定義自訂變數。

  • 使用 變數群組，在專案中的所有定義之間共用值。 當您需要在專案中的所有定義、階段和工作中使用相同的值時，請選擇變數群組，而且您想要能夠在單一位置變更值。 您可以在 [ 程式庫 ] 索引標籤中定義和管理變數群組。

  • 使用 發行管線變數，在所有階段共用值。 當您需要跨發行管線中的所有階段和工作使用相同的值時，請選擇發行管線變數，而且您想要能夠在單一位置變更值。 您可以在發行管線的 [ 變數 ] 索引標籤中定義和管理這些變數。 在 [管線變數] 頁面中，開啟 [範圍] 下拉式清單，然後選取 [發行]。 根據預設，當您新增變數時，它會設定為 [發行範圍]。

  • 使用 階段變數，在一個特定階段內的所有工作之間共用值。 針對不同階段到階段 (的值使用階段層級變數，而且與階段) 中的所有工作相同。 您可以在發行管線的 [ 變數 ] 索引標籤中定義和管理這些變數。 在 [管線變數] 頁面中，開啟 [範圍] 下拉式清單，然後選取必要的階段。 當您新增變數時，請將 [範圍] 設定為適當的環境。

在專案、發行管線和階段範圍中使用自訂變數可協助您：

  • 避免重複值，讓您更輕鬆地將所有出現專案更新為一個作業。

  • 以發行管線使用者無法看到或變更的敏感性值儲存。 選取變數旁的 (掛鎖) 圖示，將組態屬性指定為安全 (秘密) 變數 padlock 。

    重要

    隱藏 (秘密) 變數的值會安全地儲存在伺服器上，而且使用者無法在儲存之後加以檢視。 在部署期間，Azure Pipelines發行服務會在工作參考時解密這些值，並透過安全的 HTTPS 通道將它們傳遞至代理程式。

注意

建立自訂變數可以覆寫標準變數。 例如，PowerShell 路徑 環境變數。 如果您在Windows代理程式上建立自訂 Path 變數，它會覆寫 $env:Path 變數，而且 PowerShell 將無法執行。

使用自訂變數

若要在建置和發行工作中使用自訂變數，只需將變數名稱括在括弧中，並在前面加上 $ 字元。 例如，如果您有名為 adminUserName的變數，您可以將該變數的目前值插入工作的參數中做為 $(adminUserName) 。

注意

連結至相同範圍中管線的不同群組變數 (例如，作業或階段) 將會衝突，而且結果可能會無法預期。 請確定針對所有變數群組的變數使用不同的名稱。

在腳本中定義和修改變數

若要從腳本定義或修改變數，請使用 task.setvariable 記錄命令。 請注意，更新的變數值的範圍限定于正在執行的作業，而且不會流向作業或階段。 變數名稱會轉換成大寫，而字元 「.」 和 「 會取代為 」_」。

例如，Agent.WorkFolder 會成為 AGENT_WORKFOLDER。 在Windows上，您會以 或 $env:AGENT_WORKFOLDER 身分存取此專案 %AGENT_WORKFOLDER% 。 在 Linux 和 macOS 上，您可以使用 $AGENT_WORKFOLDER 。

提示

您可以在下列專案上執行腳本：

Batch 腳本

sauce設定 和 secret.Sauce 變數

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

讀取變數

引數

"$(sauce)" "$(secret.Sauce)"

指令碼

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil
     the secret)

讀取變數的主控台輸出：

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)