İşlem hattı dekoratörü yazma

Azure DevOps Services | Azure DevOps Server 2022

İşlem hattı dekoratörleri, her işin başına ve sonuna adım eklemenize olanak sağlar. İşlem hattı dekoratörünü yazma işlemi, bir kuruluştaki tüm işlem hatları için geçerli olduğundan tek bir tanıma adım eklemekten farklıdır.

Kuruluşunuzun yayınlanabilir tüm derleme çıkışlarında bir virüs tarayıcısı çalıştırması gerektiğini varsayalım. İşlem hattı yazarlarının bu adımı eklemeyi hatırlaması gerekmez. Adımı otomatik olarak ekleyen bir dekoratör oluştururuz. İşlem hattı dekoratörümüz, her işlem hattı işinin sonunda virüs taraması yapacak özel bir görev ekler.

İpucu

Azure DevOps Uzantı SDK'sını kullanarak uzantı geliştirmeyle ilgili en yeni belgelerimize göz atın.

1. Uzantıya katkı ekleme

Aşağıdaki örnek, katkı modellerini bildiğinizi varsayar.

  1. Uzantı oluşturun. Uzantınız oluşturulduktan sonra bir vss-extension.json dosyanız olur.
  2. Yeni işlem hattı dekoratörümüz için dosyaya vss-extension.json katkılar ekleyin.

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

Katkı seçenekleri

Şimdi özelliklere ve ne için kullanıldıklarına göz atalım:

Özellik Açıklama
id Katkı tanımlayıcısı. Bu uzantıdaki katkılar arasında benzersiz olmalıdır.
type Bu katkının bir işlem hattı dekoratörü olduğunu belirtir. dizesi ms.azure-pipelines.pipeline-decoratorolmalıdır.
targets Dekoratörler, işinizden/belirtilen görevden önce, sonra veya her ikisi birden çalıştırılabilir. Kullanılabilir seçenekler için aşağıdaki tabloya bakın.
properties.template (Gerekli) Şablon, uzantınıza dahil edilen ve işlem hattı dekoratörünüzün adımlarını tanımlayan bir YAML dosyasıdır. Uzantı klasörünüzün kökünden göreli bir yoldur.
properties.targettask veya ms.azure-pipelines-agent-job.post-task-tasks hedefleri için ms.azure-pipelines-agent-job.pre-task-tasks kullanılan hedef görev kimliği. Gibi GUID dizesi olmalıdır 89b8ac58-8cb7-4479-a362-1baaacc6c7ad

Hedefler

Hedef Açıklama
ms.azure-pipelines-agent-job.pre-job-tasks Klasik derleme veya YAML işlem hattındaki diğer görevlerde çalıştırma. Kaynak kodu kullanıma alma işlemindeki farklılıklar nedeniyle bu hedef, YAML işlem hattında kullanıma alma sonrasında ancak klasik derleme işlem hattında kullanıma almadan önce çalışır.
ms.azure-pipelines-agent-job.post-checkout-tasks Klasik derlemede veya YAML işlem hattında son checkout görevden sonra çalıştırın.
ms.azure-pipelines-agent-job.post-job-tasks Klasik bir derlemede veya YAML işlem hattında diğer görevlerin ardından çalıştırın.
ms.azure-pipelines-agent-job.pre-task-tasks Klasik derlemede veya YAML işlem hattında belirtilen görevden önce çalıştırın.
ms.azure-pipelines-agent-job.post-task-tasks Klasik derlemede veya YAML işlem hattında belirtilen görevden sonra çalıştırın.
ms.azure-release-pipelines-agent-job.pre-task-tasks Klasik RM işlem hattında belirtilen görevden önce komutunu çalıştırın.
ms.azure-release-pipelines-agent-job.post-task-tasks Klasik RM işlem hattında belirtilen görevden sonra çalıştır.
ms.azure-release-pipelines-agent-job.pre-job-tasks Klasik RM işlem hattındaki diğer görevlerde çalıştırma.
ms.azure-release-pipelines-agent-job.post-job-tasks Klasik RM işlem hattındaki diğer görevlerin ardından çalıştırın.

Not

YAML işlem hattındaki dağıtım işleri yalnızca ve ms.azure-pipelines-agent-job.post-job-tasks hedeflerini desteklerms.azure-pipelines-agent-job.pre-job-tasks. İşler tüm YAML işlem hattı hedeflerini destekler.

Bu örnekte, tüm derleme işlerinin sonunda çalıştırmak istediğimiz için kullanırız ms.azure-pipelines-agent-job.post-job-tasks .

Bu uzantı bir işlem hattı dekoratörüne katkıda bulunur. Ardından, dekoratörün davranışını tanımlamak için bir şablon YAML dosyası oluşturacağız.

2. Dekoratör YAML dosyası oluşturma

Uzantının özelliklerinde "my-decorator.yml" adını seçtik. Katkınızın kökünde bu dosyayı oluşturun. Her işten sonra çalıştırılacak adım kümesini tutar. Temel bir örnekle başlıyoruz ve tam görev için çalışıyoruz.

my-decorator.yml (ilk sürüm)

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

Not

Hizmet bağlantısı kullanımına sahip işlem hattı dekoratör görevleri klasik yayın işlem hatlarında desteklenmez.

3. Dekoratör'ü yükleyin

Kuruluşunuza işlem hattı dekoratörü eklemek için bir uzantı yüklemeniz gerekir. Yalnızca özel uzantılar işlem hattı dekoratörlerine katkıda bulunabilir. Uzantının kullanılabilmesi için önce uzantının yazılması ve kuruluşunuzla paylaşılması gerekir.

Uzantı kuruluşunuzla paylaşıldıktan sonra uzantıyı arayın ve yükleyin.

Dosyayı kaydedin, ardından uzantıyı derleyip yükleyin. Temel işlem hattı oluşturma ve çalıştırma. Dekoratör her işin sonuna betiğimizi dir otomatik olarak ekler. İşlem hattı çalıştırması aşağıdaki örneğe benzer.

Pipeline decorator running a simple script

Not

Dekoratör, kuruluştaki her işlem hattındaki her işte çalışır. Sonraki adımlarda dekoratörün ne zaman ve nasıl çalıştığını denetlemek için mantık ekleyeceğiz.

4. Ekleme koşulları

Örneğimizde, yalnızca derleme çıkışları genel kullanıma sunulacaksa virüs tarayıcısını çalıştırmamız gerekir. Yalnızca varsayılan daldan (genellikle main) derlemelerin yayımlandığını varsayalım. Dekoratör'leri varsayılan dalda çalışan işlerle sınırlamamız gerekir.

Güncelleştirilmiş dosya şöyle görünür:

my-decorator.yml (düzeltilmiş sürüm)


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

Bu genişletilebilirlik noktasının gücünü görmeye başlayabilirsiniz. Çalışma zamanında koşullu olarak adımlar eklemek için geçerli işin bağlamını kullanın. Hangi adımların ne zaman ve ne zaman eklenmiş olduğu hakkında kararlar almak için YAML ifadelerini kullanın. Kullanılabilir verilerin tam listesi için bkz . işlem hattı dekoratör ifadesi bağlamı .

Göz önünde bulundurmamız gereken başka bir koşul daha var: Kullanıcı virüs tarama adımını zaten eklemişse ne olur? Tekrar çalıştırmakla zaman kaybetmemeliyiz. Bu basit örnekte, işte bulunan tüm script görevlerin virüs tarayıcısını çalıştırdığını varsayacağız. (Gerçek bir uygulamada bunun yerine denetlemek için özel bir göreviniz olur.)

Betik görevinin kimliği şeklindedir d9bafed4-0b18-4f58-968d-86655b4d2ce9. Başka bir betik görevi görürsek, bizimkini eklememeliyiz.

my-decorator.yml (son sürüm)


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. Hedef görev belirtin

Hedef görev kimliğini belirtebilir ve görevleri bu hedef görevden önce veya sonra ekleyebilirsiniz. Hedef görevi belirtmek için vss-extension.json bildirim dosyasını aşağıdaki örnekte olduğu gibi değiştirebilirsiniz.

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

'targettask' özelliğini ayarladığınızda, hedef görevin kimliğini belirtebilirsiniz. Görevler, belirtilen hedef görevin tüm örneklerinden önce/sonra eklenecektir.

Hedef görevin giriş eklemesini belirtme

Eklenen göreve giriş olarak eklemek istediğiniz hedef görevin girişlerinin listesini belirtebilirsiniz.

Bu özellik, özel işlem hattı görevleriyle çalışacak şekilde tasarlanmıştır. İşlem hattı değişkenleri aracılığıyla hedef işlem hattı görev girişlerine erişim sağlamak için tasarlanmamıştır.

Hedef işlem hattı görev girişlerine (ön ekli target_ girişler) erişim elde etmek için eklenen işlem hattı görevi, işlem hattı değişkenlerini değil azure-pipelines-tasks-task-lib yöntemini kullanmalıdır. Örneğin const inputString = tl.getInput('target_targetInput')).

Bunu yapmak için kendi özel işlem hattı görevinizi oluşturabilir ve hedef girişleri orada kullanabilirsiniz. gibi CmdLine@2kullanıma hazır görevlerden birinin işlevselliğine ihtiyacınız varsa, CmdLine@2 görevinin bir kopyasını oluşturabilir ve bunu dekoratör uzantınızla yayımlayabilirsiniz.

Not

Bu işlev yalnızca hedef görevden önce veya sonra eklenen görevler için kullanılabilir.

Bu giriş listesini belirtmek için vss-extension.json bildirim dosyasını aşağıdaki örnekte olduğu gibi değiştirebilirsiniz.

vss-extension.json (eklenen görev girişleri sürümü)

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

'targettaskinputs' özelliğini ayarlayarak, eklemesi beklenen girişlerin listesini belirtebilirsiniz. Bu girişler göreve "target_" ön eki ile eklenir ve gibi target_target-task-inputeklenen görevde kullanılabilir.

Not

Değişkenlerle gizli dizi değerleri alan veya bunları diğer görevlerden alan hedef görev girişleri eklenmez.

Hata Ayıklama

Dekoratörünüzü oluştururken hata ayıklamanız gerekebilir. Ayrıca, bağlam içinde hangi verilere sahip olduğunuzu da görmek isteyebilirsiniz.

bir işlem hattını kuyruğa aldığınızda değişkenini system.debugContexttrue olarak ayarlayabilirsiniz. Ardından işlem hattı özet sayfasına bakın.

Aşağıdaki görüntüye benzer bir şey görürsünüz.

View pipeline decorator context

Çalışma zamanı değerlerini gösteren ve bağlamın kullanılabilir olduğunu gösteren günlükleri görmek için görevi seçin.