Een pijplijndecorator ontwerpen

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022

Met pijplijn-decorators kunt u stappen toevoegen aan het begin en einde van elke taak. Het proces voor het ontwerpen van een pijplijn-decorator verschilt van het toevoegen van stappen aan één definitie, omdat deze van toepassing is op alle pijplijnen in een organisatie.

Stel dat uw organisatie een virusscanner moet uitvoeren op alle build-uitvoer die kan worden vrijgegeven. Auteurs van pijplijnen hoeven deze stap niet te onthouden. We maken een decorator die de stap automatisch injecteert. Onze pijplijn decorator injecteert een aangepaste taak die virusscans uitvoert aan het einde van elke pijplijntaak.

Tip

Bekijk onze nieuwste documentatie over uitbreidingsontwikkeling met behulp van de Azure DevOps Extension SDK.

1. Bijdragen toevoegen aan een extensie

In het volgende voorbeeld wordt ervan uitgegaan dat u bekend bent met de bijdragemodellen.

  1. Maak een extensie. Zodra de extensie is gemaakt, hebt u een vss-extension.json bestand.
  2. Voeg bijdragen toe aan het vss-extension.json bestand voor onze nieuwe pijplijndecorator.

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

Opties voor bijdrage

Laten we eens kijken naar de eigenschappen en waarvoor ze worden gebruikt:

Eigenschappen Beschrijving
id Bijdrage-id. Moet uniek zijn tussen bijdragen in deze extensie.
type Hiermee geeft u op dat deze bijdrage een pijplijn-decorator is. Moet de tekenreeks ms.azure-pipelines.pipeline-decoratorzijn.
targets Decorators kunnen worden uitgevoerd vóór uw taak/opgegeven taak, na of beide. Zie de volgende tabel voor beschikbare opties.
properties.template (Vereist) De sjabloon is een YAML-bestand dat is opgenomen in uw extensie, waarmee de stappen voor uw pijplijn-decorator worden gedefinieerd. Het is een relatief pad uit de hoofdmap van uw extensiemap.
properties.targettask De doeltaak-id die wordt gebruikt voor ms.azure-pipelines-agent-job.pre-task-tasks of ms.azure-pipelines-agent-job.post-task-tasks doelen. Moet een GUID-tekenreeks zijn, zoals 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Doelen

Doel Beschrijving
ms.azure-pipelines-agent-job.pre-job-tasks Voer vóór andere taken uit in een klassieke build- of YAML-pijplijn. Vanwege verschillen in het uitchecken van broncode wordt dit doel uitgevoerd na het uitchecken in een YAML-pijplijn, maar voordat u uitcheckt in een klassieke build-pijplijn.
ms.azure-pipelines-agent-job.post-checkout-tasks Uitvoeren na de laatste checkout taak in een klassieke build- of YAML-pijplijn.
ms.azure-pipelines-agent-job.post-job-tasks Voer na andere taken uit in een klassieke build- of YAML-pijplijn.
ms.azure-pipelines-agent-job.pre-task-tasks Voer deze uit vóór de opgegeven taak in een klassieke build- of YAML-pijplijn.
ms.azure-pipelines-agent-job.post-task-tasks Voer na de opgegeven taak uit in een klassieke build- of YAML-pijplijn.
ms.azure-release-pipelines-agent-job.pre-task-tasks Uitvoeren vóór de opgegeven taak in een klassieke RM-pijplijn.
ms.azure-release-pipelines-agent-job.post-task-tasks Uitvoeren na de opgegeven taak in een klassieke RM-pijplijn.
ms.azure-release-pipelines-agent-job.pre-job-tasks Uitvoeren vóór andere taken in een klassieke RM-pijplijn.
ms.azure-release-pipelines-agent-job.post-job-tasks Voer na andere taken uit in een klassieke RM-pijplijn.

Notitie

Implementatietaken in een YAML-pijplijn ondersteunen ms.azure-pipelines-agent-job.pre-job-tasks en ms.azure-pipelines-agent-job.post-job-tasks doelen alleen. Taken ondersteunen alle YAML-pijplijndoelen.

In dit voorbeeld gebruiken ms.azure-pipelines-agent-job.post-job-tasks we omdat we aan het einde van alle buildtaken willen worden uitgevoerd.

Deze extensie draagt bij aan een pijplijn-decorator. Vervolgens maken we een YAML-sjabloonbestand om het gedrag van de decorator te definiëren.

2. Een YAML-bestand voor decorator maken

In de eigenschappen van de extensie hebben we de naam 'my-decorator.yml' gekozen. Maak dat bestand in de hoofdmap van uw bijdrage. Deze bevat de reeks stappen die na elke taak moeten worden uitgevoerd. We beginnen met een basisvoorbeeld en werken aan de volledige taak.

my-decorator.yml (eerste versie)

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

Notitie

Pijplijn decoratortaken met serviceverbindingsgebruik worden niet ondersteund voor klassieke release-pijplijnen.

3. Installeer de decorator

Als u een pijplijndecorator wilt toevoegen aan uw organisatie, moet u een extensie installeren. Alleen privé-extensies kunnen pijplijn-decorators bijdragen. De extensie moet worden gemaakt en gedeeld met uw organisatie voordat deze kan worden gebruikt.

Zodra de extensie is gedeeld met uw organisatie, zoekt u de extensie en installeert u deze.

Sla het bestand op en bouw en installeer de extensie. Een eenvoudige pijplijn maken en uitvoeren. De decorator injecteert ons dir script automatisch aan het einde van elke taak. Een pijplijnuitvoering lijkt op het volgende voorbeeld.

Pipeline decorator running a simple script

Notitie

De decorator wordt uitgevoerd op elke taak in elke pijplijn in de organisatie. In latere stappen voegen we logica toe om te bepalen wanneer en hoe de decorator wordt uitgevoerd.

4. Injectvoorwaarden

In ons voorbeeld hoeven we alleen de virusscanner uit te voeren als de build-uitvoer voor het publiek kan worden vrijgegeven. Stel dat alleen builds van de standaardbranch (meestal main) worden uitgebracht. We moeten de decorator beperken tot taken die worden uitgevoerd op basis van de standaardvertakking.

Het bijgewerkte bestand ziet er als volgt uit:

my-decorator.yml (herziene versie)

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

U kunt beginnen met het zien van de kracht van dit uitbreidbaarheidspunt. Gebruik de context van de huidige taak om stappen voorwaardelijk in te voeren tijdens runtime. Gebruik YAML-expressies om beslissingen te nemen over welke stappen u moet invoeren en wanneer. Zie de expressiecontext van de pijplijn decorator voor een volledige lijst met beschikbare gegevens.

Er is nog een voorwaarde die we moeten overwegen: wat als de gebruiker de virusscanstap al heeft opgenomen? We moeten geen tijd verspillen om het opnieuw uit te voeren. In dit eenvoudige voorbeeld doen we alsof een script taak in de taak de virusscanner uitvoert. (In een echte implementatie hebt u een aangepaste taak om dit te controleren.)

De id van de scripttaak is d9bafed4-0b18-4f58-968d-86655b4d2ce9. Als we een andere scripttaak zien, moeten we de onze niet injecteren.

my-decorator.yml (definitieve versie)

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. Geef een doeltaak op

U kunt de doeltaak-id opgeven en taken vóór of na deze doeltaak injecteren. Als u de doeltaak wilt opgeven, kunt u het manifestbestand vss-extension.json wijzigen, zoals in het volgende voorbeeld.

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"
            }
        }
    ],
    ...
}

Wanneer u de eigenschap targettask instelt, kunt u de id van een doeltaak opgeven. Taken worden geïnjecteerd voor/na alle exemplaren van de opgegeven doeltaak.

Invoerinjectie van doeltaak opgeven

U kunt een lijst opgeven met invoer van de doeltaak die u wilt injecteren als invoer voor de geïnjecteerde taak.

Deze functie is ontworpen om te werken met aangepaste pijplijntaken. Het is niet bedoeld om toegang te bieden tot invoer van doelpijplijntaken via pijplijnvariabelen.

Als u toegang wilt krijgen tot de invoer van de doelpijplijntaak (invoer met het target_ voorvoegsel), moet de geïnjecteerde pijplijntaak methoden gebruiken uit de azure-pipelines-tasks-task-lib, en niet de pijplijnvariabelen, bijvoorbeeld const inputString = tl.getInput('target_targetInput')).

Hiervoor kunt u uw eigen aangepaste pijplijntaak maken en daar de doelinvoer gebruiken. Als u de functionaliteit van een van de kant-en-klare taken nodig hebt, zoals CmdLine@2, kunt u een kopie van de CmdLine@2 taak maken en deze publiceren met uw decorator-extensie.

Notitie

Deze functionaliteit is alleen beschikbaar voor taken die vóór of na de doeltaak worden geïnjecteerd.

Als u deze lijst met invoer wilt opgeven, kunt u het manifestbestand vss-extension.json wijzigen, zoals in het volgende voorbeeld.

vss-extension.json (geïnjecteerde taakinvoerversie)

{
    "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"]
            }
        }
    ],
    ...
}

Door de eigenschap targettaskinputs in te stellen, kunt u de lijst met invoer opgeven die naar verwachting moet worden geïnjecteerd. Deze invoer wordt opgenomen in de taak met het voorvoegsel 'target_' en is beschikbaar in de geïnjecteerde taak, zoals target_target-task-input.

Notitie

Doeltaakinvoer die geheime waarden met variabelen ophalen of ophalen uit andere taken, worden niet geïnjecteerd.

Fouten opsporen

Mogelijk moet u fouten opsporen wanneer u uw decorator maakt. Mogelijk wilt u ook zien welke gegevens u beschikbaar hebt in de context.

U kunt de variabele true instellen op wanneer u een pijplijn in de system.debugContext wachtrij zet. Bekijk vervolgens de overzichtspagina van de pijplijn.

U ziet iets vergelijkbaars met de volgende afbeelding.

View pipeline decorator context

Selecteer de taak om de logboeken weer te geven, waarin runtimewaarden worden weergegeven en of de context beschikbaar is.