Share via

Tworzenie dekoratora potoku

  • Artykuł

Azure DevOps Services | Azure DevOps Server 2022

Dekoratory potoków umożliwiają dodawanie kroków do początku i końca każdego zadania. Proces tworzenia dekoratora potoku różni się od dodawania kroków do pojedynczej definicji, ponieważ ma zastosowanie do wszystkich potoków w organizacji.

Załóżmy, że twoja organizacja wymaga uruchomienia skanera wirusów na wszystkich danych wyjściowych kompilacji, które można zwolnić. Autorzy potoków nie muszą pamiętać, aby dodać ten krok. Tworzymy dekorator, który automatycznie wprowadza krok. Nasz dekorator potoku wprowadza niestandardowe zadanie, które wykonuje skanowanie antywirusowe na końcu każdego zadania potoku.

Napiwek

Zapoznaj się z naszą najnowszą dokumentacją dotyczącą programowania rozszerzeń przy użyciu zestawu SDK rozszerzenia usługi Azure DevOps.

1. Dodawanie współtworzenia do rozszerzenia

W poniższym przykładzie założono, że znasz modele współtworzenia.

  1. Utwórz rozszerzenie. Po utworzeniu rozszerzenia masz vss-extension.json plik.
  2. Dodaj wkład do vss-extension.json pliku dla naszego nowego dekoratora potoku.

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

Opcje współtworzenia

Przyjrzyjmy się właściwościom i tym, do czego służą:

Właściwości opis
id Identyfikator udziału. Musi być unikatowy wśród współtworzenia w tym rozszerzeniu.
type Określa, że ten wkład jest dekoratorem potoku. Musi być ciągiem ms.azure-pipelines.pipeline-decorator.
targets Dekoratory mogą być uruchamiane przed zadaniem/określonym zadaniem, po lub obu tych elementach. Aby uzyskać dostępne opcje, zobacz poniższą tabelę.
properties.template (Wymagane) Szablon to plik YAML zawarty w rozszerzeniu, który definiuje kroki dekoratora potoku. Jest to ścieżka względna z katalogu głównego folderu rozszerzenia.
properties.targettask Identyfikator zadania docelowego używany dla ms.azure-pipelines-agent-job.pre-task-tasks elementów docelowych lub ms.azure-pipelines-agent-job.post-task-tasks docelowych. Musi być ciągiem GUID, na przykład 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Elementy docelowe

Obiekt docelowy opis
ms.azure-pipelines-agent-job.pre-job-tasks Uruchom przed innymi zadaniami w klasycznym potoku kompilacji lub YAML. Ze względu na różnice w sposobie wyewidencjonowania kodu źródłowego ten element docelowy jest uruchamiany po wyewidencjonowania w potoku YAML, ale przed wyewidencjonowanie w klasycznym potoku kompilacji.
ms.azure-pipelines-agent-job.post-checkout-tasks Uruchom polecenie po ostatnim checkout zadaniu w klasycznym potoku kompilacji lub YAML.
ms.azure-pipelines-agent-job.post-job-tasks Uruchamiane po innych zadaniach w klasycznym potoku kompilacji lub YAML.
ms.azure-pipelines-agent-job.pre-task-tasks Uruchom przed określonym zadaniem w klasycznej kompilacji lub potoku YAML.
ms.azure-pipelines-agent-job.post-task-tasks Uruchom polecenie po określonym zadaniu w klasycznej kompilacji lub potoku YAML.
ms.azure-release-pipelines-agent-job.pre-task-tasks Uruchom polecenie przed określonym zadaniem w klasycznym potoku RM.
ms.azure-release-pipelines-agent-job.post-task-tasks Uruchom polecenie po określonym zadaniu w klasycznym potoku RM.
ms.azure-release-pipelines-agent-job.pre-job-tasks Uruchom przed innymi zadaniami w klasycznym potoku RM.
ms.azure-release-pipelines-agent-job.post-job-tasks Uruchamianie po innych zadaniach w klasycznym potoku RM.

Uwaga

Zadania wdrażania w potoku YAML obsługują ms.azure-pipelines-agent-job.pre-job-tasks tylko elementy docelowe i ms.azure-pipelines-agent-job.post-job-tasks . Zadania obsługują wszystkie docelowe potoki YAML.

W tym przykładzie użyjemy polecenia ms.azure-pipelines-agent-job.post-job-tasks , ponieważ chcemy uruchomić na końcu wszystkich zadań kompilacji.

To rozszerzenie współtworzy dekorator potoku. Następnie utworzymy plik YAML szablonu w celu zdefiniowania zachowania dekoratora.

2. Tworzenie pliku YAML dekoratora

We właściwościach rozszerzenia wybraliśmy nazwę "my-decorator.yml". Utwórz ten plik w katalogu głównym udziału. Zawiera zestaw kroków do uruchomienia po każdym zadaniu. Zaczynamy od podstawowego przykładu i pracujemy nad pełnym zadaniem.

my-decorator.yml (wersja początkowa)

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

Uwaga

Zadania dekoratora potoków z użyciem połączenia z usługą nie są obsługiwane w przypadku klasycznych potoków wydania.

3. Instalowanie dekoratora

Aby dodać dekorator potoku do organizacji, należy zainstalować rozszerzenie. Tylko rozszerzenia prywatne mogą współtworzyć dekoratory potoków. Aby można było używać rozszerzenia, należy go utworzyć i udostępnić organizacji.

Po udostępnieniu rozszerzenia organizacji wyszukaj rozszerzenie i zainstaluj je.

Zapisz plik, a następnie skompiluj i zainstaluj rozszerzenie. Tworzenie i uruchamianie podstawowego potoku. Dekorator automatycznie wprowadza nasz dir skrypt na końcu każdego zadania. Przebieg potoku wygląda podobnie do poniższego przykładu.

Pipeline decorator running a simple script

Uwaga

Dekorator jest uruchamiany w każdym zadaniu w każdym potoku w organizacji. W kolejnych krokach dodajemy logikę do kontrolowania, kiedy i jak działa dekorator.

4. Warunki wstrzykiwania

W naszym przykładzie musimy uruchomić skaner wirusów tylko wtedy, gdy dane wyjściowe kompilacji mogą zostać opublikowane publicznie. Załóżmy, że tylko kompilacje z gałęzi domyślnej (zazwyczaj main) są kiedykolwiek wydawane. Należy ograniczyć dekorator do zadań uruchomionych względem gałęzi domyślnej.

Zaktualizowany plik wygląda następująco:

my-decorator.yml (poprawiona wersja)

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

Możesz zacząć widzieć moc tego punktu rozszerzalności. Użyj kontekstu bieżącego zadania, aby warunkowo wstrzyknąć kroki w czasie wykonywania. Użyj wyrażeń YAML, aby podjąć decyzje dotyczące kroków, które należy wstrzyknąć i kiedy. Zobacz kontekst wyrażenia dekoratora potoku, aby uzyskać pełną listę dostępnych danych.

Jest inny warunek, który należy wziąć pod uwagę: co zrobić, jeśli użytkownik uwzględnił już krok skanowania antywirusowego? Nie powinniśmy tracić czasu na ponowne uruchomienie. W tym prostym przykładzie udamy, że każde script zadanie znalezione w zadaniu uruchamia skaner wirusów. (W rzeczywistej implementacji będziesz mieć zadanie niestandardowe, aby to sprawdzić).

Identyfikator zadania skryptu to d9bafed4-0b18-4f58-968d-86655b4d2ce9. Jeśli zobaczymy inne zadanie skryptu, nie powinniśmy wprowadzać naszych.

my-decorator.yml (wersja ostateczna)

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. Określ zadanie docelowe

Można określić identyfikator zadania docelowego i wstrzyknąć zadania przed lub po tym zadaniu docelowym. Aby określić zadanie docelowe, można zmodyfikować plik manifestu vss-extension.json, tak jak w poniższym przykładzie.

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

Po skonfigurowaniu właściwości "targettask" można określić identyfikator zadania docelowego. Zadania zostaną wprowadzone przed/po wszystkich wystąpieniach określonego zadania docelowego.

Określanie iniekcji danych wejściowych zadania docelowego

Można określić listę danych wejściowych zadania docelowego, które chcesz wstrzyknąć jako dane wejściowe do wstrzykniętego zadania.

Ta funkcja jest przeznaczona do pracy z niestandardowymi zadaniami potoku. Nie ma na celu zapewnienia dostępu do docelowych danych wejściowych zadań potoku za pośrednictwem zmiennych potoku.

Aby uzyskać dostęp do danych wejściowych zadania potoku docelowego (danych wejściowych z prefiksem target_ ), wstrzyknięte zadanie potoku powinno używać metod z elementu azure-pipelines-tasks-task-lib, a nie zmiennych potoku, na przykład const inputString = tl.getInput('target_targetInput')).

W tym celu możesz utworzyć własne niestandardowe zadanie potoku i użyć w nim docelowych danych wejściowych. Jeśli potrzebujesz funkcji jednego z wbudowanych zadań, takich jak CmdLine@2, możesz utworzyć kopię zadania CmdLine@2 i opublikować je za pomocą rozszerzenia dekoratora.

Uwaga

Ta funkcja jest dostępna tylko dla zadań, które są wstrzykiwane przed lub po zadaniu docelowym.

Aby określić tę listę danych wejściowych, możesz zmodyfikować plik manifestu vss-extension.json, podobnie jak w poniższym przykładzie.

vss-extension.json (wersja wprowadzonych danych wejściowych zadania)

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

Konfigurując właściwość "targettaskinputs", można określić listę danych wejściowych, które mają zostać wprowadzone. Te dane wejściowe zostaną wprowadzone do zadania z prefiksem "target_" i będą dostępne w wstrzykniętym zadaniu, na przykład target_target-task-input.

Uwaga

Docelowe dane wejściowe zadań, które pobierają wartości wpisów tajnych ze zmiennymi lub pobierają je z innych zadań, nie będą wstrzykiwane.

Debugowanie

Może być konieczne debugowanie podczas tworzenia dekoratora. Możesz również zobaczyć, jakie dane są dostępne w kontekście.

Zmienną system.debugContext można ustawić na true podczas kolejki potoku. Następnie przyjrzyj się stronie podsumowania potoku.

Zobaczysz coś podobnego do poniższego obrazu.

View pipeline decorator context

Wybierz zadanie, aby wyświetlić dzienniki, które pokazują wartości środowiska uruchomieniowego i czy kontekst jest dostępny.