管線裝飾項目表達式內容

文章
02/27/2024

Azure DevOps Services

管線裝飾專案可以存取其執行所在的管線內容。身為管線裝飾專案作者，您可以使用此內容來決定裝飾項目的行為。內容中可用的信息與管線和發行不同。此外，裝飾專案會在工作名稱解析為全域唯一標識碼（GUID）之後執行。當您的裝飾專案想要參考工作時，它應該使用 GUID，而不是名稱或關鍵詞。

提示

請參閱使用 Azure DevOps 擴充功能 SDK 進行擴充功能開發的最新檔。

資源

管線資源可在物件上使用 resources 。

儲存機制

目前只有一個索引鍵： repositories。 repositories 是從存放庫標識碼到存放庫相關信息的對應。

在設計工具組建中，主要存放庫別名為 __designer_repo。在 YAML 管線中，主要存放庫稱為 self。在發行管線中，存放庫無法使用。版本成品變數可供使用。

例如，若要在 YAML 管線中列印存放庫的名稱 self ：

steps:
- script: echo ${{ resources.repositories['self'].name }}

存放函式庫包含下列屬性：

resources['repositories']['self'] =
{
	"alias": "self",
	"id": "<repo guid>",
	"type": "Git",
	"version": "<commit hash>",
	"name": "<repo name>",
	"project": "<project guid>",
	"defaultBranch": "<default ref of repo, like 'refs/heads/main'>",
	"ref": "<current pipeline ref, like 'refs/heads/topic'>",
	"versionInfo": {
		"author": "<author of tip commit>",
		"message": "<commit message of tip commit>"
	},
	"checkoutOptions": {}
}

工作 (Job)

可在物件上使用 job 作業詳細數據。

資料看起來類似：

job = 
{
	"steps": [
		{
			"environment": null,
			"inputs": {
				"script": "echo hi"
			},
			"type": "Task",
			"task": {
				"id": "d9bafed4-0b18-4f58-968d-86655b4d2ce9",
				"name": "CmdLine",
				"version": "2.146.1"
			},
			"condition": null,
			"continueOnError": false,
			"timeoutInMinutes": 0,
			"id": "5c09f0b5-9bc3-401f-8cfb-09c716403f48",
			"name": "CmdLine",
			"displayName": "CmdLine",
			"enabled": true
		}
	]
}

例如，只有在工作不存在時，才有條件地新增工作：

- ${{ if not(containsValue(job.steps.*.task.id, 'f3ab91e7-bed6-436a-b651-399a66fe6c2a')) }}:
  - script: echo conditionally inserted

變數

您也可以使用管線變數。

例如，如果管線有一個稱為myVar的變數，其值就可供裝飾專案使用。variables['myVar']

例如，若要為裝飾專案提供退出，我們可以尋找變數。想要退出裝飾專案的管線作者可以設定此變數，而且不會插入裝飾專案。如果變數不存在，則會如往常插入裝飾專案。

my-decorator.yml

- ${{ if ne(variables['skipInjecting'], 'true') }}:
  - script: echo Injected the decorator

然後，在組織中的管線中，作者可以要求裝飾專案不要插入本身。

pipeline-with-opt-out.yml

variables:
  skipInjecting: true
steps:
- script: echo This is the only step. No decorator is added.

工作名稱和 GUID

裝飾專案會在工作已變成 GUID 之後執行。請考慮下列 YAML：

steps:
- checkout: self
- bash: echo This is the Bash task
- task: PowerShell@2
  inputs:
    targetType: inline
    script: Write-Host This is the PowerShell task

每個步驟都會對應至工作。每個工作都有唯一的 GUID。工作名稱和關鍵詞會在裝飾項目執行之前對應至工作 GUID。如果裝飾專案想要檢查另一個工作是否存在，它必須依工作 GUID 搜尋，而不是依名稱或關鍵詞搜尋。

針對一般工作（使用關鍵詞指定 task ），您可以查看 task.json 工作的來判斷其 GUID。針對如和 bash 在上一個範例中的特殊checkout關鍵詞，您可以使用下列 GUID：

關鍵字	GUID	工作名稱
`checkout`	`6D15AF64-176C-496D-B583-FD2AE21D4DF4`	n/a，請參閱附註
`bash`	`6C731C3C-3C68-459A-A5C9-BDE6E6595B5B`	Bash
`script`	`D9BAFED4-0B18-4F58-968D-86655B4D2CE9`	CmdLine
`powershell`	`E213FF0F-5D5C-4791-802D-52EA3E7BE1F1`	PowerShell
`pwsh`	`E213FF0F-5D5C-4791-802D-52EA3E7BE1F1`	PowerShell
`publish`	`ECDC45F6-832D-4AD9-B52B-EE49E94659BE`	PublishPipelineArtifact
`download`	`30f35852-3f7e-4c0c-9a88-e127b4f97211`	DownloadPipelineArtifact

在工作名稱和關鍵詞解析之後，先前的 YAML 會變成：

steps:
- task: 6D15AF64-176C-496D-B583-FD2AE21D4DF4@1
  inputs:
    repository: self
- task: 6C731C3C-3C68-459A-A5C9-BDE6E6595B5B@3
  inputs:
    targetType: inline
    script: echo This is the Bash task
- task: E213FF0F-5D5C-4791-802D-52EA3E7BE1F1@2
  inputs:
    targetType: inline
    script: Write-Host This is the PowerShell task

提示

您可以針對對應的內建工作，在中找到task.json上述每個 GUID。唯一的例外狀況是 checkout，這是代理程式的原生功能。其 GUID 內建於 Azure Pipelines 服務和代理程式中。

分享方式：