Référence du schéma d’extension VSIX 2.0

Un fichier manifeste de déploiement VSIX décrit le contenu d’un package VSIX. Le format de fichier est régi par un schéma. La version 2.0 de ce schéma prend en charge l’ajout de types et d’attributs personnalisés. Le schéma du manifeste est extensible. Le chargeur de manifeste ignore les éléments et attributs XML qu’il ne comprend pas.

Schéma du manifeste de package

L’élément racine du fichier XML du manifeste est <PackageManifest>. Il a un attribut Versionunique, qui est la version du format manifeste. Si des modifications majeures sont apportées au format, le format de version est modifié. Cet article décrit le format de manifeste version 2.0, qui est spécifié dans le manifeste en définissant l’attribut Version sur la valeur de Version="2.0 ».

Élément PackageManifest

Dans l’élément <PackageManifest> racine, vous pouvez utiliser les éléments suivants :

• <Metadata> - Métadonnées et informations publicitaires sur le package lui-même. Metadata Un seul élément est autorisé dans le manifeste.

• <Installation> - Cette section définit la façon dont ce package d’extension peut être installé, y compris les références SKU d’application dans lesquelles il peut être installé. Un seul Installation élément est autorisé dans le manifeste. Un manifeste doit avoir un Installation élément, ou ce package n’est pas installé dans une référence SKU.

• <Dependencies> - Une liste facultative de dépendances pour ce package est définie ici.

• <Assets> - Cette section contient toutes les ressources contenues dans ce package. Sans cette section, ce package n’affiche aucun contenu.

• <AnyElement>* - Le schéma de manifeste est suffisamment flexible pour autoriser les autres éléments. Tous les éléments enfants non reconnus par le chargeur de manifeste sont exposés dans l’API Extension Manager en tant qu’objets XmlElement supplémentaires. À l’aide de ces éléments enfants, les extensions VSIX peuvent définir des données supplémentaires dans le fichier manifeste qui s’exécute dans Visual Studio peuvent accéder au moment de l’exécution. Consultez Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Élément Metadata

Cette section est les métadonnées relatives au package, à son identité et à ses informations publicitaires. <Metadata> contient les éléments suivants :

• <Identity> - Définit les informations d’identification pour ce package et inclut les attributs suivants :

  • Id - Cet attribut doit être un ID unique pour le package choisi par son auteur. Le nom doit être qualifié de la même façon que les types CLR sont espaces de noms : Company.Product.Feature.Name. L’attribut Id est limité à 100 caractères.

  • Version - Définit la version de ce package et son contenu. Cet attribut suit le format de contrôle de version de l’assembly CLR : Major.Minor.Build.Revision (1.2.40308.00). Un package avec un numéro de version supérieur est considéré comme des mises à jour du package et peut être installé sur la version installée existante.

  • Language - Cet attribut est la langue par défaut du package et correspond aux données textuelles de ce manifeste. Cet attribut suit la convention de code des paramètres régionaux CLR pour les assemblys de ressources, par exemple : en-us, fr-fr. Vous pouvez spécifier neutral de déclarer une extension indépendante du langage qui s’exécutera sur n’importe quelle version de Visual Studio. La valeur par défaut est neutral.

  • Publisher - Cet attribut identifie l’éditeur de ce package, qu’il s’agisse d’une société ou d’un nom individuel. L’attribut Publisher est limité à 100 caractères.

• <DisplayName> - Cet élément spécifie le nom du package convivial affiché dans l’interface utilisateur du Gestionnaire d’extensions. Le DisplayName contenu est limité à 50 caractères.

• <Description> - Cet élément facultatif est une brève description du package et de son contenu affiché dans l’interface utilisateur d’Extension Manager. Le Description contenu peut contenir n’importe quel texte souhaité, mais il est limité à 1 000 caractères.

• <MoreInfo> - Cet élément facultatif est une URL vers une page en ligne qui contient une description complète de ce package. Le protocole doit être spécifié en tant que http.

• <License> - Cet élément facultatif est un chemin d’accès relatif à un fichier de licence (.txt, .rtf) contenu dans le package.

• <ReleaseNotes> - Cet élément facultatif est soit un chemin relatif vers un fichier de notes de publication contenu dans le package (.txt, .rtf) soit une URL vers un site web qui affiche les notes de publication.

• <Icon> - Cet élément facultatif est un chemin d’accès relatif à un fichier image (png, bmp, jpeg, ico) contenu dans le package. L’image d’icône doit être de 32 x 32 pixels (ou sera réduite à cette taille) et apparaît dans l’interface utilisateur de la vue de liste. Si aucun élément n’est Icon spécifié, l’interface utilisateur utilise une valeur par défaut.

• <PreviewImage> - Cet élément facultatif est un chemin relatif vers un fichier image (png, bmp, jpeg) contenu dans le package. L’image d’aperçu doit être de 200 x 200 pixels et affichée dans l’interface utilisateur des détails. Si aucun élément n’est PreviewImage spécifié, l’interface utilisateur utilise une valeur par défaut.

• <Tags> - Cet élément facultatif répertorie des balises de texte délimitées par des points-virgules supplémentaires qui sont utilisées pour les indicateurs de recherche. L’élément Tags est limité à 100 caractères.

• <GettingStartedGuide> - Cet élément facultatif est soit un chemin relatif vers un fichier HTML, soit une URL vers un site web qui contient des informations sur l’utilisation de l’extension ou du contenu dans ce package. Ce guide est lancé dans le cadre d’une installation.

• <AnyElement>* - Le schéma de manifeste est suffisamment flexible pour autoriser les autres éléments. Tous les éléments enfants qui ne sont pas reconnus par le chargeur de manifeste sont exposés sous la forme d’une liste d’objets XmlElement. À l’aide de ces éléments enfants, les extensions VSIX peuvent définir des données supplémentaires dans le fichier manifeste et les énumérer au moment de l’exécution.

Élément Installation

Cette section définit la façon dont ce package peut être installé et les références SKU d’application qu’il peut installer. Cette section contient les attributs suivants :

• Experimental - Définissez cet attribut sur true si vous avez une extension actuellement installée pour tous les utilisateurs, mais que vous développez une version mise à jour sur le même ordinateur. Par exemple, si vous avez installé MyExtension 1.0 pour tous les utilisateurs, mais que vous souhaitez déboguer MyExtension 2.0 sur le même ordinateur, définissez Experimental="true ». Cet attribut est disponible dans Visual Studio 2015 Update 1 et versions ultérieures.

• Scope - Cet attribut peut prendre la valeur « Global » ou « ProductExtension » :

  • « Global » spécifie que l’installation n’est pas limitée à une référence SKU spécifique. Par exemple, cette valeur est utilisée lorsqu’un SDK d’extension est installé.

  • « ProductExtension » spécifie qu’une extension VSIX traditionnelle (version 1.0) limitée à des références SKU Visual Studio individuelles est installée. Il s’agit de la valeur par défaut.

• AllUsers - Cet attribut facultatif spécifie si ce package sera installé pour tous les utilisateurs. Par défaut, cet attribut est false, ce qui spécifie que le package est par utilisateur. (Lorsque vous définissez cette valeur sur true, l’utilisateur d’installation doit élever le niveau de privilège d’administration pour installer le VSIX résultant.

• InstalledByMsi - Cet attribut facultatif spécifie si ce package est installé par une msi. Les packages installés par une msi sont installés et gérés par MSI (Programmes et fonctionnalités) et non par le Gestionnaire d’extensions Visual Studio. Par défaut, cet attribut est false, qui spécifie que le package n’est pas installé par une msi.

• SystemComponent - Cet attribut facultatif spécifie si ce package doit être considéré comme un composant système. Les composants système ne s’affichent pas dans l’interface utilisateur d’Extension Manager et ne peuvent pas être mis à jour. Par défaut, cet attribut est false, ce qui spécifie que le package n’est pas un composant système.

• AnyAttribute* - L’élément Installation accepte un ensemble ouvert d’attributs qui seront exposés au moment de l’exécution en tant que dictionnaire de paire nom-valeur.

• <InstallationTarget> -Cet élément contrôle l’emplacement où le programme d’installation VSIX installe le package. Si la valeur de l’attribut Scope est « ProductExtension », le package doit cibler une référence SKU, qui a installé un fichier manifeste dans le cadre de son contenu pour publier sa disponibilité aux extensions. L’élément <InstallationTarget> a les attributs suivants lorsque l’attribut Scope a la valeur explicite ou par défaut « ProductExtension » :

  • Id - Cet attribut identifie le package. L’attribut suit la convention d’espace de noms : Company.Product.Feature.Name. L’attribut Id peut contenir uniquement des caractères alphanumériques et est limité à 100 caractères. Valeurs attendues :

    • Microsoft.VisualStudio.IntegratedShell

    • Microsoft.VisualStudio.Pro

    • Microsoft.VisualStudio.Premium

    • Microsoft.VisualStudio.Ultimate

    • Microsoft.VisualStudio.VWDExpress

    • Microsoft.VisualStudio.VPDExpress

    • Microsoft.VisualStudio.VSWinExpress

    • Microsoft.VisualStudio.VSLS

    • My.Shell.App

  • Version - Cet attribut spécifie une plage de versions avec les versions minimales et maximales prises en charge de cette référence SKU. Un package peut détailler les versions des références SKU prises en charge. La notation de la plage de versions est [10.0 - 11.0], où

    • [ - version minimale inclusive.

    • ] : version maximale inclusive.

    • ( - version minimale exclusive.

    • ) - version maximale exclusive.

    • Version unique # : seule la version spécifiée.

    Important

    La version 2.0 du schéma VSIX a été introduite dans Visual Studio 2012. Pour utiliser ce schéma, visual Studio 2012 ou version ultérieure doit être installé sur l’ordinateur et utiliser VSIXInstaller.exe qui fait partie de ce produit. Vous pouvez cibler des versions antérieures de Visual Studio avec visual Studio 2012 ou version ultérieure de VSIXInstaller, mais uniquement à l’aide des versions ultérieures du programme d’installation.

    Les numéros de version de Visual Studio 2017 se trouvent à l’adresse des numéros de build et des dates de publication de Visual Studio.

    Lors de l’expression de la version pour les versions de Visual Studio 2017, la version mineure doit toujours être 0. Par exemple, Visual Studio 2017 version 15.3.26730.0 doit être exprimée sous la forme [15.0.26730.0,16.0). Cela n’est nécessaire que pour les numéros de version de Visual Studio 2017 et versions ultérieures.

  • AnyAttribute* - L’élément <InstallationTarget> autorise un ensemble ouvert d’attributs exposés au moment de l’exécution en tant que dictionnaire de paire nom-valeur.

Élément dependencies

Cet élément contient une liste de dépendances déclarées par ce package. Si des dépendances sont spécifiées, ces packages (identifiés par leur Id) doivent avoir été installés avant.

• <Dependency> élément - Cet élément enfant a les attributs suivants :

  • Id - Cet attribut doit être un ID unique pour le package dépendant. Cette valeur d’identité doit correspondre à l’attribut <Metadata><Identity>Id d’un package dont dépend ce package. L’attribut Id suit la convention d’espace de noms : Company.Product.Feature.Name. L’attribut peut contenir uniquement des caractères alphanumériques et est limité à 100 caractères.

  • Version - Cet attribut spécifie une plage de versions avec les versions minimales et maximales prises en charge de cette référence SKU. Un package peut détailler les versions des références SKU prises en charge. La notation de la plage de versions est [12.0, 13.0], où :

    • [ - version minimale inclusive.

    • ] : version maximale inclusive.

    • ( - version minimale exclusive.

    • ) - version maximale exclusive.

    • Version unique # : seule la version spécifiée.

  • DisplayName - Cet attribut est le nom complet du package dépendant, qui est utilisé dans les éléments d’interface utilisateur tels que les boîtes de dialogue et les messages d’erreur. L’attribut est facultatif, sauf si le package dépendant est installé par MSI.

  • Location - Cet attribut facultatif spécifie le chemin relatif dans ce VSIX vers un package VSIX imbriqué ou une URL vers l’emplacement de téléchargement de la dépendance. Cet attribut est utilisé pour aider l’utilisateur à localiser le package requis.

  • AnyAttribute* - L’élément Dependency accepte un ensemble ouvert d’attributs qui seront exposés au moment de l’exécution en tant que dictionnaire de paire nom-valeur.

Élément Assets

Cet élément contient une liste de <Asset> balises pour chaque extension ou élément de contenu exposé par ce package.

• <Asset> - Cet élément contient les attributs et éléments suivants :

  • Type - Type d’extension ou de contenu représenté par cet élément. Chaque <Asset> élément doit avoir un seul Typeélément, mais plusieurs <Asset> éléments peuvent avoir le même Type. Cet attribut doit être représenté sous la forme d’un nom complet, conformément aux conventions d’espace de noms. Les types connus sont les suivants :

    1. Microsoft.VisualStudio.VsPackage

    2. Microsoft.VisualStudio.MefComponent

    3. Microsoft.VisualStudio.ToolboxControl

    4. Microsoft.VisualStudio.Samples

    5. Microsoft.VisualStudio.ProjectTemplate

    6. Microsoft.VisualStudio.ItemTemplate

    7. Microsoft.VisualStudio.Assembly

       Vous pouvez créer vos propres types et leur donner des noms uniques. Au moment de l’exécution dans Visual Studio, votre code peut énumérer et accéder à ces types personnalisés via l’API Gestionnaire d’extensions.

  • Path - chemin d’accès relatif au fichier ou au dossier du package qui contient la ressource.

  • TargetVersion - plage de versions à laquelle l’élément multimédia donné s’applique. Utilisé pour l’expédition de plusieurs versions de ressources vers différentes versions de Visual Studio. Nécessite Que Visual Studio 2017.3 ou version ultérieure ait effet.

  • AnyAttribute* - Ensemble ouvert d’attributs exposés au moment de l’exécution en tant que dictionnaire de paire nom-valeur.

    <AnyElement>* - Tout contenu structuré est autorisé entre une balise de début et de <Asset> fin. Tous les éléments sont exposés sous forme de liste d’objets XmlElement. Les extensions VSIX peuvent définir des métadonnées spécifiques au type structuré dans le fichier manifeste et les énumérer au moment de l’exécution.

Syntaxe d’espace réservé pour les manifestes d’extension

Le .vsixmanifest fichier définit la build pour le package VSIX. Lorsqu’une build est demandée, Visual Studio analyse le manifeste pour produire un script de build, qui est généré à l’aide de MSBuild. Vous pouvez définir certaines valeurs au moment de la génération à l’aide d’espaces réservés évalués avant la génération du package VSIX. Les espaces réservés sont utilisés pour faire référence à des projets référencés dans le projet VSIX, les propriétés MSBuild et les cibles MSBuild, le plus souvent les cibles qui représentent des groupes de sortie de projet. Les groupes de sorties de projet représentent des collections de fichiers associés à un projet, et certains d’entre eux peuvent être inclus dans un package VSIX. Par exemple, PkgDefProjectOutputGroup, BuiltProjectOutputGroup ou SatelliteDllsProjectOutputGroup.

Pour référencer une propriété définie dans le projet VSIX, utilisez la même syntaxe que dans le fichier projet lui-même. $(PropertyName)

Le jeton %CurrentProject% spécial fait référence au projet VSIX. Vous pouvez référencer d’autres projets référencés dans votre projet VSIX à l’aide Name de l’élément ProjectReference d’un fichier projet VSIX, entouré de symboles de canal (|). Par exemple : |ProjectTemplate1|.

Vous pouvez référencer une cible MSBuild par le nom du projet (la Name propriété de la référence de projet dans le projet VSIX), puis le nom cible. Par exemple, pour référencer la Version cible dans l’un des projets référencés dans un package VSIX, utilisez la syntaxe |ProjectName;Version|. La cible doit avoir une Outputs valeur qui correspond au contexte dans lequel elle est utilisée ; le manifeste VSIX contient des emplacements où la substitution des valeurs de chaîne et des collections d’éléments est appropriée. Par exemple, la chaîne de version dans le manifeste peut être remplacée comme suit :

<Identity Id="0000000-0000-0000-0000-000000000000" Version="|%CurrentProject%;GetVsixVersion|" Language="en-US" Publisher="Company" />

Dans ce cas, il doit y avoir une GetVsixVersion cible dans le projet VSIX qui doit retourner une chaîne simple. Par exemple,

<Target Name="GetVsixVersion" Outputs="$(_VsixVersion)">
  <PropertyGroup>
     <_VsixVersion>1.2.3.4</_VsixVersion>
  </PropertyGroup>
</Target>

Les espaces réservés sont utilisés pour créer le fichier manifeste VSIX correct avec le projet VSIX de style SDK. Supposons que vous spécifiez la version cible de Visual Studio avec la propriété « TargetFramework » :

• <TargetFramework>vs17.0</TargetFramework> // Target Visual Studio 2022 version 17.0
• <TargetFramework>vs16.10</TargetFramework> // Target Visual Studio 2019 version 16.10

En fonction de l’infrastructure cible, la build VSIX transforme les valeurs définies dans le fichier manifeste d’extension comme suit. Pour la syntaxe suivante dans le fichier manifeste :

<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="|%CurrentProject%;GetInstallationTargetVersion|" />

La sortie utilisée dans le code MSBuild du projet VSIX est la suivante :

    <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 18.0)">
      <ProductArchitecture>amd64</ProductArchitecture>
    </InstallationTarget>

Et, pour le code suivant dans un manifeste d’extension :

 <Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="|%CurrentProject%;GetPrerequisiteTargetVersion|" DisplayName="Visual Studio core editor" />

Le code de génération du projet est :

<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[17.0, 18.0)" DisplayName="Visual Studio core editor" />

Cette fonctionnalité est également utilisée dans les fichiers manifeste VSIX générés par Visual Studio pour référencer des groupes de sortie de projet par le nom de la référence du projet, puis le nom de la cible MSBuild, séparé par un point-virgule. Par exemple, la chaîne |%CurrentProject%;PkgDefProjectOutputGroup| signifie le groupe de sortie PkgDef, qui fait référence au .pkgdef ou aux fichiers associés au projet VSIX actuel. Certaines des ProjectOutputGroup cibles définies dans le fichier de build système Microsoft.Common.CurrentVersion.targets sont utilisées dans les manifestes VSIX générés par Visual Studio. Des cibles de groupe de sortie de projet supplémentaires disponibles dans le projet VSIX sont définies dans Microsoft.VsSDK.targets. Le tableau suivant présente les groupes de sorties de projet définis :

Le système de génération remplit ces groupes de sorties avec les fichiers appropriés en fonction de la logique de génération par défaut. Dans une build personnalisée, vous pouvez ajouter des éléments aux groupes de sorties de projet en définissant l’attribut BeforeTargets sur l’une des cibles ci-dessus et dans la cible, suivez le code des cibles répertoriées ci-dessus comme exemples pour utiliser la BuiltProjectOutputGroupKeyOutput tâche pour définir les sorties.

Dans les scénarios avancés, vous pouvez référencer une cible de build ou définir une cible personnalisée que vous souhaitez appeler et utiliser la syntaxe décrite ici pour insérer des valeurs pour n’importe quel élément dans le manifeste VSIX. Une cible doit avoir le paramètre de sortie approprié qui correspond à l’attente du contexte dans lequel il est utilisé. Si une collection de fichiers comme la sortie générée d’un projet est attendue, une cible qui génère les éléments MSBuild requis est nécessaire. Les cibles générées par le groupe de sortie de projet mentionnées précédemment peuvent être utilisées comme exemples lors de la création de vos propres cibles.

Exemple de manifeste

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest Version="2.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011" xmlns:d="http://schemas.microsoft.com/developer/vsx-schema-design/2011">
  <Metadata>
    <Identity Id="0000000-0000-0000-0000-000000000000" Version="1.0" Language="en-US" Publisher="Company" />
    <DisplayName>Test Package</DisplayName>
    <Description>Information about my package</Description>
    <MoreInfo>http://www.fabrikam.com/Extension1/</MoreInfo>
    <License>eula.rtf</License>
    <ReleaseNotes>notes.txt</ReleaseNotes>
    <Icon>Images\icon.png</Icon>
    <PreviewImage>Images\preview.png</PreviewImage>
  </Metadata>
  <Installation InstalledByMsi="false" AllUsers="false" SystemComponent="false" Scope="ProductExtension">
    <InstallationTarget Id="Microsoft.VisualStudio.Pro" Version="[11.0, 12.0]" />
  </Installation>
  <Dependencies>
    <Dependency Id="Microsoft.Framework.NDP" DisplayName="Microsoft .NET Framework" d:Source="Manual" Version="[4.5,)" />
    <Dependency Id="Microsoft.VisualStudio.MPF.12.0" DisplayName="Visual Studio MPF 12.0" d:Source="Installed" Version="[12.0]" />
  </Dependencies>
  <Assets>
    <Asset Type="Microsoft.VisualStudio.VsPackage" d:Source="Project" d:ProjectName="%CurrentProject%" Path="|%CurrentProject%;PkgdefProjectOutputGroup|" />
  </Assets>
</PackageManifest>

Voir aussi

• Expédier des extensions Visual Studio