Naslaginformatie over VSIX-extensieschema 2.0

In een VSIX-distributiemanifestbestand wordt de inhoud van een VSIX-pakket beschreven. De bestandsindeling wordt beheerd door een schema. Versie 2.0 van dit schema ondersteunt het toevoegen van aangepaste typen en kenmerken. Het schema van het manifest kan worden uitgebreid. Het manifestlaadprogramma negeert XML-elementen en -kenmerken die niet worden begrepen.

Pakketmanifestschema

Het hoofdelement van het XML-manifestbestand is <PackageManifest>. Het heeft één kenmerk Version, de versie van de manifestindeling. Als er grote wijzigingen worden aangebracht in de indeling, wordt de versie-indeling gewijzigd. In dit artikel wordt de manifestindeling versie 2.0 beschreven, die in het manifest is opgegeven door het Version kenmerk in te stellen op de waarde van Version="2.0".

PackageManifest-element

Binnen het <PackageManifest> hoofdelement kunt u de volgende elementen gebruiken:

• <Metadata> - Metagegevens en reclame-informatie over het pakket zelf. Er is slechts één Metadata element toegestaan in het manifest.

• <Installation> - In deze sectie wordt gedefinieerd hoe dit extensiepakket kan worden geïnstalleerd, inclusief de toepassings-SKU's waarin het kan worden geïnstalleerd. Er is slechts één Installation element toegestaan in het manifest. Een manifest moet een Installation element hebben of dit pakket wordt niet geïnstalleerd in een SKU.

• <Dependencies> - Hier wordt een optionele lijst met afhankelijkheden voor dit pakket gedefinieerd.

• <Assets> - Deze sectie bevat alle assets in dit pakket. Zonder deze sectie wordt in dit pakket geen inhoud weergegeven.

• <AnyElement>* - Het manifestschema is flexibel genoeg om andere elementen toe te staan. Onderliggende elementen die niet worden herkend door het manifestlaadprogramma, worden weergegeven in de Extension Manager-API als extra XmlElement-objecten. Met behulp van deze onderliggende elementen kunnen VSIX-extensies aanvullende gegevens definiëren in het manifestbestand waartoe code die in Visual Studio wordt uitgevoerd, tijdens runtime toegankelijk is. Zie Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Metagegevenselement

Deze sectie bevat de metagegevens over het pakket, de identiteit en advertentie-informatie. <Metadata> bevat de volgende elementen:

• <Identity> - Definieert identificatiegegevens voor dit pakket en bevat de volgende kenmerken:

  • Id - Dit kenmerk moet een unieke id zijn voor het pakket dat door de auteur is gekozen. De naam moet op dezelfde manier worden gekwalificeerd als CLR-typen: Company.Product.Feature.Name. Het Id kenmerk is beperkt tot 100 tekens.

  • Version - Definieert de versie van dit pakket en de inhoud ervan. Dit kenmerk volgt de clr assembly-versiebeheerindeling: Major.Minor.Build.Revision (1.2.40308.00). Een pakket met een hoger versienummer wordt beschouwd als updates voor het pakket en kan worden geïnstalleerd via de bestaande geïnstalleerde versie.

  • Language - Dit kenmerk is de standaardtaal voor het pakket en komt overeen met de tekstgegevens in dit manifest. Dit kenmerk volgt de CLR-codeconventie voor resourceassembly's, bijvoorbeeld: en-us, en, fr-fr. U kunt opgeven neutral dat u een taalneutrale extensie wilt declareren die wordt uitgevoerd op elke versie van Visual Studio. De standaardwaarde is neutral.

  • Publisher - Dit kenmerk identificeert de uitgever van dit pakket, een bedrijf of afzonderlijke naam. Het Publisher kenmerk is beperkt tot 100 tekens.

• <DisplayName> - Dit element geeft de gebruiksvriendelijke pakketnaam op die wordt weergegeven in de gebruikersinterface van Extension Manager. De DisplayName inhoud is beperkt tot 50 tekens.

• <Description> - Dit optionele element is een korte beschrijving van het pakket en de inhoud die wordt weergegeven in de gebruikersinterface van Extension Manager. De Description inhoud kan elke gewenste tekst bevatten, maar is beperkt tot 1000 tekens.

• <MoreInfo> - Dit optionele element is een URL naar een pagina online die een volledige beschrijving van dit pakket bevat. Het protocol moet worden opgegeven als http.

• <License> - Dit optionele element is een relatief pad naar een licentiebestand (.txt, .rtf) in het pakket.

• <ReleaseNotes> - Dit optionele element is een relatief pad naar een releaseopmerkingsbestand in het pakket (.txt, .rtf) of een URL naar een website waarin de releaseopmerkingen worden weergegeven.

• <Icon> - Dit optionele element is een relatief pad naar een afbeeldingsbestand (png, bmp, jpeg, ico) in het pakket. De afbeelding van het pictogram moet 32 x 32 pixels zijn (of is verkleind tot die grootte) en wordt weergegeven in de gebruikersinterface van listview. Als er geen Icon element is opgegeven, gebruikt de gebruikersinterface een standaardinstelling.

• <PreviewImage> - Dit optionele element is een relatief pad naar een afbeeldingsbestand (png, bmp, jpeg) in het pakket. De voorbeeldafbeelding moet 200x200 pixels zijn en wordt weergegeven in de gebruikersinterface met details. Als er geen PreviewImage element is opgegeven, gebruikt de gebruikersinterface een standaardinstelling.

• <Tags> - Dit optionele element bevat extra door puntkomma's gescheiden teksttags die worden gebruikt voor zoekhints. Het Tags element is beperkt tot 100 tekens.

• <GettingStartedGuide> - Dit optionele element is een relatief pad naar een HTML-bestand of een URL naar een website die informatie bevat over het gebruik van de extensie of inhoud in dit pakket. Deze handleiding wordt gestart als onderdeel van een installatie.

• <AnyElement>* - Het manifestschema is flexibel genoeg om andere elementen toe te staan. Onderliggende elementen die niet worden herkend door het manifestlaadprogramma, worden weergegeven als een lijst met XmlElement-objecten. Met deze onderliggende elementen kunnen VSIX-extensies aanvullende gegevens definiëren in het manifestbestand en deze tijdens runtime opsommen.

Installatie-element

In deze sectie wordt gedefinieerd hoe dit pakket kan worden geïnstalleerd en in welke toepassings-SKU's het kan worden geïnstalleerd. Deze sectie bevat de volgende kenmerken:

• Experimental - Stel dit kenmerk in op true als u een extensie hebt die momenteel is geïnstalleerd voor alle gebruikers, maar u een bijgewerkte versie op dezelfde computer ontwikkelt. Als u bijvoorbeeld MyExtension 1.0 hebt geïnstalleerd voor alle gebruikers, maar u wilt fouten opsporen in MyExtension 2.0 op dezelfde computer, stelt u Experimenteel="true" in. Dit kenmerk is beschikbaar in Visual Studio 2015 Update 1 en hoger.

• Scope - Dit kenmerk kan de waarde 'Global' of 'ProductExtension' aannemen:

  • 'Globaal' geeft aan dat de installatie niet is gericht op een specifieke SKU. Deze waarde wordt bijvoorbeeld gebruikt wanneer een Extension SDK is geïnstalleerd.

  • 'ProductExtension' geeft aan dat een traditionele VSIX-extensie (versie 1.0) die is afgestemd op afzonderlijke Visual Studio-SKU's is geïnstalleerd. Dit is de standaardwaarde.

• AllUsers - Dit optionele kenmerk geeft aan of dit pakket wordt geïnstalleerd voor alle gebruikers. Dit kenmerk is standaard onwaar, wat aangeeft dat het pakket per gebruiker is. (Wanneer u deze waarde instelt op true, moet de installatiegebruiker het niveau van beheerdersbevoegdheden verhogen om de resulterende VSIX te installeren.

• InstalledByMsi - Dit optionele kenmerk geeft aan of dit pakket is geïnstalleerd door een MSI. Pakketten die zijn geïnstalleerd door een MSI, worden geïnstalleerd en beheerd door MSI (Programma's en onderdelen) en niet door Visual Studio Extension Manager. Dit kenmerk is standaard onwaar, waarmee wordt aangegeven dat het pakket niet door een MSI is geïnstalleerd.

• SystemComponent - Dit optionele kenmerk geeft aan of dit pakket moet worden beschouwd als een systeemonderdeel. Systeemonderdelen worden niet weergegeven in de gebruikersinterface van Extension Manager en kunnen niet worden bijgewerkt. Dit kenmerk is standaard onwaar, waarmee wordt aangegeven dat het pakket geen systeemonderdeel is.

• AnyAttribute* - Het Installation element accepteert een open-beëindigde set kenmerken die tijdens de runtime worden weergegeven als een woordenlijst voor naam-waardepaar.

• <InstallationTarget> -This element bepaalt de locatie waar het VSIX-installatieprogramma het pakket installeert. Als de waarde van het Scope kenmerk 'ProductExtension' is, moet het pakket zich richten op een SKU, die een manifestbestand heeft geïnstalleerd als onderdeel van de inhoud om de beschikbaarheid van extensies te adverteren. Het <InstallationTarget> element heeft de volgende kenmerken wanneer het Scope kenmerk de expliciete of standaardwaarde ProductExtension heeft:

  • Id - Dit kenmerk identificeert het pakket. Het kenmerk volgt de naamruimteconventie: Company.Product.Feature.Name. Het Id kenmerk mag alleen alfanumerieke tekens bevatten en mag maximaal 100 tekens bevatten. Verwachte waarden:

    • Microsoft.VisualStudio.Community

    • Microsoft.VisualStudio.Pro

    • Microsoft.VisualStudio.Enterprise

    Extensies die zijn gericht op lagere SKU's, werken met alle hogere SKU's. Extensies die gericht zijn op community werken bijvoorbeeld met alle Visual Studio-SKU's en extensies die gericht zijn op Pro, werken ook met Enterprise.

  • Version - Met dit kenmerk wordt een versiebereik opgegeven met de minimaal en maximaal ondersteunde versies van deze SKU. Een pakket kan de versies van de SKU's beschrijven die worden ondersteund. De versiebereik notatie is [10.0 - 11.0], waarbij

    • [ - minimale versie inclusief.

    • ] - maximale versie inclusief.

    • ( - minimale versie exclusief.

    • ) - maximale versie exclusief.

    • Eén versie # - alleen de opgegeven versie.

    Belangrijk

    Versie 2.0 van het VSIX-schema is geïntroduceerd in Visual Studio 2012. Als u dit schema wilt gebruiken, moet Visual Studio 2012 of hoger op de computer zijn geïnstalleerd en de VSIXInstaller.exe gebruiken die deel uitmaakt van dat product. U kunt eerdere versies van Visual Studio richten met een Visual Studio 2012 of hoger VSIXInstaller, maar alleen met behulp van de latere versies van het installatieprogramma.

    Visual Studio-versienummers vindt u op buildnummers en releasedatums van Visual Studio.

    Bij het uitdrukken van de versie voor Visual Studio-releases moet de secundaire versie altijd 0 zijn. Visual Studio 2017 versie 15.3.26730.0 moet bijvoorbeeld worden uitgedrukt als [15.0.26730.0,16.0). Dit is alleen vereist voor versienummers van Visual Studio 2017 en hoger.

  • AnyAttribute* - Het <InstallationTarget> element staat een open-ended set kenmerken toe die tijdens de runtime beschikbaar worden gesteld als een woordenlijst voor naam-waardepaar.

<Installation AllUsers="true">
   <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0,)">
      <ProductArchitecture>amd64</ProductArchitecture>
    </InstallationTarget>
   <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0,)">
     <ProductArchitecture>arm64</ProductArchitecture>
   </InstallationTarget>
</Installation>

Het element Afhankelijkheden

Dit element bevat een lijst met afhankelijkheden die dit pakket declareert. Als er afhankelijkheden zijn opgegeven, moeten deze pakketten (geïdentificeerd door hun Id) eerder zijn geïnstalleerd.

• <Dependency> element : dit onderliggende element heeft de volgende kenmerken:

  • Id - Dit kenmerk moet een unieke id zijn voor het afhankelijke pakket. Deze identiteitswaarde moet overeenkomen met het <Metadata><Identity>Id kenmerk van een pakket waarvan dit pakket afhankelijk is. Het Id kenmerk volgt de naamruimteconventie: Company.Product.Feature.Name. Het kenmerk mag alleen alfanumerieke tekens bevatten en mag maximaal 100 tekens bevatten.

  • Version - Met dit kenmerk wordt een versiebereik opgegeven met de minimaal en maximaal ondersteunde versies van deze SKU. Een pakket kan de versies van de SKU's beschrijven die worden ondersteund. De versiebereik notatie is [12.0, 13.0], waarbij:

    • [ - minimale versie inclusief.

    • ] - maximale versie inclusief.

    • ( - minimale versie exclusief.

    • ) - maximale versie exclusief.

    • Eén versie # - alleen de opgegeven versie.

  • DisplayName - Dit kenmerk is de weergavenaam van het afhankelijke pakket, dat wordt gebruikt in UI-elementen, zoals dialoogvensters en foutberichten. Het kenmerk is optioneel, tenzij het afhankelijke pakket wordt geïnstalleerd door MSI.

  • Location - Dit optionele kenmerk geeft het relatieve pad in deze VSIX op naar een genest VSIX-pakket of een URL naar de downloadlocatie voor de afhankelijkheid. Dit kenmerk wordt gebruikt om de gebruiker te helpen het vereiste pakket te vinden.

  • AnyAttribute* - Het Dependency element accepteert een open-beëindigde set kenmerken die tijdens de runtime worden weergegeven als een woordenlijst voor naam-waardepaar.

Element Activa

Dit element bevat een lijst met <Asset> tags voor elke extensie of inhoudselement die door dit pakket wordt weergegeven.

• <Asset> - Dit element bevat de volgende kenmerken en elementen:

  • Type - Type extensie of inhoud dat wordt vertegenwoordigd door dit element. Elk <Asset> element moet één Typeelement hebben, maar meerdere <Asset> elementen kunnen hetzelfde Typehebben. Dit kenmerk moet worden weergegeven als een volledig gekwalificeerde naam, volgens naamruimteconventies. De bekende typen zijn:

    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

       U kunt uw eigen typen maken en ze unieke namen geven. Tijdens runtime in Visual Studio kan uw code deze aangepaste typen inventariseren en openen via de Extension Manager-API.

  • Path - het relatieve pad naar het bestand of de map in het pakket dat de asset bevat.

  • TargetVersion - het versiebereik waarop de opgegeven asset van toepassing is. Wordt gebruikt voor het verzenden van meerdere versies van assets naar verschillende versies van Visual Studio. Hiervoor is Visual Studio 2017.3 of hoger vereist.

  • AnyAttribute* - Een open-ended set kenmerken die tijdens de runtime worden weergegeven als een woordenlijst met een paar naamwaarden.

    <AnyElement>* - Elke gestructureerde inhoud is toegestaan tussen een <Asset> begin- en eindtag. Alle elementen worden weergegeven als een lijst met XmlElement-objecten. VSIX-extensies kunnen gestructureerde typespecifieke metagegevens definiëren in het manifestbestand en deze tijdens runtime opsommen.

Syntaxis van tijdelijke aanduidingen voor extensiemanifesten

Het .vsixmanifest bestand definieert de build voor het VSIX-pakket. Wanneer een build wordt aangevraagd, parseert Visual Studio het manifest om een buildscript te produceren, dat is gebouwd met behulp van MSBuild. U kunt bepaalde waarden tijdens de build instellen met behulp van tijdelijke aanduidingen die worden geëvalueerd voordat het VSIX-pakket wordt gebouwd. Tijdelijke aanduidingen worden gebruikt om te verwijzen naar projecten waarnaar wordt verwezen in het VSIX-project, MSBuild-eigenschappen en MSBuild-doelen, meestal de doelen die projectuitvoergroepen vertegenwoordigen. Projectuitvoergroepen vertegenwoordigen verzamelingen bestanden die zijn gekoppeld aan een project. Sommige hiervan kunnen worden opgenomen in een VSIX-pakket. Bijvoorbeeld PkgDefProjectOutputGroup, BuiltProjectOutputGroup of SatelliteDllsProjectOutputGroup.

Als u wilt verwijzen naar een eigenschap die is gedefinieerd in het VSIX-project, gebruikt u dezelfde syntaxis als in het projectbestand zelf. $(PropertyName)

Het speciale token %CurrentProject% verwijst naar het VSIX-project. U kunt verwijzen naar andere projecten waarnaar wordt verwezen in uw VSIX-project met behulp Name van het ProjectReference element in een VSIX-projectbestand, omgeven door pijpsymbolen (|). Bijvoorbeeld: |ProjectTemplate1|.

U kunt verwijzen naar een MSBuild-doel door de naam van het project (de Name eigenschap van de projectreferentie in het VSIX-project) en vervolgens de doelnaam. Als u bijvoorbeeld wilt verwijzen naar het Version doel in een van de projecten waarnaar wordt verwezen in een VSIX-pakket, gebruikt u de syntaxis |ProjectName;Version|. Het doel moet een Outputs waarde hebben die overeenkomt met de context waarin het wordt gebruikt. Het VSIX-manifest bevat plaatsen waar het vervangen van tekenreekswaarden en itemverzamelingen geschikt is. De versietekenreeks in het manifest kan bijvoorbeeld als volgt worden vervangen:

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

In dat geval moet er een GetVsixVersion doel zijn in het VSIX-project dat een eenvoudige tekenreeks moet retourneren. Bijvoorbeeld

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

De tijdelijke aanduidingen worden gebruikt voor het maken van het juiste VSIX-manifestbestand met het VSIX-project in SDK-stijl. Stel dat u de doelversie van Visual Studio opgeeft met de eigenschap TargetFramework:

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

Op basis van het doelframework transformeert de VSIX-build de waarden die als volgt zijn gedefinieerd in het extensiemanifestbestand. Voor de volgende syntaxis in het manifestbestand:

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

De uitvoer die wordt gebruikt in de MSBuild-code van het VSIX-project is:

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

En voor de volgende code in een extensiemanifest:

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

De buildcode van het project is:

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

Deze functionaliteit wordt ook gebruikt in de VSIX-manifestbestanden die Visual Studio genereert om te verwijzen naar projectuitvoergroepen op de naam van de projectverwijzing en vervolgens de naam van het MSBuild-doel, gescheiden door een puntkomma. De tekenreeks |%CurrentProject%;PkgDefProjectOutputGroup| betekent bijvoorbeeld de PkgDef-uitvoergroep, die verwijst naar de .pkgdef bestanden die zijn gekoppeld aan het huidige VSIX-project. Sommige van de ProjectOutputGroup doelen die zijn gedefinieerd in het systeembuildbestand Microsoft.Common.CurrentVersion.targets worden gebruikt in de VSIX-manifesten die worden gegenereerd door Visual Studio. Aanvullende doelen voor projectuitvoergroepen die beschikbaar zijn in het VSIX-project, worden gedefinieerd in Microsoft.VsSDK.targets. In de volgende tabel ziet u de gedefinieerde projectuitvoergroepen:

Het buildsysteem vult deze uitvoergroepen met de juiste bestanden volgens de standaard buildlogica. In een aangepaste build kunt u items toevoegen aan de projectuitvoergroepen door het BeforeTargets kenmerk op uw doel in te stellen op een van de vorige doelen en in het doel de code voor de eerder vermelde doelen te volgen als voorbeelden van het gebruik van de BuiltProjectOutputGroupKeyOutput taak om de uitvoer in te stellen.

In geavanceerde scenario's kunt u verwijzen naar een builddoel of een aangepast doel definiëren dat u wilt aanroepen en de hier beschreven syntaxis gebruiken om waarden in te voegen voor elk element in het VSIX-manifest. Een doel moet de juiste uitvoerparameter hebben die overeenkomt met de verwachting van de context waarin het wordt gebruikt. Als er een verzameling bestanden zoals de ingebouwde uitvoer van een project wordt verwacht, is een doel nodig dat de vereiste MSBuild-items uitvoert. De eerder genoemde doelen voor de projectuitvoergroep kunnen worden gebruikt als voorbeelden bij het bouwen van uw eigen doelen.

Voorbeeldmanifest

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

Zie ook

• Visual Studio-extensies verzenden