Informations de référence sur le manifeste d’extension

  • Article

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Chaque extension a un fichier manifeste JSON qui définit des informations de base sur l’extension. Le fichier définit également comment il peut étendre et améliorer l’expérience. Cet article explique comment créer un manifeste pour votre extension à Azure DevOps.

Conseil

Consultez notre documentation la plus récente sur le développement d’extensions à l’aide du Kit de développement logiciel (SDK) d’extension Azure DevOps.

Créez un fichier nommé vss-extension.json à la racine de votre dossier d’extension. Ce fichier contient des attributs requis, tels que l’ID de l’extension et ses cibles d’installation, où il peut s’exécuter. Il définit également les contributions effectuées par votre extension.

Consultez l’exemple suivant d’un manifeste classique :

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "categories": [
        "Azure Boards"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "content": {
        "details": {
            "path": "readme.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ],
    "files": [
        {
            "path": "launch.html",
            "addressable": true
        },        
        {
            "path": "node_modules/vss-web-extension-sdk/lib",
            "addressable": true,
            "packagePath": "lib"
        }
    ]
}

Attributs requis

Ces propriétés sont requises :

Propriété Description Notes
manifestVersion Nombre correspondant à la version du format manifeste. doit être 1.
Identifiant Identificateur de l’extension. Th ID est une chaîne qui doit être unique parmi les extensions du même éditeur. Il doit commencer par un caractère alphabétique ou numérique et contenir « A » à « Z », « a » à « z », « 0 » à « 9 » et « - » (trait d’union). Exemple : sample-extension.
version Chaîne spécifiant la version d’une extension. Doit être au format major.minor.patch, par exemple 0.1.2 ou 1.0.0. Vous pouvez également ajouter un quatrième nombre pour le format suivant : 0.1.2.3
name Nom court et lisible par l’homme de l’extension. Limité à 200 caractères. Exemple : "Fabrikam Agile Board Extension".
publisher Identificateur de l’éditeur. Cet identificateur doit correspondre à l’identificateur sous lequel l’extension est publiée. Consultez Créer et gérer un éditeur.
Catégories Tableau de chaînes représentant les catégories auxquelles appartient votre extension. Au moins une catégorie doit être fournie et il n’existe aucune limite au nombre de catégories que vous pouvez inclure. Valeurs valides : Azure Repos, , Azure BoardsAzure Pipelines, Azure Test Plans, et Azure Artifacts.

Remarques :
    - Utilisez la version >=0.6.3 de tfx-cli si vous publiez l’extension par programmation.
    - Si vous utilisez l’extension Tâches d’extension Azure DevOps pour publier, vérifiez que sa version est >= 1.2.8. Vous devrez peut-être approuver la mise à jour de l’extension en raison des modifications d’étendue récentes.
    - Les catégories mentionnées précédemment sont présentes en mode natif dans Visual Studio Marketplace et Azure DevOps Server 2019 & ci-dessus. Pour les extensions ciblant des versions antérieures de TFS :
      - Si les clients TFS acquièrent votre extension via Visual Studio Marketplace (pas la galerie locale) dans le contexte connecté, utilisez les catégories précédemment indiquées.
      - Si vous allez partager directement l’extension (autrement dit, pas via Visual Studio Marketplace) avec un client utilisant TFS <=2018, utilisez les catégories suivantes à la place : Code, Planifier et suivre, Générer et publier, Tester, Collaborer et Intégrer. Si vous devez partager les deux via Visual Studio Marketplace et directement avec un client TFS <= 2018, vous devez disposer de 2 packages d’extension.
Cibles Produits et services pris en charge par votre intégration ou extension. Pour plus d’informations, consultez les cibles d’installation. Tableau d’objets, où chaque objet a un id champ indiquant l’un des éléments suivants :
    - Microsoft.VisualStudio.Services(extensions qui fonctionnent avec Azure DevOps ou TFS),
    Microsoft.TeamFoundation.Server- (extension qui fonctionne avec TFS),-
    Microsoft.VisualStudio.Services.Integration (intégrations qui fonctionnent avec Azure DevOps ou TFS),
    - Microsoft.TeamFoundation.Server.Integration (intégrations qui fonctionnent avec TFS)

Exemples d’attributs requis

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Attributs facultatifs

Attributs runtime

Propriété Description Notes
étendues Tableau d’étendues d’autorisation (chaînes) répertoriant les autorisations requises par votre extension. Par exemple, vso.work et vs.code_write indique que votre extension a besoin d’un accès en lecture seule aux éléments de travail et à l’accès en lecture/écriture au code source (et à la ressource associée). Les étendues sont présentées à l’utilisateur lors de l’installation de votre extension. Pour plus d’informations, consultez la liste complète des étendues.
Demandes Tableau de demandes (chaînes) répertoriant les fonctionnalités requises par votre extension. Par exemple, api-version/3.0 indique que votre extension utilise les API version 3.0 et ne peut donc pas s’exécuter dans des produits plus anciens qui ne prennent pas en charge cette version. Pour plus d’informations, consultez la liste complète des demandes.
Baseuri (Facultatif) URL de base pour toutes les URL relatives spécifiées par les contributions de l’extension. Par exemple : https://myapp.com/{{account.name}}/. Cette propriété doit être laissée vide si le contenu de votre extension est empaqueté avec votre extension.
Contributions Tableau de contributions au système.
contributionTypes Tableau de types de contributions définis par l’extension 
{
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "demands": [
        "api-version/3.0"
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}

Attributs de découverte

Ces propriétés facultatives permettent aux utilisateurs de découvrir et d’en savoir plus sur votre extension :

Propriété Description Notes
description Quelques phrases décrivant les extensions. Limité à 200 caractères. La description doit être la « hauteur de l’ascenseur » de votre extension : quelques lignes pour décrire votre extension dans la Place de marché et rendre les personnes qui veulent l’installer. Consulter l’exemple ci-dessous
Icônes Dictionnaire d’icônes représentant l’extension. Clés valides : default (128 x 128 pixels) de type BMP, GIF, EXIF, JPG, PNG et TIFF). D’autres clés telles que large (512 x 512 pixels) peuvent être prises en charge ultérieurement. La valeur de chaque clé est le chemin d’accès au fichier d’icône dans l’extension
balises Tableau de balises de chaîne pour aider les utilisateurs à trouver votre extension. Exemples : agile, , task timerproject management, et ainsi de suite.
Screenshots Tableau d’images qui n’ont pas pu être incluses dans votre contenu. Les captures d’écran sont plus précieuses lorsqu’elles sont proposées dans votre contenu et doivent être utilisées pour vous aider à créer une page de détails de marché de qualité pour votre extension. Utilisez des captures d’écran pour les images moins importantes non proposées dans votre contenu. Chaque image doit être de 1366 x 768 pixels. Chaque path élément est le chemin d’accès au fichier dans l’extension.
content Dictionnaire de fichiers de contenu qui décrivent votre extension aux utilisateurs. Chaque extension doit inclure du contenu solide. C’est ainsi que vous allez montrer aux utilisateurs ce que votre extension peut faire. Faites-le en sorte qu’il soit riche, consommable et incluez des captures d’écran si nécessaire. Incluez un overview.md fichier comme élément de contenu de base. Chaque fichier est supposé être au format GitHub Flavored Markdown . Chaque path élément est le chemin d’accès au fichier Markdown dans l’extension. Clés valides : details. D’autres clés peuvent être prises en charge à l’avenir.
links Dictionnaire de liens qui aident les utilisateurs à en savoir plus sur votre extension, obtenir du support et déplacer. Clés valides : getstarted - premières étapes, configuration ou utilisation. learn - contenu plus approfondi pour aider les utilisateurs à mieux comprendre votre extension ou service. license - Contrat de licence de l’utilisateur final. privacypolicy - Politique de confidentialité pour une extension. support - obtenir de l’aide et du support pour une extension. La valeur de chaque clé est un objet avec un uri champ, qui est l’URL absolue du lien
référentiel Dictionnaire de propriétés décrivant le référentiel de code source pour l’extension Clés valides : type - Type de référentiel. Exemple : git. uri - URL absolue du référentiel.
Badges Tableau de liens vers des badges de métadonnées externes comme TravisCI, Appveyor, et ainsi de suite, à partir des sites de badges approuvés Clés valides : href - Liez l’utilisateur à la sélection du badge. uri - URL absolue de l’image de badge à afficher. description - Description du badge à afficher au pointage.
Marque Dictionnaire des propriétés liées à la marque. Clés valides : color - couleur primaire de l’extension ou du serveur de publication ; peut être un hexadécimal (#ff00ff), RVB (rvb(100 200 50)) ou des noms de couleurs HTML pris en charge (bleu). theme - complète la couleur ; utilisez l’obscurité pour les couleurs de personnalisation foncées ou la lumière pour les couleurs de personnalisation plus claires .

Marquer une extension publique

Par défaut, toutes les extensions de la Place de marché Azure DevOps sont privées. Elles sont visibles uniquement par l’éditeur et les comptes partagés par l’éditeur. Si votre éditeur est vérifié, vous pouvez rendre votre extension publique en définissant l’indicateur Public dans votre manifeste d’extension :

{
    "galleryFlags": [
        "Public"
    ]
}

Ou :

{
    "public": true
}

Pour plus d’informations, consultez Package/Publish/Install.

Marquer une extension pour qu’elle soit en préversion

Si votre extension est prête pour les utilisateurs de la Place de marché à essayer, mais que vous travaillez toujours à quelques bogues ou à ajouter une fonction, vous pouvez la marquer comme preview:

{
    "galleryFlags": [
        "Preview"
    ]
}

Marquer une extension comme préversion payante

Si vous envisagez de vendre votre extension sur la Place de marché, marquez-la comme préversion payante. Une extension marquée comme gratuite ne peut pas être modifiée en paiement.

{
    "galleryFlags": [
        "Paid",
        "Preview"
    ]
}

Marquer une extension comme étant payante

Si vous souhaitez vendre votre extension sur la Place de marché, vous pouvez la marquer avec l’indicateur et __BYOLENFORCED la Paid balise (commence par deux traits de soulignement) :

{
    "galleryFlags": [
        "Paid"        
    ],
     "tags": [        
        "__BYOLENFORCED"
    ]
}

L’indicateur et __BYOLENFORCED la Paid balise doivent être présents pour marquer une extension comme payante sur la Place de marché. ByOL (Bring-Your-Own-License) signifie que l’éditeur de l’extension fournit le mécanisme de facturation et de licence de l’extension, car il n’est pas fourni par Microsoft pour les extensions Azure DevOps. Toutes les extensions payantes sont requises pour définir la stratégie de confidentialité, la stratégie de support et un contrat de licence utilisateur final. En outre, les éditeurs doivent fournir du contenu pour l’onglet tarification de la Place de marché comme suit :

{
    "content": {
        "details": {
            "path": "overview.md"
        }, 
        "pricing": {
            "path": "pricing.md"
        }
    }
}

Vous devez également ajouter une nouvelle section dans votre manifeste d’extension pour remplacer les licences payantes. À l’avenir, nous supprimons les licences payantes case activée et n’avons plus besoin du remplacement. Pour l’instant, vérifiez que votre extension s’affiche comme prévu. Chaque remplacement se compose d’un « ID » et d’un « comportement ». L'« ID » doit correspondre à l’ID des contributions définies dans le manifeste.

"licensing": {

      "overrides": [

        { "id": "my-hub", "behavior": " AlwaysInclude" }
      ]
    }

Si votre extension BYOL payante offre une période d’essai (nous vous recommandons donc), vous pouvez spécifier la durée de l’essai en jours :

{
    "galleryproperties": {
        "trialDays": "30"
    } 
}

Remarque

Si vous souhaitez cibler Azure DevOps, mais que vous ne souhaitez pas exposer d’option de téléchargement pour votre extension, ajoutez la __DoNotDownload balise (commence par deux traits de soulignement) au manifeste d’extension. Si vous déplacez une extension de la facturation et des licences précédemment proposées de Microsoft vers le modèle BYOL, contactez-nous pour connaître les étapes appropriées.

Exemple de propriétés supplémentaires

{
    "description": "Awesome tools to help you and your team do great things everyday.",
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "license-terms.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/tools"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ]
}

Exemple de page Détails

  • 1 - description
  • 2 - icône
  • 3 - catégories
  • 4 - Captures d’écran
  • 5 - contenu (détails)
  • 6 - liens
  • 7 - Personnalisation

carte

Place de marché Q &A - Propriété CustomerQnASupport

Toutes les extensions de Visual Studio Marketplace ont une section Q&A pour autoriser les conversations publiques un-à-un entre les utilisateurs d’extension et les éditeurs. Les éditeurs peuvent choisir entre le Q&A de la Place de marché, les problèmes GitHub ou une URL de Q&A personnalisée. Vous pouvez désactiver Q&A dans la Place de marché à l’aide de la propriété CustomerQnASupport dans le manifeste.

Expérience par défaut (aucune modification du manifeste n’est requise)

  • Pour les extensions avec un dépôt GitHub, Marketplace redirige les utilisateurs dans la section Q&A vers les problèmes GitHub associés.
  • Pour les extensions sans dépôt GitHub, la Place de marché Q&A est activée.

Pour une expérience différente de l’une des options par défaut, utilisez la propriété CustomerQnASupport dans le manifeste.

{
    "CustomerQnASupport": {
        "enablemarketplaceqna": true,
        "url": "http://uservoice.visualstudio.com"
    } 
}

Propriétés

Propriétés de la section Customer Q &A Support :

  • enablemarketplaceqna - champ booléen, défini sur true pour la Place de marché ou la valeur Q&A personnalisée pour désactiver Q&A
  • URL - chaîne, URL pour Q&A personnalisé

Exemples montrant l’utilisation de la prise en charge de Q &A

Exemple : Extension à l’aide de Q &A personnalisés

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true",
        "url": "http://uservoice.visualstudio.com"
    } 
}

Exemple : Extension avec dépôt GitHub, mais utilisation de la Place de marché Q &A au lieu de problèmes GitHub

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true"
    } 
}

Exemple : Extension désactivant la section Q &A

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"false"
    } 
}

Étendues

Dans votre extension, vous pouvez définir une ou plusieurs étendues. Ces étendues déterminent les ressources auxquelles votre extension peut accéder et les opérations qu’il est autorisée à effectuer sur ces ressources. Les étendues que vous spécifiez dans votre manifeste d’extension sont les étendues définies sur les jetons d’accès émis à votre extension. Pour plus d’informations, consultez Authentification et sécurité.

Si aucune étendue n’est spécifiée, les extensions ne sont fournies qu’à l’accès aux données de profil utilisateur et d’extension.

Étendues prises en charge

Catégorie Étendue Nom Description
Pools d’agents vso.agentpools Pools d’agents (lecture) Accorde la possibilité d’afficher des tâches, des pools, des files d’attente, des agents et des travaux en cours d’exécution ou récemment terminés pour les agents.
vso.agentpools_manage Pools d’agents (lecture, gestion) Accorde la possibilité de gérer des pools, des files d’attente et des agents.
vso.environment_manage Environnement (lecture, gestion) Accorde la possibilité de gérer des pools, des files d’attente, des agents et des environnements.
Analyse vso.analytics Analytique (lecture) Accorde la possibilité d’interroger des données d’analyse.
Audit vso.auditlog Journal d’audit (lecture) Accorde la possibilité de lire le journal d’audit aux utilisateurs.
vso.auditstreams_manage Audit Flux (lecture) Accorde la possibilité de gérer les flux d’audit aux utilisateurs.
Créer vso.build Build (lire) Accorde la possibilité d’accéder aux artefacts de build, notamment les résultats de build, les définitions et les demandes, et la possibilité de recevoir des notifications sur les événements de génération via des hooks de service.
vso.build_execute Générer (lecture et exécution) Accorde la possibilité d’accéder aux artefacts de build, notamment les résultats de build, les définitions et les demandes, ainsi que la possibilité de mettre en file d’attente une build, de mettre à jour les propriétés de build et de recevoir des notifications sur les événements de génération via des hooks de service.
Code vso.code Code (lire) Accorde la possibilité de lire le code source et les métadonnées sur les validations, les ensembles de modifications, les branches et d’autres artefacts de contrôle de version. Accorde également la possibilité de rechercher du code et d’être averti des événements de contrôle de version via des hooks de service.
vso.code_write Code (lecture et écriture) Accorde la possibilité de lire, de mettre à jour et de supprimer du code source, d’accéder aux métadonnées relatives aux validations, aux ensembles de modifications, aux branches et à d’autres artefacts de contrôle de version. Accorde également la possibilité de créer et de gérer des demandes de tirage et des révisions de code et de recevoir des notifications sur les événements de contrôle de version via des hooks de service.
vso.code_manage Code (lecture, écriture et gestion) Accorde la possibilité de lire, de mettre à jour et de supprimer du code source, d’accéder aux métadonnées relatives aux validations, aux ensembles de modifications, aux branches et à d’autres artefacts de contrôle de version. Accorde également la possibilité de créer et de gérer des référentiels de code, de créer et de gérer des demandes de tirage et des révisions de code, et de recevoir des notifications sur les événements de contrôle de version via des hooks de service.
vso.code_full Code (complet) Octroie un accès complet au code source, aux métadonnées sur les validations, les ensembles de modifications, les branches et d’autres artefacts de contrôle de version. Accorde également la possibilité de créer et de gérer des référentiels de code, de créer et de gérer des demandes de tirage et des révisions de code, et de recevoir des notifications sur les événements de contrôle de version via des hooks de service. Inclut également une prise en charge limitée des API d’om client.
vso.code_status Code (état) Accorde la possibilité de lire et d’écrire l’état de la validation et de la demande de tirage.
serveur Connecter ed vso.connected_server Serveur connecté Accorde la possibilité d’accéder aux points de terminaison nécessaires à partir d’un serveur connecté local.
Droits vso.entitlements Droits d’utilisation (lecture) Fournit un accès en lecture seule au point de terminaison des droits de licence pour obtenir les droits de compte.
vso.memberentitlementmanagement MemberEntitlement Management (lecture) Accorde la possibilité de lire les utilisateurs, leurs licences ainsi que les projets et extensions auxquels ils peuvent accéder.
vso.memberentitlementmanagement_write MemberEntitlement Management (écriture) Accorde la possibilité de gérer les utilisateurs, leurs licences ainsi que les projets et extensions auxquels ils peuvent accéder.
Extensions vso.extension Extensions (lecture) Accorde la possibilité de lire les extensions installées.
vso.extension_manage Extensions (lecture et gestion) Accorde la possibilité d’installer, de désinstaller et d’effectuer d’autres actions administratives sur les extensions installées.
vso.extension.data Données d’extension (lecture) Accorde la possibilité de lire des données (paramètres et documents) stockées par des extensions installées.
vso.extension.data_write Données d’extension (lecture et écriture) Accorde la possibilité de lire et d’écrire des données (paramètres et documents) stockées par les extensions installées.
Graph &identity vso.graph Graphe (lecture) Accorde la possibilité de lire les informations d’appartenance à l’utilisateur, au groupe, à l’étendue et au groupe.
vso.graph_manage Graph (gérer) Accorde la possibilité de lire les informations d’appartenance des utilisateurs, des groupes, de l’étendue et du groupe, et d’ajouter des utilisateurs, des groupes et de gérer les appartenances aux groupes.
vso.identity Identité (lire) Accorde la possibilité de lire des identités et des groupes.
vso.identity_manage Identité (gérer) Accorde la possibilité de lire, d’écrire et de gérer des identités et des groupes.
Groupe d’ordinateurs vso.machinegroup_manage Groupe de déploiement (lecture, gestion) Permet de gérer les pools de groupes de déploiement et d’agents.
Marché vso.gallery Marketplace Accorde l’accès en lecture aux éléments publics et privés et aux éditeurs.
vso.gallery_acquire Place de marché (acquisition) Accorde l’accès en lecture et la possibilité d’acquérir des éléments.
vso.gallery_publish Place de marché (publication) Accorde l’accès en lecture et la possibilité de charger, mettre à jour et partager des éléments.
vso.gallery_manage Place de marché (gérer) Accorde l’accès en lecture et la possibilité de publier et de gérer des éléments et des éditeurs.
Notifications vso.notification Notifications (lecture) Fournit un accès en lecture aux abonnements et aux métadonnées d’événement, y compris les valeurs de champ filtrables.
vso.notification_write Notifications (écriture) Fournit un accès en lecture et en écriture aux abonnements et un accès en lecture aux métadonnées d’événement, y compris les valeurs de champ filtrables.
vso.notification_manage Notifications (gérer) Fournit un accès en lecture, en écriture et en gestion aux abonnements et l’accès en lecture aux métadonnées d’événement, y compris les valeurs de champ filtrables.
vso.notification_diagnostics Notifications (diagnostics) Fournit l’accès aux journaux de diagnostic liés aux notifications et offre la possibilité d’activer les diagnostics pour des abonnements individuels.
Emballage vso.packaging Empaquetage (lecture) Accorde la possibilité de lire des flux et des packages.
vso.packaging_write Empaquetage (lecture et écriture) Accorde la possibilité de créer et lire des flux et des packages.
vso.packaging_manage Empaquetage (lecture, écriture et gestion) Accorde la possibilité de créer, lire, mettre à jour et supprimer des flux et des packages.
Ressources de pipeline vso.pipelineresources_use Ressources de pipeline (utilisation) Accorde la possibilité d’approuver la demande d’un pipeline pour utiliser une ressource protégée : pool d’agents, environnement, file d’attente, référentiel, fichiers sécurisés, connexion de service et groupe de variables.
vso.pipelineresources_manage Ressources de pipeline (utilisation et gestion) Accorde la possibilité de gérer une ressource protégée ou la demande d’un pipeline pour utiliser une ressource protégée : pool d’agents, environnement, file d’attente, référentiel, fichiers sécurisés, connexion de service et groupe de variables.
Projet et équipe vso.project Projet et équipe (lire) Accorde la possibilité de lire des projets et des équipes.
vso.project_write Projet et équipe (lecture et écriture) Accorde la possibilité de lire et de mettre à jour des projets et des équipes.
vso.project_manage Projet et équipe (lecture, écriture et gestion) Accorde la possibilité de créer, lire, mettre à jour et supprimer des projets et des équipes.
Version release vso.release Mise en production (lecture) Accorde la possibilité de lire les artefacts de mise en production, notamment les versions, les définitions de mise en production et l’environnement de mise en production.
vso.release_execute Mise en production (lecture, écriture et exécution) Accorde la possibilité de lire et de mettre à jour les artefacts de mise en production, notamment les versions, les définitions de mise en production et l’environnement de mise en production, ainsi que la possibilité de mettre en file d’attente une nouvelle version.
vso.release_manage Mise en production (lecture, écriture, exécution et gestion) Accorde la possibilité de lire, de mettre à jour et de supprimer des artefacts de mise en production, notamment les versions, les définitions de mise en production et l’environnement de mise en production, ainsi que la possibilité de mettre en file d’attente et d’approuver une nouvelle version.
Fichiers sécurisés vso.securefiles_read Fichiers sécurisés (lecture) Accorde la possibilité de lire des fichiers sécurisés.
vso.securefiles_write Fichiers sécurisés (lecture, création) Accorde la possibilité de lire et de créer des fichiers sécurisés.
vso.securefiles_manage Fichiers sécurisés (lecture, création et gestion) Accorde la possibilité de lire, de créer et de gérer des fichiers sécurisés.
Sécurité vso.security_manage Sécurité (gérer) Accorde la possibilité de lire, d’écrire et de gérer les autorisations de sécurité.
Connexions de service vso.serviceendpoint Points de terminaison de service (lecture) Accorde la possibilité de lire les points de terminaison de service.
vso.serviceendpoint_query Points de terminaison de service (lecture et requête) Accorde la possibilité de lire et d’interroger des points de terminaison de service.
vso.serviceendpoint_manage Points de terminaison de service (lecture, requête et gestion) Accorde la possibilité de lire, d’interroger et de gérer les points de terminaison de service.
Paramètres vso.settings Paramètres (lecture) Accorde la possibilité de lire les paramètres.
vso.settings_write Paramètres (lecture et écriture) Accorde la possibilité de créer et de lire des paramètres.
Symboles vso.symbols Symboles (lecture) Accorde la possibilité de lire des symboles.
vso.symbols_write Symboles (lecture et écriture) Accorde la possibilité de lire et d’écrire des symboles.
vso.symbols_manage Symboles (lecture, écriture et gestion) Accorde la possibilité de lire, d’écrire et de gérer des symboles.
Groupes de tâches vso.taskgroups_read Groupes de tâches (lecture) Accorde la possibilité de lire des groupes de tâches.
vso.taskgroups_write Groupes de tâches (lecture, création) Accorde la possibilité de lire et de créer des groupes de tâches.
vso.taskgroups_manage Groupes de tâches (lecture, création et gestion) Accorde la possibilité de lire, de créer et de gérer des groupes de tâches.
Tableau de bord de l’équipe vso.dashboards Tableaux de bord d’équipe (lecture) Accorde la possibilité de lire les informations du tableau de bord de l’équipe.
vso.dashboards_manage Tableaux de bord d’équipe (gérer) Accorde la possibilité de gérer les informations du tableau de bord de l’équipe.
Gestion des tests vso.test Gestion des tests (lecture) Accorde la possibilité de lire des plans de test, des cas, des résultats et d’autres artefacts associés à la gestion des tests.
vso.test_write Gestion des tests (lecture et écriture) Accorde la possibilité de lire, de créer et de mettre à jour des plans de test, des cas, des résultats et d’autres artefacts associés à la gestion des tests.
Threads vso.threads_full Threads de demande de tirage Accorde la possibilité de lire et d’écrire pour extraire des threads de commentaires de demande.
Jetons vso.tokens Jetons d’autorisation délégués Accorde la possibilité de gérer les jetons d’autorisation délégués aux utilisateurs.
vso.tokenadministration Jeton Administration istration Accorde la possibilité de gérer (afficher et révoquer) des jetons existants aux administrateurs de l’organisation.
Profil utilisateur vso.profile Profil utilisateur (lire) Accorde la possibilité de lire votre profil, comptes, collections, projets, équipes et autres artefacts organisationnels de niveau supérieur.
vso.profile_write Profil utilisateur (écriture) Accorde la possibilité d’écrire dans votre profil.
Groupes de variables vso.variablegroups_read Groupes de variables (lecture) Accorde la possibilité de lire des groupes de variables.
vso.variablegroups_write Groupes de variables (lecture, création) Accorde la possibilité de lire et de créer des groupes de variables.
vso.variablegroups_manage Groupes de variables (lecture, création et gestion) Accorde la possibilité de lire, de créer et de gérer des groupes de variables.
Wiki vso.wiki Wiki (lecture) Accorde la possibilité de lire des wikis, des pages wiki et des pièces jointes wiki. Accorde également la possibilité de rechercher des pages wiki.
vso.wiki_write Wiki (lecture et écriture) Accorde la possibilité de lire, de créer et de mettre à jour des wikis, des pages wiki et des pièces jointes wiki.
Éléments de travail vso.work Éléments de travail (lire) Octroie la possibilité de lire des éléments de travail, des requêtes, des tableaux, des zones et des itérations, ainsi que d’autres métadonnées associées au suivi des éléments de travail. Accorde également la possibilité d’exécuter des requêtes, de rechercher des éléments de travail et de recevoir des notifications sur les événements d’élément de travail via des hooks de service.
vso.work_write Éléments de travail (lire et écrire) Octroie la possibilité de lire, de créer et de mettre à jour des éléments de travail et des requêtes, de mettre à jour des métadonnées de carte, de lire des zones de lecture et des itérations chemins d’accès à d’autres métadonnées associées au suivi des éléments de travail, d’exécuter des requêtes et de recevoir des notifications sur les événements d’élément de travail via des hooks de service.
vso.work_full Éléments de travail (complet) Octroie un accès complet aux éléments de travail, aux requêtes, aux backlogs, aux plans et aux métadonnées de suivi des éléments de travail. Fournit également la possibilité de recevoir des notifications sur les événements d’élément de travail via des hooks de service.
Emprunt d’identité utilisateur user_impersonation Emprunt d’identité utilisateur Disposez d’un accès complet aux API REST Visual Studio Team Services. Demandez et/ou donnez votre consentement à cette étendue avec précaution, car elle est très puissante !

Modification de l’étendue de l’extension publiée

Vous pouvez modifier l’étendue d’une extension publiée. Si vous avez déjà installé votre extension (et autorisé l’ensemble d’étendues précédent), vous devez autoriser les nouvelles étendues avant de pouvoir effectuer une mise à niveau vers la version la plus récente.

La section Action requise du hub des paramètres d’extension affiche un utilisateur qui, le cas échéant, nécessite une autorisation :

modification de portée

Un administrateur peut ensuite passer en revue et autoriser le nouvel ensemble d’étendues :

scope-change-dialog

Cibles d’installation

Comme le nom l’indique, les cibles d’installation définissent les produits et services où vous pouvez installer votre extension. Microsoft.VisualStudio.Services est la cible d’installation la plus courante et indique que l’extension peut être installée dans Azure DevOps.

Les cibles d’installation d’une extension ou d’une intégration sont spécifiées via le targets champ du manifeste.

Identificateurs pris en charge pour les extensions :

  • Microsoft.VisualStudio.Services.Cloud: installe dans Azure DevOps Services
  • Microsoft.TeamFoundation.Server: installe dans Azure DevOps Server
  • Microsoft.VisualStudio.Services: s’installe dans les deux. Raccourci pour Microsoft.VisualStudio.Services.Cloud et Microsoft.TeamFoundation.Server version [14.2,)

Identificateurs pris en charge pour les intégrations :

  • Microsoft.VisualStudio.Services.Cloud.Integration: s’intègre à Azure DevOps Services
  • Microsoft.TeamFoundation.Server.Integration: s’intègre à Azure DevOps Server
  • Microsoft.VisualStudio.Services.Integration: s’intègre avec les deux. Raccourci pour Microsoft.VisualStudio.Services.Cloud.Integration et Microsoft.TeamFoundation.Server.Integration

Pour plus d’informations, consultez les points d’extensibilité.

Exemples de cibles d’installation

Exemple : Extension qui fonctionne avec Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Exemple : Extension qui fonctionne uniquement avec Azure DevOps Services

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        }
    ]
}

Les cibles d’installation peuvent également être utilisées dans le manifeste des intégrations. Par exemple, les produits, les applications ou les outils qui fonctionnent avec, mais qui ne s’installent pas dans Azure DevOps.

Exemple : Intégration qui fonctionne avec Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ]
}

Exemple : Intégration qui fonctionne uniquement avec Azure DevOps Server

{
    "targets": [
        {
            "id": "Microsoft.TeamFoundation.Server.Integration"
        }
    ]
}

Versions cibles d’installation

Certains identificateurs cibles d’installation, tels Microsoft.TeamFoundation.Server que et Microsoft.TeamFoundation.Server.Integration, prennent en charge une plage de versions facultative. Cette plage de versions facultative précise davantage les versions prises en charge sur laquelle l’extension ou l’intégration est prise en charge.

La version ou la plage de versions est spécifiée via le version champ sur l’objet cible d’installation. Cette valeur peut être :

  • Une version spécifique, par exemple : 15.0 (2017 RTM uniquement)
  • Plage de versions prises en charge, par exemple : [14.0) (2015 RTM et versions ultérieures), [14.3,15.1] (2015 Update 3 à 2017 Update 1). Les valeurs de plage sont affinées à l’aide de :
    • [: version minimale inclusive
    • ]: version maximale inclusive
    • (: version minimale exclusive
    • ): version maximale exclusive

Numéros de version pour Azure DevOps Server :

Version release Versions Version
2010 Toutes les mises en production 10.0
2012 Toutes les mises en production 11.0
2013 RTM et mises à jour 12.0, 12.1, 12.2, 12.3, 12.4
2015 RTM et mises à jour 14.0, 14.1, 14.2, 14.3
2017 RTM et mises à jour 15.0, 15.1
2018 RTM et mises à jour 16,0
2019 RTM et mises à jour 17,0
2020 RTM et mises à jour 18.0

Exemples montrant les versions

Exemple : Extension qui fonctionne avec Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[15.0,)"
        }
    ]
}

Raccourcis

Microsoft.VisualStudio.Services est un raccourci pour Azure DevOps.

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

équivaut à :

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[14.2,)"
        }
    ]
}

Utilisation des cibles et des demandes d’installation

Les cibles et demandes d’installation sont utilisées ensemble pour présenter aux utilisateurs une vue correcte des produits/services avec lesquels votre extension ou intégration est compatible. Par exemple, en spécifiant une cible d’installation avec Microsoft.VisualStudio.Services une demande de api-version/3.0 moyens, l’extension fonctionne avec Azure DevOps.

Conseil

Pour plus d’informations sur les API REST, consultez la référence de l’API REST.

Exemple : Extension qui utilise les API version 3.0

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ]
}

Résout les cibles d’installation suivantes :

  1. Microsoft.VisualStudio.Services.Cloud
  2. Microsoft.TeamFoundation.ServerVersion: [15.0,)

Exemple : Intégration qui utilise les API version 2.0

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ],
    "demands": [
        "api-version/2.0"
    ]
}

Résout les cibles d’installation suivantes :

  1. Microsoft.VisualStudio.Services.Cloud.Integration
  2. Microsoft.TeamFoundation.Server.IntegrationVersion: [14.0,)

Demandes

Les demandes vous permettent de spécifier des fonctionnalités et d’autres fonctionnalités requises par votre extension. Vous pouvez utiliser ces demandes pour limiter l’emplacement où votre extension peut être publiée ou installée.

Les demandes sont utilisées par visual Studio Marketplace pour répertorier les produits et les environnements avec lesquels votre extension est compatible, ce qui permet aux clients de comprendre si votre extension fonctionne avec leur version d’Azure DevOps, par exemple.

Consultez l’exemple suivant de la façon dont les demandes sont spécifiées dans le manifeste d’extension.

{
    "demands": [
        "api-version/3.0",
        "contribution/ms.vss-dashboards-web.widget-catalog"
    ]
}

Dans cet exemple, l’extension exige la version 3.0 des API, ce qui signifie qu’elle ne peut être installée que sur Azure DevOps. L’extension (et sa widget-catalog contribution) doivent également ms.vss-dashboards-web être installées (et activées) dans le regroupement avant que votre extension puisse être installée.

Demandes prises en charge

Type Description Vérifié lors de la publication ? Activé lors de l’installation ?
environment/cloud Nécessite une exécution dans un environnement cloud Oui Oui
environment/onprem Nécessite l’exécution dans un environnement local Oui Oui
api-version/{version} Nécessite une version d’API spécifique (minimum) Non Oui
extension/{id} Nécessite l’installation/l’activation d’une extension spécifique Non Oui
contribution/{id} Nécessite la disponibilité d’une contribution spécifique Non Oui
contributionType/{id} Nécessite qu’un type de contribution spécifique soit disponible Non Oui

Remarque

  • Utilisez environment/cloud et environment/onprem uniquement lorsque votre extension a des exigences liées à la topologie qui nécessitent l’exécution dans cet environnement particulier.
  • extension, contributionet contributionType les demandes sont évaluées au moment de l’installation et nécessitent que l’extension spécifiée soit déjà installée et activée dans l’organisation/le regroupement.

Fichiers

La files section est l’endroit où vous référencez tous les fichiers que vous souhaitez inclure dans votre extension. Vous pouvez ajouter des dossiers et des fichiers individuels :

{
    "files": [
        {
            "path": "hello-world.html", "addressable": true
        },
        {
            "path": "scripts", "addressable": true
        },
        {
            "path": "images/logo.png", "addressable": true, "packagePath": "/"
        }
    ]
}

Propriétés

Propriétés de la section Fichiers :

  • chemin d’accès : chemin d’accès à la ressource sur le disque, qui peut être relatif à votre répertoire racine.
  • adressable : (facultatif) Défini sur true si vous souhaitez que votre fichier soit adressable à l’URL. La valeur par défaut est false.
  • packagePath : (facultatif) Chemin d’accès à la ressource dans le package. La valeur par défaut est le chemin relatif sur le disque à partir de votre répertoire racine.
  • contentType – (facultatif) type MIME du fichier. La valeur par défaut est la meilleure estimation en fonction des paramètres de l’extension de fichier et du système d’exploitation.
  • assetType : (facultatif) Spécifiez la valeur de l’attribut Type de l’entrée de ressource dans le manifeste VSIX. Il peut également s’agir d’un tableau de chaînes, auquel cas plusieurs entrées de ressources sont ajoutées pour ce fichier. Valeur par défaut du packagePath.
  • lang – (facultatif) Langue de cette ressource. Les fichiers localisés sont servis en fonction de l’en-tête Accept-Language. Laissez vide pour indiquer que ce fichier est dans la langue par défaut (ou de secours). Les versions localisées du même fichier doivent avoir le même assetType.

Contributions

Chaque entrée de contribution a les propriétés suivantes :

  • ID : ID de référence (chaîne) pour la contribution. L’ID de chaque contribution doit être unique dans une extension. Voir référencer des contributions et des types.
  • type : ID du contributionType de cette contribution.
  • description - (Facultatif) Chaîne décrivant ce que fournit la contribution.
  • cibles : tableau d’ID de contribution auquel la contribution cible (contribution). Consultez Les contributions de ciblage.
  • properties - (Facultatif) Objet qui inclut des propriétés pour la contribution, tel que défini dans le type de contribution.

Pour plus d’informations, consultez la vue d’ensemble du modèle de contribution.

Types de contribution

Chaque entrée de contribution a les propriétés suivantes :

  • ID : ID de référence (chaîne) pour le type de contribution. L’ID de chaque type de contribution doit être unique dans une extension. Voir référencer des contributions et des types.
  • nom : nom convivial du type de contribution.
  • description : (Facultatif) Chaîne décrivant plus en détail le type de contribution.
  • properties - (Facultatif) Dictionnaire qui mappe les noms de propriétés aux descriptions de propriétés. Ces propriétés décrivent les propriétés obligatoires et facultatives que les contributions de ce type peuvent utiliser.

Les descriptions des propriétés ont les propriétés suivantes :

  • description : (Facultatif) Chaîne décrivant ce que la propriété est utilisée.
  • obligatoire : (Facultatif) Valeur booléenne, qui, si true indique que la propriété est requise pour toutes les contributions de ce type.
  • type : type de valeur que la propriété peut avoir, qui peut être chaîne, uri, guid, booléen, entier, double, dateTime, tableau ou objet.

Pour plus d’informations, consultez la vue d’ensemble du modèle de contribution.

Référencement des contributions et des types

Utilisez des identificateurs uniques pour référencer les contributions et les types de contributions. Types de référence avec la type propriété et référencer d’autres contributions avec la targets propriété.

  • Une référence complète de contribution inclut l’identificateur de l’éditeur, l’identificateur d’extension et l’identificateur de contribution/type, séparés par un point (.). Par exemple, ms.vss-web.hub est l’identificateur complet de la contribution avec l’identificateur de « hub » dans l’extension « vss-web » publiée par l’éditeur « ms » (Microsoft).
  • Les références de contribution relatives peuvent être utilisées dans un manifeste d’extension pour la référence d’une contribution à un autre type de contribution ou de contribution dans cette même extension. Dans ce cas, les identificateurs d’éditeur et d’extension ne sont pas inclus, et l’identificateur est un point (.) suivi de l’identificateur de contribution. Par exemple, .hub » peut être utilisé dans l’extension « vss-web » mentionnée précédemment comme raccourci pour « ms.vss-web.hub ».

Ciblage des contributions

Certaines contributions agissent comme des conteneurs ciblés par d’autres contributions.

  • Les contributions hub peuvent cibler des groupes hub. Lorsqu’une page est affichée, l’interface utilisateur web affiche toutes les contributions hub qui ciblent le groupe hub sélectionné. Les groupes hub ciblent une collection de groupes hub, qui définit un ensemble de groupes hub qui s’affichent dans une zone de navigation donnée, par exemple, des pages d’administration au niveau du projet.
  • Différents types de contributions peuvent cibler des menus : action, action de lien hypertexte et fournisseur d’actions. Les actions et les actions de lien hypertexte fournissent des entrées d’élément de menu uniques. Un fournisseur d’actions peut fournir plusieurs éléments de menu dynamique. Pour un menu donné, les éléments sont agrégés sur toutes les contributions (de l’un de ces types) qui ciblent cette contribution de menu spécifique.

Ajout d’une icône hub

Pour plus d’informations sur l’ajout d’une icône à votre hub, case activée instructions sur l’icône hub.

Services de badge pris en charge

La Place de marché prend uniquement en charge les badges des services approuvés suivants :

  • api.travis-ci.org/
  • badge.fury.io/
  • badges.frapsoft.com/
  • badges.gitter.im/
  • badges.greenkeeper.io/
  • cdn.travis-ci.org/
  • ci.appveyor.com/
  • codeclimate.com/
  • codecov.io/
  • coveralls.io/
  • david-dm.org/
  • gemnasium.com/
  • img.shields.io/
  • isitmaintained.com/
  • marketplace.visualstudio.com/
  • snyk.io/
  • travis-ci.com/
  • travis-ci.org/
  • vsmarketplacebadges.dev/
  • bithound.io/
  • deepscan.io/
  • githost.io/
  • gitlab.com/
  • opencollective.co/

Remarque

Remplacez « vsmarketplacebadge.apphb.com » par « vsmarketplacebadges.dev ».

Pour afficher un badge à partir d’un autre service, contactez vsmarketplace@microsoft.com.

Exemple de manifeste

L’extension suivante contribue à une action au menu contextuel des builds terminées et à un hub au groupe de hubs de build :

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write"
    ],
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}