Referenční informace ke schématu rozšíření VSIX 2.0

  • Článek
  • 9 min ke čtení

Platí pro:yes Visual Studio Visual Studio pro Mac noVisual Studio noCode

Soubor manifestu nasazení VSIX popisuje obsah balíčku VSIX. Formát souboru se řídí schématem. Verze 2.0 tohoto schématu podporuje přidávání vlastních typů a atributů. Schéma manifestu je rozšiřitelné. Zavaděč manifestu ignoruje elementy a atributy XML, kterým nerozumí.

Důležité

Visual Studio 2015 může načíst soubory VSIX ve formátech sady Visual Studio 2010, Visual Studio 2012 nebo Visual Studio 2013.

Schéma manifestu balíčku

Kořenový prvek souboru XML manifestu je <PackageManifest>. Má jeden atribut Version, což je verze formátu manifestu. Pokud jsou ve formátu provedeny hlavní změny, změní se formát verze. Tento článek popisuje formát manifestu verze 2.0, který je určen v manifestu nastavením Version atributu na hodnotu Version="2.0".

PackageManifest – element

V kořenovém elementu <PackageManifest> můžete použít následující prvky:

  • <Metadata> - Metadata a reklamní informace o samotném balíčku. V manifestu je povolen pouze jeden Metadata prvek.

  • <Installation> – Tato část definuje způsob instalace tohoto balíčku rozšíření, včetně skladových položek aplikace, do které je možné nainstalovat. V manifestu je povolen pouze jeden Installation prvek. Manifest musí mít Installation prvek nebo se tento balíček nenainstaluje do žádné skladové položky.

  • <Dependencies> – Zde je definován volitelný seznam závislostí pro tento balíček.

  • <Assets> - Tato část obsahuje všechny prostředky obsažené v tomto balíčku. Bez této části se tento balíček nezomení na žádný obsah.

  • <AnyElement>* – Schéma manifestu je dostatečně flexibilní, aby bylo možné povolit další prvky. Všechny podřízené elementy, které zavaděč manifestu nerozpozná, jsou vystaveny v rozhraní API Správce rozšíření jako objekty XmlElement navíc. Pomocí těchto podřízených prvků můžou rozšíření VSIX definovat další data v souboru manifestu, ke kterému má kód spuštěný v sadě Visual Studio přístup za běhu. Viz Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Element Metadata

Tato část je metadata balíčku, její identity a reklamních informací. <Metadata> obsahuje následující prvky:

  • <Identity> - Definuje identifikační informace pro tento balíček a obsahuje následující atributy:

    • Id – Tento atribut musí být jedinečným ID balíčku zvoleného jeho autorem. Název by měl být kvalifikovaný stejně jako typy CLR jsou obory názvů: Company.Product.Feature.Name. Atribut Id je omezen na 100 znaků.

    • Version - Definuje verzi tohoto balíčku a její obsah. Tento atribut se řídí formátem správy verzí sestavení CLR: Major.Minor.Build.Revision (1.2.40308.00). Balíček s vyšším číslem verze se považuje za aktualizace balíčku a dá se nainstalovat přes stávající nainstalovanou verzi.

    • Language – Tento atribut je výchozím jazykem balíčku a odpovídá textovým datům v tomto manifestu. Tento atribut se řídí konvencí kódu národního prostředí CLR pro sestavení prostředků, například en-us, en, fr-fr. Můžete zadat neutral deklaraci jazykově neutrálního rozšíření, které bude spuštěno v libovolné verzi sady Visual Studio. Výchozí hodnota je neutral.

    • Publisher – Tento atribut identifikuje vydavatele tohoto balíčku, buď společnost, nebo individuální název. Atribut Publisher je omezen na 100 znaků.

  • <DisplayName> – Tento prvek určuje uživatelsky přívětivý název balíčku, který se zobrazí v uživatelském rozhraní Správce rozšíření. Obsah DisplayName je omezen na 50 znaků.

  • <Description> – Tento volitelný prvek je krátký popis balíčku a jeho obsahu, který se zobrazí v uživatelském rozhraní Správce rozšíření. Obsah Description může obsahovat libovolný text, který chcete, ale je omezený na 1000 znaků.

  • <MoreInfo> – Tento volitelný prvek je adresa URL stránky online, která obsahuje úplný popis tohoto balíčku. Protokol musí být zadán jako http.

  • <License> – Tento volitelný prvek je relativní cesta k licenčnímu souboru (.txt, .rtf) obsaženému v balíčku.

  • <ReleaseNotes> – Tento volitelný prvek je relativní cesta k souboru poznámek k verzi obsaženému v balíčku (.txt, .rtf) nebo jiné adrese URL webu, který zobrazuje poznámky k verzi.

  • <Icon> - Tento volitelný prvek je relativní cesta k souboru obrázku (png, bmp, jpeg, ico) obsaženého v balíčku. Obrázek ikony by měl být 32 × 32 pixelů (nebo se na danou velikost zmáčkne) a zobrazí se v uživatelském rozhraní listview. Pokud není zadaný žádný Icon prvek, uživatelské rozhraní použije výchozí hodnotu.

  • <PreviewImage> – Tento volitelný prvek je relativní cesta k souboru obrázku (png, bmp, jpeg) obsaženému v balíčku. Obrázek náhledu by měl být 200 × 200 pixelů a zobrazený v uživatelském rozhraní podrobností. Pokud není zadaný žádný PreviewImage prvek, uživatelské rozhraní použije výchozí hodnotu.

  • <Tags> - Tento volitelný prvek obsahuje seznam dalších textových značek oddělených středníkem, které se používají pro nápovědu pro vyhledávání. Prvek Tags je omezen na 100 znaků.

  • <GettingStartedGuide> - Tento volitelný prvek je relativní cesta k souboru HTML nebo adresa URL webu, který obsahuje informace o tom, jak používat příponu nebo obsah v rámci tohoto balíčku. Tato příručka se spustí jako součást instalace.

  • <AnyElement>* – Schéma manifestu je dostatečně flexibilní, aby bylo možné povolit další prvky. Všechny podřízené elementy, které zavaděč manifestu nerozpozná, jsou vystaveny jako seznam XmlElement objektů. Pomocí těchto podřízených elementů můžou rozšíření VSIX definovat další data v souboru manifestu a vypsat je za běhu.

Instalační prvek

Tato část definuje způsob instalace tohoto balíčku a skladové položky aplikace, do které se dá nainstalovat. Tato část obsahuje následující atributy:

  • Experimental – Tento atribut nastavte na hodnotu True, pokud máte rozšíření, které je aktuálně nainstalované pro všechny uživatele, ale vyvíjíte aktualizovanou verzi na stejném počítači. Pokud jste například nainstalovali MyExtension 1.0 pro všechny uživatele, ale chcete ladit MyExtension 2.0 na stejném počítači, nastavte Experimentální="true". Tento atribut je k dispozici v sadě Visual Studio 2015 Update 1 a novějších verzích.

  • Scope – Tento atribut může převzít hodnotu "Global" nebo "ProductExtension":

    • Globální určuje, že instalace není vymezena na konkrétní skladovou položku. Tato hodnota se například používá při instalaci sady Extension SDK.

    • ProductExtension určuje, že je nainstalované tradiční rozšíření VSIX (verze 1.0) vymezené na jednotlivé skladové položky sady Visual Studio. Toto je výchozí hodnota.

  • AllUsers – Tento volitelný atribut určuje, jestli bude tento balíček nainstalován pro všechny uživatele. Ve výchozím nastavení je tento atribut false, který určuje, že balíček je pro každého uživatele. (Když nastavíte tuto hodnotu na hodnotu true, musí uživatel instalace zvýšit úroveň oprávnění správce, aby nainstaloval výsledný VSIX.

  • InstalledByMsi – Tento volitelný atribut určuje, jestli je tento balíček nainstalován msi. Balíčky nainstalované pomocí MSI se instalují a spravují pomocí MSI (Programy a funkce) a ne správcem rozšíření sady Visual Studio. Ve výchozím nastavení je tento atribut false, který určuje, že balíček není nainstalován msi.

  • SystemComponent – Tento volitelný atribut určuje, zda má být tento balíček považován za systémovou komponentu. Systémové komponenty se nezobrazují v uživatelském rozhraní Správce rozšíření a nelze je aktualizovat. Ve výchozím nastavení je tento atribut false, který určuje, že balíček není systémová komponenta.

  • AnyAttribute* – Element Installation přijímá otevřenou sadu atributů, které budou vystaveny za běhu jako slovník páru name-value.

  • <InstallationTarget> -Tento prvek řídí umístění, kam instalační program VSIX nainstaluje balíček. Pokud je hodnota atributu Scope ProductExtension, balíček musí cílit na skladovou položku, která nainstalovala soubor manifestu jako součást jeho obsahu, aby inzerovala dostupnost rozšíření. Element <InstallationTarget> má následující atributy, pokud Scope má atribut explicitní nebo výchozí hodnotu "ProductExtension":

    • Id – Tento atribut identifikuje balíček. Atribut se řídí konvencí oboru názvů: Company.Product.Feature.Name. Atribut Id může obsahovat pouze alfanumerické znaky a je omezený na 100 znaků. Očekávané hodnoty:

      • 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 – Tento atribut určuje rozsah verzí s minimální a maximální podporovanou verzí této skladové položky. Balíček může podrobně zobrazit verze skladových položek, které podporuje. Zápis rozsahu verzí je [10.0 – 11.0], kde

      • [ - minimální verze včetně.

      • ] - maximální verze včetně.

      • ( - minimální verze exkluzivní.

      • ) – maximální verze exkluzivní.

      • Jedna verze # – pouze zadaná verze.

      Důležité

      V sadě Visual Studio 2012 byla zavedena verze 2.0 schématu VSIX. Pokud chcete toto schéma použít, musíte mít v počítači nainstalovanou sadu Visual Studio 2012 nebo novější a používat VSIXInstaller.exe, která je součástí tohoto produktu. Můžete cílit na starší verze sady Visual Studio se sadou Visual Studio 2012 nebo novějším VSIXInstaller, ale pouze pomocí novějších verzí instalačního programu.

      Čísla verzí sady Visual Studio 2017 najdete na číslech sestavení a datech vydání sady Visual Studio.

      Při vyjádření verze sady Visual Studio 2017 by podverze měla být vždy 0. Například Visual Studio 2017 verze 15.3.26730.0 by se mělo vyjádřit jako [15.0.26730.0,16.0). To se vyžaduje jenom pro čísla verzí sady Visual Studio 2017 a novějších verzí.

    • AnyAttribute* – Element <InstallationTarget> umožňuje otevřenou sadu atributů, které jsou vystaveny za běhu jako slovník páru name-value.

Dependencies – element

Tento prvek obsahuje seznam závislostí, které tento balíček deklaruje. Pokud jsou zadány nějaké závislosti, musí být tyto balíčky (identifikované jejich Id) nainstalovány dříve.

  • <Dependency> element – Tento podřízený element má následující atributy:

    • Id – Tento atribut musí být jedinečným ID závislého balíčku. Tato hodnota identity musí odpovídat <Metadata><Identity>Id atributu balíčku, na který je tento balíček závislý. Atribut Id se řídí konvencí oboru názvů: Company.Product.Feature.Name. Atribut může obsahovat pouze alfanumerické znaky a je omezený na 100 znaků.

    • Version – Tento atribut určuje rozsah verzí s minimální a maximální podporovanou verzí této skladové položky. Balíček může podrobně zobrazit verze skladových položek, které podporuje. Zápis rozsahu verzí je [12.0, 13.0], kde:

      • [ - minimální verze včetně.

      • ] - maximální verze včetně.

      • ( - minimální verze exkluzivní.

      • ) – maximální verze exkluzivní.

      • Jedna verze # – pouze zadaná verze.

    • DisplayName - Tento atribut je zobrazovaný název závislého balíčku, který se používá v prvcích uživatelského rozhraní, jako jsou dialogová okna a chybové zprávy. Atribut je nepovinný, pokud msi nenainstaluje závislý balíček.

    • Location – Tento volitelný atribut určuje relativní cestu v rámci tohoto VSIX k vnořenému balíčku VSIX nebo adresu URL umístění pro stažení závislosti. Tento atribut slouží k tomu, aby uživatel vyhlašil požadovaný balíček.

    • AnyAttribute* – Element Dependency přijímá otevřenou sadu atributů, které budou vystaveny za běhu jako slovník páru name-value.

Assets – element

Tento prvek obsahuje seznam <Asset> značek pro každé rozšíření nebo prvek obsahu, který tento balíček obsahuje.

  • <Asset> – Tento prvek obsahuje následující atributy a prvky:

    • Type - Typ rozšíření nebo obsahu reprezentovaný tímto prvkem. Každý <Asset> prvek musí mít jeden Type, ale více <Asset> prvků může mít stejný Type. Tento atribut by měl být reprezentován jako plně kvalifikovaný název podle konvencí oboru názvů. Známé typy jsou:

      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

        Můžete vytvořit vlastní typy a pojmenovat je jedinečnými názvy. V době běhu v sadě Visual Studio může váš kód vytvořit výčet a přistupovat k těmto vlastním typům prostřednictvím rozhraní API Správce rozšíření.

    • Path – relativní cesta k souboru nebo složce v balíčku, který obsahuje prostředek.

    • TargetVersion – rozsah verzí, na který se daný prostředek vztahuje. Používá se k odeslání více verzí prostředků do různých verzí sady Visual Studio. Vyžaduje, aby se projevila sada Visual Studio 2017.3 nebo novější.

    • AnyAttribute* - Otevřená sada atributů, které jsou vystaveny za běhu jako slovník páru název-hodnota.

      <AnyElement>* – Veškerý strukturovaný obsah je povolený mezi počáteční a koncovou značkou <Asset> . Všechny prvky jsou vystaveny jako seznam XmlElement objekty. Rozšíření VSIX mohou definovat metadata specifická pro strukturovaný typ v souboru manifestu a vytvořit jejich výčet za běhu.

Ukázkový manifest

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

Viz také