Vytvoření dekorátoru kanálu

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.

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í:

Cíle

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

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.

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. Chcete-li určit cílovou úlohu, můžete upravit vss-extension.json soubor manifestu jako v následujícím příkladu.

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.

Chcete-li zadat tento seznam vstupů, můžete upravit vss-extension.json soubor manifestu 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.

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.

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

Související články

• Syntaxe výrazů YAML
• Kontext výrazu dekorátoru kanálu
• Vývoj webového rozšíření
• Průvodce ověřováním