通过

管道修饰器表达式上下文

  • 项目

Azure DevOps Services

管道修饰器 有权访问运行管道的上下文。 作为管道修饰器作者，可以使用此上下文来决定修饰器的行为。 上下文中提供的信息因管道和发布而异。 此外，修饰器在任务名称解析为任务全局唯一标识符（GUID）后运行。 当修饰器想要引用任务时，它应使用 GUID 而不是名称或关键字。

提示

查看有关使用 Azure DevOps 扩展 SDK 进行扩展开发的最新文档。

注意

生成 Web 扩展时使用管道修饰器。 这些示例不设计为在 YAML 管道中工作。

资源

管道资源在对象上 resources 可用。

存储库

目前，只有一个键： repositories repositories 是存储库 ID 到存储库相关信息的映射。

在设计器版本中，主存储库别名为 __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 = 
{
	"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。 对于类似于checkoutbash上一示例中的特殊关键字，可以使用以下 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 服务和代理中。