Referenční informace ke schématu rozšíření VSIX 2.0
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ání vlastních typů a atributů. Schéma manifestu je rozšiřitelné. Zavaděč manifestu ignoruje elementy a atributy XML, kterým nerozumí.
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, formát verze se změní. 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 jedenMetadataprvek.<Installation>– Tato část definuje způsob instalace tohoto balíčku rozšíření, včetně skladových položek aplikace, do které se dá nainstalovat. V manifestu je povolen pouze jedenInstallationprvek. Manifest musí mítInstallationprvek nebo se tento balíček nenainstaluje do žádné skladové položky.<Dependencies>– Tady 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 nezobřestí žádného obsahu.<AnyElement>*– Schéma manifestu je dostatečně flexibilní, aby umožňovalo všechny ostatní prvky. Všechny podřízené elementy, které zavaděč manifestu nerozpozná, jsou zpřístupněny v rozhraní API Extension Manageru jako další objekty XmlElement. Pomocí těchto podřízených prvků mohou 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 metadat
Tato část obsahuje metadata o balíčku, jeho identitě a reklamních informacích. <Metadata> obsahuje následující prvky:
<Identity>- Definuje identifikační informace pro tento balíček a zahrnuje 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ým způsobem, jakým jsou typy CLR oborem názvů: Company.Product.Feature.Name. AtributIdje 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 lze jej 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 určitneutraldeklaraci jazykově neutrálního rozšíření, které se spustí v libovolné verzi sady Visual Studio. Výchozí hodnota jeneutral.Publisher– Tento atribut identifikuje vydavatele tohoto balíčku, buď společnost, nebo individuální název. AtributPublisherje 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í. ObsahDisplayNameje omezen na 50 znaků.<Description>– Tento volitelný prvek je stručný popis balíčku a jeho obsah, který se zobrazí v uživatelském rozhraní Správce rozšíření. ObsahDescriptionmůže obsahovat libovolný text, ale je omezený na 1 000 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 na web, 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 zvětší na danou velikost) a zobrazí se v uživatelském rozhraní listview. Pokud není zadaný žádnýIconprvek, 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. Náhled obrázku by měl být 200 × 200 pixelů a zobrazený v uživatelském rozhraní podrobností. Pokud není zadaný žádnýPreviewImageprvek, 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 k hledání. ElementTagsje omezen na 100 znaků.<GettingStartedGuide>- Tento volitelný prvek je relativní cesta k souboru HTML nebo adrese URL webu, který obsahuje informace o tom, jak používat rozšíření 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 umožňovalo všechny ostatní prvky. Všechny podřízené elementy, které nejsou rozpoznány zavaděčem manifestu, jsou vystaveny jako seznam XmlElement objekty. Pomocí těchto podřízených elementů mohou 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 true, pokud máte rozšíření, které je aktuálně nainstalováno 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ším.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) omezené na jednotlivé skladové položky sady Visual Studio. Tato hodnota je výchozí.
AllUsers– Tento volitelný atribut určuje, zda 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 na uživatele. (Když nastavíte tuto hodnotu na true, musí instalační uživatel 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 nedají se aktualizovat. Ve výchozím nastavení je tento atribut false, který určuje, že balíček není systémová komponenta.AnyAttribute*– ElementInstallationpř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í, kde instalační program VSIX nainstaluje balíček. Pokud je hodnota atributuScopeProductExtension, balíček musí cílit na SKU, který nainstaloval soubor manifestu jako součást jeho obsahu, aby inzeroval jeho dostupnost rozšířením. Element<InstallationTarget>má následující atributy, pokudScopeatribut má explicitní nebo výchozí hodnotu "ProductExtension":Id– Tento atribut identifikuje balíček. Atribut se řídí konvencí oboru názvů: Company.Product.Feature.Name. AtributIdmůž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ími a maximálními podporovanými verzemi 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é
Verze 2.0 schématu VSIX byla zavedena v sadě Visual Studio 2012. Chcete-li použít toto schéma, musíte mít na počítači nainstalovanou sadu Visual Studio 2012 nebo novější a použít soubor VSIXInstaller.exe, který je součástí tohoto produktu. Starší verze sady Visual Studio můžete cílit pomocí nástroje Visual Studio 2012 nebo novějšího nástroje VSIXInstaller, ale pouze pomocí novějších verzí instalačního programu.
Čísla verzí sady Visual Studio 2017 najdete v číslech buildů 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ší.
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>Idatributu balíčku, na který je tento balíček závislý. AtributIdse ří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ími a maximálními podporovanými verzemi 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*– ElementDependencypřijímá otevřenou sadu atributů, které budou vystaveny za běhu jako slovník páru name-value.
Element Assets
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 jedenType, 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:Microsoft.VisualStudio.VsPackage
Microsoft.VisualStudio.MefComponent
Microsoft.VisualStudio.ToolboxControl
Microsoft.VisualStudio.Samples
Microsoft.VisualStudio.ProjectTemplate
Microsoft.VisualStudio.ItemTemplate
Microsoft.VisualStudio.Assembly
Můžete vytvořit vlastní typy a pojmenovat je jedinečnými názvy. V běhu v sadě Visual Studio může váš kód vytvořit výčet a získat přístup 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. Slouží k přesouvá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 vypsat je za běhu.
Syntaxe zástupného symbolu pro manifesty rozšíření
Soubor .vsixmanifest definuje sestavení pro balíček VSIX. Při vyžádání sestavení sada Visual Studio parsuje manifest tak, aby vytvořil skript sestavení, který je sestaven pomocí nástroje MSBuild. Určité hodnoty v době sestavení můžete nastavit pomocí zástupných symbolů, které se vyhodnocují před sestavením balíčku VSIX. Zástupné symboly se používají k odkazům na projekty odkazované v projektu VSIX, vlastnostech NÁSTROJE MSBuild a cílech NÁSTROJE MSBuild, nejčastěji cílů, které představují výstupní skupiny projektu. Výstupní skupiny projektu představují kolekce souborů přidružených k projektu a některé z nich mohou být zahrnuty do balíčku VSIX. Například , PkgDefProjectOutputGroup, BuiltProjectOutputGroupnebo SatelliteDllsProjectOutputGroup.
Pokud chcete odkazovat na vlastnost definovanou v projektu VSIX, použijte stejnou syntaxi jako v samotném $(PropertyName)souboru projektu .
Speciální token %CurrentProject% odkazuje na projekt VSIX. Na jiné projekty odkazované v projektu VSIX můžete odkazovat pomocí Name elementu ProjectReference v souboru projektu VSIX, který je obklopen symboly svislých čar (|). Například |ProjectTemplate1|.
Cíl MSBuild můžete odkazovat podle názvu projektu ( Name vlastnost odkazu projektu v projektu VSIX) a pak cílového názvu. Pokud například chcete odkazovat na Version cíl v jednom z projektů odkazovaných v balíčku VSIX, použijte syntaxi |ProjectName;Version|. Cíl by měl mít Outputs hodnotu, která odpovídá kontextu, ve kterém se používá. Manifest VSIX obsahuje místa, kde je vhodné nahradit řetězcové hodnoty a kolekce položek. Například řetězec verze v manifestu může být nahrazen následujícím způsobem:
<Identity Id="0000000-0000-0000-0000-000000000000" Version="|%CurrentProject%;GetVsixVersion|" Language="en-US" Publisher="Company" />
V takovém případě by měl být GetVsixVersion v projektu VSIX cíl, který by měl vrátit jednoduchý řetězec. Příklad:
<Target Name="GetVsixVersion" Outputs="$(_VsixVersion)">
<PropertyGroup>
<_VsixVersion>1.2.3.4</_VsixVersion>
</PropertyGroup>
</Target>
Zástupné symboly slouží k vytvoření správného souboru manifestu VSIX pomocí projektu VSIX ve stylu sady SDK. Předpokládejme, že zadáte cílovou verzi sady Visual Studio s vlastností TargetFramework:
<TargetFramework>vs17.0</TargetFramework> // Target Visual Studio 2022 version 17.0<TargetFramework>vs16.10</TargetFramework> // Target Visual Studio 2019 version 16.10
Na základě cílové architektury sestavení VSIX transformuje hodnoty definované v souboru manifestu přípony následujícím způsobem. Pro následující syntaxi v souboru manifestu:
<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="|%CurrentProject%;GetInstallationTargetVersion|" />
Výstup použitý v kódu MSBuild projektu VSIX je:
<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 18.0)">
<ProductArchitecture>amd64</ProductArchitecture>
</InstallationTarget>
A pro následující kód v manifestu rozšíření:
<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="|%CurrentProject%;GetPrerequisiteTargetVersion|" DisplayName="Visual Studio core editor" />
Kód sestavení projektu je:
<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[17.0, 18.0)" DisplayName="Visual Studio core editor" />
Tato funkce se také používá v souborech manifestu VSIX, které Sada Visual Studio generuje k odkazování na výstupní skupiny projektu podle názvu odkazu projektu a potom názvu cíle NÁSTROJE MSBuild oddělené středníkem. Řetězec například |%CurrentProject%;PkgDefProjectOutputGroup| znamená výstupní skupinu PkgDef, která odkazuje na .pkgdef soubory přidružené k aktuálnímu projektu VSIX. Některé cíle ProjectOutputGroup definované v souboru sestavení systému Microsoft.Common.CurrentVersion.targets se používají v manifestech VSIX vygenerovaných sadou Visual Studio. Další cíle výstupní skupiny projektu dostupné v projektu VSIX jsou definovány v microsoft.VsSDK.targets. Následující tabulka ukazuje definované výstupní skupiny projektu:
| ProjectOutputGroup | Popis |
|---|---|
| BuiltProjectOutputGroup | Soubory, které představují výstup sestavení. |
| ContentFilesProjectOutputGroup | Jiné než binární soubory přidružené k projektu, například soubory HTML a CSS. |
| DebugSymbolsProjectOutputGroup | Soubory symbolů (.pdb) pro ladění rozšíření v experimentální instanci sady Visual Studio. |
| DocumentationFilesProjectOutputGroup | Soubory dokumentace XML. |
| PkgDefProjectOutputGroup | Soubory definice balíčku (.pkgdef) |
| PriFilesOutputGroup | Soubory .pri zdrojů přidružené k projektu UPW. |
| SatelliteDllsProjectOutputGroup | Satelitní sestavení pro lokalizované prostředky |
| SDKRedistOutputGroup | Redistribuovatelné složky ze sad SDK, na které odkazuje projekt. |
| SGenFilesOutputGroup | GenerateSerializationAssemblies soubory, které jsou generovány GenerateSerializationAssemblies cíl a úkol. |
| SourceFilesProjectOutputGroup | Soubory zdrojového kódu. |
| TemplateProjectOutputGroup | Šablony projektů. |
Systém sestavení naplní tyto výstupní skupiny příslušnými soubory podle výchozí logiky sestavení. Ve vlastním sestavení můžete do výstupních skupin projektu přidat položky buď nastavením atributu BeforeTargets na cíl na jeden z výše uvedených cílů, a v cíli postupovat podle kódu cílů uvedených výše, jako příklady použití BuiltProjectOutputGroupKeyOutput úlohy k nastavení výstupů.
V pokročilých scénářích můžete odkazovat na cíl sestavení nebo definovat vlastní cíl, který chcete vyvolat, a pomocí syntaxe popsané zde můžete vložit hodnoty pro libovolný prvek v manifestu VSIX. Cíl musí mít odpovídající výstupní parametr, který odpovídá očekávání kontextu, ve kterém se používá. Pokud se očekává kolekce souborů, jako je například sestavený výstup projektu, je potřeba cíl, který vypíše požadované položky NÁSTROJE MSBuild. Jako příklady při vytváření vlastních cílů je možné použít dříve uvedené výstupní skupiny projektu.
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>