Skapa en pipelinedekoratör
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.jsonfil. - Lägg till bidrag i
vss-extension.jsonfilen 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.
Distributionsjobb stöds inte i klassiska versionspipelines.
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 (ursprunglig 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.
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 vss-extension.json manifestfil 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 manifestfil som i följande exempel.
vss-extension.json (inmatad uppgift matar in version)
{
"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.
Välj uppgiften för att se loggarna, som visar körningsvärden och att kontexten är tillgänglig.