傳統發行和成品變數

  • 發行項

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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

變數與運行時間參數不同 ，這些參數 僅適用於範本剖析時間。

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

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

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

注意

如需詳細資訊，請參閱 YAML 管線，請參閱 使用者定義的變數 和 預先定義的變數 。

預設變數

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

提示

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

系統

變數名稱 描述
System.TeamFoundationServerUri 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 這個組建或發行所屬集合的標識碼。

範例: 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId 目前版本所屬發行管線的標識碼。

範例: 1
System.TeamProject 此組建或發行所屬項目的名稱。

範例: Fabrikam
System.TeamProjectId 此組建或發行所屬項目的標識碼。

範例: 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 此版本在此階段中部署的次數。

範例: 1
Release.DefinitionEnvironmentId 對應發行管線中階段的標識碼。

範例: 1
Release.DefinitionId 目前版本所屬發行管線的標識碼。

範例: 1
Release.DefinitionName 目前版本所屬之發行管線的名稱。

範例: fabrikam-cd
Release.Deployment.RequestedFor 目前正在進行中部署之觸發之身分識別的顯示名稱。

範例: Mateo Escobedo
Release.Deployment.RequestedForEmail 目前正在進行中部署之觸發之身分識別的電子郵件位址。

範例: mateo@fabrikam.com
Release.Deployment.RequestedForId 目前正在進行中部署之觸發之身分識別的標識碼。

範例: 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.Environments。{stage-name}.status 階段的部署狀態。

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

範例: fabrikam\_web
Release.Reason 部署的原因。 支援的值為：
ContinuousIntegration - 組建完成之後，於持續部署中啟動的版本。
Manual - 以手動方式啟動版本。
None - 尚未指定部署原因。
Schedule - 從排程開始的版本。
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.Environments。{階段名稱}。地位 此版本在指定階段內部署的狀態。

範例: NotStarted

專員

變數名稱 描述
Agent.Name 以代理程式集區註冊 的代理程序名稱。 這與計算機名稱可能不同。

範例: fabrikam-agent
Agent.MachineName 設定代理程式的計算機名稱。

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

範例: 2.109.1
Agent.JobName 正在執行的作業名稱，例如 Release 或 Build。

範例: 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 代理程式註冊之部署群組的標識碼。 這僅適用於部署群組作業。

範例: 1

一般成品

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

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

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

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

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

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

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

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

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

Azure Pipelines 範例： main
Release.Artifacts。{alias}。SourceVersion 已建立的認可。

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

Azure Pipelines 範例： Git
Release.Artifacts。{alias}。RequestedForID 觸發組建之帳戶的標識碼。

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

Azure Pipelines 範例： Mateo Escobedo
Release.Artifacts。{alias}。類型 成品來源的類型，例如組建。

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

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

Azure Pipelines 範例： main

另 請參閱成品來源別名

主要成品

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

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

使用預設變數

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

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

在自變數中使用成品變數至 PowerShell 腳本工作

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

在內嵌PowerShell腳本中使用成品變數

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

檢視所有變數的目前值

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

    開啟發行的記錄檔

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

    檢視版本中變數的值

以偵錯模式執行發行

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

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

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

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

提示

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

自訂變數

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

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

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

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

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

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

  • 以發行管線的用戶無法看到或變更敏感性值的方式儲存。 選取變數旁的 掛鎖 [掛鎖] 圖示，將組態屬性指定為安全 （secret） 變數。

    重要

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

注意

建立自定義變數可以覆寫標準變數。 例如，PowerShell Path 環境變數。 如果您在 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)