共用方式為

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

  • 發行項

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 的 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
詹金斯： 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 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

使用預設變數

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

您可以直接使用預設變數做為工作的輸入。 例如，若要將 作為自變數傳遞Release.Artifacts.{Artifact alias}.DefinitionName至具有 ASPNET4.CI 做為其別名之成品的 PowerShell 工作，您可以使用 $(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 上，以 或 $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)

檢視所有變數的目前值

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

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

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

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

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

以偵錯模式執行發行

在偵錯模式中執行發行可協助您診斷和解決問題或失敗，方法是在發行執行期間顯示其他資訊。 您可以針對整個版本啟用偵錯模式，或只針對特定發行階段內的工作啟用偵錯模式。

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

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

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

提示

如果您遇到與 Azure ARM 服務連線相關的錯誤，請參閱 如何：針對 Azure Resource Manager 服務連線 進行疑難解答，以取得詳細數據。

相關內容