記錄命令

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

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

類型 命令
工作命令 AddAttachmentCompleteLogDetailLogIssuePrependPathSetEndpointSetProgressSetVariableUploadFileUploadSummary
成品命令 關聯上傳
建置命令 AddBuildTagUpdateBuildNumberUploadLog
釋放命令 UpdateReleaseName

記錄命令格式

記錄命令的一般格式為:

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

另外還有一些格式設定命令,語法稍有不同:

##[command]message

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

#!/bin/bash
echo "##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 工作中使用格式化命令。

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]"

這些命令會在記錄中轉譯,如下所示:

具有自訂格式選項的記錄螢幕擷取畫面

該命令區塊也可以折迭,看起來像這樣:

已折迭記錄區段的螢幕擷取畫面

工作命令

LogIssue:記錄錯誤或警告

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

使用量

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

屬性

  • type = errorwarning (必要)
  • sourcepath = 來源檔案位置
  • linenumber = 行號
  • columnnumber = 欄號
  • code = 錯誤或警告碼

範例:記錄錯誤

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

提示

exit 1 是選擇性的,但通常是在記錄錯誤之後,您很快就會發出的命令。 如果您選取 [控制項選項:發生錯誤時繼續],則 exit 1 會導致部分成功建置,而不是失敗的組建。

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

#!/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."

SetProgress:顯示已完成的百分比

##vso[task.setprogress]current operation

使用量

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

屬性

  • value = 完成百分比

範例

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."

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

完成:完成時間軸

##vso[task.complete]current operation

使用量

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

屬性

  • result =
    • Succeeded 工作成功。
    • SucceededWithIssues 工作發生問題。 建置會以部分成功方式完成。
    • Failed 建置將會因為失敗而完成。 (如果選取 [控制選項:在錯誤時繼續] 選項,建置會以部分成功方式完成。)

範例

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

LogDetail:建立或更新工作的時間軸記錄

##vso[task.logdetail]current operation

使用量

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

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

工作作者必須記住它們用於每個時程表記錄的 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 的變數服務中設定變數。 第一個工作可以設定變數,而且下列工作可以使用 變數。 變數會公開給下列工作做為環境變數。

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

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

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

屬性

  • variable = 變數名稱 (必要)
  • issecret = 布林值 (選擇性,預設值為 false)
  • isoutput = 布林值 (選擇性,預設值為 false)
  • isreadonly = 布林值 (選擇性,預設值為 false)
  • variable = 變數名稱 (必要)
  • issecret = 布林值 (選擇性,預設值為 false)
  • isreadonly = 布林值 (選擇性,預設值為 false)

範例

設定變數︰

- 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 "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
  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)"
- 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)"

主控台輸出:

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
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: ***

SetEndpoint:修改服務連線欄位

##vso[task.setendpoint]value

使用量

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

屬性

  • id = 服務連線識別碼 (必要)
  • field = 欄位類型、、 authParameterdataParameterurl (必要)
  • 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 至目前的時程表記錄。 此摘要應新增至組建/發行摘要,且無法使用記錄進行下載。 摘要應為 UTF-8 或 ASCII 格式。 摘要會出現在 [延伸模組] 索引標籤上。

範例

##vso[task.uploadsummary]c:\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

範例

  • container

    ##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 之間的差異在於,第一個可用來建立現有成品的連結,而後者可用來上傳/發佈新的成品。

建置命令

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

使用量

新增目前組建的標記。

範例

##vso[build.addbuildtag]Tag_UnitTestPassed

釋放命令

UpdateReleaseName:重新命名目前版本

##vso[release.updatereleasename]release name

使用量

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

注意

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

範例

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