記錄命令

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

記錄命令是工作和腳本與代理程序通訊的方式。 它們涵蓋建立新 變數、將步驟標示為失敗，以及上傳 成品等動作。 當您針對管線進行疑難解答時，記錄命令很有用。

重要

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

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

類型	命令
工作命令	AddAttachment、Complete、LogDetail、LogIssue、PrependPath、SetEndpoint、SetProgress、SetVariable、SetSecret、UploadFile、UploadSummary
成品命令	關聯、 上傳
建置命令	AddBuildTag、 UpdateBuildNumber、 UploadLog
發行命令	UpdateReleaseName

記錄命令格式

記錄命令的一般格式為：

##vso[area.action property1=value;property2=value;...]message

另外還有一些具有稍微不同語法的格式命令：

##[command]message

若要叫用記錄命令，請透過標準輸出回應命令。

Bash

#!/bin/bash
echo "##vso[task.setvariable variable=testvar;]testvalue"

PowerShell

Write-Host "##vso[task.setvariable variable=testvar;]testvalue"

檔案路徑應指定為絕對路徑：根目錄至 Windows 上的磁碟驅動器，或從 Linux 和 macOS 開始 / 。

注意

請注意，當您使用 Linux 或 macOS 時，無法在記錄命令之前使用 set -x 命令。 請參閱 疑難解答，以瞭解如何暫時停用 set -x Bash。

格式化命令

注意

使用UTF-8編碼來記錄命令。

這些命令是 Azure Pipelines 中記錄格式子的訊息。 它們會將特定記錄行標示為錯誤、警告、可折迭區段等等。

格式化命令如下：

##[group]Beginning of a group
##[warning]Warning message
##[error]Error message
##[section]Start of a section
##[debug]Debug text
##[command]Command-line being run
##[endgroup]

您可以在 bash 或 PowerShell 工作中使用格式化命令。

Bash

steps:
- bash: |
    echo "##[group]Beginning of a group"
    echo "##[warning]Warning message"
    echo "##[error]Error message"
    echo "##[section]Start of a section"
    echo "##[debug]Debug text"
    echo "##[command]Command-line being run"
    echo "##[endgroup]"

PowerShell

steps:
- powershell: |
    Write-Host "##[group]Beginning of a group"
    Write-Host "##[warning]Warning message"
    Write-Host "##[error]Error message"
    Write-Host "##[section]Start of a section"
    Write-Host "##[debug]Debug text"
    Write-Host "##[command]Command-line being run"
    Write-Host "##[endgroup]"

這些命令會在記錄中轉譯，如下所示：

該區塊的命令也可以折疊，如下所示：

工作命令

LogIssue：記錄錯誤或警告

##vso[task.logissue]error/warning message

使用方式

在目前工作的時間軸記錄中記錄錯誤或警告訊息。

屬性

• type = error 或 warning （必要）
• sourcepath = 來源檔案位置
• linenumber = 行號
• columnnumber = 欄號
• code = 錯誤或警告碼

範例：記錄錯誤

Bash

#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1

PowerShell

Write-Host "##vso[task.logissue type=error]Something went very wrong."
exit 1

提示

exit 1 是選擇性的，但通常是您在記錄錯誤之後不久就會發出的命令。 如果您選取 [ 控制選項：發生錯誤時繼續]，則 exit 1 會導致部分成功建置，而不是失敗的組建。 或者，您也可以使用 task.logissue type=error。

範例：記錄檔案中特定位置的相關警告

Bash

#!/bin/bash
echo "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

PowerShell

Write-Host "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

SetProgress：顯示已完成的百分比

##vso[task.setprogress]current operation

使用方式

設定目前工作的進度和目前作業。

屬性

• value = 完成百分比

範例

Bash

echo "Begin a lengthy process..."
for i in {0..100..10}
do
   sleep 1
   echo "##vso[task.setprogress value=$i;]Sample Progress Indicator"
done
echo "Lengthy process is complete."

PowerShell

Write-Host "Begin a lengthy process..."
$i=0
While ($i -le 100)
{
   Start-Sleep 1
   Write-Host "##vso[task.setprogress value=$i;]Sample Progress Indicator"
   $i += 10
}
Write-Host "Lengthy process is complete."

若要查看其外觀，請儲存並排入組建佇列，然後監看組建執行。 觀察工作執行此腳本時進度指示器變更。

完成：完成時間軸

##vso[task.complete]current operation

使用方式

完成目前工作的時程表記錄、設定工作結果和目前作業。 未提供結果時，將結果設定為成功。

屬性

• result =
  • Succeeded 工作成功。
  • SucceededWithIssues 工作遇到問題。 建置會以部分成功方式完成。
  • Failed 建置將會因為失敗而完成。 （如果 控制選項：選取 [在錯誤 時繼續] 選項，建置會以部分成功方式完成。

範例

將工作記錄為成功。

##vso[task.complete result=Succeeded;]DONE

將工作設定為失敗。 或者，您也可以使用 exit 1。

- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi

LogDetail：建立或更新工作的時程表記錄

##vso[task.logdetail]current operation

使用方式

建立及更新時程表記錄。 這主要是由 Azure Pipelines 在內部用來報告步驟、作業和階段的相關信息。 雖然客戶可以將專案新增至時程表，但通常不會顯示在UI中。

第一次在步驟期間看到 ##vso[task.detail] 時，我們會建立步驟的「詳細時間軸」記錄。 我們可以根據 id 和 parentid來建立和更新巢狀時程表記錄。

工作作者必須記住用於每個時間軸記錄的 GUID。 記錄系統會追蹤每個時程表記錄的 GUID，因此任何新的 GUID 都會產生新的時程表記錄。

屬性

• id = 時程表記錄 GUID （必要）
• parentid = 父時間軸記錄 GUID
• type = 記錄類型 （第一次需要，無法覆寫）
• name = 記錄名稱 （第一次需要，無法覆寫）
• order = 時間軸記錄的順序（第一次需要，無法覆寫）
• starttime = Datetime
• finishtime = Datetime
• progress = 完成百分比
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

範例

建立新的根時程表紀錄：

##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record

建立新的巢狀時程表記錄：

##vso[task.logdetail id=new guid;parentid=exist timeline record guid;name=project1;type=build;order=1]create new nested timeline record

更新存在時間軸記錄：

##vso[task.logdetail id=existing timeline record guid;progress=15;state=InProgress;]update timeline record

SetVariable：初始化或修改變量的值

##vso[task.setvariable]value

使用方式

在 taskcontext 的變數服務中設定變數。 第一個工作可以設定變數，而下列工作可以使用 變數。 變數會以環境變數的形式公開給下列工作。

當 設定為 true時issecret，變數的值將會儲存為秘密，並從記錄中遮罩。 祕密變數不會以環境變數的形式傳遞至工作，且必須改為傳遞為輸入。

當 isoutput 設定為 true 參考集合變數的語法時，會根據您是否在相同作業、未來作業或未來階段中存取該變數而有所不同。 此外，如果 isoutput 設定為 false 在相同作業內使用該變數的語法，則不同。 請參閱 輸出變數 層級，以判斷每個使用案例的適當語法。

如需詳細資訊，請參閱 在腳本 中設定變數並 定義變數 。

屬性

• variable = 變數名稱 （必要）
• issecret = 布林值 （選擇性，預設值為 false）
• isoutput = 布林值 （選擇性，預設值為 false）
• isreadonly = 布林值 （選擇性，預設值為 false）

範例

Bash

設定變數：

- bash: |
    echo "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
    echo "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods"
  name: SetVars

讀取變數：

- bash: |
    echo "Non-secrets automatically mapped in, sauce is $SAUCE"
    echo "Secrets are not automatically mapped in, secretSauce is $SECRETSAUCE"
    echo "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"

PowerShell

設定變數：

- pwsh: |
    Write-Host "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    Write-Host "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
    Write-Host "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods"
  name: SetVars

讀取變數：

- pwsh: |
    Write-Host "Non-secrets automatically mapped in, sauce is $env:SAUCE"
    Write-Host "Secrets are not automatically mapped in, secretSauce is $env:SECRETSAUCE"
    Write-Host "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"
    Write-Host "Future jobs can also see $env:SETVARS_OUTPUTSAUCE"
    write-Host "Future jobs can also see $(SetVars.outputSauce)"

主控台輸出：

Non-secrets automatically mapped in, sauce is crushed tomatoes
Secrets are not automatically mapped in, secretSauce is 
You can use macro replacement to get secrets, and they'll be masked in the log: ***
Future jobs can also see canned goods
Future jobs can also see canned goods

SetSecret：將值註冊為秘密

##vso[task.setsecret]value

使用方式

此值會在作業期間註冊為秘密。 值會從這一點往前的記錄中遮罩。 當秘密轉換（例如base64編碼）或衍生時，此命令很有用。

注意：先前出現的秘密值將不會遮罩。

範例

Bash

設定變數：

- bash: |
    NEWSECRET=$(echo $OLDSECRET|base64)
    echo "##vso[task.setsecret]$NEWSECRET"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

讀取變數：

- bash: |
    echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)"
  env:
    OLDSECRET: "SeCrEtVaLuE"

PowerShell

設定變數：

- pwsh: |
    $NewSecret = [convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET))
    Write-Host "##vso[task.setsecret]$NewSecret"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

讀取變數：

- pwsh: |
    Write-Host "Transformed and derived secrets will be masked: $([convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET)))"
  env:
    OLDSECRET: "SeCrEtVaLuE"

主控台輸出：

Transformed and derived secrets will be masked: ***

SetEndpoint：修改服務連線欄位

##vso[task.setendpoint]value

使用方式

使用指定的值設定服務連接欄位。 更新的值將會保留在端點中，以供在相同作業內執行的後續工作使用。

屬性

• id = 服務連線識別碼 （必要）
• field = 欄位類型、其中 authParameter一個、 dataParameter或 url （必要）
• key = 索引鍵 （必要，除非 field = url）

範例

##vso[task.setendpoint id=000-0000-0000;field=authParameter;key=AccessToken]testvalue
##vso[task.setendpoint id=000-0000-0000;field=dataParameter;key=userVariable]testvalue
##vso[task.setendpoint id=000-0000-0000;field=url]https://example.com/service

AddAttachment：將檔案附加至組建

##vso[task.addattachment]value

使用方式

將附件上傳並附加至目前的時程表記錄。 這些檔案無法透過記錄下載。 這些只能由使用型別或名稱值的延伸模塊參考。

屬性

• type = 附件型態 （必要）
• name = 附件名稱 （必要）

範例

##vso[task.addattachment type=myattachmenttype;name=myattachmentname;]c:\myattachment.txt

UploadSummary：將一些 Markdown 內容新增至組建摘要

##vso[task.uploadsummary]local file path

使用方式

將摘要 Markdown 從存放庫中的 .md 檔案上傳並附加至目前的時程表記錄。 此摘要應新增至組建/發行摘要，且無法使用記錄進行下載。 摘要應為UTF-8或 ASCII 格式。 摘要會出現在 管線執行的 [延伸模組 ] 索引標籤上。 [延伸模組] 索引標籤上的 Markdown 轉譯與 Azure DevOps Wiki 轉譯不同。

範例

##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md

這是命令的簡短表單

##vso[task.addattachment type=Distributedtask.Core.Summary;name=testsummaryname;]c:\testsummary.md

UploadFile：上傳可使用工作記錄下載的檔案

##vso[task.uploadfile]local file path

使用方式

將感興趣的使用者檔案作為其他記錄資訊上傳至目前的時程表記錄。 檔案應可供下載，以及工作記錄檔。

範例

##vso[task.uploadfile]c:\additionalfile.log

PrependPath：在PATH環境變數的路徑前面加上

##vso[task.prependpath]local file path

使用方式

在PATH前面加上PATH，以更新PATH環境變數。 更新的環境變數將會反映在後續工作中。

範例

##vso[task.prependpath]c:\my\directory\path

成品命令

關聯：初始化成品

##vso[artifact.associate]artifact location

使用方式

建立現有成品的連結。 成品位置必須是檔案容器路徑、VC 路徑或 UNC 共享路徑。

屬性

• artifactname = 成品名稱 （必要）
• type = 成品類型 （必要） container | filepath | versioncontrol | gitref | tfvclabel

範例

• 容器

  ##vso[artifact.associate type=container;artifactname=MyServerDrop]#/1/build
  

• filepath

  ##vso[artifact.associate type=filepath;artifactname=MyFileShareDrop]\\MyShare\MyDropLocation
  

• versioncontrol

  ##vso[artifact.associate type=versioncontrol;artifactname=MyTfvcPath]$/MyTeamProj/MyFolder
  

• gitref

  ##vso[artifact.associate type=gitref;artifactname=MyTag]refs/tags/MyGitTag
  

• tfvclabel

  ##vso[artifact.associate type=tfvclabel;artifactname=MyTag]MyTfvcLabel
  

• 自定義成品

  ##vso[artifact.associate artifactname=myDrop;artifacttype=myartifacttype]https://downloads.visualstudio.com/foo/bar/package.zip
  

上傳：上傳成品

##vso[artifact.upload]local file path

使用方式

將本機檔案上傳至檔案容器資料夾，並選擇性地將成品發佈為 artifactname。

屬性

• containerfolder = 檔案將上傳至的資料夾，視需要建立資料夾。
• artifactname = 成品名稱。 (必要項)

範例

##vso[artifact.upload containerfolder=testresult;artifactname=uploadedresult]c:\testresult.trx

注意

Artifact.associate 和 Artifact.upload 之間的差異在於，第一個可用來建立現有成品的連結，而後者可用來上傳/發佈新的 Artifact。

建置命令

UploadLog：上傳記錄

##vso[build.uploadlog]local file path

使用方式

上傳使用者感興趣的記錄檔，以建置的容器 “logs\tool” 資料夾。

範例

##vso[build.uploadlog]c:\msbuild.log

UpdateBuildNumber：覆寫自動產生的組建編號

##vso[build.updatebuildnumber]build number

使用方式

您可以從管線選項中指定的權杖自動產生組建編號。 不過，如果您想要使用自己的邏輯來設定組建編號，則可以使用此記錄命令。

範例

##vso[build.updatebuildnumber]my-new-build-number

AddBuildTag：將標籤新增至組建

##vso[build.addbuildtag]build tag

使用方式

新增目前組建的標籤。 您可以使用預先定義或使用者定義的變數展開標記。 例如，在這裡，會在Bash工作中新增具有 值 last_scanned-$(currentDate)的新標記。 您無法搭配 AddBuildTag 使用冒號。

範例

- task: Bash@3
    inputs:
    targetType: 'inline'
    script: |
        last_scanned="last_scanned-$(currentDate)"
        echo "##vso[build.addbuildtag]$last_scanned"
    displayName: 'Apply last scanned tag'

發行命令

UpdateReleaseName：重新命名目前的版本

##vso[release.updatereleasename]release name

使用方式

更新執行中版本的發行名稱。

注意

從 2020 版開始，Azure DevOps 和 Azure DevOps Server 支援。

範例

##vso[release.updatereleasename]my-new-release-name