Share via

Créer un décorateur de pipeline

  • Article

Azure DevOps Services | Azure DevOps Server 2022

Les décorateurs de pipeline vous permettent d’ajouter des étapes au début et à la fin de chaque travail. Le processus de création d’un décorateur de pipeline est différent de l’ajout d’étapes à une définition unique, car il s’applique à tous les pipelines d’une organisation.

Supposons que votre organisation exige l’exécution d’un scanneur antivirus sur toutes les sorties de build qui peuvent être publiées. Les auteurs de pipelines n’ont pas besoin de se rappeler d’ajouter cette étape. Nous créons un décorateur qui injecte automatiquement l’étape. Notre décorateur de pipeline injecte une tâche personnalisée qui effectue une analyse antivirus à la fin de chaque travail de pipeline.

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.

1. Ajouter des contributions à une extension

L’exemple suivant part du principe que vous connaissez les modèles de contribution.

  1. Créez une extension. Une fois votre extension créée, vous disposez d’un vss-extension.json fichier.
  2. Ajoutez des contributions au vss-extension.json fichier pour notre nouveau décorateur de pipeline.

vss-extension.json

{
    "manifestVersion": 1,
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.post-job-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml"
            }
        }
    ],
    "files": [
        {
            "path": "my-decorator.yml",
            "addressable": true,
            "contentType": "text/plain"
        }
    ]
}

Options de contribution

Examinons les propriétés et ce qu’elles sont utilisées pour :

Propriété Description
id Identificateur de contribution. Doit être unique parmi les contributions de cette extension.
type Spécifie que cette contribution est un décorateur de pipeline. Doit être la chaîne ms.azure-pipelines.pipeline-decorator.
targets Les décorateurs peuvent s’exécuter avant votre tâche/tâche spécifiée, après ou les deux. Consultez le tableau suivant pour connaître les options disponibles.
properties.template (Obligatoire) Le modèle est un fichier YAML inclus dans votre extension, qui définit les étapes de votre décorateur de pipeline. Il s’agit d’un chemin relatif à partir de la racine de votre dossier d’extension.
properties.targettask ID de tâche cible utilisé pour ms.azure-pipelines-agent-job.pre-task-tasks ou ms.azure-pipelines-agent-job.post-task-tasks cible. Doit être une chaîne GUID comme 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Targets

Cible Description
ms.azure-pipelines-agent-job.pre-job-tasks Exécutez avant d’autres tâches dans un pipeline yaML ou build classique. En raison de différences dans la façon dont le code source case activée out se produit, cette cible s’exécute après case activée out dans un pipeline YAML, mais avant case activée out dans un pipeline de build classique.
ms.azure-pipelines-agent-job.post-checkout-tasks Exécutez après la dernière checkout tâche d’une build classique ou d’un pipeline YAML.
ms.azure-pipelines-agent-job.post-job-tasks Exécutez après d’autres tâches dans un pipeline de build ou YAML classique.
ms.azure-pipelines-agent-job.pre-task-tasks Exécutez avant la tâche spécifiée dans une build classique ou un pipeline YAML.
ms.azure-pipelines-agent-job.post-task-tasks Exécutez après la tâche spécifiée dans une build classique ou un pipeline YAML.
ms.azure-release-pipelines-agent-job.pre-task-tasks Exécutez avant la tâche spécifiée dans un pipeline RM classique.
ms.azure-release-pipelines-agent-job.post-task-tasks Exécutez après la tâche spécifiée dans un pipeline RM classique.
ms.azure-release-pipelines-agent-job.pre-job-tasks Exécutez avant d’autres tâches dans un pipeline RM classique.
ms.azure-release-pipelines-agent-job.post-job-tasks Exécutez après d’autres tâches dans un pipeline RM classique.

Remarque

Les travaux de déploiement dans un pipeline YAML prennent uniquement en charge ms.azure-pipelines-agent-job.pre-job-tasks et ms.azure-pipelines-agent-job.post-job-tasks cible. Les travaux prennent en charge toutes les cibles de pipeline YAML.

Dans cet exemple, nous utilisons ms.azure-pipelines-agent-job.post-job-tasks parce que nous voulons exécuter à la fin de tous les travaux de génération.

Cette extension contribue à un décorateur de pipeline. Ensuite, nous créons un fichier YAML de modèle pour définir le comportement du décorateur.

2. Créer un fichier YAML décoratif

Dans les propriétés de l’extension, nous avons choisi le nom « my-decorationor.yml ». Créez ce fichier à la racine de votre contribution. Il contient l’ensemble des étapes à exécuter après chaque travail. Nous commençons par un exemple de base et travaillons jusqu’à la tâche complète.

my-decorationor.yml (version initiale)

steps:
- task: CmdLine@2
  displayName: 'Run my script (injected from decorator)'
  inputs:
    script: dir

Remarque

Les tâches de décorateur de pipeline avec utilisation de la connexion de service ne sont pas prises en charge pour les pipelines de mise en production classiques.

3. Installer le décorateur

Pour ajouter un décorateur de pipeline à votre organisation, vous devez installer une extension. Seules les extensions privées peuvent contribuer aux décorateurs de pipeline. L’extension doit être créée et partagée avec votre organisation avant de pouvoir être utilisée.

Une fois l’extension partagée avec votre organisation, recherchez l’extension et installez-la.

Enregistrez le fichier, puis générez et installez l’extension. Créez et exécutez un pipeline de base. Le décorateur injecte automatiquement notre dir script à la fin de chaque travail. Une exécution de pipeline ressemble à l’exemple suivant.

Pipeline decorator running a simple script

Remarque

Le décorateur s’exécute sur chaque travail de chaque pipeline de l’organisation. Dans les étapes ultérieures, nous ajoutons une logique pour contrôler quand et comment l’élément décoratif s’exécute.

4. Injecter des conditions

Dans notre exemple, nous n’avons besoin d’exécuter le scanneur antivirus que si les sorties de build peuvent être publiées sur le public. Supposons que seules les builds des branche par défaut (généralementmain) soient publiées. Nous devrions limiter le décorateur aux travaux qui s’exécutent sur le branche par défaut.

Le fichier mis à jour ressemble à ceci :

my-decorationor.yml (version révisée)

steps:
- ${{ if eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

Vous pouvez commencer à voir la puissance de ce point d’extensibilité. Utilisez le contexte du travail actuel pour injecter des étapes conditionnellement au moment de l’exécution. Utilisez des expressions YAML pour prendre des décisions sur les étapes à injecter et quand. Consultez le contexte d’expression de décorateur de pipeline pour obtenir la liste complète des données disponibles.

Il existe une autre condition à prendre en compte : que se passe-t-il si l’utilisateur a déjà inclus l’étape d’analyse du virus ? On ne devrait pas perdre du temps à le réécuter. Dans cet exemple simple, nous allons prétendre que toute script tâche trouvée dans le travail exécute le scanneur antivirus. (Dans une implémentation réelle, vous avez une tâche personnalisée à case activée pour cela à la place.)

L’ID de la tâche de script est d9bafed4-0b18-4f58-968d-86655b4d2ce9. Si nous voyons une autre tâche de script, nous ne devrions pas injecter le nôtre.

my-decorationor.yml (version finale)

steps:
- ${{ if and(eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch), not(containsValue(job.steps.*.task.id, 'd9bafed4-0b18-4f58-968d-86655b4d2ce9'))) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

5. Spécifier une tâche cible

Vous pouvez spécifier l’ID de tâche cible et injecter des tâches avant ou après cette tâche cible. Pour spécifier la tâche cible, vous pouvez modifier le fichier manifeste vss-extension.json comme dans l’exemple suivant.

vss-extension.json

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id"
            }
        }
    ],
    ...
}

Lorsque vous configurez la propriété « targettask », vous pouvez spécifier l’ID d’une tâche cible. Les tâches seront injectées avant/après toutes les instances de la tâche cible spécifiée.

Spécifier l’injection d’entrées de la tâche cible

Vous pouvez spécifier une liste d’entrées de la tâche cible que vous souhaitez injecter en tant qu’entrées à la tâche injectée.

Cette fonctionnalité est conçue pour fonctionner avec des tâches de pipeline personnalisées. Il n’est pas destiné à fournir l’accès aux entrées de tâche de pipeline cible via des variables de pipeline.

Pour accéder aux entrées de tâche de pipeline cible (entrées avec le target_ préfixe), la tâche de pipeline injectée doit utiliser des méthodes à partir d’azure-pipelines-tasks-task-lib, et non les variables de pipeline, par exempleconst inputString = tl.getInput('target_targetInput')).

Pour ce faire, vous pouvez créer votre propre tâche de pipeline personnalisée et utiliser les entrées cibles là-bas. Si vous avez besoin des fonctionnalités de l’une des tâches prêtes à l’emploi, par CmdLine@2exemple, vous pouvez créer une copie de la tâche CmdLine@2 et la publier avec votre extension de décorateur.

Remarque

Cette fonctionnalité est disponible uniquement pour les tâches qui sont injectées avant ou après la tâche cible.

Pour spécifier cette liste d’entrées, vous pouvez modifier le fichier manifeste vss-extension.json comme dans l’exemple suivant.

vss-extension.json (version des entrées de tâche injectées)

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id",
                "targettaskinputs": ["target-task-input", "target-task-second-input"]
            }
        }
    ],
    ...
}

En configurant la propriété « targettaskinputs », vous pouvez spécifier la liste des entrées attendues à injecter. Ces entrées seront injectées dans la tâche avec le préfixe «target_ » et seront disponibles dans la tâche injectée comme target_target-task-input.

Remarque

Les entrées de tâche cible qui obtiennent des valeurs secrètes avec des variables ou les obtiennent à partir d’autres tâches ne seront pas injectées.

Déboguer

Vous devrez peut-être déboguer lorsque vous créez votre décorateur. Vous pouvez également voir les données disponibles dans le contexte.

Vous pouvez définir la system.debugContext variable true sur quand vous mettez en file d’attente un pipeline. Examinez ensuite la page récapitulative du pipeline.

Vous voyez quelque chose de similaire à l’image suivante.

View pipeline decorator context

Sélectionnez la tâche pour afficher les journaux, qui affichent les valeurs d’exécution et que le contexte est disponible.