Skapa en pipelinedekoratör

Artikel
10/28/2023

Azure DevOps Services | Azure DevOps Server 2022

Med pipelinedekoratörer kan du lägga till steg i början och slutet av varje jobb. Processen för att skapa en pipelinedekoratör skiljer sig från att lägga till steg i en enskild definition eftersom den gäller för alla pipelines i en organisation.

Anta att din organisation kräver att du kör en virusskanner på alla build-utdata som kan släppas. Pipelineförfattare behöver inte komma ihåg att lägga till det steget. Vi skapar en dekoratör som automatiskt matar in steget. Vår pipelinedekoratör matar in en anpassad uppgift som utför virusgenomsökning i slutet av varje pipelinejobb.

Dricks

Läs vår senaste dokumentation om tilläggsutveckling med hjälp av Azure DevOps Extension SDK.

1. Lägg till bidrag till en förlängning

I följande exempel förutsätter vi att du är bekant med bidragsmodellerna.

Skapa ett tillägg. När tillägget har skapats har du en vss-extension.json fil.
Lägg till bidrag i vss-extension.json filen för vår nya pipelinedekoratör.

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

Bidragsalternativ

Nu ska vi ta en titt på egenskaperna och vad de används till:

Property	beskrivning
`id`	Bidragsidentifierare. Måste vara unikt bland bidragen i det här tillägget.
`type`	Anger att det här bidraget är en pipelinedekoratör. Måste vara strängen `ms.azure-pipelines.pipeline-decorator`.
`targets`	Dekoratörer kan köras före jobbet/den angivna aktiviteten, efter eller båda. Se följande tabell för tillgängliga alternativ.
`properties.template`	(Krävs) Mallen är en YAML-fil som ingår i tillägget, som definierar stegen för pipelinedekoratören. Det är en relativ sökväg från roten i tilläggsmappen.
`properties.targettask`	Målaktivitets-ID:t som används för `ms.azure-pipelines-agent-job.pre-task-tasks` eller `ms.azure-pipelines-agent-job.post-task-tasks` mål. Måste vara GUID-sträng som `89b8ac58-8cb7-4479-a362-1baaacc6c7ad`

Mål

Mål	beskrivning
`ms.azure-pipelines-agent-job.pre-job-tasks`	Kör före andra uppgifter i en klassisk bygg- eller YAML-pipeline. På grund av skillnader i hur källkodsutcheckningen sker körs det här målet efter utcheckningen i en YAML-pipeline men före utcheckningen i en klassisk bygg-pipeline.
`ms.azure-pipelines-agent-job.post-checkout-tasks`	Kör efter den sista `checkout` uppgiften i en klassisk bygg- eller YAML-pipeline.
`ms.azure-pipelines-agent-job.post-job-tasks`	Kör efter andra uppgifter i en klassisk bygg- eller YAML-pipeline.
`ms.azure-pipelines-agent-job.pre-task-tasks`	Kör före angiven aktivitet i en klassisk bygg- eller YAML-pipeline.
`ms.azure-pipelines-agent-job.post-task-tasks`	Kör efter angiven aktivitet i en klassisk bygg- eller YAML-pipeline.
`ms.azure-release-pipelines-agent-job.pre-task-tasks`	Kör före angiven aktivitet i en klassisk RM-pipeline.
`ms.azure-release-pipelines-agent-job.post-task-tasks`	Kör efter angiven aktivitet i en klassisk RM-pipeline.
`ms.azure-release-pipelines-agent-job.pre-job-tasks`	Kör före andra uppgifter i en klassisk RM-pipeline.
`ms.azure-release-pipelines-agent-job.post-job-tasks`	Kör efter andra uppgifter i en klassisk RM-pipeline.

Kommentar

Distributionsjobb i en YAML-pipeline stöder och ms.azure-pipelines-agent-job.post-job-tasks riktar endast in ms.azure-pipelines-agent-job.pre-job-tasks sig på mål. Jobb stöder alla YAML-pipelinemål.

I det här exemplet använder ms.azure-pipelines-agent-job.post-job-tasks vi eftersom vi vill köra i slutet av alla byggjobb.

Det här tillägget bidrar med en pipelinedekoratör. Därefter skapar vi en YAML-mallfil för att definiera dekoratörens beteende.

2. Skapa en YAML-fil för dekoratör

I tilläggets egenskaper valde vi namnet "my-decorator.yml". Skapa filen i roten för ditt bidrag. Den innehåller de steg som ska köras efter varje jobb. Vi börjar med ett grundläggande exempel och arbetar fram till den fullständiga uppgiften.

my-decorator.yml (initial version)

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

Kommentar

Pipelinedekoratörsuppgifter med tjänstanslutningsanvändning stöds inte för klassiska versionspipelines.

3. Installera dekoratören

Om du vill lägga till en pipelinedekoratör i din organisation måste du installera ett tillägg. Endast privata tillägg kan bidra med pipelinedekoratörer. Tillägget måste skapas och delas med din organisation innan det kan användas.

När tillägget har delats med din organisation söker du efter tillägget och installerar det.

Spara filen och skapa och installera sedan tillägget. Skapa och köra en grundläggande pipeline. Dekoratören matar automatiskt in vårt dir skript i slutet av varje jobb. En pipelinekörning ser ut ungefär som i följande exempel.

Pipeline decorator running a simple script

Kommentar

Dekoratören körs på varje jobb i varje pipeline i organisationen. I senare steg lägger vi till logik för att styra när och hur dekoratören körs.

4. Mata in villkor

I vårt exempel behöver vi bara köra virusskannern om build-utdata kan släppas till allmänheten. Anta att endast versioner från standardgrenen (vanligtvis main) släpps någonsin. Vi bör begränsa dekoratören till jobb som körs mot standardgrenen.

Den uppdaterade filen ser ut så här:

my-decorator.yml (reviderad version)

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

Du kan börja se kraften i den här utökningspunkten. Använd kontexten för det aktuella jobbet för att villkorligt mata in steg vid körning. Använd YAML-uttryck för att fatta beslut om vilka steg som ska matas in och när. Se kontexten för pipelinedekoratöruttryck för en fullständig lista över tillgängliga data.

Det finns ett annat villkor som vi måste tänka på: vad händer om användaren redan har inkluderat steget för virusgenomsökning? Vi borde inte slösa tid på att köra den igen. I det här enkla exemplet låtsas vi att alla script uppgifter som hittas i jobbet kör virusskannern. (I en verklig implementering skulle du ha en anpassad uppgift att söka efter i stället.)

Skriptaktivitetens ID är d9bafed4-0b18-4f58-968d-86655b4d2ce9. Om vi ser en annan skriptuppgift bör vi inte mata in vår.

my-decorator.yml (slutlig version)

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. Ange en målaktivitet

Du kan ange målaktivitets-ID och mata in aktiviteter före eller efter den här målaktiviteten. Om du vill ange målaktivitet kan du ändra manifestfilen vss-extension.json som i följande exempel.

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

När du konfigurerar egenskapen "targettask" kan du ange ID för en målaktivitet. Aktiviteter matas in före/efter alla instanser av den angivna målaktiviteten.

Ange målaktivitetens indatainmatning

Du kan ange en lista över indata för målaktiviteten som du vill mata in som indata till den inmatade aktiviteten.

Den här funktionen är utformad för att fungera med anpassade pipelineuppgifter. Det är inte avsett att ge åtkomst till målindata för pipelineaktiviteter via pipelinevariabler.

För att få åtkomst till målindata för pipelineaktiviteten (indata med prefixet target_ ) bör den inmatade pipelineaktiviteten använda metoder från azure-pipelines-tasks-task-lib och inte pipelinevariablerna, till exempel const inputString = tl.getInput('target_targetInput')).

För att göra det kan du skapa en egen anpassad pipelineuppgift och använda målindata där. Om du behöver funktionerna i en av de färdiga uppgifterna, till exempel CmdLine@2, kan du skapa en kopia av CmdLine@2 uppgift och publicera den med tillägg för dekoratör.

Kommentar

Den här funktionen är endast tillgänglig för aktiviteter som matas in före eller efter målaktiviteten.

Om du vill ange den här listan med indata kan du ändra vss-extension.json-manifestfilen som i följande exempel.

vss-extension.json (inmatad uppgiftsindataversion)

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

Genom att konfigurera egenskapen "targettaskinputs" kan du ange listan över indata som förväntas matas in. Dessa indata matas in i uppgiften med prefixet "target_" och kommer att vara tillgängliga i den inmatade aktiviteten som target_target-task-input.

Kommentar

Målaktivitetsindata som hämtar hemliga värden med variabler eller hämtar dem från andra aktiviteter matas inte in.

Felsöka

Du kan behöva felsöka när du skapar din dekoratör. Du kanske också vill se vilka data du har tillgängliga i kontexten.

Du kan ange variabeln system.debugContext till true när du köar en pipeline. Titta sedan på sammanfattningssidan för pipelinen.

Du ser något som liknar följande bild.

View pipeline decorator context

Välj uppgiften för att se loggarna, som visar körningsvärden och att kontexten är tillgänglig.

Share via

Skapa en pipelinedekoratör

1. Lägg till bidrag till en förlängning

vss-extension.json

Bidragsalternativ

Mål

2. Skapa en YAML-fil för dekoratör

my-decorator.yml (initial version)

3. Installera dekoratören

4. Mata in villkor

my-decorator.yml (reviderad version)

my-decorator.yml (slutlig version)

5. Ange en målaktivitet

vss-extension.json

Ange målaktivitetens indatainmatning

vss-extension.json (inmatad uppgiftsindataversion)

Felsöka

Feedback

Feedback

Ytterligare resurser

Share via

Skapa en pipelinedekoratör

1. Lägg till bidrag till en förlängning

vss-extension.json

Bidragsalternativ

Mål

2. Skapa en YAML-fil för dekoratör

my-decorator.yml (initial version)

3. Installera dekoratören

4. Mata in villkor

my-decorator.yml (reviderad version)

my-decorator.yml (slutlig version)

5. Ange en målaktivitet

vss-extension.json

Ange målaktivitetens indatainmatning

vss-extension.json (inmatad uppgiftsindataversion)

Felsöka

Relaterade artiklar

Feedback

Feedback

Ytterligare resurser