傳統發行和成品變數
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
傳統發行和成品變數是在整個管線中交換和傳輸數據的便利方式。 每個變數都會儲存為字串,其值可以在管線的執行之間變更。
變數與運行時間參數不同 ,這些參數 僅適用於範本剖析時間。
當您撰寫將應用程式部署至 DevOps CI/CD 程式中每個階段的工作時,變數將協助您:
定義更通用的部署管線一次,然後輕鬆地為每個階段自定義它。 例如,變數可用來代表 Web 部署的 連接字串,而且此變數的值可以從一個階段變更為另一個階段。 這些是 自定義變數。
使用執行部署管線之特定發行、 階段、 成品或 代理程式 之內容的相關信息。 例如,您的腳本可能需要存取組建的位置以下載它,或存取代理程式上的工作目錄,以建立暫存盤。 這些是 預設變數。
預設變數
執行內容的相關信息可供透過預設變數執行工作使用。 您的工作和腳本可以使用這些變數來尋找其執行中系統、發行、階段或代理程式的相關信息。 除了 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腳本中 ASPNET4.CI 別名的成品來源列印成品變數Release.Artifacts.{Artifact alias}.DefinitionName
的值,您可以使用 $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME
。
請注意,成品來源別名 ASPNET4.CI
的原始名稱會取代為 ASPNET4_CI
。
檢視所有變數的目前值
開啟發行摘要的管線檢視,然後選擇您感興趣的階段。 在步驟清單中,選擇 [ 初始化作業]。
這會開啟此步驟的記錄。 向下捲動以查看代理程序針對此作業所使用的值。
以偵錯模式執行發行
藉由執行整個版本,或只執行個別發行階段的工作,在偵錯模式中,在記錄檔中顯示其他資訊。 這可協助您解決問題和失敗。
若要起始整個發行的偵錯模式,請將名為
System.Debug
true
的變數新增至 發行管線的 [變數 ] 索引標籤。若要起始單一階段的偵錯模式,請從階段的快捷方式功能表開啟 [設定階段] 對話框,並將名為
true
System.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)
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應