Bagikan melalui

Menambahkan ekstensi tugas alur kerja kustom

Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Panduan ini memandu Anda membuat, menguji, dan menerbitkan tugas build atau rilis kustom sebagai ekstensi Azure DevOps. Tugas alur kustom memungkinkan Anda memperluas Azure DevOps dengan fungsionalitas khusus yang disesuaikan dengan alur kerja tim Anda, dari utilitas sederhana hingga integrasi kompleks dengan sistem eksternal.

Pelajari cara melakukan tugas berikut:

  • Menyiapkan lingkungan pengembangan dan struktur proyek
  • Membuat logika tugas menggunakan TypeScript dan Pustaka Tugas Azure Pipelines
  • Menerapkan pengujian unit komprehensif dengan kerangka kerja tiruan
  • Mengemas ekstensi Anda untuk distribusi
  • Menerbitkan ke Visual Studio Marketplace
  • Menyiapkan alur CI/CD otomatis untuk pemeliharaan ekstensi

Untuk informasi selengkapnya tentang Azure Pipelines, lihat Apa itu Azure Pipelines?

Catatan

Artikel ini membahas tugas agen dalam ekstensi berbasis agen. Untuk informasi tentang tugas server dan ekstensi berbasis server, lihat Penulisan Tugas Server.

Prasyarat

Sebelum memulai, pastikan Anda memiliki persyaratan berikut:

Komponen Persyaratan Deskripsi
Organisasi Azure DevOps Diperlukan Membuat organisasi jika Anda tidak memilikinya
Editor teks Direkomendasikan Visual Studio Code untuk IntelliSense dan dukungan penelusuran kesalahan
Node.js Diperlukan Instal versi terbaru (disarankanNode.js 20 atau yang lebih baru)
Pengkompilasi TypeScript Diperlukan Instal versi terbaru (versi 4.6.3 atau yang lebih baru)
Azure DevOps CLI (tfx-cli) Diperlukan Menginstal menggunakan npm i -g tfx-cli ekstensi paket
SDK Ekstensi Azure DevOps Diperlukan Menginstal paket azure-devops-extension-sdk
Kerangka kerja pengujian Diperlukan Mocha untuk pengujian unit (diinstal selama penyiapan)

Struktur proyek

Buat home direktori untuk proyek Anda. Setelah Anda menyelesaikan tutorial ini, ekstensi Anda harus memiliki struktur berikut:

|--- README.md    
|--- images                        
    |--- extension-icon.png  
|--- buildandreleasetask            // Task scripts location
    |--- task.json                  // Task definition
    |--- index.ts                   // Main task logic
    |--- package.json               // Node.js dependencies
    |--- tests/                     // Unit tests
        |--- _suite.ts
        |--- success.ts
        |--- failure.ts
|--- vss-extension.json             // Extension manifest

Penting

Komputer pengembangan Anda harus menjalankan versi terbaru Node.js untuk memastikan kompatibilitas dengan lingkungan produksi. Perbarui file Anda task.json untuk menggunakan Node 20:

"execution": {
    "Node20_1": {
      "target": "index.js"
    }
}

1. Buat tugas kustom

Bagian ini memandu Anda membuat struktur dasar dan implementasi tugas kustom Anda. Semua file dalam langkah ini harus dibuat dalam folder di buildandreleasetask dalam direktori proyek home Anda.

Catatan

Panduan ini menggunakan Windows dengan PowerShell. Langkah-langkahnya berfungsi pada semua platform, tetapi sintaks variabel lingkungan berbeda. Di Mac atau Linux, ganti $env:<var>=<val> dengan export <var>=<val>.

Menyiapkan perancah tugas

Buat struktur proyek dasar dan instal dependensi yang diperlukan:

  1. Untuk menginisialisasi proyek Node.js, buka PowerShell, buka folder Anda buildandreleasetask , dan jalankan:

    npm init --yes

    File package.json dibuat dengan pengaturan default. Bendera --yes menerima semua opsi default secara otomatis.

    Tips

    Agen Azure Pipelines mengharapkan folder tugas menyertakan modul simpul. Salin node_modules ke folder Anda buildandreleasetask . Untuk mengelola ukuran file VSIX (batas 50 MB), pertimbangkan untuk menjalankan npm install --production atau npm prune --production sebelum pengemasan.

  2. Instal Pustaka Tugas Azure Pipelines:

    npm install azure-pipelines-task-lib --save

  3. Pasang definisi jenis TypeScript:

    npm install @types/node --save-dev
npm install @types/q --save-dev

  4. Menyiapkan pengecualian kontrol versi

    echo node_modules > .gitignore

    Proses build Anda harus berjalan npm install untuk membangun kembali node_modules setiap kali.

  5. Instal dependensi pengujian:

    npm install mocha --save-dev -g
npm install sync-request --save-dev
npm install @types/mocha --save-dev

  6. Instal pengkompilasi TypeScript:

    npm install typescript@4.6.3 -g --save-dev

    Catatan

    Instal TypeScript secara global untuk memastikan tsc perintah tersedia. Tanpanya, TypeScript 2.3.4 digunakan secara default.

  7. Mengonfigurasi kompilasi TypeScript:

    tsc --init --target es2022

    File tsconfig.json dibuat dengan pengaturan target ES2022.

Menerapkan logika tugas

Dengan perancah selesai, buat file tugas inti yang menentukan fungsionalitas dan metadata:

  1. Membuat file definisi tugas: Buat task.json di buildandreleasetask folder. File ini menjelaskan tugas Anda ke sistem Azure Pipelines, menentukan input, pengaturan eksekusi, dan presentasi UI.

    {
 "$schema": "https://raw.githubusercontent.com/Microsoft/azure-pipelines-task-lib/master/tasks.schema.json",
 "id": "{{taskguid}}",
 "name": "{{taskname}}",
 "friendlyName": "{{taskfriendlyname}}",
 "description": "{{taskdescription}}",
 "helpMarkDown": "",
 "category": "Utility",
 "author": "{{taskauthor}}",
 "version": {
     "Major": 0,
     "Minor": 1,
     "Patch": 0
 },
 "instanceNameFormat": "Echo $(samplestring)",
 "inputs": [
     {
         "name": "samplestring",
         "type": "string",
         "label": "Sample String",
         "defaultValue": "",
         "required": true,
         "helpMarkDown": "A sample string"
     }
 ],
 "execution": {
     "Node20_1": {
         "target": "index.js"
     }
 }
 }

    Catatan

    Ganti {{placeholders}} dengan informasi aktual tugas Anda. harus taskguid unik. Hasilkan menggunakan PowerShell: (New-Guid).Guid

  2. Untuk menerapkan logika tugas, buat index.ts dengan fungsionalitas utama tugas Anda:

    import tl = require('azure-pipelines-task-lib/task');

 async function run() {
     try {
         const inputString: string | undefined = tl.getInput('samplestring', true);
         if (inputString == 'bad') {
             tl.setResult(tl.TaskResult.Failed, 'Bad input was given');
             return;
         }
         console.log('Hello', inputString);
     }
     catch (err: any) {
         tl.setResult(tl.TaskResult.Failed, err.message);
     }
 }

 run();

  3. Kompilasi TypeScript ke JavaScript:

    tsc

    File index.js dibuat dari sumber TypeScript Anda.

Memahami komponen task.json

File task.json adalah inti dari definisi tugas Anda. Berikut adalah properti utamanya:

Properti Deskripsi Contoh
id Pengidentifikasi GUID unik untuk tugas Anda Dihasilkan menggunakan (New-Guid).Guid
name Nama tugas tanpa spasi (digunakan secara internal) MyCustomTask
friendlyName Nama tampilan ditampilkan di UI My Custom Task
description Deskripsi terperinci tentang fungsionalitas tugas Performs custom operations on files
author Penerbit atau nama penulis My Company
instanceNameFormat Bagaimana tugas muncul dalam langkah-langkah alur Process $(inputFile)
inputs Array parameter input Lihat jenis input berikut
execution Spesifikasi lingkungan eksekusi Node20_1, PowerShell3, dll.
restrictions Pembatasan keamanan untuk perintah dan variabel Direkomendasikan untuk tugas baru

Pembatasan keamanan

Untuk tugas produksi, tambahkan pembatasan keamanan untuk membatasi penggunaan perintah dan akses variabel:

"restrictions": {
  "commands": {
    "mode": "restricted"
  },
  "settableVariables": {
    "allowed": ["variable1", "test*"]
  }
}

Mode terbatas hanya memungkinkan perintah ini:

  • logdetail,logissue,complete,setprogress
  • setsecret,setvariable,debug,settaskvariable
  • prependpath, publish

Variabel allowlist mengontrol variabel mana yang dapat diatur melalui setvariable atau prependpath. Mendukung pola regex dasar.

Catatan

Fitur ini memerlukan agen versi 2.182.1 atau yang lebih baru.

Jenis dan contoh input

Jenis input umum untuk parameter tugas:

"inputs": [
    {
        "name": "stringInput",
        "type": "string",
        "label": "Text Input",
        "defaultValue": "",
        "required": true,
        "helpMarkDown": "Enter a text value"
    },
    {
        "name": "boolInput",
        "type": "boolean",
        "label": "Enable Feature",
        "defaultValue": "false",
        "required": false
    },
    {
        "name": "picklistInput",
        "type": "pickList",
        "label": "Select Option",
        "options": {
            "option1": "First Option",
            "option2": "Second Option"
        },
        "defaultValue": "option1"
    },
    {
        "name": "fileInput",
        "type": "filePath",
        "label": "Input File",
        "required": true,
        "helpMarkDown": "Path to the input file"
    }
]

Menguji tugas Anda secara lokal

Sebelum pengemasan, uji tugas Anda untuk memastikannya berfungsi dengan benar:

  1. Uji dengan input yang hilang (seharusnya gagal):

    node index.js

    Output yang diharapkan:

    ##vso[task.debug]agent.workFolder=undefined
##vso[task.debug]loading inputs and endpoints
##vso[task.debug]loaded 0
##vso[task.debug]task result: Failed
##vso[task.issue type=error;]Input required: samplestring
##vso[task.complete result=Failed;]Input required: samplestring

  2. Uji dengan input yang valid (harus berhasil):

    $env:INPUT_SAMPLESTRING="World"
node index.js

    Output yang diharapkan:

    ##vso[task.debug]agent.workFolder=undefined
##vso[task.debug]loading inputs and endpoints
##vso[task.debug]loading INPUT_SAMPLESTRING
##vso[task.debug]loaded 1
##vso[task.debug]samplestring=World
Hello World

  3. Penanganan kesalahan pengujian:

    $env:INPUT_SAMPLESTRING="bad"
node index.js

    Tindakan ini harus memicu jalur penanganan kesalahan dalam kode Anda.

    Tips

    Untuk informasi tentang pelari tugas dan versi Node.js, lihat Panduan pembaruan runner node.

Untuk informasi selengkapnya, lihat referensi tugas Build/release.

2. Menerapkan pengujian unit komprehensif

Menguji tugas Anda secara menyeluruh memastikan keandalan dan membantu menangkap masalah sebelum penyebaran ke alur produksi.

Menginstal dependensi pengujian

Instal alat pengujian yang diperlukan:

npm install mocha --save-dev -g
npm install sync-request --save-dev
npm install @types/mocha --save-dev

Membuat pengujian

  1. Buat tests folder di direktori tugas Anda yang _suite.ts berisi file:

     import * as path from 'path';
 import * as assert from 'assert';
 import * as ttm from 'azure-pipelines-task-lib/mock-test';

 describe('Sample task tests', function () {

     before( function() {
         // Setup before tests
     });

     after(() => {
         // Cleanup after tests
     });

     it('should succeed with simple inputs', function(done: Mocha.Done) {
         // Success test implementation
     });

     it('should fail if tool returns 1', function(done: Mocha.Done) {
         // Failure test implementation
     });    
   });

    Tips

    Folder pengujian Anda harus terletak di folder tugas (misalnya, buildandreleasetask). Jika Anda mengalami kesalahan permintaan sinkronisasi, instal di folder tugas: npm i --save-dev sync-request.

  2. Buat success.ts di direktori pengujian Anda untuk mensimulasikan keberhasilan eksekusi tugas:

     import ma = require('azure-pipelines-task-lib/mock-answer');
 import tmrm = require('azure-pipelines-task-lib/mock-run');
 import path = require('path');

 let taskPath = path.join(__dirname, '..', 'index.js');
 let tmr: tmrm.TaskMockRunner = new tmrm.TaskMockRunner(taskPath);

 // Set valid input for success scenario
 tmr.setInput('samplestring', 'human');

 tmr.run();

  3. Tambahkan pengujian keberhasilan ke file Anda _suite.ts :

     it('should succeed with simple inputs', function(done: Mocha.Done) {
     this.timeout(1000);

     let tp: string = path.join(__dirname, 'success.js');
     let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp);

     tr.runAsync().then(() => {
         console.log(tr.succeeded);
         assert.equal(tr.succeeded, true, 'should have succeeded');
         assert.equal(tr.warningIssues.length, 0, "should have no warnings");
         assert.equal(tr.errorIssues.length, 0, "should have no errors");
         console.log(tr.stdout);
         assert.equal(tr.stdout.indexOf('Hello human') >= 0, true, "should display Hello human");
         done();
     }).catch((error) => {
         done(error); // Ensure the test case fails if there's an error
     });
 });

  4. Buat failure.ts di direktori pengujian Anda untuk menguji penanganan kesalahan:

    import ma = require('azure-pipelines-task-lib/mock-answer');
import tmrm = require('azure-pipelines-task-lib/mock-run');
import path = require('path');

let taskPath = path.join(__dirname, '..', 'index.js');
let tmr: tmrm.TaskMockRunner = new tmrm.TaskMockRunner(taskPath);

// Set invalid input to trigger failure
tmr.setInput('samplestring', 'bad');

tmr.run();

  5. Tambahkan pengujian kegagalan ke file Anda _suite.ts :

     it('should fail if tool returns 1', function(done: Mocha.Done) {
     this.timeout(1000);

     const tp = path.join(__dirname, 'failure.js');
     const tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp);

     tr.runAsync().then(() => {
         console.log(tr.succeeded);
         assert.equal(tr.succeeded, false, 'should have failed');
         assert.equal(tr.warningIssues.length, 0, 'should have no warnings');
         assert.equal(tr.errorIssues.length, 1, 'should have 1 error issue');
         assert.equal(tr.errorIssues[0], 'Bad input was given', 'error issue output');
         assert.equal(tr.stdout.indexOf('Hello bad'), -1, 'Should not display Hello bad');
         done();
     });
 });

Jalankan pengujian Anda

Jalankan rangkaian pengujian:

# Compile TypeScript
tsc

# Run tests
mocha tests/_suite.js

Kedua tes harus lulus. Untuk output verbose (mirip dengan output konsol build), atur variabel lingkungan pelacakan:

$env:TASK_TEST_TRACE=1
mocha tests/_suite.js

Menguji praktik terbaik cakupan

  • Uji semua kombinasi input: Input yang valid, input yang tidak valid, input yang diperlukan hilang
  • Skenario kesalahan pengujian: Kegagalan jaringan, kesalahan sistem file, masalah izin
  • Menipu dependensi eksternal: Jangan mengandalkan layanan eksternal dalam pengujian unit
  • Memvalidasi output: Memeriksa output konsol, hasil tugas, dan artefak yang dihasilkan
  • Pengujian performa: Pertimbangkan untuk menambahkan pengujian untuk tugas yang memproses file besar

Praktik terbaik keamanan

  • Validasi input: Selalu validasi dan bersihkan input
  • Penanganan rahasia: Gunakan setSecret untuk data sensitif
  • Pembatasan perintah: Menerapkan pembatasan perintah untuk tugas produksi
  • Izin minimal: Minta izin yang diperlukan saja
  • Pembaruan reguler: Menjaga dependensi dan versi Node.js terkini

Setelah menguji tugas Anda secara lokal dan menerapkan pengujian unit yang komprehensif, kemas ke dalam ekstensi untuk Azure DevOps.

Menginstal alat pengemasan

Instal Antarmuka Baris Perintah Lintas Platform (tfx-cli):

npm install -g tfx-cli

Membuat manifes ekstensi

Manifes ekstensi (vss-extension.json) berisi semua informasi tentang ekstensi Anda, termasuk referensi ke folder dan gambar tugas Anda.

  1. Membuat folder gambar dengan extension-icon.png file

  2. Buat vss-extension.json di direktori akar ekstensi Anda (bukan di folder tugas):

    {
 "manifestVersion": 1,
 "id": "my-custom-tasks",
 "name": "My Custom Tasks",
 "version": "1.0.0",
 "publisher": "your-publisher-id",
 "targets": [
     {
         "id": "Microsoft.VisualStudio.Services"
     }
 ],
 "description": "Custom build and release tasks for Azure DevOps",
 "categories": [
     "Azure Pipelines"
 ],
 "icons": {
     "default": "images/extension-icon.png"
 },
 "files": [
     {
         "path": "MyCustomTask"
     }
 ],
 "contributions": [
     {
         "id": "my-custom-task",
         "type": "ms.vss-distributed-task.task",
         "targets": [
             "ms.vss-distributed-task.tasks"
         ],
         "properties": {
             "name": "MyCustomTask"
         }
     }
 ]
}

Properti manifes kunci

Properti Deskripsi
publisher Pengidentifikasi penerbit marketplace Anda
contributions.id Pengidentifikasi unik dalam ekstensi
contributions.properties.name Harus cocok dengan nama folder tugas Anda
files.path Jalur ke folder tugas Anda relatif terhadap manifes

Catatan

Ubah nilai penerbit menjadi nama penerbit Anda. Untuk informasi tentang membuat penerbit, lihat Membuat penerbit Anda.

Mengemas ekstensi perangkat lunak Anda

Kemas ekstensi Anda ke dalam file .vsix:

tfx extension create --manifest-globs vss-extension.json

Manajemen versi

  • Versi ekstensi: Menaikkan versi untuk vss-extension.json setiap pembaruan
  • Versi tugas: Menaikkan versi untuk task.json setiap pembaruan tugas
  • Kenaikan otomatis: Gunakan --rev-version untuk secara otomatis meningkatkan versi patch
tfx extension create --manifest-globs vss-extension.json --rev-version

Penting

Versi tugas dan versi ekstensi harus diperbarui agar perubahan diterapkan di Azure DevOps.

Strategi penerapan versi

Ikuti prinsip penerapan versi semantik untuk pembaruan tugas Anda:

  • Versi utama: Melanggar perubahan pada input/output
  • Versi minor: Fitur baru, kompatibel mundur
  • Versi patch: Perbaikan bug saja

Proses pembaruan:

  1. Perbarui task.json versi
  2. Perbarui vss-extension.json versi
  3. Menguji secara menyeluruh dalam organisasi pengujian
  4. Menerbitkan dan memantau masalah

Terbitkan ke Visual Studio Marketplace

1. Buat penerbit Anda

  1. Masuk ke Portal Penerbitan Marketplace Visual Studio
  2. Buat penerbit baru jika diminta:
    • Pengidentifikasi penerbit: Digunakan dalam manifes ekstensi Anda (misalnya, mycompany-myteam)
    • Nama tampilan: Nama publik yang ditampilkan di marketplace (misalnya, My Team)
  3. Meninjau dan menerima Perjanjian Penerbit Marketplace

2. Unggah ekstensi Anda

Metode antarmuka web:

  1. Pilih Unggah ekstensi baru
  2. Pilih file paket .vsix Anda
  3. Pilih Unggah

Metode baris perintah:

tfx extension publish --manifest-globs vss-extension.json --share-with yourOrganization

3. Bagikan ekstensi Anda

  1. Klik kanan ekstensi Anda di marketplace
  2. Pilih Bagikan
  3. Masukkan nama organisasi Anda
  4. Menambahkan lebih banyak organisasi sesuai kebutuhan

Penting

Penerbit harus diverifikasi untuk berbagi ekstensi secara publik. Untuk informasi selengkapnya, lihat Paket/Terbitkan/Instal.

4. Instal ke organisasi Anda

Setelah berbagi, instal ekstensi ke organisasi Azure DevOps Anda:

  1. Menavigasi keEkstensi> Organisasi
  2. Telusuri ekstensi Anda
  3. Pilih Dapatkan gratis dan instal

3. Mengemas dan menerbitkan ekstensi Anda

Memverifikasi ekstensi Anda

Setelah penginstalan, verifikasi tugas Anda berfungsi dengan benar:

  1. Membuat atau mengedit alur.
  2. Tambahkan tugas kustom Anda:
    • Pilih Tambahkan tugas di editor alur
    • Cari tugas kustom Anda berdasarkan nama
    • Menambahkannya ke alur Anda
  3. Mengonfigurasi parameter tugas:
    • Mengatur input yang diperlukan
    • Mengonfigurasi pengaturan opsional
  4. Jalankan alur untuk menguji fungsionalitas
  5. Pantau eksekusi:
    • Periksa log tugas untuk eksekusi yang tepat
    • Memverifikasi output yang diharapkan
    • Pastikan tidak ada kesalahan atau peringatan

4. Mengotomatiskan penerbitan ekstensi dengan CI/CD

Untuk mempertahankan tugas kustom Anda secara efektif, buat alur build dan rilis otomatis yang menangani pengujian, pengemasan, dan penerbitan.

Prasyarat untuk otomatisasi

  • Tugas Ekstensi Azure DevOps: Instal ekstensi secara gratis
  • Grup variabel: Buat grup variabel pustaka alur dengan variabel ini:
    • publisherId: ID penerbit marketplace Anda
    • extensionId: ID Ekstensi dari vss-extension.json
    • extensionName: Nama ekstensi dari vss-extension.json
    • artifactName: Nama untuk artefak VSIX
  • Koneksi layanan: Membuat koneksi layanan Marketplace dengan izin akses alur

Menyelesaikan alur CI/CD

Buat alur YAML dengan tahap komprehensif untuk pengujian, pengemasan, dan penerbitan:

trigger: 
- main

pool:
  vmImage: "ubuntu-latest"

variables:
  - group: extension-variables # Your variable group name

stages:
  - stage: Test_and_validate
    displayName: 'Run Tests and Validate Code'
    jobs:
      - job: RunTests
        displayName: 'Execute unit tests'
        steps:
          - task: TfxInstaller@4
            displayName: 'Install TFX CLI'
            inputs:
              version: "v0.x"
          
          - task: Npm@1
            displayName: 'Install task dependencies'
            inputs:
              command: 'install'
              workingDir: '/MyCustomTask' # Update to your task directory
          
          - task: Bash@3
            displayName: 'Compile TypeScript'
            inputs:
              targetType: "inline"
              script: |
                cd MyCustomTask # Update to your task directory
                tsc
          
          - task: Npm@1
            displayName: 'Run unit tests'
            inputs:
              command: 'custom'
              workingDir: '/MyCustomTask' # Update to your task directory
              customCommand: 'test' # Ensure this script exists in package.json
          
          - task: PublishTestResults@2
            displayName: 'Publish test results'
            inputs:
              testResultsFormat: 'JUnit'
              testResultsFiles: '**/test-results.xml'
              searchFolder: '$(System.DefaultWorkingDirectory)'

  - stage: Package_extension
    displayName: 'Package Extension'
    dependsOn: Test_and_validate
    condition: succeeded()
    jobs:
      - job: PackageExtension
        displayName: 'Create VSIX package'
        steps:
          - task: TfxInstaller@4
            displayName: 'Install TFX CLI'
            inputs:
              version: "v0.x"
          
          - task: Npm@1
            displayName: 'Install dependencies'
            inputs:
              command: 'install'
              workingDir: '/MyCustomTask'
          
          - task: Bash@3
            displayName: 'Compile TypeScript'
            inputs:
              targetType: "inline"
              script: |
                cd MyCustomTask
                tsc
          
          - task: QueryAzureDevOpsExtensionVersion@4
            name: QueryVersion
            displayName: 'Query current extension version'
            inputs:
              connectTo: 'VsTeam'
              connectedServiceName: 'marketplace-connection'
              publisherId: '$(publisherId)'
              extensionId: '$(extensionId)'
              versionAction: 'Patch'
          
          - task: PackageAzureDevOpsExtension@4
            displayName: 'Package extension'
            inputs:
              rootFolder: '$(System.DefaultWorkingDirectory)'
              publisherId: '$(publisherId)'
              extensionId: '$(extensionId)'
              extensionName: '$(extensionName)'
              extensionVersion: '$(QueryVersion.Extension.Version)'
              updateTasksVersion: true
              updateTasksVersionType: 'patch'
              extensionVisibility: 'private'
              extensionPricing: 'free'
          
          - task: PublishBuildArtifacts@1
            displayName: 'Publish VSIX artifact'
            inputs:
              PathtoPublish: '$(System.DefaultWorkingDirectory)/*.vsix'
              ArtifactName: '$(artifactName)'
              publishLocation: 'Container'

  - stage: Publish_to_marketplace
    displayName: 'Publish to Marketplace'
    dependsOn: Package_extension
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - deployment: PublishExtension
        displayName: 'Deploy to marketplace'
        environment: 'marketplace-production'
        strategy:
          runOnce:
            deploy:
              steps:
                - task: TfxInstaller@4
                  displayName: 'Install TFX CLI'
                  inputs:
                    version: "v0.x"
                
                - task: PublishAzureDevOpsExtension@4
                  displayName: 'Publish to marketplace'
                  inputs:
                    connectTo: 'VsTeam'
                    connectedServiceName: 'marketplace-connection'
                    fileType: 'vsix'
                    vsixFile: '$(Pipeline.Workspace)/$(artifactName)/*.vsix'
                    publisherId: '$(publisherId)'
                    extensionId: '$(extensionId)'
                    extensionName: '$(extensionName)'
                    updateTasksVersion: false
                    extensionVisibility: 'private'
                    extensionPricing: 'free'

Mengonfigurasi package.json untuk pengujian

Tambahkan skrip pengujian ke package.json:

{
  "scripts": {
    "test": "mocha tests/_suite.js --reporter xunit --reporter-option output=test-results.xml",
    "test-verbose": "cross-env TASK_TEST_TRACE=1 npm test"
  }
}

Perincian tahap alur

Tahap 1: Menguji dan memvalidasi

  • Tujuan: Memastikan kualitas dan fungsionalitas kode
  • Tindakan: Menginstal dependensi, mengkompilasi TypeScript, menjalankan pengujian unit, menerbitkan hasil
  • Validasi: Semua pengujian harus lulus untuk melanjutkan

Tahap 2: Ekstensi paket

  • Tujuan: Membuat paket VSIX yang dapat disebarkan
  • Tindakan: Mengkueri versi saat ini, versi tahapan, ekstensi paket, menerbitkan artefak
  • Penerapan versi: Secara otomatis menangani kenaikan versi

Tahap 3: Terbitkan ke marketplace

  • Tujuan: Sebarkan ke Visual Studio Marketplace
  • Kondisi: Hanya berjalan di cabang utama setelah kemasan berhasil
  • Lingkungan: Menggunakan lingkungan penyebaran untuk gerbang persetujuan

Praktik terbaik untuk CI/CD

  • Perlindungan cabang: Hanya terbitkan dari cabang utama/rilis
  • Gerbang lingkungan: Menggunakan lingkungan penyebaran untuk rilis produksi
  • Manajemen versi: Mengotomatiskan kenaikan versi untuk menghindari konflik
  • Cakupan pengujian: Memastikan cakupan pengujian komprehensif sebelum pengemasan
  • Keamanan: Gunakan koneksi layanan alih-alih kredensial yang dikodekan secara permanen
  • Pemantauan: Menyiapkan pemberitahuan untuk penyebaran yang gagal

Untuk alur build klasik, ikuti langkah-langkah berikut untuk menyiapkan pengemasan dan penerbitan ekstensi:

  1. Bash Tambahkan tugas untuk mengkompilasi TypeScript ke Dalam JavaScript.

  2. Untuk mengkueri versi yang sudah ada, tambahkan tugas Versi Ekstensi Kueri menggunakan input berikut:

    • Menyambungkan ke: Visual Studio Marketplace
    • Visual Studio Marketplace (Koneksi layanan): Koneksi layanan
    • ID Penerbit: ID penerbit Visual Studio Marketplace Anda
    • ID Ekstensi: ID ekstensi Anda dalam vss-extension.json file
    • Tingkatkan versi: Patch
    • Variabel Output: Task.Extension.Version

  3. Untuk mengemas ekstensi berdasarkan Json manifes, tambahkan tugas Ekstensi Paket menggunakan input berikut:

    • Folder utama manifes: Mengarah ke direktori akar yang berisi file manifes. Misalnya, $(System.DefaultWorkingDirectory) adalah direktori akar
    • File manifes: vss-extension.json
    • ID Penerbit: ID penerbit Visual Studio Marketplace Anda
    • ID Ekstensi: ID ekstensi Anda dalam vss-extension.json file
    • Nama Ekstensi: Nama ekstensi Anda dalam vss-extension.json file
    • Versi Ekstensi: $(Task.Extension.Version)
    • Ganti versi tugas: ditandai (true)
    • Penggantian Tipe: Hanya Gantikan Patch (1.0.r)
    • Visibilitas Ekstensi: Jika ekstensi masih dalam pengembangan, atur nilai ke privat. Untuk merilis ekstensi ke publik, atur nilai ke publik.

  4. Untuk menyalin ke file yang diterbitkan, tambahkan tugas Salin file menggunakan input berikut:

    • Isi: Semua file yang akan disalin untuk dipublikasikan sebagai artefak
    • Folder tujuan: Folder tempat file disalin
      • Misalnya: $(Build.ArtifactStagingDirectory)

  5. Tambahkan Terbitkan artefak build untuk menerbitkan artefak agar dapat digunakan dalam pekerjaan atau pipeline lain. Gunakan input berikut:

    • Jalur untuk diterbitkan: Jalur ke folder yang berisi file yang sedang diterbitkan
      • Misalnya: $(Build.ArtifactStagingDirectory)
    • Nama artefak: Nama yang diberikan ke artefak
    • Lokasi penerbitan artifak: Pilih Azure Pipelines untuk menggunakan artifak dalam pekerjaan mendatang

Tahap 3: Unduh artefak build dan terbitkan ekstensi

  1. Untuk menginstal tfx-cli ke agen build Anda, tambahkan Gunakan Node CLI untuk Azure DevOps (tfx-cli).

  2. Untuk mengunduh artefak pada pekerjaan baru, tambahkan tugas Download build artifacts dengan menggunakan input berikut:

    • Unduh artefak yang diproduksi oleh: Jika Anda mengunduh artefak pada pekerjaan baru dari rangkaian proses yang sama, pilih Rancangan saat ini. Jika Anda mengunduh di jalur baru, pilih Build tertentu
    • Jenis unduhan: Pilih Artefak tertentu untuk mengunduh semua file yang diterbitkan.
    • Nama artefak: Nama artefak yang diterbitkan
    • Direktori tujuan: Folder tempat file harus diunduh

  3. Untuk mendapatkan tugas Terbitkan Ekstensi , gunakan input berikut:

    • Menyambungkan ke: Visual Studio Marketplace
    • Koneksi Visual Studio Marketplace: ServiceConnection
    • Jenis file input: File VSIX
    • File VSIX: /Publisher.*.vsix
    • ID Penerbit: ID penerbit Visual Studio Marketplace Anda
    • ID Ekstensi: ID ekstensi Anda dalam vss-extension.json file
    • Nama Ekstensi: Nama ekstensi Anda dalam vss-extension.json file
    • Visibilitas ekstensi: Baik privat atau publik

Opsional: Menginstal dan menguji ekstensi Anda

Setelah Anda menerbitkan ekstensi, ekstensi perlu diinstal di organisasi Azure DevOps.

Menginstal ekstensi ke organisasi

Instal ekstensi bersama Anda dalam beberapa langkah:

  1. Buka Pengaturan organisasi dan pilih Ekstensi.

  2. Temukan ekstensi Anda di bagian Ekstensi Dibagikan Dengan Saya :

    • Pilih tautan ekstensi
    • Pilih Dapatkan gratis atau Instal

  3. Periksa apakah ekstensi muncul di daftar Ekstensi terinstal Anda:

    • Mengonfirmasi bahwa tersedia di pustaka tugas alur Anda

Catatan

Jika Anda tidak melihat tab Ekstensi , pastikan Anda berada di tingkat administrasi organisasi (https://dev.azure.com/{organization}/_admin) dan bukan di tingkat proyek.

Pengujian ujung-ke-ujung

Setelah penginstalan, lakukan pengujian komprehensif:

  1. Buat alur pengujian:

    • Menambahkan tugas kustom Anda ke alur baru
    • Mengonfigurasi semua parameter input
    • Uji dengan berbagai kombinasi input

  2. Memvalidasi fungsionalitas:

    • Jalankan eksekusi alur dan pantau
    • Memeriksa output dan log tugas
    • Memverifikasi penanganan kesalahan dengan input yang tidak valid

  3. Performa pengujian:

    • Uji dengan file input besar (jika berlaku)
    • Memantau penggunaan sumber daya
    • Memvalidasi perilaku batas waktu

Tanya jawab umum

T: Bagaimana pembatalan tugas ditangani?

A: Agen alur mengirim SIGINT dan SIGTERM memberi sinyal ke proses tugas. Meskipun pustaka tugas tidak menyediakan penanganan pembatalan eksplisit, tugas Anda dapat menerapkan penangan sinyal. Untuk detailnya, lihat Pembatalan pekerjaan agen.

T: Bagaimana cara menghapus tugas dari organisasi saya?

A: Penghapusan otomatis tidak didukung karena akan merusak alur yang ada. Sebaliknya:

  1. Menghentikan tugas: Menandai tugas sebagai tidak digunakan lagi
  2. Manajemen versi: Benjolan versi tugas
  3. Komunikasi: Memberi tahu pengguna tentang garis waktu penghentian

T: Bagaimana cara memutakhirkan tugas saya ke versi Node.js terbaru?

A: Tingkatkan ke versi Node terbaru untuk performa dan keamanan yang lebih baik. Untuk panduan migrasi, lihat Meningkatkan tugas ke Node 20.

Dukung beberapa versi Node dengan menyertakan beberapa bagian eksekusi di task.json:

"execution": {
  "Node20_1": {
    "target": "index.js"
  },
  "Node10": {
    "target": "index.js"
  }
}

Agen dengan Node 20 menggunakan versi pilihan, sementara agen yang lebih lama kembali ke Node 10.

Untuk meningkatkan tugas Anda:

  • Untuk memastikan kode Anda berperilaku seperti yang diharapkan, uji tugas Anda pada berbagai versi runner Node.

  • Di bagian eksekusi tugas Anda, perbarui dari Node atau Node10 ke Node16 atau Node20.

  • Untuk mendukung versi server yang lebih lama, Anda harus mempertahankan target Node/Node10. Versi Azure DevOps Server yang lebih lama mungkin tidak menyertakan versi runner Node terbaru.

  • Anda dapat memilih untuk membagikan titik entri yang ditentukan dalam target atau memiliki target yang dioptimalkan untuk versi Node yang digunakan.

    "execution": {
   "Node10": {
     "target": "bash10.js",
     "argumentFormat": ""
   },
   "Node16": {
     "target": "bash16.js",
     "argumentFormat": ""
   },
   "Node20_1": {
     "target": "bash20.js",
     "argumentFormat": ""
   }
}

Penting

Jika Anda tidak menambahkan dukungan untuk runner Node 20 pada tugas kustom Anda, tugas tersebut akan gagal pada agen yang diinstal dari umpan rilis pipelines-agent-*.

Konten terkait

  • Last updated on