Contexto de expressão do decorador de pipeline

Artigo
11/09/2024

Azure DevOps Services

Os decoradores de pipeline têm acesso ao contexto sobre o pipeline no qual são executados. Como autor de decorador de pipeline, você pode usar esse contexto para tomar decisões sobre o comportamento do decorador. As informações disponíveis no contexto são diferentes para pipelines e para lançamento. Além disso, os decoradores são executados depois que os nomes das tarefas são resolvidos para GUIDs (identificadores globais exclusivos) da tarefa. Quando o decorador quiser fazer referência a uma tarefa, ele deverá usar o GUID em vez do nome ou da palavra-chave.

Dica

Confira nossa documentação mais recente sobre o desenvolvimento de extensão usando o SDK da Extensão do Azure DevOps.

Observação

Os decoradores de pipeline são usados ao criar extensões da Web. Esses exemplos não foram projetados para funcionar em pipelines YAML.

Recursos

Os recursos de pipeline estão disponíveis no resources objeto.

Repositórios

Atualmente, há apenas uma chave: repositories. repositories é um mapa do ID do repositório para informações sobre o repositório.

Em uma compilação de designer, o alias do repositório primário é __designer_repo. Em um pipeline YAML, o repositório primário é chamado de self. Em um pipeline de lançamento, os repositórios não estão disponíveis. Variáveis de artefato de versão estão disponíveis.

Por exemplo, para imprimir o self nome do repositório em um pipeline YAML:

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

Os repositórios contêm estas propriedades:

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": {}
}

Trabalho

Os detalhes do trabalho estão disponíveis no job objeto.

Os dados são semelhantes a:

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

Por exemplo, para adicionar condicionalmente uma tarefa somente se ela ainda não existir:

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

Variáveis

Variáveis de pipeline também estão disponíveis.

Por exemplo, se o pipeline tivesse uma variável chamada myVar, seu valor estaria disponível para o decorador como variables['myVar'].

Por exemplo, para dar a um decorador um opt-out, podemos procurar uma variável. Os autores de pipeline que desejam recusar o decorador podem definir essa variável e o decorador não é injetado. Se a variável não estiver presente, o decorador será injetado como de costume.

my-decorator.yml

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

Então, em um pipeline na organização, o autor pode solicitar ao decorador que não se injete.

pipeline-with-opt-out.yml

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

Nomes de tarefas e GUIDs

Os decoradores são executados depois que as tarefas já se transformaram em GUIDs. Considere o seguinte 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

Cada uma dessas etapas é mapeada para uma tarefa. Cada tarefa tem um GUID exclusivo. Os nomes das tarefas e as palavras-chave são mapeados para os GUIDs da tarefa antes da execução dos decoradores. Se um decorador quiser verificar a existência de outra tarefa, ele deverá pesquisar por GUID de tarefa em vez de por nome ou palavra-chave.

Para tarefas normais (que você especifica com a task palavra-chave), você pode examinar a tarefa task.json para determinar seu GUID. Para palavras-chave especiais como checkout e bash no exemplo anterior, você pode usar os seguintes GUIDs:

Palavra-chave	GUID	Nome da Tarefa
`checkout`	`6D15AF64-176C-496D-B583-FD2AE21D4DF4`	n/a, ver nota
`bash`	`6C731C3C-3C68-459A-A5C9-BDE6E6595B5B`	Bash
`script`	`D9BAFED4-0B18-4F58-968D-86655B4D2CE9`	Linha Cmd
`powershell`	`E213FF0F-5D5C-4791-802D-52EA3E7BE1F1`	PowerShell
`pwsh`	`E213FF0F-5D5C-4791-802D-52EA3E7BE1F1`	PowerShell
`publish`	`ECDC45F6-832D-4AD9-B52B-EE49E94659BE`	Artefato PublishPipelineArtifact
`download`	`30f35852-3f7e-4c0c-9a88-e127b4f97211`	DownloadPipelineArtifact

Depois que os nomes das tarefas e as palavras-chave são resolvidos, o YAML anterior se torna:

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

Dica

Você pode encontrar cada um desses GUIDs na task.json tarefa in-box correspondente. A única exceção é checkout, que é um recurso nativo do agente. Seu GUID é integrado ao serviço e ao agente do Azure Pipelines.

Compartilhar via