Vytvoření dekorátoru kanálu

  • Článek

Azure DevOps Services | Azure DevOps Server 2022

Dekorátory kanálu umožňují přidat kroky na začátek a konec každé úlohy. Proces vytváření dekorátoru kanálu se liší od přidání kroků do jedné definice, protože se vztahuje na všechny kanály v organizaci.

Předpokládejme, že vaše organizace vyžaduje spuštění antivirového skeneru na všech výstupech sestavení, které by bylo možné vydat. Autoři kanálů si tento krok nemusí pamatovat. Vytvoříme dekorátor, který tento krok automaticky vloží. Náš dekorátor kanálu vloží vlastní úlohu, která provede kontrolu virů na konci každé úlohy kanálu.

Tip

Projděte si nejnovější dokumentaci k vývoji rozšíření pomocí sady SDK rozšíření Azure DevOps.

1. Přidání příspěvků do rozšíření

Následující příklad předpokládá, že znáte modely příspěvků.

  1. Vytvořte rozšíření. Po vytvoření rozšíření máte vss-extension.json soubor.
  2. Přidejte do vss-extension.json souboru příspěvky pro náš nový dekorátor kanálu.

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

Možnosti příspěvku

Podívejme se na vlastnosti a na to, k čemu se používají:

Vlastnost Popis
id Identifikátor příspěvku Mezi příspěvky v tomto rozšíření musí být jedinečné.
type Určuje, že tento příspěvek je dekorátor kanálu. Musí to být řetězec ms.azure-pipelines.pipeline-decorator.
targets Dekorátory mohou běžet před úlohou nebo zadanou úlohou, po nebo obojím. Dostupné možnosti najdete v následující tabulce.
properties.template (Povinné) Šablona je soubor YAML, který je součástí vašeho rozšíření, který definuje kroky pro dekorátor kanálu. Jedná se o relativní cestu z kořenové složky rozšíření.
properties.targettask ID cílového úkolu, které se používá pro ms.azure-pipelines-agent-job.pre-task-tasks cíle.ms.azure-pipelines-agent-job.post-task-tasks Musí to být řetězec GUID, například 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Cíle

Cíl Popis
ms.azure-pipelines-agent-job.pre-job-tasks Spusťte před jinými úlohami v klasickém kanálu buildu nebo YAML. Vzhledem k rozdílům v tom, jak probíhá kontrola zdrojového kódu, se tento cíl spustí po rezervaci v kanálu YAML, ale před rezervacemi v klasickém kanálu buildu.
ms.azure-pipelines-agent-job.post-checkout-tasks Spusťte po poslední checkout úloze v klasickém buildu nebo kanálu YAML.
ms.azure-pipelines-agent-job.post-job-tasks Spusťte po dalších úkolech v klasickém kanálu buildu nebo YAML.
ms.azure-pipelines-agent-job.pre-task-tasks Spusťte před zadaným úkolem v klasickém buildu nebo kanálu YAML.
ms.azure-pipelines-agent-job.post-task-tasks Spusťte po zadané úloze v klasickém buildu nebo kanálu YAML.
ms.azure-release-pipelines-agent-job.pre-task-tasks Spusťte před zadaným úkolem v klasickém kanálu RM.
ms.azure-release-pipelines-agent-job.post-task-tasks Spusťte po zadané úloze v klasickém kanálu RM.
ms.azure-release-pipelines-agent-job.pre-job-tasks Spusťte před jinými úlohami v klasickém kanálu RM.
ms.azure-release-pipelines-agent-job.post-job-tasks Spusťte po dalších úlohách v klasickém kanálu RM.

Poznámka:

Úlohy nasazení v kanálu YAML podporují ms.azure-pipelines-agent-job.pre-job-tasksms.azure-pipelines-agent-job.post-job-tasks a cílí pouze. Úlohy podporují všechny cíle kanálu YAML.

V tomto příkladu používáme ms.azure-pipelines-agent-job.post-job-tasks , protože chceme spustit na konci všech úloh sestavení.

Toto rozšíření přispívá k dekorátoru kanálu. Dále vytvoříme soubor YAML šablony, který definuje chování dekorátoru.

2. Vytvoření souboru YAML dekorátoru

Ve vlastnostech rozšíření jsme zvolili název my-decorator.yml. Vytvořte tento soubor v kořenovém adresáři příspěvku. Obsahuje sadu kroků, které se mají spustit po každé úloze. Začneme základním příkladem a pracujeme na úplném úkolu.

my-decorator.yml (počáteční verze)

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

Poznámka:

Úlohy dekorátoru kanálu s využitím připojení služby se nepodporují pro klasické kanály verze.

3. Instalace dekorátoru

Pokud chcete do organizace přidat dekorátor kanálu, musíte nainstalovat rozšíření. Dekorátory kanálu můžou přispívat pouze privátní rozšíření. Rozšíření musí být vytvořené a sdílené s vaší organizací, aby bylo možné ho použít.

Po sdílení rozšíření s vaší organizací vyhledejte rozšíření a nainstalujte ho.

Uložte soubor a pak sestavte a nainstalujte příponu. Vytvořte a spusťte základní kanál. Dekorátor automaticky vloží náš dir skript na konec každé úlohy. Spuštění kanálu vypadá podobně jako v následujícím příkladu.

Pipeline decorator running a simple script

Poznámka:

Dekorátor běží na každé úloze v každém kanálu v organizaci. V pozdějších krocích přidáme logiku pro řízení, kdy a jak se dekorátor spustí.

4. Vkládání podmínek

V našem příkladu potřebujeme spustit jenom virovou kontrolu, pokud se výstupy sestavení můžou vydat veřejnosti. Řekněme, že se někdy vydávají jenom buildy z výchozí větve (obvykle main). Dekorátor bychom měli omezit na úlohy spuštěné ve výchozí větvi.

Aktualizovaný soubor vypadá takto:

my-decorator.yml (revidovaná verze)

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

Můžete začít zobrazovat sílu tohoto bodu rozšiřitelnosti. Podmíněným vložením kroků za běhu použijte kontext aktuální úlohy. Pomocí výrazů YAML můžete rozhodovat o tom, jaké kroky vložit a kdy. Úplný seznam dostupných dat najdete v kontextu výrazu dekorátoru kanálu.

Je potřeba vzít v úvahu další podmínku: co když uživatel už zahrnul krok kontroly virů? Neměli bychom ztrácet čas dalším spuštěním. V tomto jednoduchém příkladu budeme předstírat, že všechny script úkoly nalezené v úloze spouští virový skener. (Ve skutečné implementaci byste měli vlastní úlohu, kterou byste měli zkontrolovat.)

ID úkolu skriptu je d9bafed4-0b18-4f58-968d-86655b4d2ce9. Pokud uvidíme další úkol skriptu, neměli bychom vkládat naše.

my-decorator.yml (konečná verze)

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. Zadání cílového úkolu

Můžete zadat ID cílového úkolu a vložit úkoly před nebo za tento cílový úkol. Pokud chcete určit cílovou úlohu, můžete upravit soubor manifestu vss-extension.json, jako je následující příklad.

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

Při nastavování vlastnosti targettask můžete zadat ID cílového úkolu. Úkoly se vloží před/za všechny instance zadané cílové úlohy.

Zadání injektáže vstupů cílového úkolu

Můžete zadat seznam vstupů cílového úkolu, který chcete vložit jako vstupy do vložené úlohy.

Tato funkce je navržená tak, aby fungovala s vlastními úlohami kanálu. Účelem není poskytnout přístup ke vstupům úkolů cílového kanálu prostřednictvím proměnných kanálu.

Pokud chcete získat přístup ke vstupům úloh cílového kanálu (vstupy s target_ předponou), měla by úloha vloženého kanálu používat metody z knihovny azure-pipelines-tasks-task-lib, a ne proměnné kanálu, například const inputString = tl.getInput('target_targetInput')).

Uděláte to tak, že vytvoříte vlastní úlohu kanálu a použijete v ní cílové vstupy. Pokud potřebujete funkci některého z předpotřebných úkolů, například CmdLine@2, můžete vytvořit kopii CmdLine@2 úkolu a publikovat ji s rozšířením dekorátoru.

Poznámka:

Tato funkce je k dispozici pouze pro úlohy, které jsou vloženy před nebo za cílovou úlohu.

Chcete-li zadat tento seznam vstupů, můžete upravit soubor manifestu vss-extension.json jako v následujícím příkladu.

vss-extension.json (vložená verze vstupů úloh)

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

Nastavením vlastnosti targettaskinputs můžete zadat seznam vstupů, které se mají vložit. Tyto vstupy se vloží do úkolu s předponou "target_" a budou k dispozici v vložené úloze jako target_target-task-input.

Poznámka:

Cílové vstupy úkolů, které získají tajné hodnoty s proměnnými nebo je z jiných úkolů, se nevkážou.

Ladění

Při vytváření dekorátoru možná budete muset ladit. Můžete také chtít zjistit, jaká data máte v kontextu k dispozici.

Proměnnou system.debugContext můžete nastavit při true zařadíte do fronty kanálu. Pak se podívejte na stránku se souhrnem kanálu.

Zobrazí se něco podobného jako na následujícím obrázku.

View pipeline decorator context

Vyberte úlohu, aby se zobrazily protokoly, které zobrazují hodnoty modulu runtime a že je kontext k dispozici.