共用方式為

在傳統發行管線中使用變數

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

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

與僅能在範本剖析時使用的執行階段參數不同，經典釋出管線中的變數在整個部署過程中都可存取。

在設定工作以在「傳統」發行管線的每個階段部署應用程式時，變數可以幫助您：

  • 簡化自定義：定義一次泛型部署管線，並輕鬆地針對不同的階段進行調整。 例如，使用變數來代表Web部署的連接字串，並視每個階段的需求調整其值。 這些稱為 自定義變數。

  • 利用情境資訊：存取有關發行環境的詳細資訊，例如 階段、成品或執行部署的 代理程式。 例如，您的腳本可能需要建置位置進行下載，或代理程式的工作目錄來建立暫存盤。 這些稱為 預設變數。

注意

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

預設變數

預設變數會將執行內容的基本資訊提供給執行中的工作和腳本。 這些變數可讓您存取其執行所在的 系統、 發行、 階段或 代理程序 詳細數據。

除了 System.Debug 之外，預設變數是只讀的，系統會自動設定其值。

下表說明一些最重要的變數。 若要檢視完整清單，請參閱 檢視所有變數的目前值。

系統變數

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

範例: https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri Team Foundation 集合或 Azure Pipelines 的網址。 從您的腳本或工作中使用此功能，對其他服務（例如建置和版本控制）調用 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
發行.定義名稱 目前版本所屬之發行管線的名稱。

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

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

範例: 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
發布原因 部署的原因。 支援的值為：
ContinuousIntegration - 在組建完成後，版本在持續部署過程中啟動。
Manual - 發行是以手動方式開始的。
None - 尚未指定部署原因。
Schedule - 從排程開始的釋出。
版本.版本描述 發行時提供的文字描述。

範例: 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
釋出.跳過檔案下載 布爾值，指定是否要略過將成品下載至代理程式。

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

範例: fabrikam\_app

發行階段變數

變數名稱 描述
Release.Environments.{階段名稱}.狀態 此版本在指定階段內部署的狀態。

範例: NotStarted

代理程式變數

變數名稱 描述
Agent.Name 作為登記在 代理程式集區 中的代理名稱。 這與計算機名稱可能不同。

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

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

範例: 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
詹金斯： 20170112.1
TFVC： Changeset 3
Git： 38629c964
GitHub：38629c964
Release.Artifacts.{alias}.BuildId 組建識別碼。範例：

Azure Pipelines： 130
詹金斯： 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}。類型 工件來源的類型，例如 Build.Examples

Azure Pipelines： Build
詹金斯： Jenkins
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 釋出.成品.{主要成品別名}.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

使用預設變數

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

您可以直接使用預設變數做為工作的輸入。 例如，若要在 PowerShell 工作中將Release.Artifacts.{Artifact alias}.DefinitionName作為參數傳遞給以 ASPNET4.CI 為別名的工件，您可以使用$(Release.Artifacts.ASPNET4.CI.DefinitionName)。

顯示如何使用預設變數作為自變數的螢幕快照。

若要在您的文稿中使用預設變數，您必須先將 預設變數名稱中的 取代 . 為 _。 例如，若要在 PowerShell 腳本中列印別名為 ASPNET4.CI 的工件的值Release.Artifacts.{Artifact alias}.DefinitionName，請使用$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME。 請注意，原始別名 ASPNET4.CI 會取代為 ASPNET4_CI。

顯示如何在內嵌 PowerShell 腳本中使用預設變數的螢幕快照。

自訂變數

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

  • 變數群組：使用變數群組在專案中的所有定義之間共用值。 當您想要在整個項目內定義、階段和工作使用相同的值，並從單一位置管理它們時，這會很有用。 在管線>庫中定義和管理變數群組。

  • 發行管線變數：使用發行管線變數，在發行管線內的所有階段之間共用值。 這非常適合需要在跨階段和任務中保持一致值的情況，並且可以從單一位置更新它。 在發行管線的 [ 變數 ] 索引標籤中定義和管理這些變數。 在 [管線變數] 頁面中，將 [範圍] 下拉式清單設定為 [發行]，以新增變數。

  • 階段變數：使用階段變數在發行管線的特定階段內共用值。 這對於在不同階段中有所變化但在同一階段內的所有任務中保持一致的數值很有用。 在發行管線的 [ 變數 ] 索引標籤中定義和管理這些變數。 在 [管線變數] 頁面中，將 [範圍] 下拉式清單設定為適當的環境，以便新增變數。

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

  • 避免重複值，這樣可以更輕鬆地透過單一變更來更新所有項目的出現。

  • 防止用戶檢視或修改敏感性值，以保護敏感性值。 若要將變數標示為安全（秘密），請選取 掛鎖 變數旁邊的圖示。

    重要

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

注意

建立自定義變數可以覆寫標準變數。 例如，如果您在 Windows 代理程式上定義自定義 Path 變數，它會覆寫 $env：Path 變數，這可能會導致 PowerShell 無法正常執行。

使用自訂變數

若要在工作中使用自定義變數，請將變數名稱括在括弧中，並在其前面加上 $ 字元。 例如，如果您有名為 adminUserName 的變數，您可以將其目前值插入工作中做為 $(adminUserName)。

注意

連結至相同範圍管線之不同群組的變數（例如作業或階段）可能會發生衝突，導致無法預測的結果。 若要避免這種情況，請確定所有變數群組中的變數都有唯一的名稱。

在腳本中定義和修改變數

若要從文稿定義或修改變量，請使用 task.setvariable 記錄命令。 更新的變數值範圍設定為正在執行的作業，且不會跨作業或階段保存。 請注意，變數名稱會轉換成大寫，並以 “.” 和 “ 取代為 ”_“。

例如，Agent.WorkFolder 會成為 AGENT_WORKFOLDER。

  • 在 Windows 上，用%AGENT_WORKFOLDER%或$env: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)

檢視所有變數的目前值

  1. 選取 管線>發行，然後選取您的發行管線。

  2. 開啟版本摘要視圖，然後選取您有興趣的階段。 在步驟清單中，選擇 [ 初始化作業]。

    顯示初始化作業步驟的螢幕快照。

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

    顯示代理程式所使用變數的螢幕快照。

以偵錯模式執行發行

在發行中啟用偵錯模式可以協助您在發行執行期間顯示更多資訊，從而診斷和解決問題或故障。 您可以針對整個版本啟用偵錯模式，或只針對特定發行階段內的工作啟用偵錯模式。

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

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

  • 或者，建立true，並將此變數群組連結至發行管線。

提示

如果您遇到與 Azure ARM 服務連線相關的錯誤，請參閱 如何：Azure Resource Manager 服務連線疑難排解指引 以了解更多詳情。

相關內容