Dokumentacja schematu rozszerzenia VSIX 2.0
Plik manifestu wdrożenia VSIX opisuje zawartość pakietu VSIX. Format pliku podlega schematowi. Wersja 2.0 tego schematu obsługuje dodawanie typów niestandardowych i atrybutów. Schemat manifestu jest rozszerzalny. Moduł ładujący manifest ignoruje elementy XML i atrybuty, których nie rozumie.
Schemat manifestu pakietu
Elementem głównym pliku XML manifestu jest <PackageManifest>
. Ma jeden atrybut Version
, który jest wersją formatu manifestu. Jeśli w formacie zostaną wprowadzone poważne zmiany, format wersji zostanie zmieniony. W tym artykule opisano format manifestu w wersji 2.0, który jest określony w manifeście przez ustawienie Version
atrybutu na wartość Version="2.0".
PackageManifest, element
W elemecie <PackageManifest>
głównym można użyć następujących elementów:
<Metadata>
- Metadane i anonsowanie informacji o samym pakiecie. Tylko jedenMetadata
element jest dozwolony w manifeście.<Installation>
— W tej sekcji zdefiniowano sposób instalowania tego pakietu rozszerzeń, w tym jednostek SKU aplikacji, w których można go zainstalować. Tylko jedenInstallation
element jest dozwolony w manifeście. Manifest musi miećInstallation
element lub ten pakiet nie zostanie zainstalowany w żadnej jednostce SKU.<Dependencies>
— W tym miejscu zdefiniowano opcjonalną listę zależności dla tego pakietu.<Assets>
— Ta sekcja zawiera wszystkie zasoby zawarte w tym pakiecie. Bez tej sekcji ten pakiet nie będzie zawierać żadnej zawartości.<AnyElement>*
- Schemat manifestu jest wystarczająco elastyczny, aby zezwolić na inne elementy. Wszystkie elementy podrzędne, które nie są rozpoznawane przez moduł ładujący manifestu, są widoczne w interfejsie API menedżera rozszerzeń jako dodatkowe obiekty XmlElement. Korzystając z tych elementów podrzędnych, rozszerzenia VSIX mogą definiować dodatkowe dane w pliku manifestu, do którego kod uruchomiony w programie Visual Studio może uzyskiwać dostęp w czasie wykonywania. Zobacz Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.
Element metadanych
Ta sekcja zawiera metadane dotyczące pakietu, jego tożsamości i informacji reklamowych. <Metadata>
zawiera następujące elementy:
<Identity>
- Definiuje informacje identyfikacyjne dla tego pakietu i zawiera następujące atrybuty:Id
- Ten atrybut musi być unikatowym identyfikatorem pakietu wybranego przez jego autora. Nazwa powinna być kwalifikowana w taki sam sposób, jak typy CLR są przestrzeniami nazw: Company.Product.Feature.Name. AtrybutId
jest ograniczony do 100 znaków.Version
— Definiuje wersję tego pakietu i jego zawartość. Ten atrybut jest zgodny z formatem przechowywania wersji zestawu CLR: Major.Minor.Build.Revision (1.2.40308.00). Pakiet o wyższym numerze wersji jest uznawany za aktualizacje pakietu i można go zainstalować za pośrednictwem istniejącej zainstalowanej wersji.Language
— Ten atrybut jest domyślnym językiem pakietu i odpowiada tekstowym danym w tym manifeście. Ten atrybut jest zgodny z konwencją kodu ustawień regionalnych CLR dla zestawów zasobów, na przykład: en-us, en, fr-fr. Można określićneutral
, aby zadeklarować rozszerzenie neutralne dla języka, które będzie działać w dowolnej wersji programu Visual Studio. Domyślna wartość toneutral
.Publisher
- Ten atrybut identyfikuje wydawcę tego pakietu, firmę lub nazwę indywidualną. AtrybutPublisher
jest ograniczony do 100 znaków.
<DisplayName>
— Ten element określa przyjazną dla użytkownika nazwę pakietu wyświetlaną w interfejsie użytkownika Menedżera rozszerzeń. Zawartość jest ograniczonaDisplayName
do 50 znaków.<Description>
— Ten opcjonalny element jest krótkim opisem pakietu i jego zawartości wyświetlanej w interfejsie użytkownika menedżera rozszerzeń. ZawartośćDescription
może zawierać dowolny tekst, ale jest ograniczona do 1000 znaków.<MoreInfo>
— Ten opcjonalny element jest adresem URL strony w trybie online, która zawiera pełny opis tego pakietu. Protokół musi być określony jako http.<License>
— Ten opcjonalny element jest ścieżką względną do pliku licencji (.txt, .rtf) zawartego w pakiecie.<ReleaseNotes>
— Ten opcjonalny element jest ścieżką względną do pliku informacji o wersji zawartego w pakiecie (.txt, rtf) lub innym adresem URL witryny internetowej, która wyświetla informacje o wersji.<Icon>
— Ten opcjonalny element jest ścieżką względną do pliku obrazu (png, bmp, jpeg, ico) zawartego w pakiecie. Obraz ikony powinien mieć rozmiar 32x32 pikseli (lub zostanie skurczyny do tego rozmiaru) i pojawi się w interfejsie użytkownika widoku listy. Jeśli nieIcon
określono żadnego elementu, interfejs użytkownika używa wartości domyślnej.<PreviewImage>
— Ten opcjonalny element jest ścieżką względną do pliku obrazu (png, bmp, jpeg) zawartego w pakiecie. Obraz podglądu powinien mieć rozmiar 200x200 pikseli i wyświetlany w interfejsie użytkownika szczegółów. Jeśli niePreviewImage
określono żadnego elementu, interfejs użytkownika używa wartości domyślnej.<Tags>
— Ten opcjonalny element zawiera listę dodatkowych tagów tekstowych rozdzielanych średnikami, które są używane do wyszukiwania wskazówek. ElementTags
jest ograniczony do 100 znaków.<GettingStartedGuide>
— Ten opcjonalny element jest ścieżką względną do pliku HTML lub adresu URL witryny internetowej zawierającej informacje o sposobie używania rozszerzenia lub zawartości w tym pakiecie. Ten przewodnik jest uruchamiany w ramach instalacji.<AnyElement>*
- Schemat manifestu jest wystarczająco elastyczny, aby zezwolić na inne elementy. Wszystkie elementy podrzędne, które nie są rozpoznawane przez moduł ładujący manifestu, są widoczne jako lista obiektów XmlElement. Korzystając z tych elementów podrzędnych, rozszerzenia VSIX mogą definiować dodatkowe dane w pliku manifestu i wyliczać je w czasie wykonywania.
Element instalacji
W tej sekcji zdefiniowano sposób instalowania tego pakietu oraz jednostek SKU aplikacji, w których można je zainstalować. Ta sekcja zawiera następujące atrybuty:
Experimental
— Ustaw ten atrybut na wartość true, jeśli masz rozszerzenie, które jest obecnie zainstalowane dla wszystkich użytkowników, ale tworzysz zaktualizowaną wersję na tym samym komputerze. Jeśli na przykład zainstalowano program MyExtension 1.0 dla wszystkich użytkowników, ale chcesz debugować program MyExtension 2.0 na tym samym komputerze, ustaw wartość Experimental="true". Ten atrybut jest dostępny w programie Visual Studio 2015 Update 1 lub nowszym.Scope
— Ten atrybut może przyjmować wartość "Global" lub "ProductExtension":"Globalny" określa, że instalacja nie jest ograniczona do określonej jednostki SKU. Na przykład ta wartość jest używana podczas instalowania zestawu SDK rozszerzenia.
"ProductExtension" określa, że jest zainstalowane tradycyjne rozszerzenie VSIX (wersja 1.0) do poszczególnych jednostek SKU programu Visual Studio. Jest to wartość domyślna.
AllUsers
- Ten opcjonalny atrybut określa, czy ten pakiet zostanie zainstalowany dla wszystkich użytkowników. Domyślnie ten atrybut ma wartość false, co określa, że pakiet jest na użytkownika. (Po ustawieniu tej wartości na wartość true użytkownik instalowany musi podnieść poziom uprawnień administracyjnych, aby zainstalować wynikowy plik VSIX.InstalledByMsi
— Ten opcjonalny atrybut określa, czy ten pakiet jest instalowany przez tożsamość usługi zarządzanej. Pakiety zainstalowane przez msi są instalowane i zarządzane przez msi (programy i funkcje), a nie przez Menedżera rozszerzeń programu Visual Studio. Domyślnie ten atrybut ma wartość false, co określa, że pakiet nie jest zainstalowany przez tożsamość usługi zarządzanej.SystemComponent
- Ten opcjonalny atrybut określa, czy ten pakiet powinien być traktowany jako składnik systemowy. Składniki systemowe nie są wyświetlane w interfejsie użytkownika menedżera rozszerzeń i nie można ich zaktualizować. Domyślnie ten atrybut ma wartość false, która określa, że pakiet nie jest składnikiem systemu.AnyAttribute*
— ElementInstallation
akceptuje otwarty zestaw atrybutów, które zostaną uwidocznione w czasie wykonywania jako słownik par nazwa-wartość.<InstallationTarget>
-Ten element kontroluje lokalizację, w której instalator VSIX instaluje pakiet. Jeśli wartość atrybutuScope
to "ProductExtension", pakiet musi być przeznaczony dla jednostki SKU, która zainstalowała plik manifestu w ramach jego zawartości, aby anonsować jego dostępność do rozszerzeń. Element<InstallationTarget>
ma następujące atrybuty, gdyScope
atrybut ma jawną lub domyślną wartość "ProductExtension":Id
- Ten atrybut identyfikuje pakiet. Atrybut jest zgodny z konwencją przestrzeni nazw: Company.Product.Feature.Name. AtrybutId
może zawierać tylko znaki alfanumeryczne i jest ograniczony do 100 znaków. Oczekiwane wartości: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
— Ten atrybut określa zakres wersji z minimalną i maksymalną obsługiwaną wersją tej jednostki SKU. Pakiet może szczegółowo określić wersje jednostek SKU, które obsługuje. Notacja zakresu wersji to [10.0 – 11.0], gdzie[ — minimalna wersja włącznie.
] — maksymalna wersja włącznie.
( — minimalna wersja na wyłączność.
) — maksymalna wersja na wyłączność.
Pojedyncza wersja # — tylko określona wersja.
Ważne
W programie Visual Studio 2012 wprowadzono wersję 2.0 schematu VSIX. Aby użyć tego schematu, na komputerze musi być zainstalowany program Visual Studio 2012 lub nowszy i użyć narzędzia VSIXInstaller.exe będącego częścią tego produktu. Można kierować starsze wersje programu Visual Studio z programem Visual Studio 2012 lub nowszym programem VSIXInstaller, ale tylko przy użyciu nowszych wersji instalatora.
Numery wersji programu Visual Studio 2017 można znaleźć w artykule Numery kompilacji i daty wydania programu Visual Studio.
W przypadku wyrażania wersji programu Visual Studio 2017 wersja pomocnicza powinna zawsze mieć wartość 0. Na przykład program Visual Studio 2017 w wersji 15.3.26730.0 powinien być wyrażony jako [15.0.26730.0,16.0). Jest to wymagane tylko w przypadku wersji programu Visual Studio 2017 i nowszych wersji.
AnyAttribute*
— Element<InstallationTarget>
umożliwia otwarty zestaw atrybutów uwidocznionych w czasie wykonywania jako słownik par nazwa-wartość.
Element Dependencies
Ten element zawiera listę zależności zadeklarowanych przez ten pakiet. Jeśli określono jakiekolwiek zależności, te pakiety (zidentyfikowane przez ich Id
) muszą zostać zainstalowane wcześniej.
<Dependency>
element — ten element podrzędny ma następujące atrybuty:Id
— Ten atrybut musi być unikatowym identyfikatorem pakietu zależnego. Ta wartość tożsamości musi być zgodna z<Metadata><Identity>Id
atrybutem pakietu, od którego zależy ten pakiet. AtrybutId
jest zgodny z konwencją przestrzeni nazw: Company.Product.Feature.Name. Atrybut może zawierać tylko znaki alfanumeryczne i jest ograniczony do 100 znaków.Version
— Ten atrybut określa zakres wersji z minimalną i maksymalną obsługiwaną wersją tej jednostki SKU. Pakiet może szczegółowo określić wersje jednostek SKU, które obsługuje. Notacja zakresu wersji to [12.0, 13.0], gdzie:[ — minimalna wersja włącznie.
] — maksymalna wersja włącznie.
( — minimalna wersja na wyłączność.
) — maksymalna wersja na wyłączność.
Pojedyncza wersja # — tylko określona wersja.
DisplayName
- Ten atrybut jest nazwą wyświetlaną pakietu zależnego, który jest używany w elementach interfejsu użytkownika, takich jak okna dialogowe i komunikaty o błędach. Atrybut jest opcjonalny, chyba że pakiet zależny jest zainstalowany przez tożsamość usługi zarządzanej.Location
- Ten opcjonalny atrybut określa ścieżkę względną w tym VSIX do zagnieżdżonego pakietu VSIX lub adres URL lokalizacji pobierania zależności. Ten atrybut służy do ułatwienia użytkownikowi zlokalizowania pakietu wymagań wstępnych.AnyAttribute*
— ElementDependency
akceptuje otwarty zestaw atrybutów, które zostaną uwidocznione w czasie wykonywania jako słownik par nazwa-wartość.
Element Assets
Ten element zawiera listę tagów <Asset>
dla każdego rozszerzenia lub elementu zawartości udostępnianego przez ten pakiet.
<Asset>
— Ten element zawiera następujące atrybuty i elementy:Type
- Typ rozszerzenia lub zawartości reprezentowanej przez ten element. Każdy<Asset>
element musi mieć jedenType
element , ale wiele<Asset>
elementów może mieć ten samType
element . Ten atrybut powinien być reprezentowany jako w pełni kwalifikowana nazwa zgodnie z konwencjami przestrzeni nazw. Znane typy to:Microsoft.VisualStudio.VsPackage
Microsoft.VisualStudio.MefComponent
Microsoft.VisualStudio.ToolboxControl
Microsoft.VisualStudio.Samples
Microsoft.VisualStudio.ProjectTemplate
Microsoft.VisualStudio.ItemTemplate
Microsoft.VisualStudio.Assembly
Możesz utworzyć własne typy i nadać im unikatowe nazwy. W czasie wykonywania w programie Visual Studio kod może wyliczać i uzyskiwać dostęp do tych typów niestandardowych za pośrednictwem interfejsu API menedżera rozszerzeń.
Path
— względna ścieżka do pliku lub folderu w pakiecie zawierającym zasób.TargetVersion
— zakres wersji, do którego ma zastosowanie dany zasób. Służy do wysyłania wielu wersji zasobów do różnych wersji programu Visual Studio. Wymaga zastosowania programu Visual Studio 2017.3 lub nowszego.AnyAttribute*
— otwarty zestaw atrybutów, który jest udostępniany w czasie wykonywania jako słownik par nazwa-wartość.<AnyElement>*
— Dowolna zawartość ustrukturyzowana jest dozwolona między tagiem początkowym<Asset>
a końcowym. Wszystkie elementy są widoczne jako lista obiektów XmlElement. Rozszerzenia VSIX mogą definiować metadane specyficzne dla typu strukturalnego w pliku manifestu i wyliczać je w czasie wykonywania.
Składnia symboli zastępczych dla manifestów rozszerzeń
Plik .vsixmanifest
definiuje kompilację pakietu VSIX. Po zażądaniu kompilacji program Visual Studio analizuje manifest w celu utworzenia skryptu kompilacji, który jest kompilowany przy użyciu programu MSBuild. Niektóre wartości można ustawić w czasie kompilacji przy użyciu symboli zastępczych, które są oceniane przed skompilowanie pakietu VSIX. Symbole zastępcze są używane do odwoływania się do projektów, do których odwołuje się projekt VSIX, właściwości MSBuild i obiekty docelowe MSBuild, najczęściej obiekty docelowe reprezentujące grupy danych wyjściowych projektu. Grupy danych wyjściowych projektu reprezentują kolekcje plików skojarzonych z projektem, a niektóre z nich można uwzględnić w pakiecie VSIX. Na przykład, PkgDefProjectOutputGroup
, BuiltProjectOutputGroup
lub SatelliteDllsProjectOutputGroup
.
Aby odwołać się do właściwości zdefiniowanej w projekcie VSIX, użyj tej samej składni, co w samym pliku projektu . $(PropertyName)
Specjalny token %CurrentProject%
odwołuje się do projektu VSIX. Można odwoływać się do innych projektów, do których odwołuje się projekt VSIX, używając Name
ProjectReference
elementu w pliku projektu VSIX otoczonym symbolami potoku (|
). Na przykład |ProjectTemplate1|
.
Możesz odwołać się do obiektu docelowego MSBuild według nazwy projektu ( Name
właściwości odwołania projektu w projekcie VSIX), a następnie nazwy docelowej. Aby na przykład odwołać się do obiektu docelowego w jednym z projektów, do których odwołuje Version
się pakiet VSIX, użyj składni |ProjectName;Version|
. Obiekt docelowy powinien mieć wartość zgodną Outputs
z kontekstem, w którym jest używany. Manifest VSIX zawiera miejsca, w których odpowiednie jest podstawianie wartości ciągów i kolekcji elementów. Na przykład ciąg wersji w manifeście może zostać zastąpiony w następujący sposób:
<Identity Id="0000000-0000-0000-0000-000000000000" Version="|%CurrentProject%;GetVsixVersion|" Language="en-US" Publisher="Company" />
W takim przypadku w projekcie VSIX powinien znajdować się GetVsixVersion
element docelowy, który powinien zwrócić prosty ciąg. Przykład:
<Target Name="GetVsixVersion" Outputs="$(_VsixVersion)">
<PropertyGroup>
<_VsixVersion>1.2.3.4</_VsixVersion>
</PropertyGroup>
</Target>
Symbole zastępcze są używane do tworzenia poprawnego pliku manifestu VSIX z projektem VSIX w stylu zestawu SDK. Załóżmy, że określisz docelową wersję programu Visual Studio z właściwością "TargetFramework":
<TargetFramework>vs17.0</TargetFramework> // Target Visual Studio 2022 version 17.0
<TargetFramework>vs16.10</TargetFramework> // Target Visual Studio 2019 version 16.10
Na podstawie platformy docelowej kompilacja VSIX przekształca wartości zdefiniowane w pliku manifestu rozszerzenia w następujący sposób. Następująca składnia w pliku manifestu:
<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="|%CurrentProject%;GetInstallationTargetVersion|" />
Dane wyjściowe używane w kodzie MSBuild projektu VSIX to:
<InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 18.0)">
<ProductArchitecture>amd64</ProductArchitecture>
</InstallationTarget>
Dla następującego kodu w manifeście rozszerzenia:
<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="|%CurrentProject%;GetPrerequisiteTargetVersion|" DisplayName="Visual Studio core editor" />
Kod kompilacji projektu to:
<Prerequisite Id="Microsoft.VisualStudio.Component.CoreEditor" Version="[17.0, 18.0)" DisplayName="Visual Studio core editor" />
Ta funkcja jest również używana w plikach manifestu VSIX generowanych przez program Visual Studio w celu odwołwania się do grup wyjściowych projektu według nazwy odwołania do projektu, a następnie nazwy obiektu docelowego MSBuild oddzielonego średnikiem. Na przykład ciąg |%CurrentProject%;PkgDefProjectOutputGroup|
oznacza grupę danych wyjściowych PkgDef, która odwołuje się do .pkgdef
plików skojarzonych z bieżącym projektem VSIX. Niektóre obiekty ProjectOutputGroup
docelowe zdefiniowane w pliku kompilacji systemu Microsoft.Common.CurrentVersion.targets są używane w manifestach VSIX generowanych przez program Visual Studio. Dodatkowe elementy docelowe grupy danych wyjściowych projektu dostępne w projekcie VSIX są zdefiniowane w pliku Microsoft.VsSDK.targets. W poniższej tabeli przedstawiono zdefiniowane grupy danych wyjściowych projektu:
ProjectOutputGroup | opis |
---|---|
BuiltProjectOutputGroup | Pliki reprezentujące dane wyjściowe kompilacji. |
ContentFilesProjectOutputGroup | Pliki inne niż binarne skojarzone z projektem, takie jak pliki HTML i CSS. |
DebugSymbolsProjectOutputGroup | Pliki symboli (.pdb ) do debugowania rozszerzenia w eksperymentalnym wystąpieniu programu Visual Studio. |
DocumentationFilesProjectOutputGroup | Pliki dokumentacji XML. |
PkgDefProjectOutputGroup | Pliki definicji pakietu (.pkgdef ). |
PriFilesOutputGroup | Pliki .pri zasobów skojarzone z projektem platformy UWP. |
SatelliteDllsProjectOutputGroup | Zestawy satelitarne dla zlokalizowanych zasobów. |
SDKRedistOutputGroup | Foldery redystrybucyjne z zestawów SDK, do których odwołuje się projekt. |
SGenFilesOutputGroup | Pliki GenerateSerializationAssemblies, które są generowane przez element docelowy GenerateSerializationAssemblies i zadanie. |
SourceFilesProjectOutputGroup | Pliki kodu źródłowego. |
TemplateProjectOutputGroup | Szablony projektów. |
System kompilacji wypełnia te grupy wyjściowe odpowiednimi plikami zgodnie z domyślną logiką kompilacji. W niestandardowej kompilacji można dodawać elementy do grup danych wyjściowych projektu, ustawiając BeforeTargets
atrybut docelowy na jeden z powyższych obiektów docelowych, a w obiekcie docelowym postępuj zgodnie z kodem dla elementów docelowych wymienionych powyżej jako przykłady BuiltProjectOutputGroupKeyOutput
użycia zadania w celu ustawienia danych wyjściowych.
W zaawansowanych scenariuszach można odwołać się do obiektu docelowego kompilacji lub zdefiniować niestandardowy element docelowy, który chcesz wywołać i użyć składni opisanej tutaj, aby wstawić wartości dla dowolnego elementu w manifeście VSIX. Obiekt docelowy musi mieć odpowiedni parametr wyjściowy zgodny z oczekiwaniami kontekstu, w którym jest używany. Jeśli oczekiwana jest kolekcja plików, takich jak skompilowane dane wyjściowe projektu, element docelowy, który wyprowadza wymagane elementy MSBuild. Grupy danych wyjściowych projektu utworzone obiekty docelowe wymienione wcześniej mogą być używane jako przykłady podczas tworzenia własnych obiektów docelowych.
Przykładowy 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>