定義變數

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

注意

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

變數可讓您輕鬆地將資料的重要部分放入管線的各個部分。 變數最常見的用法是定義您可以在管線中使用的值。 所有變數都會儲存為字串,而且是可變動的。 變數的值可以從執行變更為執行,或從作業變更為管線作業。

當您在多個位置中使用相同的名稱定義相同的變數時,最有本機範圍的變數會優先使用。 因此,在作業層級定義的變數可以覆寫在階段層級設定的變數。 在階段層級定義的變數會覆寫管線根層級設定的變數。 管線根層級中設定的變數將會覆寫管線設定 UI 中的變數集。

您可以使用變數搭配 運算式 來有條件地指派值,並進一步自訂管線。

變數與 執行時間參數不同,這些參數是在範本剖析期間類型和可用的。

使用者定義變數

當您定義變數時,您可以使用 不同的語法 (宏、範本運算式或執行時間) ,以及您使用的語法會決定變數在管線中轉譯的位置。

在 YAML 管線中,您可以在根、階段和作業層級設定變數。 您也可以在 UI 中指定 YAML 管線外部的變數。 當您在 UI 中設定變數時,該變數可以加密並設定為秘密。

使用者定義的變數可以 設定為唯讀。 變數 (範例有 命名限制 :您無法在變數名稱開頭使用 secret) 。

您可以使用 變數群組 ,讓變數可在多個管線之間使用。

您可以使用 範本 來定義一個檔案中多個管線中使用的變數。

系統變數

除了使用者定義的變數之外,Azure Pipelines具有預先定義值的系統變數。 如果您使用 YAML 或傳統組建管線,請參閱 預先定義的變數 ,以取得完整的系統變數清單。 如果您使用傳統發行管線,請參閱 發行變數

當您執行管線時,系統會使用其目前值來設定系統變數。 某些變數會自動設定。 身為管線作者或終端使用者,您可以在管線執行之前變更系統變數的值。

系統變數是唯讀的。

環境變數

環境變數專屬於您所使用的作業系統。 它們會以平臺特定方式插入管線。 格式會對應至環境變數如何針對您的特定腳本平臺進行格式化。

在 UNIX 系統上, (macOS和 Linux) ,環境變數的格式為 $NAME 。 在Windows上,格式適用于 %NAME% 批次和 $env:NAME PowerShell。

系統與使用者定義變數也會插入為平臺的環境變數。 當變數轉換成環境變數時,變數名稱會變成大寫,而句號會變成底線。 例如,變數名稱 any.variable 會變成變數名稱 $ANY_VARIABLE

環境變數有 變數命名限制 , (範例:您無法在變數名稱開頭使用 secret) 。

變數命名限制

使用者定義的和環境變數可以包含字母、數位、 ._ 字元。 請勿使用系統所保留的變數前置詞。 這些是: endpoint 、、 secretinputpath 、 和 securefile 。 任何以這些字串開頭的變數 (不論大小寫) 都不適用於您的工作和腳本。

瞭解變數語法

Azure Pipelines支援三種不同的參考變數方式:宏、範本運算式和運行時程表達式。 每個語法都可用於不同的用途,並有一些限制。

在管線中,範本運算式變數 (${{ variables.var }}) 在執行時間啟動之前,于編譯時期進行處理。 在工作執行之前,宏語法變數 ($(var)) 在執行時間處理。 運行時程表達式 () $[variables.var] 也會在執行時間處理,但專為搭配 條件運算式使用而設計。 當您使用運行時程表達式時,它必須佔用定義的整個右側。

在此範例中,您可以看到範本運算式在更新變數之後仍具有變數的初始值。 宏語法變數的值會更新。 範本運算式值不會變更,因為在工作執行之前,所有範本運算式變數都會在編譯時期進行處理。 相反地,宏語法變數會在每次工作執行之前進行評估。

variables:
- name: one
  value: initialValue 

steps:
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one)
    displayName: First variable pass
  - bash: echo "##vso[task.setvariable variable=one]secondValue"
    displayName: Set new variable value
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one) # outputs secondValue
    displayName: Second variable pass

宏語法變數

大部分的檔範例都會使用宏語法 ($(var)) 。 宏語法的設計目的是為了將變數值插入工作輸入和其他變數中。

在執行時間期間執行工作之前,會先處理具有宏語法的變數。 執行時間會在 範本擴充之後發生。 當系統遇到宏運算式時,它會將運算式取代為變數的內容。 如果沒有該名稱的變數,則宏運算式會保持不變。 例如,如果 $(var) 無法取代, $(var) 將不會由任何專案取代。

宏語法變數保持不變,沒有值,因為 之類的 $() 空值可能表示您正在執行的工作,而且代理程式不應該假設您想要取代該值。 例如,如果您使用 $(foo) 在 Bash 工作中參考變數 foo ,則取代工作輸入中的所有 $() 運算式可能會中斷 Bash 腳本。

巨集變數只有在用於值時才會展開,而不是關鍵字。 值會出現在管線定義的右側。 下列是有效的: key: $(value) 。 下列無效: $(key): value 。 當用來內嵌顯示作業名稱時,不會展開巨集變數。 您必須改用 displayName 屬性。

注意

宏語法變數只會針對 stagesjobssteps 展開。 例如,您無法在 或 trigger 中使用 resource 宏語法。

在此範例中,宏語法會與 Bash、PowerShell 和腳本工作搭配使用。 使用宏語法呼叫變數的語法,這三者都相同。

variables:
 - name: projectName
   value: contoso

steps: 
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)

範本運算式語法

您可以使用範本運算式語法來展開 範本參數 和變數, ${{ variables.var }} () 。 範本變數會在編譯時期處理,並在執行時間啟動之前被取代。 範本運算式是專為重複使用 YAML 部分做為範本而設計。

找不到取代值時,範本變數會以無訊息方式聯合至空字串。 範本運算式與宏和運行時程表達式不同,可以顯示為左側 (索引鍵) 或右邊 (值) 。 下列是有效的: ${{ variables.key }} : ${{ variables.value }}

運行時程表達式語法

您可以將運行時程表達式語法用於執行時間 () $[variables.var] 擴充的變數。 找不到取代值時,運行時程表達式變數會以無訊息方式聯合至空字串。 運行時程表達式的設計目的是要用於作業的條件、支援作業的條件執行或整個階段。

運行時程表達式變數只有在用於值時才會展開,而不是作為關鍵字。 值會出現在管線定義的右側。 下列是有效的: key: $[variables.value] 。 下列無效: $[variables.key]: value 。 運行時程表達式必須佔用索引鍵/值組的整個右側。 例如, key: $[variables.value] 有效,但 key: $[variables.value] foo 無效。

語法 範例 何時處理? 它會在管線定義中展開的位置? 找不到時會如何呈現?
巨集 $(var) 工作執行前的執行時間 值 (右側) 指紋 $(var)
範本運算式 ${{ variables.var }} 編譯時間 索引鍵或值 (左邊或右側) 空字串
運行時程表達式 $[variables.var] 執行階段 值 (右側) 空字串

我應該使用哪一種語法?

如果您要提供工作的輸入,請使用宏語法。

如果您使用 條件 和運算式,請選擇執行時間 運算式。 例外狀況是,如果您有管線會導致空白變數列印出的問題。例如,如果您有依賴具有特定值或無值之變數的條件式邏輯。 在此情況下,您應該使用運行時程表達式。

如果您要在範本中定義變數,請使用範本運算式。

在管線中設定變數

在最常見的案例中,您會設定變數,並在 YAML 檔案中使用它們。 這可讓您追蹤版本控制系統中變數的變更。 您也可以在管線設定 UI 中定義變數, (查看 [傳統] 索引標籤) ,並在您的 YAML 中加以參考。

以下是示範如何設定兩個變數 和 platform 的範例, configuration 稍後在步驟中使用這些變數。 若要在 YAML 語句中使用變數,請將它包裝在 中 $() 。 變數不能用來在 YAML 語句中定義 repository

# Set variables once
variables:
  configuration: debug
  platform: x64

steps:

# Use them once
- task: MSBuild@1
  inputs:
    solution: solution1.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

# Use them again
- task: MSBuild@1
  inputs:
    solution: solution2.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

變數範圍

在 YAML 檔案中,您可以在各種範圍設定變數:

  • 在根層級,讓它可供管線中的所有作業使用。
  • 在階段層級,使其僅適用于特定階段。
  • 在作業層級,使其僅適用于特定作業。

在 YAML 頂端定義變數時,管線中的所有作業和階段都可以使用變數,而且是全域變數。 YAML 中定義的全域變數不會顯示在管線設定 UI 中。

作業層級的變數會覆寫根層級和階段層級的變數。 階段層級的變數會覆寫根層級的變數。

variables:
  global_variable: value    # this is available to all jobs

jobs:
- job: job1
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable1: value1    # this is only available in job1
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable1)
  - bash: echo $JOB_VARIABLE1 # variables are available in the script environment too

- job: job2
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable2: value2    # this is only available in job2
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable2)
  - bash: echo $GLOBAL_VARIABLE

這兩個作業的輸出看起來像這樣:

# job1
value 
value1
value1

# job2
value
value2
value

指定變數

在上述範例中 variables ,關鍵字後面接著索引鍵/值組的清單。 索引鍵是變數名稱,而值是變數值。

當您想要使用 變數範本變數群組時,還有另一個語法很有用。 此語法應該在管線的根層級使用。

在此替代語法中 variables ,關鍵字會採用變數規範的清單。 變數規範適用于 name 一般變數、 group 變數群組,以及 template 包含變數範本。 下列範例示範這三個。

variables:
# a regular variable
- name: myvariable
  value: myvalue
# a variable group
- group: myvariablegroup
# a reference to a variable template
- template: myvariabletemplate.yml

深入瞭解 使用範本重複使用變數

透過環境存取變數

請注意,變數也可透過環境變數提供給腳本使用。 使用這些環境變數的語法取決於指令碼語言。

名稱為大寫,並以 . 取代 _ 。 這會自動插入進程環境。 以下是一些範例:

  • Batch腳本:%VARIABLE_NAME%
  • PowerShell 腳本: $env:VARIABLE_NAME
  • Bash 腳本: $VARIABLE_NAME

重要

包含檔案路徑的預先定義變數會根據代理程式主機類型和殼層類型,轉譯為適當的樣式 (Windows樣式 C:\foo\ 與 Unix 樣式 /foo/) 。 如果您在Windows上執行 bash 腳本工作,您應該使用環境變數方法來存取這些變數,而不是管線變數方法,以確保您擁有正確的檔案路徑樣式。

TFS 不支援 YAML。

設定秘密變數

請勿在 YAML 檔案中設定秘密變數。 作業系統通常會記錄它們執行之進程的命令,而且您不希望記錄檔包含您以輸入方式傳入的秘密。 使用腳本的環境,或將 區塊內的 variables 變數對應至管線。

您必須在管線的管線設定 UI 中設定秘密變數。 這些變數的範圍限定于您設定它們的管線。 您也可以 在變數群組中設定秘密變數

若要在 Web 介面中設定秘密,請遵循下列步驟:

  1. 前往 [管線] 頁面,選取適當的管線,然後選取 [編輯]。
  2. 找出此管線的 [變數]。
  3. 新增或更新變數。
  4. 選取 Secret 鎖定圖示,以加密方式儲存變數。
  5. 儲存管線。

秘密變數會使用 2048 位 RSA 金鑰來加密待用變數。 代理程式上有可用的秘密,可供工作和腳本使用。 請留意誰有權改變您的管線。

重要

我們會努力遮罩秘密,使其無法出現在Azure Pipelines輸出中,但您仍然需要採取預防措施。 永不回應秘密作為輸出。 某些作業系統會記錄命令列引數。 永遠不要在命令列上傳遞秘密。 相反地,我們建議您將秘密對應至環境變數。

我們絕不會遮罩秘密的子字串。 例如,如果 「abc123」 設定為秘密,則 「abc」 不會從記錄中遮罩。 這是為了避免在層級太細微地遮罩秘密,使記錄無法讀取。 因此,秘密不應包含結構化資料。 例如,如果 「{ 」foo「: 」bar「 }」 設定為秘密,則 「bar」 不會從記錄中遮罩。

不同于一般變數,它們不會自動解密為腳本的環境變數。 您必須明確對應秘密變數。

下列範例示範如何使用 PowerShell 和 Bash 腳本中稱為 mySecret 的秘密變數。 不同于一般管線變數,沒有稱為 的 MYSECRET 環境變數。

variables:
 GLOBAL_MYSECRET: $(mySecret) # this will not work because the secret variable needs to be mapped as env
 GLOBAL_MY_MAPPED_ENV_VAR: $(nonSecretVariable) # this works because it's not a secret.

steps:

- powershell: |
    Write-Host "Using an input-macro works: $(mySecret)"
    Write-Host "Using the env var directly does not work: $env:MYSECRET"
    Write-Host "Using a global secret var mapped in the pipeline does not work either: $env:GLOBAL_MYSECRET"
    Write-Host "Using a global non-secret var mapped in the pipeline works: $env:GLOBAL_MY_MAPPED_ENV_VAR" 
    Write-Host "Using the mapped env var for this task works and is recommended: $env:MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

- bash: |
    echo "Using an input-macro works: $(mySecret)"
    echo "Using the env var directly does not work: $MYSECRET"
    echo "Using a global secret var mapped in the pipeline does not work either: $GLOBAL_MYSECRET"
    echo "Using a global non-secret var mapped in the pipeline works: $GLOBAL_MY_MAPPED_ENV_VAR" 
    echo "Using the mapped env var for this task works and is recommended: $MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable


上述腳本中這兩個工作的輸出看起來會像這樣:

Using an input-macro works: ***
Using the env var directly does not work:
Using a global secret var mapped in the pipeline does not work either:
Using a global non-secret var mapped in the pipeline works: foo
Using the mapped env var for this task works and is recommended: ***

您也可以在腳本外部使用秘密變數。 例如,您可以使用定義,將秘密變數對應至工作 variables 。 此範例示範如何在 Azure 檔案複製工作中使用秘密變數 $(vmsUser)$(vmsAdminPass)

variables:
  VMS_USER: $(vmsUser)
  VMS_PASS: $(vmsAdminPass)

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureFileCopy@4
  inputs:
    SourcePath: 'my/path'
    azureSubscription: 'my-subscription'
    Destination: 'AzureVMs'
    storage: 'my-storage'
    resourceGroup: 'my-rg'
    vmsAdminUserName: $(VMS_USER)
    vmsAdminPassword: $(VMS_PASS)

參考變數群組中的秘密變數

此範例示範如何在 YAML 檔案中參考變數群組,並在 YAML 中新增變數。 變數群組使用兩個變數: usertoken 。 變數 token 是秘密,而且會對應至環境變數 $env:MY_MAPPED_TOKEN ,以便在 YAML 中參考它。

此 YAML 會進行 REST 呼叫以擷取版本清單,並輸出結果。

variables: 
- group: 'my-var-group' # variable group
- name: 'devopsAccount' # new variable defined in YAML
  value: 'contoso'
- name: 'projectName' # new variable defined in YAML
  value: 'contosoads'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
        # Encode the Personal Access Token (PAT)
        # $env:USER is a normal variable in the variable group
        # $env:MY_MAPPED_TOKEN is a mapped secret variable
        $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $env:USER,$env:MY_MAPPED_TOKEN)))

        # Get a list of releases
        $uri = "https://vsrm.dev.azure.com/$(devopsAccount)/$(projectName)/_apis/release/releases?api-version=5.1"

        # Invoke the REST call
        $result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

        # Output releases in JSON
        Write-Host $result.value
  env:
    MY_MAPPED_TOKEN: $(token) # Maps the secret variable $(token) from my-var-group

重要

根據預設,GitHub存放庫,不會提供與管線相關聯的秘密變數來提取分叉的要求組建。 如需詳細資訊,請參閱 分叉的貢獻

TFS 不支援 YAML。

跨管線共用變數

若要在專案中跨多個管線共用變數,請使用 Web 介面。 在 [程式庫] 下,使用 變數群組

使用來自工作的輸出變數

某些工作會定義輸出變數,您可以在下游步驟、作業和階段中使用。 在 YAML 中,您可以使用相 依性,跨作業和階段存取變數。

某些工作會定義輸出變數,您可以在相同階段內的下游步驟和作業中取用。 在 YAML 中,您可以使用相 依性來存取作業之間的變數。

某些工作會定義輸出變數,您可以在相同作業內的下游步驟中取用。

  • 若要從相同作業內的不同工作參考變數,請使用 TASK.VARIABLE
  • 若要從不同作業的工作參考變數,請使用 dependencies.JOB.outputs['TASK.VARIABLE']

注意

根據預設,管線中的每個階段都相依于 YAML 檔案中的階段之前。 如果您需要參考目前階段之前的階段,您可以將區段新增 dependsOn 至階段,以覆寫此自動預設值。

注意

下列範例使用標準管線語法。 如果您使用部署管線,變數和條件變數語法將會有所不同。 如需要使用的特定語法的相關資訊,請參閱 部署作業

在這些範例中,假設我們有一個名為 MyTask 的工作,它會設定名為 的 MyVar 輸出變數。 深入瞭解 運算式 - 相依性中的語法。

在相同的作業中使用輸出

steps:
- task: MyTask@1  # this step generates the output variable
  name: ProduceVar  # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable

在不同的作業中使用輸出

jobs:
- job: A
  steps:
  # assume that MyTask generates an output variable called "MyVar"
  # (you would learn that from the task's documentation)
  - task: MyTask@1
    name: ProduceVar  # because we're going to depend on it, we need to name the step
- job: B
  dependsOn: A
  variables:
    # map the output variable from A into this job
    varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
  steps:
  - script: echo $(varFromA) # this step uses the mapped-in variable

在不同的階段中使用輸出

若要在作業層級使用不同階段的輸出,請使用 stageDependencies 語法:

  • 在階段層級,從不同階段參考變數的格式為 dependencies.STAGE.outputs['JOB.TASK.VARIABLE']
  • 在作業層級,從不同階段參考變數的格式為 stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE']
stages:
- stage: One
  jobs:
  - job: A
    steps:
    - task: MyTask@1  # this step generates the output variable
      name: ProduceVar  # because we're going to depend on it, we need to name the step
- stage: Two
  jobs:
  - job: B
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

您也可以使用檔案輸入在階段之間傳遞變數。 若要這樣做,您必須在作業層級的第二個階段定義變數,然後將變數當做 env: 輸入傳遞。

## script-a.sh
echo "##vso[task.setvariable variable=sauce;isOutput=true]crushed tomatoes"
## script-b.sh
echo 'Hello file version'
echo $skipMe
echo $StageSauce
## azure-pipelines.yml
stages:

- stage: one
  jobs:
  - job: A
    steps:
    - task: Bash@3
      inputs:
          filePath: 'script-a.sh'
      name: setvar
    - bash: |
       echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]true"
      name: skipstep

- stage: two
  jobs:
  - job: B
    variables:
      - name: StageSauce
        value: $[ stageDependencies.one.A.outputs['setvar.sauce'] ]
      - name: skipMe
        value: $[ stageDependencies.one.A.outputs['skipstep.skipsubsequent'] ]
    steps:
    - task: Bash@3
      inputs:
        filePath: 'script-b.sh'
      name: fileversion
      env:
        StageSauce: $(StageSauce) # predefined in variables section
        skipMe: $(skipMe) # predefined in variables section
    - task: Bash@3
      inputs:
        targetType: 'inline'
        script: |
          echo 'Hello inline version'
          echo $(skipMe) 
          echo $(StageSauce) 

上述管線中階段的輸出如下所示:

Hello inline version
true
crushed tomatoes

列出變數

您可以使用 az pipelines variable list 命令,列出管線中的所有變數。 若要開始使用,請參閱使用 Azure DevOps CLI 開始

az pipelines variable list [--org]
                           [--pipeline-id]
                           [--pipeline-name]
                           [--project]

參數

  • 組織:Azure DevOps組織 URL。 您可以使用 來設定預設組織 az devops configure -d organization=ORG_URL 。 如果未設定為預設或使用 挑選 git config ,則為必要專案。 範例: --org https://dev.azure.com/MyOrganizationName/.
  • pipeline-id:如果未提供 pipeline-name ,則為必要專案。 管線的識別碼。
  • pipeline-name:如果未提供 pipeline-id ,則為必要專案,但如果提供 pipeline-id ,則會予以忽略。 管線的名稱。
  • 專案:專案的名稱或識別碼。 您可以使用 來設定預設專案 az devops configure -d project=NAME_OR_ID 。 如果未設定為預設或使用 git config 來挑選,則為必要專案。

範例

下列命令會列出管線中識別碼 為 12 的所有變數,並以資料表格式顯示結果。

az pipelines variable list --pipeline-id 12 --output table

Name           Allow Override    Is Secret    Value
-------------  ----------------  -----------  ------------
MyVariable     False             False        platform
NextVariable   False             True         platform
Configuration  False             False        config.debug

在腳本中設定變數

管線中的腳本可以定義變數,以便由管線中的其中一個後續步驟取用。 這個方法設定的所有變數都會被視為字串。 若要從腳本設定變數,您可以使用命令語法並列印至 stdout。

從腳本設定作業範圍的變數

若要從腳本設定變數,請使用 task.setvariable記錄命令。 這會更新後續作業的環境變數。 後續作業將可透過宏語法和工作中的 宏語法 來存取新的變數,做為環境變數。

當 設定為 true 時 issecret ,變數的值將會儲存為秘密,並從記錄中遮罩。 如需秘密變數的詳細資訊,請參閱 記錄命令

steps:
# Create a variable
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes" # remember to use double quotes

# Use the variable
# "$(sauce)" is replaced by the contents of the `sauce` variable by Azure Pipelines
# before handing the body of the script to the shell.
- bash: |
    echo my pipeline variable is $(sauce)

後續步驟也會將管線變數新增至其環境。 您無法在已定義的步驟中使用 變數。

steps:
# Create a variable
# Note that this does not update the environment of the current script.
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes"

# An environment variable called `SAUCE` has been added to all downstream steps
- bash: |
    echo "my environment variable is $SAUCE"
- pwsh: |
    Write-Host "my environment variable is $env:SAUCE"

上述管線的輸出。

my environment variable is crushed tomatoes
my environment variable is crushed tomatoes

設定多作業輸出變數

如果您想要讓變數可供未來的作業使用,您必須使用 isOutput=true 將其標示為輸出變數。 然後,您可以使用 語法將它對應至未來的作業 $[] ,並包含設定變數的步驟名稱。 多作業輸出變數僅適用于相同階段中的作業。

若要在不同的階段將變數傳遞至作業,請使用 階段相依性 語法。

注意

根據預設,管線中的每個階段都相依于 YAML 檔案中的階段之前。 因此,每個階段都可以使用先前階段的輸出變數。 若要存取進一步階段,您必須改變相依性圖形,例如,如果階段 3 需要階段 1 的變數,您必須在階段 1 上宣告明確的相依性。

當您建立多作業輸出變數時,應該將運算式指派給變數。 在此 YAML 中, $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] 會指派給變數 $(myVarFromJobA)

jobs:
# Set an output variable from job A
- job: A
  pool:
    vmImage: 'windows-latest'
  steps:
  - powershell: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable into job B
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromJobA: $[ dependencies.A.outputs['setvarStep.myOutputVar'] ]  # map in the variable
                                                                          # remember, expressions require single quotes
  steps:
  - script: echo $(myVarFromJobA)
    name: echovar

上述管線的輸出。

this is the value
this is the value

如果您要將變數從一個階段設定為另一個階段,請使用 stageDependencies

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=myStageOutputVar;isOutput=true]this is a stage output var"
       name: printvar

- stage: B
  dependsOn: A
  variables:
    myVarfromStageA: $[ stageDependencies.A.A1.outputs['printvar.myStageOutputVar'] ]
  jobs:
  - job: B1
    steps:
    - script: echo $(myVarfromStageA)

如果您要從 矩陣配量設定變數,則在從下游作業存取變數時,若要參考變數,您必須包含:

  • 作業的名稱。
  • 步驟。
jobs:

# Set an output variable from a job with a matrix
- job: A
  pool:
    vmImage: 'ubuntu-18.04'
  strategy:
    maxParallel: 2
    matrix:
      debugJob:
        configuration: debug
        platform: x64
      releaseJob:
        configuration: release
        platform: x64
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the $(configuration) value"
    name: setvarStep
  - bash: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the debug job
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromJobADebug: $[ dependencies.A.outputs['debugJob.setvarStep.myOutputVar'] ]
  steps:
  - script: echo $(myVarFromJobADebug)
    name: echovar
jobs:

# Set an output variable from a job with slicing
- job: A
  pool:
    vmImage: 'ubuntu-18.04'
    parallel: 2 # Two slices
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the slice $(system.jobPositionInPhase) value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ]
  steps:
  - script: "echo $(myVarFromJobsA1)"
    name: echovar

請務必在作業名稱前面加上 部署 作業的輸出變數。 在此情況下,作業名稱為 A

jobs:

# Set an output variable from a deployment
- deployment: A
  pool:
    vmImage: 'ubuntu-18.04'
  environment: staging
  strategy:
    runOnce:
      deploy:
        steps:
        - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the deployment variable value"
          name: setvarStep
        - bash: echo $(setvarStep.myOutputVar)
          name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-18.04'
  variables:
    myVarFromDeploymentJob: $[ dependencies.A.outputs['A.setvarStep.myOutputVar'] ]
  steps:
  - bash: "echo $(myVarFromDeploymentJob)"
    name: echovar

TFS 不支援 YAML。

使用運算式設定變數

您可以使用運算式來設定變數。 我們已遇到這種情況的其中一個案例,將變數設定為上一個作業中另一個的輸出。

- job: B
  dependsOn: A
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ] # remember to use single quotes

您可以使用任何支援的運算式來設定變數。 以下是將變數設定為以 100 開始的計數器、針對每次執行遞增 1 的計數器,以及每天重設為 100 的範例。

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

如需計數器、相依性和其他運算式的詳細資訊,請參閱 運算式

TFS 不支援 YAML。

設定步驟的可設定變數

您可以在步驟中定義 settableVariables ,或指定無法設定任何變數。

在此範例中,腳本無法設定變數。

steps:
- script: echo This is a step
  target:
    settableVariables: none

在此範例中,腳本允許變數 sauce ,但不允許變數 secretSauce 。 您會在管線執行頁面上看到警告。

Warning that you cannot set secretSauce.

steps:
  - bash: |
      echo "##vso[task.setvariable variable=Sauce;]crushed tomatoes"
      echo "##vso[task.setvariable variable=secretSauce;]crushed tomatoes with garlic"
    target:
     settableVariables:
      - sauce
    name: SetVars
  - bash: 
      echo "Sauce is $(sauce)"
      echo "secretSauce is $(secretSauce)"
    name: OutputVars

允許在佇列時間

如果變數出現在 YAML 檔案的 區塊中 variables ,其值是固定的,而且無法在佇列時覆寫。 最佳做法是在 YAML 檔案中定義變數,但有時候這並不合理。 例如,您可能想要定義秘密變數,而不會在 YAML 中公開變數。 或者,您可能需要在管線執行期間手動設定變數值。

您有兩個選項可用來定義佇列時間值。 您可以在 UI 中定義變數,並選取 [ 讓使用者在執行此管線時覆寫此值 ] 選項,或者您可以改用 執行時間參數 。 如果您的變數不是秘密,最佳做法是使用 執行時間參數

若要在佇列時間設定變數,請在管線內新增變數,然後選取覆寫選項。

Set a variable at queue time.

若要允許在佇列時間設定變數,請確定變數不會同時出現在管線或作業的區塊中 variables 。 如果您在 YAML 和 UI 的 variables 區塊中定義變數,YAML 中的值將具有優先順序。

TFS 不支援 YAML。

變數的擴充

當您在多個範圍中設定具有相同名稱的變數時,下列優先順序會先套用 (最高優先順序) 。

  1. YAML 檔案中設定的作業層級變數
  2. YAML 檔案中設定的階段層級變數
  3. YAML 檔案中設定的管線層級變數
  4. 在佇列時間設定的變數
  5. 管線設定 UI 中設定的管線變數

在下列範例中,相同的變數 a 是在 YAML 檔案中的管線層級和作業層級設定。 它也會設定在變數群組 G 中,並在管線設定 UI 中設定為變數。

variables:
  a: 'pipeline yaml'

stages:
- stage: one
  displayName: one
  variables:
  - name: a
    value: 'stage yaml'

  jobs:
  - job: A
    variables:
    - name: a
      value: 'job yaml'
    steps:
    - bash: echo $(a)        # This will be 'job yaml'

當您在相同範圍中設定具有相同名稱的變數時,最後一個設定的值會優先。

stages:
- stage: one
  displayName: Stage One
  variables: 
    - name: a
      value: alpha
    - name: a
      value: beta
  jobs: 
  - job: I
    displayName: Job I
    variables:
      - name: b
        value: uno
      - name: b
        value: dos
    steps: 
    - script: echo $(a) #outputs beta
    - script: echo $(b) #outputs dos

注意

當您在 YAML 檔案中設定變數時,請勿在 Web 編輯器中將其定義為可在佇列時設定。 您目前無法在佇列時變更 YAML 檔案中設定的變數。 如果您需要在佇列時設定變數,請勿在 YAML 檔案中設定變數。

啟動執行時,變數會展開一次,然後在每個步驟的開頭再次展開。 例如:

jobs:
- job: A
  variables:
    a: 10
  steps:
  - bash: |
      echo $(a)            # This will be 10
      echo '##vso[task.setvariable variable=a]20'
      echo $(a)            # This will also be 10, since the expansion of $(a) happens before the step
  - bash: echo $(a)        # This will be 20, since the variables are expanded just before the step

上述範例中有兩個步驟。 的展開 $(a) 會在作業開始時發生一次,一次是在兩個步驟的開頭進行。

因為變數會在作業開始時展開,所以您無法在策略中使用變數。 在下列範例中,您無法使用 變數 a 來展開作業矩陣,因為變數只能在每個展開作業的開頭使用。

jobs:
- job: A
  variables:
    a: 10
  strategy:
    matrix:
      x:
        some_variable: $(a)    # This does not work

如果變數 a 是先前作業的輸出變數,您可以在未來的作業中使用它。

- job: A
  steps:
  - powershell: echo "##vso[task.setvariable variable=a;isOutput=true]10"
    name: a_step

# Map the variable into job B
- job: B
  dependsOn: A
  variables:
    some_variable: $[ dependencies.A.outputs['a_step.a'] ]

遞迴展開

在代理程式上,使用 $( ) 語法參考的變數會以遞迴方式展開。 例如:

variables:
  myInner: someValue
  myOuter: $(myInner)

steps:
- script: echo $(myOuter)  # prints "someValue"
  displayName: Variable is $(myOuter)  # display name is "Variable is someValue"

TFS 不支援 YAML。