Ajouter une extension de tâche de pipelines personnalisée
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
Découvrez comment installer des extensions à votre organisation pour des tâches de génération ou de mise en production personnalisées dans Azure DevOps. Pour plus d’informations, consultez Qu’est-ce qu’Azure Pipelines ?
Remarque
Cet article traite des tâches d’agent dans les extensions basées sur l’agent. Pour plus d’informations sur les tâches de serveur et les extensions basées sur le serveur, consultez la documentation GitHub de la tâche serveur.
Prérequis
Pour créer des extensions pour Azure DevOps, vous avez besoin des logiciels et outils suivants.
Logiciel/outil | Information |
---|---|
Organisation Azure DevOps | Créez une organisation. |
Un éditeur de texte | Pour de nombreuses procédures, nous utilisons Visual Studio Code, qui fournit une prise en charge intellisense et de débogage. Téléchargez la version la plus récente. |
Node.JS | Téléchargez la version la plus récente. |
npmjs.com 4.0.2 ou version ultérieure | Compilateur TypeScript. Téléchargez la version la plus récente. |
tfx-cli | Empaqueter votre extension avec l’interface CLI multiplateforme pour Azure DevOps. using npm , un composant de Node.js, en exécutant npm i -g tfx-cli . |
Kit de développement logiciel (SDK) d’extension Azure DevOps | Installez le package azure-devops-extension-sdk. |
Répertoire home de votre projet |
Le home répertoire d’une extension de tâche de génération ou de mise en production doit ressembler à l’exemple suivant après avoir effectué les étapes décrites dans cet article. |
|--- README.md
|--- images
|--- extension-icon.png
|--- buildandreleasetask // where your task scripts are placed
|--- vss-extension.json // extension's manifest
Important
La machine de développement doit exécuter la dernière version de Node pour s’assurer que le code écrit est compatible avec l’environnement de production sur l’agent et la dernière version non préliminaire de azure-pipelines-task-lib
. Mettez à jour votre fichier task.json conformément à la commande suivante :
"execution": {
"Node20_1": {
"target": "index.js"
}
}
1. Créer une tâche personnalisée
Effectuez toutes les parties de cette procédure dans le buildandreleasetask
dossier.
Remarque
Cet exemple de procédure pas à pas utilise Windows avec PowerShell. Nous l’avons rendu générique pour toutes les plateformes, mais la syntaxe pour obtenir des variables d’environnement est différente. Si vous utilisez un Mac ou Linux, remplacez toutes les instances de $env:<var>=<val>
export <var>=<val>
.
Créer une structure de tâche
Créez la structure de dossiers pour la tâche et installez les bibliothèques et dépendances requises.
Ouvrez une fenêtre de commande PowerShell, accédez à votre
buildandreleasetask
dossier et exécutez la commande suivante.npm init --yes
npm init
crée lepackage.json
fichier. Nous avons ajouté le--yes
paramètre pour accepter toutes les options par défautnpm init
.Conseil
L’agent n’installe pas automatiquement les modules requis, car il s’attend à ce que votre dossier de tâches inclue les modules de nœud. Pour atténuer ce problème, copiez la valeur
node_modules
versbuildandreleasetask
. À mesure que votre tâche augmente, il est facile de dépasser la limite de taille (50 Mo) d’un fichier VSIX. Avant de copier le dossier du nœud, vous souhaiterez peut-être exécuternpm install --production
ou, ounpm prune --production
vous pouvez écrire un script pour générer et empaquetez tout.Ajouter
azure-pipelines-task-lib
à votre bibliothèque.npm install azure-pipelines-task-lib --save
Vérifiez que les frappes TypeScript sont installées pour les dépendances externes.
npm install @types/node --save-dev npm install @types/q --save-dev
Créez un
.gitignore
fichier et ajoutez-y node_modules. Votre processus de génération doit effectuer unenpm install
opération et untypings install
pour que node_modules soient générées chaque fois et n’ont pas besoin d’être archivés.echo node_modules > .gitignore
Installez Mocha comme dépendance de développement.
npm install mocha --save-dev -g npm install sync-request --save-dev npm install @types/mocha --save-dev
Choisissez TypeScript version 2.3.4 ou 4.6.3.
npm install typescript@4.6.3 -g --save-dev
Remarque
Assurez-vous que TypeScript est installé globalement avec npm dans votre environnement de développement. La
tsc
commande est donc disponible. Si vous ignorez cette étape, TypeScript version 2.3.4 est utilisée par défaut et vous devez toujours installer le package globalement pour que latsc
commande soit disponible.Créez des
tsconfig.json
options de compilateur. Ce fichier garantit que vos fichiers TypeScript sont compilés en fichiers JavaScript.tsc --init --target es2022
Créer une tâche
Maintenant que la structure est terminée, nous pouvons créer notre tâche personnalisée.
Créez un
task.json
fichier dans lebuildandreleasetask
dossier. Letask.json
fichier décrit la tâche de génération/mise en production et correspond à ce que le système de génération/mise en production utilise pour afficher les options de configuration à l’utilisateur et pour connaître les scripts à exécuter au moment de la génération/mise en production.Copiez le code suivant et remplacez les
{{placeholders}}
informations de votre tâche. L’espace réservé le plus important est letaskguid
, et il doit être unique.{ "$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" } } }
Créez un
index.ts
fichier à l’aide du code suivant comme référence. Ce code s’exécute lorsque la tâche est appelée.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();
Entrez « tsc » à partir du
buildandreleasetask
dossier pour compiler unindex.js
fichier à partir deindex.ts
.
composants task.json
Consultez les descriptions suivantes de certains composants du task.json
fichier.
Propriété | Description |
---|---|
id |
GUID unique pour votre tâche. |
name |
Nom sans espace. |
friendlyName |
Nom descriptif (espaces autorisés). |
description |
Description détaillée de ce que fait votre tâche. |
author |
Chaîne courte décrivant l’entité qui développe la tâche de génération ou de mise en production, par exemple : « Microsoft Corporation ». |
instanceNameFormat |
Comment la tâche s’affiche dans la liste d’étapes de génération/mise en production. Vous pouvez utiliser des valeurs de variable à l’aide de $(nom_variable). |
groups |
Décrit le regroupement logique des propriétés de tâche dans l’interface utilisateur. |
inputs |
Entrées à utiliser lorsque votre tâche de génération ou de mise en production s’exécute. Cette tâche attend une entrée avec l’exemple de chaîne de nom. |
execution |
Options d’exécution pour cette tâche, y compris les scripts. |
restrictions |
Les restrictions appliquées à la tâche concernant les commandes GitHub Codespaces peuvent appeler et les variables peuvent être définies. Nous vous recommandons de spécifier le mode de restriction pour les nouvelles tâches. |
Remarque
Créez une id
commande avec la commande suivante dans PowerShell :
(New-Guid).Guid
Pour plus d’informations, consultez la référence de tâche build/mise en production.
Exécuter la tâche
Exécutez la tâche à node index.js
partir de PowerShell.
Dans l’exemple suivant, la tâche échoue, car les entrées n’ont pas été fournies (samplestring
est une entrée obligatoire).
node index.js
##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
En guise de correctif, nous pouvons définir l’entrée samplestring
et réexécuter la tâche.
$env:INPUT_SAMPLESTRING="Human"
node index.js
##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]Agent.ProxyUrl=undefined
##vso[task.debug]Agent.CAInfo=undefined
##vso[task.debug]Agent.ClientCert=undefined
##vso[task.debug]Agent.SkipCertValidation=undefined
##vso[task.debug]samplestring=Human
Hello Human
Cette fois, la tâche a réussi car samplestring
elle a été fournie et elle a correctement généré « Hello Human ! »
Conseil
Pour plus d’informations sur différents exécuteurs de tâches et sur la façon d’inclure la dernière version du nœud dans le task.json, consultez les instructions de mise à jour de l’exécuteur de nœuds pour les auteurs de tâches Azure Pipelines.
2. Test unitaire de vos scripts de tâche
Effectuez des tests unitaires pour tester rapidement le script de tâche, et non les outils externes qu’il appelle. Testez tous les aspects des chemins de réussite et d’échec.
Installez les outils de test. Nous utilisons Mocha comme pilote de test dans cette procédure.
npm install mocha --save-dev -g npm install sync-request --save-dev npm install @types/mocha --save-dev
Créez un
tests
dossier contenant un_suite.ts
fichier avec le contenu suivant :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() { }); after(() => { }); it('should succeed with simple inputs', function(done: Mocha.Done) { // Add success test here }); it('it should fail if tool returns 1', function(done: Mocha.Done) { // Add failure test here }); });
Conseil
Votre dossier de test doit se trouver dans le dossier buildandreleasetask. Si vous obtenez une erreur de requête de synchronisation, vous pouvez la contourner en ajoutant la requête de synchronisation au dossier buildandreleasetask avec la commande
npm i --save-dev sync-request
.Créez un
success.ts
fichier dans votre répertoire de test avec le contenu suivant. Cette création de fichier simule l’exécution de la tâche et simule tous les appels à des méthodes externes.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); tmr.setInput('samplestring', 'human'); tmr.run();
Le test de réussite valide qu’avec les entrées appropriées, il réussit sans erreurs ni avertissements et retourne la sortie correcte.
Ajoutez l’exemple de test de réussite suivant à votre
_suite.ts
fichier pour exécuter l’exécuteur fictif de tâche.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.run(); //current, old function. 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 }); });
Créez un
failure.ts
fichier dans votre répertoire de test en tant qu’exécuteur fictif de tâche avec le contenu suivant :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); tmr.setInput('samplestring', 'bad'); tmr.run();
Le test d’échec valide que lorsque l’outil obtient une entrée incorrecte ou incomplète, il échoue de la manière attendue avec une sortie utile.
Ajoutez le code suivant à votre
_suite.ts
fichier pour exécuter l’exécuteur fictif de tâche.it('it should fail if tool returns 1', function(done: Mocha.Done) { this.timeout(1000); let tp = path.join(__dirname, 'failure.js'); let tr: ttm.MockTestRunner = new ttm.MockTestRunner(tp); tr.run(); 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(); });
Exécutez les tests.
tsc mocha tests/_suite.js
Les deux tests doivent réussir. Si vous souhaitez exécuter les tests avec une sortie plus détaillée (ce que vous verrez dans la console de build), définissez la variable d’environnement :
TASK_TEST_TRACE=1
.$env:TASK_TEST_TRACE=1
3. Créer le fichier manifeste d’extension
Le manifeste d’extension contient toutes les informations relatives à votre extension. Il inclut des liens vers vos fichiers, y compris vos dossiers de tâches et dossiers d’images. Vérifiez que vous avez créé un dossier d’images avec extension-icon.png. L’exemple suivant est un manifeste d’extension qui contient la tâche de génération ou de mise en production.
Copiez le code .json suivant et enregistrez-le sous forme vss-extension.json
de fichier dans votre home
répertoire.
Ne créez pas ce fichier dans le dossier buildandreleasetask.
{
"manifestVersion": 1,
"id": "build-release-task",
"name": "Fabrikam Build and Release Tools",
"version": "0.0.1",
"publisher": "fabrikam",
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"description": "Tools for building/releasing with Fabrikam. Includes one build/release task.",
"categories": [
"Azure Pipelines"
],
"icons": {
"default": "images/extension-icon.png"
},
"files": [
{
"path": "buildandreleasetask"
}
],
"contributions": [
{
"id": "custom-build-release-task",
"type": "ms.vss-distributed-task.task",
"targets": [
"ms.vss-distributed-task.tasks"
],
"properties": {
"name": "buildandreleasetask"
}
}
]
}
Remarque
Remplacez l’éditeur par le nom de votre éditeur. Pour plus d’informations, consultez Créer un éditeur.
Contributions
Propriété | Description |
---|---|
id |
Identificateur de la contribution. Doit être unique dans l’extension. Ne doit pas correspondre au nom de la tâche de génération ou de mise en production. En règle générale, le nom de la tâche de génération ou de mise en production se trouve dans l’ID de la contribution. |
type |
Type de contribution. Doit être ms.vss-distributed-task.task. |
targets |
Contributions « ciblées » par cette contribution. Doit être ms.vss-distributed-task.tasks. |
properties.name |
Nom de la tâche. Ce nom doit correspondre au nom du dossier de la tâche de génération autonome ou de pipeline de mise en production correspondante. |
Fichiers
Propriété | Description |
---|---|
path |
Chemin d’accès du fichier ou du dossier par rapport au home répertoire. |
Remarque
Pour plus d’informations sur le fichier manifeste d’extension, tels que ses propriétés et ce qu’ils font, consultez la référence du manifeste d’extension.
4. Empaqueter votre extension
Empaqueter tous vos fichiers ensemble pour obtenir votre extension dans Visual Studio Marketplace. Toutes les extensions sont empaquetées en tant que fichiers .vsix compatibles VSIX 2.0. Microsoft fournit une interface de ligne de commande multiplateforme (CLI) pour empaqueter votre extension.
Une fois que vous disposez de tfx-cli, accédez au répertoire de base de votre extension, puis exécutez la commande suivante :
tfx extension create --manifest-globs vss-extension.json
Remarque
Une version d’extension ou d’intégration doit être incrémentée sur chaque mise à jour.
Lorsque vous mettez à jour une extension existante, mettez à jour la version dans le manifeste ou passez le commutateur de --rev-version
ligne de commande. Cela incrémente le numéro de version de correctif de votre extension et enregistre la nouvelle version dans votre manifeste.
Vous devez révérendr la version de la tâche et la version d’extension pour qu’une mise à jour se produise. tfx extension create --manifest-globs vss-extension.json --rev-version
met uniquement à jour la version de l’extension et non la version de la tâche. Pour plus d’informations, consultez La tâche de génération dans GitHub.
Une fois que votre extension empaquetée se trouve dans un fichier .vsix, vous êtes prêt à publier votre extension sur la Place de marché.
5. Publier votre extension
Pour publier votre extension, vous créez d’abord votre éditeur, puis chargez votre extension, puis partagez-la.
Créer votre éditeur
Toutes les extensions, y compris les extensions de Microsoft, sont identifiées comme étant fournies par un éditeur. Si vous n’êtes pas déjà membre d’un éditeur existant, vous en créez un.
- Connectez-vous au portail de publication visual Studio Marketplace.
- Si vous n’êtes pas déjà membre d’un éditeur existant, vous êtes invité à créer un éditeur. Si vous n’êtes pas invité à créer un éditeur, faites défiler vers le bas de la page et sélectionnez Publier des extensions sous Sites connexes.
- Spécifiez un identificateur pour votre éditeur, par exemple :
mycompany-myteam
.- Cet identificateur est utilisé comme valeur de l’attribut dans le
publisher
fichier manifeste de vos extensions.
- Cet identificateur est utilisé comme valeur de l’attribut dans le
- Spécifiez un nom complet pour votre éditeur, par exemple :
My Team
.
- Spécifiez un identificateur pour votre éditeur, par exemple :
- Passez en revue le Contrat d’éditeur de la Place de marché, puis sélectionnez Créer.
Votre éditeur est défini. Dans une version ultérieure, vous pouvez accorder des autorisations pour afficher et gérer les extensions de votre éditeur. Il est plus facile et plus sécurisé de publier des extensions sous un éditeur commun, sans avoir à partager un ensemble d’informations d’identification entre les utilisateurs.
Charger votre extension
Recherchez le bouton Charger une nouvelle extension , accédez à votre fichier .vsix empaqueté, puis sélectionnez Charger.
Vous pouvez également charger votre extension via l’interface de ligne de commande (CLI) à l’aide de la
tfx extension publish
commande au lieu detfx extension create
empaqueter et de publier votre extension en une seule étape. Vous pouvez éventuellement utiliser--share-with
pour partager votre extension avec un ou plusieurs comptes après sa publication.tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization
Créez un jeton d’accès personnel (PAT).
- Sélectionnez l’étendue « Place de marché (publication) ». Cette étendue limite le jeton à la seule possibilité de publier des extensions sur la Place de marché.
Partager votre extension
Maintenant que vous avez chargé votre extension, elle se trouve sur la Place de marché, mais personne ne peut la voir. Partagez-le avec votre organisation pour pouvoir l’installer et le tester.
Sélectionnez avec le bouton droit votre extension, puis sélectionnez Partager, puis entrez les informations de votre organisation. Vous pouvez également le partager avec d’autres comptes que vous souhaitez avoir accès à votre extension.
Important
Les serveurs de publication doivent être vérifiés pour partager des extensions publiquement. Pour plus d’informations, consultez Package/Publish/Install.
Maintenant que votre extension est partagée dans la Place de marché, toute personne qui souhaite l’utiliser doit l’installer.
6. Créer un pipeline de build et de mise en production pour publier l’extension sur La Place de marché
Créez un pipeline de build et de mise en production sur Azure DevOps pour aider à gérer la tâche personnalisée sur la Place de marché.
Prérequis
Logiciel/outil
Informations
Azure DevOps Projects
Extension Tâches d’extension Azure DevOps
Installez gratuitement les tâches d’extension Azure DevOps dans votre organisation.
Groupe de variables de bibliothèque de pipelines
Créez un groupe de variables de bibliothèque de pipelines pour contenir les variables utilisées par le pipeline. Pour plus d’informations, consultez Ajouter et utiliser des groupes de variables. Vous pouvez créer des groupes de variables à partir de l’onglet Bibliothèque Azure DevOps ou via l’interface CLI. Utilisez les variables de ce groupe dans votre pipeline. Déclarez également les variables suivantes dans le groupe de variables :
publisherId
: ID de votre éditeur de la Place de marchéextensionId
: ID de votre extension, comme déclaré dans le fichier vss-extension.jsonextensionName
: Nom de votre extension, comme déclaré dans le fichier vss-extension.jsonartifactName
: nom de l’artefact créé pour le fichier VSIX
Connexion du service
Créez une connexion de service de la Place de marché et accordez des autorisations d’accès pour tous les pipelines.
Pipeline YAML
Utilisez l’exemple suivant pour créer un pipeline avec YAML. Pour plus d’informations, consultez Créer votre premier pipeline et schéma YAML.
trigger:
- main
pool:
vmImage: "ubuntu-latest"
variables:
- group: variable-group # Rename to whatever you named your variable group in the prerequisite stage of step 6
stages:
- stage: Run_and_publish_unit_tests
jobs:
- job:
steps:
- task: TfxInstaller@4
inputs:
version: "v0.x"
- task: Npm@1
inputs:
command: 'install'
workingDir: '/TaskDirectory' # Update to the name of the directory of your task
- task: Bash@3
displayName: Compile Javascript
inputs:
targetType: "inline"
script: |
cd TaskDirectory # Update to the name of the directory of your task
tsc
- task: Npm@1
inputs:
command: 'custom'
workingDir: '/TestsDirectory' # Update to the name of the directory of your task's tests
customCommand: 'testScript' # See the definition in the explanation section below - it may be called test
- task: PublishTestResults@2
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: '**/ResultsFile.xml'
- stage: Package_extension_and_publish_build_artifacts
jobs:
- job:
steps:
- task: TfxInstaller@4
inputs:
version: "0.x"
- task: Npm@1
inputs:
command: 'install'
workingDir: '/TaskDirectory' # Update to the name of the directory of your task
- task: Bash@3
displayName: Compile Javascript
inputs:
targetType: "inline"
script: |
cd TaskDirectory # Update to the name of the directory of your task
tsc
- task: QueryAzureDevOpsExtensionVersion@4
name: QueryVersion
inputs:
connectTo: 'VsTeam'
connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection
publisherId: '$(PublisherID)'
extensionId: '$(ExtensionID)'
versionAction: 'Patch'
- task: PackageAzureDevOpsExtension@4
inputs:
rootFolder: '$(System.DefaultWorkingDirectory)'
publisherId: '$(PublisherID)'
extensionId: '$(ExtensionID)'
extensionName: '$(ExtensionName)'
extensionVersion: '$(QueryVersion.Extension.Version)'
updateTasksVersion: true
updateTasksVersionType: 'patch'
extensionVisibility: 'private' # Change to public if you're publishing to the marketplace
extensionPricing: 'free'
- task: CopyFiles@2
displayName: "Copy Files to: $(Build.ArtifactStagingDirectory)"
inputs:
Contents: "**/*.vsix"
TargetFolder: "$(Build.ArtifactStagingDirectory)"
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: '$(Build.ArtifactStagingDirectory)'
ArtifactName: '$(ArtifactName)'
publishLocation: 'Container'
- stage: Download_build_artifacts_and_publish_the_extension
jobs:
- job:
steps:
- task: TfxInstaller@4
inputs:
version: "v0.x"
- task: DownloadBuildArtifacts@0
inputs:
buildType: "current"
downloadType: "single"
artifactName: "$(ArtifactName)"
downloadPath: "$(System.DefaultWorkingDirectory)"
- task: PublishAzureDevOpsExtension@4
inputs:
connectTo: 'VsTeam'
connectedServiceName: 'ServiceConnection' # Change to whatever you named the service connection
fileType: 'vsix'
vsixFile: '$(PublisherID).$(ExtensionName)/$(PublisherID)..vsix'
publisherId: '$(PublisherID)'
extensionId: '$(ExtensionID)'
extensionName: '$(ExtensionName)'
updateTasksVersion: false
extensionVisibility: 'private' # Change to public if you're publishing to the marketplace
extensionPricing: 'free'
Pour plus d’informations, consultez Spécifier des événements qui déclenchent des pipelines.
Remarque
Chaque travail utilise un nouvel agent utilisateur et nécessite l’installation de dépendances.
Étapes de canalisation
La section suivante vous aide à comprendre le fonctionnement des étapes du pipeline.
Étape 1 : Exécuter et publier des tests unitaires
Cette étape exécute des tests unitaires et publie les résultats des tests dans Azure DevOps.
Pour exécuter des tests unitaires, ajoutez un script personnalisé au fichier package.json comme dans l’exemple suivant.
"scripts": {
"testScript": "mocha ./TestFile --reporter xunit --reporter-option output=ResultsFile.xml"
},
Ajoutez « Utiliser Node CLI pour Azure DevOps (tfx-cli) » pour installer tfx-cli sur votre agent de build.
Ajoutez la tâche « npm » avec la commande « install » et ciblez le dossier avec le fichier package.json.
Ajoutez la tâche « Bash » pour compiler le TypeScript en JavaScript.
Ajoutez la tâche « npm » avec la commande « custom », ciblez le dossier qui contient les tests unitaires et entrez
testScript
la commande. Utilisez les entrées suivantes :- Commande : personnalisée
- Dossier de travail contenant package.json : /TestsDirectory
- Commande et arguments :
testScript
Ajoutez la tâche « Publier les résultats des tests ». Si vous utilisez le journaliste Mocha XUnit, assurez-vous que le format de résultat est « JUnit » et non « XUnit ». Définissez le dossier de recherche sur le répertoire racine. Utilisez les entrées suivantes :
- Format de résultat de test : JUnit
- Fichiers de résultats des tests : **/ResultsFile.xml
- Dossier de recherche :
$(System.DefaultWorkingDirectory)
Une fois les résultats de test publiés, la sortie sous l’onglet tests doit ressembler à l’exemple suivant.
Étape 2 : Empaqueter l’extension et publier des artefacts de build
Ajoutez « Utiliser Node CLI pour Azure DevOps (tfx-cli) » pour installer tfx-cli sur votre agent de build.
Ajoutez la tâche « npm » avec la commande « install » et ciblez le dossier avec le fichier package.json.
Ajoutez la tâche « Bash » pour compiler le TypeScript en JavaScript.
Ajoutez la tâche « Version de l’extension de requête » pour interroger la version d’extension existante. Utilisez les entrées suivantes :
- Se connecter à : Visual Studio Marketplace
- Visual Studio Marketplace (connexion de service) : Connexion de service
- ID de l’éditeur : ID de votre éditeur visual Studio Marketplace
- ID d’extension : ID de votre extension dans le fichier vss-extension.json
- Augmenter la version : Correctif
- Variable de sortie : Task.Extension.Version
Ajoutez la tâche « Extension de package » pour empaqueter les extensions en fonction du manifeste Json. Utilisez les entrées suivantes :
- Dossier manifestes racines : pointe vers le répertoire racine qui contient le fichier manifeste. Par exemple, $(System.DefaultWorkingDirectory) est le répertoire racine
- Fichier(s) manifeste(s) : vss-extension.json
- ID de l’éditeur : ID de votre éditeur visual Studio Marketplace
- ID d’extension : ID de votre extension dans le fichier vss-extension.json
- Nom de l’extension : nom de votre extension dans le fichier vss-extension.json
- Version de l’extension : $(Task.Extension.Version)
- Remplacer la version des tâches : cochée (true)
- Type de remplacement : Remplacer uniquement le correctif (1.0.r)
- Visibilité de l’extension : si l’extension est toujours en cours de développement, définissez la valeur sur privée. Pour libérer l’extension sur le public, définissez la valeur sur public
Ajoutez la tâche « Copier des fichiers » pour copier des fichiers publiés. Utilisez les entrées suivantes :
- Contenu : tous les fichiers à copier pour les publier en tant qu’artefact
- Dossier cible : dossier dans lequel les fichiers sont copiés
- Par exemple : $(Build.ArtifactStagingDirectory)
Ajoutez « Publier des artefacts de build » pour publier les artefacts à utiliser dans d’autres travaux ou pipelines. Utilisez les entrées suivantes :
- Chemin d’accès à la publication : chemin d’accès au dossier qui contient les fichiers en cours de publication
- Par exemple : $(Build.ArtifactStagingDirectory)
- Nom de l’artefact : nom donné à l’artefact
- Emplacement de publication des artefacts : choisissez « Azure Pipelines » pour utiliser l’artefact dans les travaux futurs
- Chemin d’accès à la publication : chemin d’accès au dossier qui contient les fichiers en cours de publication
Étape 3 : Télécharger les artefacts de build et publier l’extension
Ajoutez « Utiliser Node CLI pour Azure DevOps (tfx-cli) » pour installer tfx-cli sur votre agent de build.
Ajoutez la tâche « Télécharger les artefacts de build » pour télécharger les artefacts dans un nouveau travail. Utilisez les entrées suivantes :
- Téléchargez les artefacts générés par : si vous téléchargez l’artefact sur un nouveau travail à partir du même pipeline, sélectionnez « Build actuelle ». Si vous téléchargez sur un nouveau pipeline, sélectionnez « Build spécifique ».
- Type de téléchargement : choisissez « Artefact spécifique » pour télécharger tous les fichiers publiés.
- Nom de l’artefact : nom de l’artefact publié.
- Répertoire de destination : dossier dans lequel les fichiers doivent être téléchargés.
La dernière tâche dont vous avez besoin est la tâche « Publier l’extension ». Utilisez les entrées suivantes :
- Se connecter à : Visual Studio Marketplace
- Connexion visual Studio Marketplace : ServiceConnection
- Type de fichier d’entrée : fichier VSIX
- Fichier VSIX : /Publisher.*.vsix
- ID de l’éditeur : ID de votre éditeur visual Studio Marketplace
- ID d’extension : ID de votre extension dans le fichier vss-extension.json
- Nom de l’extension : nom de votre extension dans le fichier vss-extension.json
- Visibilité de l’extension : privé ou public
Facultatif : Installer et tester votre extension
Installez une extension partagée avec vous en quelques étapes :
- À partir du panneau de configuration de votre organisation (
https://dev.azure.com/{organization}/_admin
), accédez à la page d’administration de collection de projets. - Sous l’onglet Extensions , recherchez votre extension dans le groupe « Extensions partagées avec moi », puis sélectionnez le lien d’extension.
- Installez l’extension.
Si vous ne voyez pas l’onglet Extensions , vérifiez que vous êtes dans le panneau de configuration (la page d’administration au niveau https://dev.azure.com/{organization}/_admin
de la collection de projets) et non la page d’administration d’un projet.
Si vous ne voyez pas l’onglet Extensions , les extensions ne sont pas activées pour votre organisation. Vous pouvez obtenir un accès anticipé à la fonctionnalité d’extensions en joignant le programme partenaire Visual Studio.
Pour empaqueter et publier des extensions Azure DevOps sur Visual Studio Marketplace, vous pouvez télécharger les tâches d’extension Azure DevOps.
FAQ
Consultez les questions fréquemment posées (FAQ) suivantes sur l’ajout de tâches de build ou de mise en production personnalisées dans les extensions pour Azure DevOps.
Q : Comment puis-je restreindre l’utilisation des commandes Azure Pipelines pour la tâche ?
Vous pouvez restreindre l’utilisation et les variables des commandes Azure Pipelines, qui sont définies par tâche. Cette action peut être utile pour empêcher l’accès illimité aux variables/commandes vso pour les scripts personnalisés exécutés par la tâche. Nous vous recommandons de le configurer pour les nouvelles tâches. Pour appliquer, vous devrez peut-être ajouter l’instruction suivante à votre fichier task.json :
"restrictions": {
"commands": {
"mode": "restricted"
},
"settableVariables": {
"allowed": ["variable1", "test*"]
}
}
Si restricted
la valeur est spécifiée pour mode
: vous ne pouvez exécuter que les commandes suivantes par la tâche :
logdetail
logissue
complete
setprogress
setsecret
setvariable
debug
settaskvariable
prependpath
publish
Les settableVariables
restrictions vous permettent de passer une liste verte de variables, qui sont définies par ou prependpath
par setvariable
commandes. Il permet également des expressions régulières de base. Par exemple, si votre liste verte était : ['abc', 'test*']
, paramètre abc
, test
ou test1
en tant que variables avec n’importe quelle valeur ou les précédant sur le chemin d’accès réussirait, mais si vous essayez de définir un proxy de variable, il est averti. La liste vide signifie qu’aucune variable n’est modifiée par tâche.
Si la ou commands
la clé est omise, la settableVariables
restriction pertinente n’est pas appliquée.
La fonctionnalité de restriction est disponible à partir de la version de l’agent 2.182.1 .
Q : Comment le signal d’annulation est-il géré par une tâche ?
R : L’agent de pipeline envoie et SIGTERM
signale SIGINT
au processus enfant approprié. Il n’existe aucun moyen explicite dans la bibliothèque de tâches à traiter. Pour plus d’informations, consultez l’annulation des travaux de l’agent.
Q : Comment puis-je supprimer la tâche de la collection de projets ?
R : Nous ne prenons pas en charge la suppression automatique des tâches. La suppression automatique n’est pas sécurisée et interrompt les pipelines existants qui utilisent déjà ces tâches. Toutefois, vous pouvez marquer les tâches comme déconseillées. Pour ce faire, placez la version de la tâche et marquez la tâche comme déconseillée.
Q : Comment puis-je mettre à niveau ma tâche personnalisée vers le dernier nœud ?
R : Nous vous recommandons de procéder à la mise à niveau vers la dernière version de Node. Pour obtenir des exemples d’informations, consultez Mise à niveau des tâches vers le nœud 20.
Étant donné que les agents hébergés Par Microsoft et les différentes versions d’Azure DevOps Server ont des cycles de vie différents, il peut y avoir différentes versions de Node Runner installées en fonction de l’emplacement d’exécution d’une tâche. Pour pouvoir exécuter la même tâche sur les agents avec différentes versions de l’exécuteur de nœud, le fichier task.json peut contenir plusieurs sections d’exécution. Dans l’exemple suivant, les agents Azure Pipeline qui incluent l’exécuteur Node 20 le choisissent par défaut, et ceux qui ne revient pas à l’implémentation de Node 10.
"execution": {
"Node10": {
"target": "bash.js",
"argumentFormat": ""
},
"Node20_1": {
"target": "bash.js",
"argumentFormat": ""
}
Pour mettre à niveau vos tâches :
Testez votre ou vos tâches sur les différentes versions de l’exécuteur de nœud pour vous assurer que votre code se comporte comme prévu.
Dans la section d’exécution de votre tâche, mettez à jour depuis
Node
ouNode10
vers ouNode20
versNode16
.Pour prendre en charge les versions antérieures du serveur, vous devez laisser la
Node
/Node10
cible. Les versions antérieures d’Azure DevOps Server peuvent ne pas avoir la dernière version de Node Runner incluse.Vous pouvez choisir de partager le point d’entrée défini dans la cible ou d’avoir des cibles optimisées pour la version du nœud utilisée.
"execution": { "Node10": { "target": "bash10.js", "argumentFormat": "" }, "Node16": { "target": "bash16.js", "argumentFormat": "" }, "Node20_1": { "target": "bash20.js", "argumentFormat": "" }
Important
L’ajout de la prise en charge de l’exécuteur Node 20 sur vos tâches personnalisées entraîne l’échec des tâches sur les agents installés à partir du pipelines-agent-*
flux de mise en production.