Sdílet prostřednictvím

Přidání rozšíření úloh pro vlastní potrubí

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Tato příručka vás provede vytvářením, testováním a publikováním vlastních úloh sestavení nebo vydaných verzí jako rozšíření Azure DevOps. Vlastní úlohy kanálu umožňují rozšířit Azure DevOps o specializované funkce přizpůsobené pracovním postupům vašeho týmu, od jednoduchých nástrojů až po komplexní integraci s externími systémy.

Naučte se provádět následující úlohy:

  • Nastavení vývojového prostředí a struktury projektu
  • Vytvoření logiky úloh pomocí TypeScriptu a knihovny úloh Azure Pipelines
  • Implementace komplexního testování jednotek s využitím napodobených architektur
  • Zabalení rozšíření pro distribuci
  • Publikování na Visual Studio Marketplace
  • Nastavení automatizovaných kanálů CI/CD pro údržbu rozšíření

Další informace o službě Azure Pipelines najdete v tématu Co je Azure Pipelines?

Poznámka:

Tento článek popisuje úlohy agenta v rozšířeních založených na agentech. Informace o úlohách serveru a serverových rozšířeních naleznete v tématu Vytváření úloh serveru.

Požadavky

Než začnete, ujistěte se, že máte splněné následující požadavky:

Součást Požadavek Popis
Organizace Azure DevOps Povinné Vytvoření organizace, pokud ho nemáte
Textový editor Doporučeno Visual Studio Code pro IntelliSense a podporu ladění
Node.js Povinné Instalace nejnovější verze (doporučenoNode.js 20 nebo novější)
Kompilátor TypeScriptu Povinné Instalace nejnovější verze (verze 4.6.3 nebo novější)
Azure DevOps CLI (tfx-cli) Povinné Instalace pomocí npm i -g tfx-cli rozšíření balíčků
Sada SDK rozšíření Azure DevOps Povinné Instalace balíčku azure-devops-extension-sdk
Testovací architektura Povinné Mocha pro testování jednotek (nainstalované během instalace)

Struktura projektu

Vytvořte home adresář pro projekt. Po dokončení tohoto kurzu by vaše rozšíření mělo mít následující strukturu:

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

Důležité

Aby se zajistila kompatibilita s produkčním prostředím, musí váš vývojový počítač používat nejnovější verzi Node.js . Aktualizujte task.json soubor tak, aby používal Node 20:

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

1. Vytvoření vlastního úkolu

Tato část vás provede vytvořením základní struktury a implementace vlastní úlohy. Všechny soubory v tomto kroku by se měly vytvořit ve buildandreleasetask složce v adresáři projektu home .

Poznámka:

Tento názorný postup používá Windows s PowerShellem. Postup funguje na všech platformách, ale syntaxe proměnných prostředí se liší. Na Macu nebo Linuxu nahraďte $env:<var>=<val> textem export <var>=<val>.

Nastavení generování uživatelského rozhraní úkolu

Vytvořte základní strukturu projektu a nainstalujte požadované závislosti:

  1. Pokud chcete inicializovat projekt Node.js, otevřete PowerShell, přejděte do složky a spusťte buildandreleasetask :

    npm init --yes

    Soubor package.json se vytvoří s výchozím nastavením. Příznak --yes přijímá všechny výchozí možnosti automaticky.

    Doporučení

    Agenti Azure Pipelines očekávají, že složky úloh budou zahrnovat moduly uzlů. Zkopírujte node_modules ji do složky buildandreleasetask . Pokud chcete spravovat velikost souboru VSIX (limit 50 MB), zvažte spuštění npm install --production nebo npm prune --production před balením.

  2. Nainstalujte knihovnu úloh Azure Pipelines:

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

  3. Nainstalujte definice typů TypeScriptu:

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

  4. Nastavení vyloučení správy verzí

    echo node_modules > .gitignore

    Proces sestavení by se měl spustit npm install , aby se pokaždé znovu sestavil node_modules.

  5. Instalace testovacích závislostí:

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

  6. Nainstalujte kompilátor TypeScriptu:

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

    Poznámka:

    Nainstalujte TypeScript globálně, abyste měli jistotu, že tsc je příkaz dostupný. Bez ní se ve výchozím nastavení používá TypeScript 2.3.4.

  7. Konfigurace kompilace TypeScriptu:

    tsc --init --target es2022

    Soubor tsconfig.json se vytvoří s nastavením cíle ES2022.

Implementace logiky úlohy

Po dokončení generování uživatelského rozhraní vytvořte základní soubory úloh, které definují funkce a metadata:

  1. Vytvořte definiční soubor úlohy: Vytvořte task.json ve buildandreleasetask složce. Tento soubor popisuje vaši úlohu v systému Azure Pipelines, definování vstupů, nastavení spuštění a prezentace uživatelského rozhraní.

    {
 "$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"
     }
 }
 }

    Poznámka:

    Nahraďte {{placeholders}} skutečnými informacemi o úkolu. Musí taskguid být jedinečný. Vygenerujte ho pomocí PowerShellu: (New-Guid).Guid

  2. Pokud chcete implementovat logiku úlohy, vytvořte index.ts ji pomocí hlavních funkcí úkolu:

    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. Kompilace TypeScriptu do JavaScriptu:

    tsc

    Soubor index.js se vytvoří z vašeho zdroje TypeScriptu.

Principy komponent task.json

Soubor task.json je jádrem definice úkolu. Tady jsou klíčové vlastnosti:

Vlastnost Popis Příklad
id Jedinečný identifikátor GUID pro váš úkol Vygenerováno pomocí (New-Guid).Guid
name Název úkolu bez mezer (používá se interně) MyCustomTask
friendlyName Zobrazovaný název zobrazený v uživatelském rozhraní My Custom Task
description Podrobný popis funkcí úloh Performs custom operations on files
author Jméno vydavatele nebo autora My Company
instanceNameFormat Jak se úloha zobrazí v krocích kanálu Process $(inputFile)
inputs Pole vstupních parametrů Podívejte se na následující typy vstupu.
execution Specifikace spouštěcího prostředí Node20_1, PowerShell3atd.
restrictions Omezení zabezpečení pro příkazy a proměnné Doporučeno pro nové úkoly

Bezpečnostní omezení

V případě produkčních úloh přidejte omezení zabezpečení pro omezení využití příkazů a přístupu k proměnným:

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

Režim s omezeným přístupem umožňuje pouze tyto příkazy:

  • logdetail, logissue, , completesetprogress
  • setsecret, setvariable, , debugsettaskvariable
  • prependpath, publish

Ovládací prvky seznamu povolených proměnných, které proměnné lze nastavit pomocí setvariable nebo prependpath. Podporuje základní vzory regulárních výrazů.

Poznámka:

Tato funkce vyžaduje agenta verze 2.182.1 nebo novější.

Vstupní typy a příklady

Běžné vstupní typy pro parametry úkolu:

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

Místní testování úlohy

Před zabalením otestujte úlohu, abyste měli jistotu, že funguje správně:

  1. Test s chybějícím vstupem (měl by selhat):

    node index.js

    Očekávaný výstup:

    ##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. Test s platným vstupem (měl by být úspěšný):

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

    Očekávaný výstup:

    ##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. Zpracování chyb testu:

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

    Tato akce by měla aktivovat cestu zpracování chyb v kódu.

    Doporučení

    Informace o spouštěčích úloh a verzích Node.js najdete v pokynech k aktualizaci Node Runneru.

Další informace najdete v referenční příručce k úlohám sestavení a vydání.

2. Implementace komplexního testování jednotek

Důkladné testování úlohy zajišťuje spolehlivost a pomáhá zachytit problémy před nasazením do produkčních kanálů.

Instalace testovacích závislostí

Nainstalujte požadované testovací nástroje:

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

Vytvoření testu

  1. Vytvořte tests složku v adresáři úloh obsahujícím _suite.ts soubor:

     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
     });    
   });

    Doporučení

    Testovací složka by měla být umístěná ve složce úkolů (například buildandreleasetask). Pokud dojde k chybě žádosti o synchronizaci, nainstalujte ji do složky úloh: npm i --save-dev sync-request.

  2. Vytvořte success.ts v testovacím adresáři pro simulaci úspěšného spuštění úlohy:

     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. Přidejte do _suite.ts souboru test úspěchu:

     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. Vytvořte failure.ts v testovacím adresáři pro testování zpracování chyb:

    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. Přidejte do _suite.ts souboru test selhání:

     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();
     });
 });

Spuštění testů

Spusťte testovací sadu:

# Compile TypeScript
tsc

# Run tests
mocha tests/_suite.js

Oba testy by měly proběhnout. Pro podrobný výstup (podobný výstupu konzoly sestavení) nastavte proměnnou prostředí trasování:

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

Osvědčené postupy pro testování pokrytí

  • Test všech kombinací vstupu: Platné vstupy, neplatné vstupy, chybějící požadované vstupy
  • Scénáře chyb testů: Selhání sítě, chyby systému souborů, problémy s oprávněními
  • Napodobení externích závislostí: Nespoléhejte na externí služby v testech jednotek
  • Ověření výstupů: Kontrola výstupu konzoly, výsledků úloh a vygenerovaných artefaktů
  • Testování výkonu: Zvažte přidání testů pro úlohy, které zpracovávají velké soubory.

Osvědčené postupy zabezpečení

  • Ověřování vstupu: Vždy ověřte a sanitujte vstupy.
  • Zpracování tajných kódů: Použití setSecret pro citlivá data
  • Omezení příkazů: Implementace omezení příkazů pro produkční úlohy
  • Minimální oprávnění: Požadovat pouze potřebná oprávnění
  • Pravidelné aktualizace: Udržování závislostí a Node.js aktuálních verzí

Po místním otestování úlohy a implementaci komplexních testů jednotek ho zabalte do rozšíření pro Azure DevOps.

Instalace nástrojů pro balení

Nainstalujte rozhraní příkazového řádku pro různé platformy (tfx-cli):

npm install -g tfx-cli

Vytvoření manifestu rozšíření

Manifest rozšíření (vss-extension.json) obsahuje všechny informace o vašem rozšíření, včetně odkazů na složky úkolů a obrázky.

  1. Vytvoření složky obrázků se souborem extension-icon.png

  2. Vytvořte vss-extension.json v kořenovém adresáři rozšíření (ne ve složce úloh):

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

Klíčové vlastnosti manifestu

Vlastnost Popis
publisher Identifikátor vydavatele marketplace
contributions.id Jedinečný identifikátor v rámci rozšíření
contributions.properties.name Musí odpovídat názvu složky úkolu.
files.path Cesta ke složce úkolů vzhledem k manifestu

Poznámka:

Změňte hodnotu vydavatele na název vydavatele. Informace o vytvoření vydavatele najdete v tématu Vytvoření vydavatele.

Zabalte své rozšíření

Zabalte příponu do souboru .vsix:

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

Správa verzí

  • Verze rozšíření: Zvýšení verze vss-extension.json pro každou aktualizaci
  • Verze úlohy: Zvýšení verze task.json pro každou aktualizaci úlohy
  • Automatické přírůstky: Slouží --rev-version k automatickému zvýšení verze opravy.
tfx extension create --manifest-globs vss-extension.json --rev-version

Důležité

Aby se změny projevily v Azure DevOps, musí se aktualizovat verze úlohy i verze rozšíření.

Strategie správy verzí

Při aktualizacích úloh postupujte podle sémantických principů správy verzí:

  • Hlavní verze: Zásadní změny vstupů a výstupů
  • Podverze: Nové funkce, zpětně kompatibilní
  • Verze opravy: Pouze opravy chyb

Proces aktualizace:

  1. Aktualizace task.json verze
  2. Aktualizace vss-extension.json verze
  3. Důkladně testovat v testovací organizaci
  4. Publikování a monitorování problémů

Publikování na Visual Studio Marketplace

1. Vytvoření vydavatele

  1. Přihlášení k portálu publikování na Webu Visual Studio Marketplace
  2. Pokud se zobrazí výzva, vytvořte nového vydavatele:
    • Identifikátor vydavatele: Používá se v manifestu rozšíření (například mycompany-myteam)
    • Zobrazovaný název: Veřejný název zobrazený na marketplace (například My Team)
  3. Kontrola a přijetí smlouvy vydavatele Marketplace

2. Nahrání rozšíření

Metoda webového rozhraní:

  1. Vyberte Nahrát nové rozšíření.
  2. Volba zabaleného .vsix souboru
  3. Vyberte Nahrát.

Metoda příkazového řádku:

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

3. Sdílení rozšíření

  1. Klikněte pravým tlačítkem na rozšíření na marketplace.
  2. Vyberte Sdílet.
  3. Zadejte název organizace.
  4. Podle potřeby přidejte další organizace.

Důležité

Aby bylo možné sdílet rozšíření veřejně, musí být vydavatelé ověřeni. Další informace najdete v tématu Balíček, Publikování/ Instalace.

4. Instalace do vaší organizace

Po sdílení nainstalujte rozšíření do vaší organizace Azure DevOps:

  1. Přechod narozšíření> organizace
  2. Vyhledejte rozšíření.
  3. Vyberte Získat zdarma a nainstalujte

3. Zabalení a publikování rozšíření

Ověření rozšíření

Po instalaci ověřte, že vaše úloha funguje správně:

  1. Vytvoření nebo úprava kanálu
  2. Přidejte vlastní úkol:
    • Výběr možnosti Přidat úlohu v editoru kanálů
    • Vyhledání vlastního úkolu podle názvu
    • Přidejte ho do kanálu.
  3. Konfigurace parametrů úkolu:
    • Nastavení požadovaných vstupů
    • Konfigurace volitelných nastavení
  4. Spuštění kanálu pro testování funkčnosti
  5. Monitorování provádění:
    • Kontrola správného spuštění v protokolech úloh
    • Ověření očekávaných výstupů
    • Ujistěte se, že nedošlo k žádným chybám nebo upozorněním.

4. Automatizace publikování rozšíření pomocí CI/CD

Pokud chcete efektivně udržovat vlastní úlohu, vytvořte automatizované kanály sestavení a verze, které zpracovávají testování, balení a publikování.

Požadavky pro automatizaci

  • Úlohy rozšíření Azure DevOps: Bezplatná instalace rozšíření
  • Skupina proměnných: Vytvořte skupinu proměnných knihovny kanálů s těmito proměnnými:
    • publisherId: ID vydavatele marketplace
    • extensionId: ID rozšíření z vss-extension.json
    • extensionName: Název rozšíření z vss-extension.json
    • artifactName: Název artefaktu VSIX
  • Připojení ke službě: Vytvoření připojení služby Marketplace s oprávněními pro přístup ke kanálu

Dokončení kanálu CI/CD

Vytvořte kanál YAML s komplexními fázemi pro testování, balení a publikování:

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'

Konfigurace package.json pro testování

Přidejte do aplikace package.jsontestovací skripty:

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

Rozpis fáze kanálu

Fáze 1: Testování a ověření

  • Účel: Zajištění kvality a funkčnosti kódu
  • Akce: Instalace závislostí, kompilace TypeScriptu, spouštění testů jednotek, publikování výsledků
  • Ověření: Všechny testy musí projít, aby bylo pokračovat.

Fáze 2: Rozšíření balíčku

  • Účel: Vytvoření nasaditelného balíčku VSIX
  • Akce: Dotazování aktuální verze, přírůstkové verze, rozšíření balíčku, publikování artefaktů
  • Správaverzích

Fáze 3: Publikování na marketplace

  • Účel: Nasazení na Visual Studio Marketplace
  • Podmínky: Po úspěšném balení se spouští pouze v hlavní větvi.
  • Prostředí: Používá prostředí nasazení pro schvalovací brány.

Osvědčené postupy pro CI/CD

  • Ochrana větví: Publikování pouze z hlavních/vydaných větví
  • Brány prostředí: Použití prostředí nasazení pro produkční verze
  • Správa verzí: Automatizace přírůstků verzí, aby nedocházelo ke konfliktům
  • Pokrytí testu: Zajištění komplexního pokrytí testu před balením
  • Zabezpečení: Používejte připojení služeb místo pevně zakódovaných přihlašovacích údajů.
  • Monitorování: Nastavení upozornění pro neúspěšná nasazení

V případě klasických kanálů buildu postupujte podle těchto kroků a nastavte balení a publikování rozšíření:

  1. Bash Přidejte úlohu pro kompilaci TypeScriptu do JavaScriptu.

  2. Pokud chcete zadat dotaz na existující verzi, přidejte úlohu Verze rozšíření dotazu pomocí následujících vstupů:

    • Připojení: Visual Studio Marketplace
    • Visual Studio Marketplace (připojení služby): Připojení ke službě
    • ID vydavatele: ID vašeho vydavatele sady Visual Studio Marketplace
    • ID přípony: ID vaší přípony vss-extension.json v souboru
    • Zvýšení verze: Oprava
    • Výstupní proměnná: Task.Extension.Version

  3. Pokud chcete zabalit rozšíření na základě kódu JSON manifestu, přidejte úlohu rozšíření balíčku pomocí následujících vstupů:

    • Kořenová složka manifestů: Odkazuje na kořenový adresář, který obsahuje soubor manifestu. Je to například kořenový adresář. $(System.DefaultWorkingDirectory)
    • Soubor manifestu: vss-extension.json
    • ID vydavatele: ID vašeho vydavatele sady Visual Studio Marketplace
    • ID přípony: ID vaší přípony vss-extension.json v souboru
    • Název rozšíření: Název vašeho rozšíření v souboru vss-extension.json
    • Verze rozšíření: $(Task.Extension.Version)
    • Verze přepsání úkolů: zaškrtnuto (pravda)
    • Typ přepsání: Pouze náhrada opravy (1.0.r)
    • Viditelnost rozšíření: Pokud je rozšíření stále ve vývoji, nastavte hodnotu na privátní. Pokud chcete rozšíření uvolnit pro veřejnost, nastavte hodnotu na veřejnou.

  4. Pokud chcete kopírovat do publikovaných souborů, přidejte úlohu Kopírovat soubory pomocí následujících vstupů:

    • Obsah: Všechny soubory, které se mají zkopírovat pro jejich publikování jako artefakt
    • Cílová složka: Složka, do které se soubory zkopírují
      • Příklad: $(Build.ArtifactStagingDirectory)

  5. Přidejte artefakty sestavení pro publikování artefaktů pro použití v jiných úlohách nebo kanálech. Použijte následující vstupy:

    • Cesta k publikování: Cesta ke složce, která obsahuje publikované soubory
      • Příklad: $(Build.ArtifactStagingDirectory)
    • Název artefaktu: Název udělený artefaktu
    • Umístění publikování artefaktů: Vyberte Azure Pipelines pro použití artefaktu v budoucích úlohách

Fáze 3: Stažení artefaktů sestavení a publikování rozšíření

  1. Pokud chcete do agenta sestavení nainstalovat tfx-cli, přidejte Use Node CLI for Azure DevOps (tfx-cli).

  2. Pokud chcete stáhnout artefakty do nové úlohy, přidejte úlohu Stáhnout artefakty sestavení pomocí následujících vstupů:

    • Stažení artefaktů vytvořených pomocí: Pokud stahujete artefakt do nové úlohy ze stejného kanálu, vyberte Aktuální sestavení. Pokud stahujete nový kanál, vyberte Konkrétní sestavení.
    • Typ stahování: Zvolte konkrétní artefakt a stáhněte všechny publikované soubory.
    • Název artefaktu: Název publikovaného artefaktu
    • Cílový adresář: Složka, do které se mají soubory stáhnout

  3. Pokud chcete získat úlohu Publikovat rozšíření , použijte následující vstupy:

    • Připojení: Visual Studio Marketplace
    • Připojení k Visual Studio Marketplace: ServiceConnection
    • Typ vstupního souboru: Soubor VSIX
    • Soubor VSIX: /Publisher.*.vsix
    • ID vydavatele: ID vašeho vydavatele sady Visual Studio Marketplace
    • ID přípony: ID vaší přípony vss-extension.json v souboru
    • Název rozšíření: Název vašeho rozšíření v souboru vss-extension.json
    • Viditelnost rozšíření: Soukromá nebo veřejná

Volitelné: Instalace a otestování rozšíření

Po publikování rozšíření je potřeba ho nainstalovat v organizacích Azure DevOps.

Instalace rozšíření do organizace

Nainstalujte sdílené rozšíření v několika krocích:

  1. Přejděte do nastavení organizace a vyberte Rozšíření.

  2. Vyhledejte své rozšíření v části Rozšíření sdílená se mnou :

    • Výběr odkazu na rozšíření
    • Vyberte Získat zdarma nebo Nainstalovat.

  3. Zkontrolujte, že se rozšíření zobrazí v seznamu nainstalovaných rozšíření:

    • Ověřte, že je dostupná v knihovně úloh kanálu.

Poznámka:

Pokud kartu Rozšíření nevidíte, ujistěte se, že jste na úrovni správy organizace (https://dev.azure.com/{organization}/_admin) a ne na úrovni projektu.

Testování od začátku do konce

Po instalaci proveďte komplexní testování:

  1. Vytvoření testovacího kanálu:

    • Přidání vlastní úlohy do nového kanálu
    • Konfigurace všech vstupních parametrů
    • Testování s různými kombinacemi vstupu

  2. Ověření funkčnosti:

    • Spuštění kanálu a monitorování spuštění
    • Kontrola výstupů a protokolů úloh
    • Ověření zpracování chyb s neplatnými vstupy

  3. Výkon testu:

    • Testování s velkými vstupními soubory (pokud je k dispozici)
    • Monitorování využití prostředků
    • Ověření chování časového limitu

Nejčastější dotazy

Otázka: Jak se zpracovává zrušení úlohy?

A: Agent kanálu odesílá SIGINT procesy úloh a SIGTERM signály. Knihovna úloh sice neposkytuje explicitní zpracování zrušení, ale vaše úloha může implementovat obslužné rutiny signálu. Podrobnosti najdete v tématu Zrušení úloh agenta.

Otázka: Jak můžu odebrat úkol z organizace?

A: Automatické odstranění se nepodporuje , protože by přerušilo stávající kanály. Namísto:

  1. Vyřazení úkolu: Označte ho jako zastaralý.
  2. Správa verzí: Zvýšení verze úlohy
  3. Komunikace: Upozorněte uživatele na časovou osu vyřazení

Otázka: Jak můžu upgradovat úlohu na nejnovější verzi Node.js?

A: Upgradujte na nejnovější verzi uzlu , abyste zlepšili výkon a zabezpečení. Pokyny k migraci najdete v tématu Upgrade úloh na Node 20.

Podpora více verzí uzlů zahrnutím více oddílů spuštění v task.json:

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

Agenti s Uzlem 20 používají upřednostňovanou verzi, zatímco starší agenti se vrátí na Node 10.

Jak vylepšit úkoly:

  • Abyste zajistili, že se váš kód chová podle očekávání, otestujte úlohy na různých verzích Node Runneru.

  • V části provádění úkolu aktualizujte z Node nebo Node10 do Node16 nebo Node20.

  • Pokud chcete podporovat starší verze serveru, měli byste ponechat Node/Node10 cíl. Starší verze Azure DevOps Serveru nemusí obsahovat nejnovější verzi Node Runneru.

  • Můžete se rozhodnout sdílet vstupní bod definovaný v cíli nebo mít cíle optimalizované pro použitou verzi uzlu.

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

Důležité

Pokud do vlastních úloh nepřidáte podporu pro spouštěč Node 20, úlohy se nezdaří na agentech nainstalovaných ze zdroje verze pipelines-agent-*.

Související obsah

  • Last updated on