Menulis dekorator alur

Artikel
10/27/2023

Layanan Azure DevOps | Azure DevOps Server 2022

Dekorator alur memungkinkan Anda menambahkan langkah-langkah ke awal dan akhir setiap pekerjaan. Proses penulisan dekorator alur berbeda dari menambahkan langkah-langkah ke satu definisi karena berlaku untuk semua alur dalam organisasi.

Misalkan organisasi Anda memerlukan menjalankan pemindai virus pada semua output build yang dapat dirilis. Penulis alur tidak perlu ingat untuk menambahkan langkah tersebut. Kami membuat dekorator yang secara otomatis menyuntikkan langkah. Dekorator alur kami menyuntikkan tugas kustom yang melakukan pemindaian virus di akhir setiap pekerjaan alur.

Tip

Lihat dokumentasi terbaru kami tentang pengembangan ekstensi menggunakan Azure DevOps Extension SDK.

1. Tambahkan kontribusi ke ekstensi

Contoh berikut mengasumsikan Anda terbiasa dengan model kontribusi.

Buat ekstensi. Setelah ekstensi dibuat, Anda memiliki vss-extension.json file.
Tambahkan kontribusi ke vss-extension.json file untuk dekorator alur baru kami.

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

Opsi kontribusi

Mari kita lihat properti dan apa yang digunakan untuk:

Properti	Deskripsi
`id`	Pengidentifikasi kontribusi. Harus unik di antara kontribusi dalam ekstensi ini.
`type`	Menentukan bahwa kontribusi ini adalah dekorator alur. Harus berupa string `ms.azure-pipelines.pipeline-decorator`.
`targets`	Dekorator dapat berjalan sebelum pekerjaan/tugas yang ditentukan, setelah, atau keduanya. Lihat tabel berikut untuk opsi yang tersedia.
`properties.template`	(Diperlukan) Templat adalah file YAML yang disertakan dalam ekstensi Anda, yang menentukan langkah-langkah untuk dekorator alur Anda. Ini adalah jalur relatif dari akar folder ekstensi Anda.
`properties.targettask`	ID tugas target yang digunakan untuk `ms.azure-pipelines-agent-job.pre-task-tasks` atau `ms.azure-pipelines-agent-job.post-task-tasks` target. Harus berupa string GUID seperti `89b8ac58-8cb7-4479-a362-1baaacc6c7ad`

Target

Target	Deskripsi
`ms.azure-pipelines-agent-job.pre-job-tasks`	Jalankan sebelum tugas lain dalam build klasik atau alur YAML. Karena perbedaan bagaimana checkout kode sumber terjadi, target ini berjalan setelah checkout di alur YAML tetapi sebelum checkout di alur build klasik.
`ms.azure-pipelines-agent-job.post-checkout-tasks`	Jalankan setelah tugas terakhir `checkout` dalam build klasik atau alur YAML.
`ms.azure-pipelines-agent-job.post-job-tasks`	Jalankan setelah tugas lain dalam build klasik atau alur YAML.
`ms.azure-pipelines-agent-job.pre-task-tasks`	Jalankan sebelum tugas yang ditentukan dalam build klasik atau alur YAML.
`ms.azure-pipelines-agent-job.post-task-tasks`	Jalankan setelah tugas yang ditentukan dalam build klasik atau alur YAML.
`ms.azure-release-pipelines-agent-job.pre-task-tasks`	Jalankan sebelum tugas yang ditentukan dalam alur RM klasik.
`ms.azure-release-pipelines-agent-job.post-task-tasks`	Jalankan setelah tugas yang ditentukan dalam alur RM klasik.
`ms.azure-release-pipelines-agent-job.pre-job-tasks`	Jalankan sebelum tugas lain dalam alur RM klasik.
`ms.azure-release-pipelines-agent-job.post-job-tasks`	Jalankan setelah tugas lain dalam alur RM klasik.

Catatan

Pekerjaan penyebaran dalam alur YAML hanya mendukung ms.azure-pipelines-agent-job.pre-job-tasks dan ms.azure-pipelines-agent-job.post-job-tasks menargetkan. Pekerjaan mendukung semua target alur YAML. Pekerjaan penyebaran tidak didukung dalam alur rilis klasik.

Dalam contoh ini, kami menggunakan ms.azure-pipelines-agent-job.post-job-tasks karena kami ingin menjalankan di akhir semua pekerjaan build.

Ekstensi ini berkontribusi pada dekorator alur. Selanjutnya, kita membuat file YAML templat untuk menentukan perilaku dekorator.

2. Buat file YAML dekorator

Di properti ekstensi, kami memilih nama "my-decorator.yml". Buat file tersebut di akar kontribusi Anda. Ini menyimpan serangkaian langkah yang akan dijalankan setelah setiap pekerjaan. Kita mulai dengan contoh dasar dan bekerja hingga tugas penuh.

my-decorator.yml (versi awal)

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

Catatan

Tugas dekorator alur dengan penggunaan koneksi layanan tidak didukung untuk alur rilis klasik.

3. Pasang dekorator

Untuk menambahkan dekorator alur ke organisasi, Anda harus menginstal ekstensi. Hanya ekstensi privat yang dapat berkontribusi pada dekorator alur. Ekstensi harus ditulis dan dibagikan dengan organisasi Anda sebelum dapat digunakan.

Setelah ekstensi dibagikan dengan organisasi Anda, cari ekstensi dan instal.

Simpan file, lalu buat dan instal ekstensi. Membuat dan menjalankan alur dasar. Dekorator secara otomatis menyuntikkan skrip kami dir di akhir setiap pekerjaan. Eksekusi alur terlihat mirip dengan contoh berikut.

Dekorator alur yang menjalankan skrip sederhana

Catatan

Dekorator berjalan pada setiap pekerjaan di setiap alur dalam organisasi. Pada langkah selanjutnya, kami menambahkan logika untuk mengontrol kapan dan bagaimana dekorator berjalan.

4. Menyuntikkan kondisi

Dalam contoh kami, kita hanya perlu menjalankan pemindai virus jika output build mungkin dirilis ke publik. Katakanlah hanya build dari cabang default (biasanya main) yang pernah dirilis. Kita harus membatasi dekorator untuk pekerjaan yang berjalan terhadap cabang default.

File yang diperbarui terlihat seperti ini:

my-decorator.yml (versi yang direvisi)

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

Anda dapat mulai melihat kekuatan titik ekstensibilitas ini. Gunakan konteks pekerjaan saat ini untuk menyuntikkan langkah-langkah secara kondisional pada runtime. Gunakan ekspresi YAML untuk membuat keputusan tentang langkah-langkah apa yang akan disuntikkan dan kapan. Lihat konteks ekspresi dekorator alur untuk daftar lengkap data yang tersedia.

Ada kondisi lain yang perlu kita pertimbangkan: bagaimana jika pengguna sudah menyertakan langkah pemindaian virus? Kita tidak boleh membuang waktu menjalankannya lagi. Dalam contoh sederhana ini, kita akan berpura-pura bahwa tugas apa pun script yang ditemukan dalam pekerjaan menjalankan pemindai virus. (Dalam implementasi nyata, Anda akan memiliki tugas kustom untuk memeriksanya sebagai gantinya.)

ID tugas skrip adalah d9bafed4-0b18-4f58-968d-86655b4d2ce9. Jika kita melihat tugas skrip lain, kita tidak boleh menyuntikkan tugas kita.

my-decorator.yml (versi akhir)

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. Tentukan tugas target

Anda dapat menentukan ID tugas target, dan menyuntikkan tugas sebelum atau sesudah tugas target ini. Untuk menentukan tugas target, Anda dapat memodifikasi file manifes vss-extension.json seperti contoh berikut.

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

Saat menyiapkan properti 'targettask', Anda dapat menentukan ID tugas target. Tugas akan disuntikkan sebelum/sesudah semua instans tugas target yang ditentukan.

Tentukan injeksi input tugas target

Anda dapat menentukan daftar input tugas target yang ingin Anda masukkan sebagai input ke tugas yang disuntikkan.

Fitur ini dirancang untuk bekerja dengan tugas alur kustom. Ini tidak dimaksudkan untuk menyediakan akses ke input tugas alur target melalui variabel alur.

Untuk mendapatkan akses ke input tugas alur target (input dengan target_ awalan), tugas alur yang disuntikkan harus menggunakan metode dari azure-pipelines-tasks-task-lib, dan bukan variabel alur, misalnya const inputString = tl.getInput('target_targetInput')).

Untuk melakukannya, Anda dapat membuat tugas alur kustom Anda sendiri dan menggunakan input target di sana. Jika Anda memerlukan fungsionalitas salah satu tugas di luar kotak, seperti CmdLine@2, Anda dapat membuat salinan tugas CmdLine@2 dan menerbitkannya dengan ekstensi dekorator Anda.

Catatan

Fungsionalitas ini hanya tersedia untuk tugas yang disuntikkan sebelum atau sesudah tugas target.

Untuk menentukan daftar input ini, Anda dapat memodifikasi file manifes vss-extension.json seperti contoh berikut.

vss-extension.json (versi input tugas yang disuntikkan)

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

Dengan menyiapkan properti 'targettaskinputs', Anda dapat menentukan daftar input yang diharapkan untuk disuntikkan. Input ini akan disuntikkan ke dalam tugas dengan awalan "target_" dan akan tersedia dalam tugas yang disuntikkan seperti target_target-task-input.

Catatan

Input tugas target yang mendapatkan nilai rahasia dengan variabel atau mendapatkannya dari tugas lain tidak akan disuntikkan.

Debug

Anda mungkin perlu men-debug saat membuat dekorator. Anda mungkin juga ingin melihat data apa yang telah Anda sediakan dalam konteks.

Anda dapat mengatur variabel ke system.debugContext true saat Anda mengantrekan alur. Kemudian, lihat halaman ringkasan alur.

Anda melihat sesuatu yang mirip dengan gambar berikut.

Menampilkan konteks dekorator alur

Pilih tugas untuk melihat log, yang menampilkan nilai runtime dan bahwa konteks tersedia.

Bagikan melalui

Menulis dekorator alur

1. Tambahkan kontribusi ke ekstensi

vss-extension.json

Opsi kontribusi

Target

2. Buat file YAML dekorator

my-decorator.yml (versi awal)

3. Pasang dekorator

4. Menyuntikkan kondisi

my-decorator.yml (versi yang direvisi)

my-decorator.yml (versi akhir)

5. Tentukan tugas target

vss-extension.json

Tentukan injeksi input tugas target

vss-extension.json (versi input tugas yang disuntikkan)

Debug

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Menulis dekorator alur

1. Tambahkan kontribusi ke ekstensi

vss-extension.json

Opsi kontribusi

Target

2. Buat file YAML dekorator

my-decorator.yml (versi awal)

3. Pasang dekorator

4. Menyuntikkan kondisi

my-decorator.yml (versi yang direvisi)

my-decorator.yml (versi akhir)

5. Tentukan tugas target

vss-extension.json

Tentukan injeksi input tugas target

vss-extension.json (versi input tugas yang disuntikkan)

Debug

Artikel terkait

Saran dan Komentar

Sumber Daya Tambahan: