Contexte d’expression de décorateur de pipeline

Article
11/09/2024

Azure DevOps Services

Les décorateurs de pipeline ont accès au contexte sur le pipeline dans lequel ils s’exécutent. En tant qu’auteur de décorateur de pipeline, vous pouvez utiliser ce contexte pour prendre des décisions sur le comportement du décorateur. Les informations disponibles dans le contexte sont différentes pour les pipelines et pour la mise en production. En outre, les décorateurs s’exécutent une fois que les noms des tâches sont résolus en identificateurs globaux uniques (GUID). Lorsque votre décorateur souhaite référencer une tâche, il doit utiliser le GUID plutôt que le nom ou le mot clé.

Conseil

Consultez notre documentation la plus récente sur le développement d’extensions à l’aide du Kit de développement logiciel (SDK) d’extension Azure DevOps.

Remarque

Les décorateurs de pipeline sont utilisés lors de la création d’extensions web. Ces exemples ne sont pas conçus pour fonctionner dans des pipelines YAML.

Ressources

Les ressources de pipeline sont disponibles sur l’objet resources .

Référentiels

Actuellement, il n’y a qu’une seule clé : repositories. repositories est un mappage de l’ID de dépôt aux informations sur le référentiel.

Dans une build de concepteur, l’alias de dépôt principal est __designer_repo. Dans un pipeline YAML, le dépôt principal est appelé self. Dans un pipeline de mise en production, les référentiels ne sont pas disponibles. Les variables d’artefact de mise en production sont disponibles.

Par exemple, pour imprimer le nom du self dépôt dans un pipeline YAML :

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

Les référentiels contiennent ces propriétés :

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

Travail

Les détails du travail sont disponibles sur l’objet job .

Les données ressemblent à ce qui suit :

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

Par exemple, pour ajouter une tâche de manière conditionnelle uniquement s’il n’existe pas encore :

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

Variables

Les variables de pipeline sont également disponibles.

Par exemple, si le pipeline avait une variable appelée myVar, sa valeur serait disponible pour le décorateur en tant que variables['myVar'].

Par exemple, pour donner à un décorateur un opt-out, nous pourrions rechercher une variable. Les auteurs de pipelines qui souhaitent refuser le décorateur peuvent définir cette variable et le décorateur n’est pas injecté. Si la variable n’est pas présente, le décorateur est injecté comme d’habitude.

my-decorator.yml

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

Ensuite, dans un pipeline de l’organisation, l’auteur peut demander au décorateur de ne pas s’injecter lui-même.

pipeline-with-opt-out.yml

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

Noms des tâches et GUID

Les décorateurs s’exécutent après que les tâches ont déjà été transformées en GUID. Considérez le yaML suivant :

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

Chacune de ces étapes est mappée à une tâche. Chaque tâche a un GUID unique. Les noms et mots clés des tâches sont mappés aux GUID des tâches avant l’exécution des décorateurs. Si un décorateur souhaite vérifier l’existence d’une autre tâche, il doit effectuer une recherche par GUID de tâche plutôt que par nom ou mot clé.

Pour les tâches normales (que vous spécifiez avec le task mot clé), vous pouvez examiner les tâches task.json pour déterminer son GUID. Pour des mots clés spéciaux comme checkout et bash dans l’exemple précédent, vous pouvez utiliser les GUID suivants :

Mot clé	GUID	Nom de la tâche
`checkout`	`6D15AF64-176C-496D-B583-FD2AE21D4DF4`	n/a, voir remarque
`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

Une fois les noms de tâches et les mots clés résolus, le YAML précédent devient :

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

Conseil

Vous trouverez chacun de ces GUID dans la tâche dans la task.json zone correspondante. La seule exception est checkout, qui est une fonctionnalité native de l’agent. Son GUID est intégré au service et à l’agent Azure Pipelines.

Partager via