Справочник по схеме расширения VSIX 2.0

Область применения:Visual StudioVisual Studio для Mac Visual Studio Code

Файл манифеста развертывания VSIX описывает содержимое пакета VSIX. Формат файла регулируется схемой. Эта схема версии 2.0 поддерживает добавление настраиваемых типов и атрибутов. Схема манифеста является расширяемой. Загрузчик манифестов игнорирует элементы XML и атрибуты, которые он не понимает.

Схема манифеста пакета

Корневой элемент XML-файла манифеста — <PackageManifest>. Он имеет один атрибут Version, который является версией формата манифеста. Если в формат вносятся существенные изменения, изменяется формат версии. В этой статье описывается формат манифеста версии 2.0, который указывается в манифесте Version путем задания атрибуту значения Version="2.0".

Элемент PackageManifest

В корневом <PackageManifest> элементе можно использовать следующие элементы:

• <Metadata> — Метаданные и рекламные сведения о самом пакете. В манифесте допускается только один Metadata элемент.

• <Installation> — В этом разделе определяется способ установки этого пакета расширения, включая номера SKU приложений, в которые он может устанавливаться. В манифесте допускается только один Installation элемент. Манифест должен иметь Installation элемент , иначе этот пакет не будет устанавливаться ни в один номер SKU.

• <Dependencies> — Здесь определен необязательный список зависимостей для этого пакета.

• <Assets> — Этот раздел содержит все ресурсы, содержащиеся в этом пакете. Без этого раздела этот пакет не будет отображать содержимое.

• <AnyElement>* — Схема манифеста достаточно гибкая, чтобы разрешить любые другие элементы. Все дочерние элементы, не распознанные загрузчиком манифестов, предоставляются в API диспетчера расширений в виде дополнительных объектов XmlElement. Используя эти дочерние элементы, расширения VSIX могут определять дополнительные данные в файле манифеста, к которым код, выполняющийся в Visual Studio, может получить доступ во время выполнения. См . статью Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements.

Элемент Metadata

В этом разделе содержатся метаданные о пакете, его идентификаторе и рекламной информации. <Metadata> содержит следующие элементы:

• <Identity> — определяет сведения об идентификации для этого пакета и включает следующие атрибуты:

  • Id — Этот атрибут должен быть уникальным идентификатором пакета, выбранного его автором. Имя должно быть указано так же, как типы CLR имеют пространство имен: Company.Product.Feature.Name. Длина Id атрибута ограничена 100 символами.

  • Version — определяет версию этого пакета и его содержимое. Этот атрибут соответствует формату управления версиями сборки CLR: Major.Minor.Build.Revision (1.2.40308.00). Пакет с более высоким номером версии считается обновлением пакета и может быть установлен поверх существующей установленной версии.

  • Language — Этот атрибут является языком по умолчанию для пакета и соответствует текстовым данным в этом манифесте. Этот атрибут соответствует соглашению о коде языкового стандарта CLR для сборок ресурсов, например en-us, en, fr-fr. Можно указать neutral , чтобы объявить расширение, не зависящее от языка, которое будет выполняться в любой версии Visual Studio. Значение по умолчанию — neutral.

  • Publisher — Этот атрибут идентифицирует издателя этого пакета, название компании или отдельного пользователя. Длина Publisher атрибута ограничена 100 символами.

• <DisplayName> — Этот элемент задает понятное имя пакета, отображаемое в пользовательском интерфейсе диспетчера расширений. Длина DisplayName содержимого ограничена 50 символами.

• <Description> — Этот необязательный элемент представляет собой краткое описание пакета и его содержимого, которое отображается в пользовательском интерфейсе диспетчера расширений. Содержимое Description может содержать любой текст, но он ограничен 1000 символами.

• <MoreInfo> — Этот необязательный элемент является URL-адресом страницы в Интернете, содержащей полное описание этого пакета. Протокол должен быть указан как http.

• <License> — Этот необязательный элемент представляет собой относительный путь к файлу лицензии (.txt, .RTF), который содержится в пакете.

• <ReleaseNotes> — Этот необязательный элемент представляет собой относительный путь к файлу заметок о выпуске, который содержится в пакете (.txt, .RTF), или URL-адрес веб-сайта, на котором отображаются заметки о выпуске.

• <Icon> — Этот необязательный элемент является относительным путем к файлу изображения (png, bmp, jpeg, ico), который содержится в пакете. Изображение значка должно быть размером 32 x 32 пикселя (или будет сжато до этого размера) и отображается в пользовательском интерфейсе listview. Если элемент не Icon указан, в пользовательском интерфейсе используется значение по умолчанию.

• <PreviewImage> — Этот необязательный элемент является относительным путем к файлу изображения (png, bmp, jpeg), который содержится в пакете. Изображение предварительного просмотра должно иметь размер 200 x 200 пикселей и отображаться в пользовательском интерфейсе сведений. Если элемент не PreviewImage указан, в пользовательском интерфейсе используется значение по умолчанию.

• <Tags> — Этот необязательный элемент содержит дополнительные текстовые теги с разделителями запятой, которые используются для подсказок поиска. Длина Tags элемента ограничена 100 символами.

• <GettingStartedGuide> — Этот необязательный элемент представляет собой относительный путь к HTML-файлу или URL-адрес веб-сайта, содержащий сведения об использовании расширения или содержимого в этом пакете. Это руководство запускается в рамках установки.

• <AnyElement>* — Схема манифеста достаточно гибкая, чтобы разрешить любые другие элементы. Все дочерние элементы, которые не распознаются загрузчиком манифеста, предоставляются в виде списка объектов XmlElement. Используя эти дочерние элементы, расширения VSIX могут определять дополнительные данные в файле манифеста и перечислять их во время выполнения.

Элемент Installation

В этом разделе определяется способ установки этого пакета и номера SKU приложений, в которые он может устанавливаться. Этот раздел содержит следующие атрибуты:

• Experimental — Установите для этого атрибута значение true, если у вас есть расширение, которое в настоящее время установлено для всех пользователей, но вы разрабатываете обновленную версию на том же компьютере. Например, если вы установили MyExtension 1.0 для всех пользователей, но хотите выполнить отладку MyExtension 2.0 на том же компьютере, установите для параметра Experimental="true". Этот атрибут доступен в Visual Studio 2015 с обновлением 1 и более поздних версий.

• Scope — Этот атрибут может принимать значение Global или ProductExtension:

  • "Global" указывает, что установка не ограничена определенным номером SKU. Например, это значение используется при установке пакета SDK расширения.

  • "ProductExtension" указывает, что установлено традиционное расширение VSIX (версия 1.0), ограниченное отдельными номерами SKU Visual Studio. Это значение по умолчанию.

• AllUsers — Этот необязательный атрибут указывает, будет ли установлен этот пакет для всех пользователей. По умолчанию этот атрибут имеет значение false, указывающее, что пакет предназначен для каждого пользователя. (Если для этого значения задано значение true, пользователь установки должен повысить уровень прав администратора, чтобы установить результирующий VSIX.

• InstalledByMsi — Этот необязательный атрибут указывает, установлен ли этот пакет MSI. Пакеты, установленные MSI, устанавливаются и управляются с помощью MSI (программы и компоненты), а не с помощью диспетчера расширений Visual Studio. По умолчанию этот атрибут имеет значение false, указывающее, что пакет не устанавливается MSI.

• SystemComponent — Этот необязательный атрибут указывает, следует ли считать этот пакет системным компонентом. Системные компоненты не отображаются в пользовательском интерфейсе диспетчера расширений и не могут быть обновлены. По умолчанию этот атрибут имеет значение false, указывающее, что пакет не является системным компонентом.

• AnyAttribute* — Элемент Installation принимает открытый набор атрибутов, который будет предоставляться во время выполнения в виде словаря пар "имя-значение".

• <InstallationTarget> Этот элемент управляет расположением, в котором установщик VSIX устанавливает пакет. Если атрибут имеет значение Scope "ProductExtension", пакет должен быть нацелен на номер SKU, который установил файл манифеста в составе своего содержимого, чтобы объявить о его доступности расширениям. Элемент <InstallationTarget> имеет следующие атрибуты, если Scope атрибут имеет явное или значение по умолчанию "ProductExtension":

  • Id — этот атрибут идентифицирует пакет. Атрибут соответствует соглашению о пространстве имен: Company.Product.Feature.Name. Атрибут Id может содержать только буквенно-цифровые символы и ограничен 100 символами. Ожидаемые значения:

    • 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 — Этот атрибут задает диапазон версий с минимальной и максимальной поддерживаемыми версиями этого номера SKU. Пакет может подробно описывать версии номеров SKU, которые он поддерживает. Нотация диапазона версий — [10.0 – 11.0], где

    • [ — минимальная версия включительно.

    • ] — максимальная версия включительно.

    • ( — минимальная версия, исключаемая.

    • ) — максимальная версия, исключаемая.

    • Single version # — только указанная версия.

    Важно!

    В Visual Studio 2012 появилась версия 2.0 схемы VSIX. Чтобы использовать эту схему, необходимо установить на компьютере Visual Studio 2012 или более поздней версии и использовать VSIXInstaller.exe, которая является частью этого продукта. Для более ранних версий Visual Studio можно использовать visual Studio 2012 или более поздней версии VSIXInstaller, но только с помощью более поздних версий установщика.

    Номера версий Visual Studio 2017 можно найти в разделе Номера сборки и даты выпуска Visual Studio.

    При выражении версии для выпусков Visual Studio 2017 дополнительная версия всегда должна быть 0. Например, Visual Studio 2017 версии 15.3.26730.0 должен быть выражен как [15.0.26730.0;16.0). Это необходимо только для номеров Visual Studio 2017 и более поздних версий.

  • AnyAttribute* — Элемент <InstallationTarget> позволяет использовать открытый набор атрибутов, который предоставляется во время выполнения в виде словаря пар "имя-значение".

Элемент Dependencies

Этот элемент содержит список зависимостей, объявленных этим пакетом. Если указаны какие-либо зависимости, эти пакеты (определяемые ими Id) должны быть установлены ранее.

• <Dependency> element — этот дочерний элемент имеет следующие атрибуты:

  • Id — Этот атрибут должен быть уникальным идентификатором зависимого пакета. Это значение идентификатора должно соответствовать атрибуту <Metadata><Identity>Id пакета, от который зависит этот пакет. Атрибут Id соответствует соглашению о пространстве имен: Company.Product.Feature.Name. Атрибут может содержать только буквенно-цифровые символы и ограничен 100 символами.

  • Version — Этот атрибут задает диапазон версий с минимальной и максимальной поддерживаемыми версиями этого номера SKU. Пакет может подробно описывать версии номеров SKU, которые он поддерживает. Нотация диапазона версий — [12.0, 13.0], где:

    • [ — минимальная версия включительно.

    • ] — максимальная версия включительно.

    • ( — минимальная версия, исключаемая.

    • ) — максимальная версия, исключаемая.

    • Single version # — только указанная версия.

  • DisplayName — Этот атрибут представляет собой отображаемое имя зависимого пакета, которое используется в элементах пользовательского интерфейса, таких как диалоговые окна и сообщения об ошибках. Атрибут является необязательным, если зависимый пакет не установлен MSI.

  • Location — Этот необязательный атрибут указывает относительный путь внутри этой VSIX к вложенной версии пакета VSIX или URL-адрес к расположению загрузки зависимости. Этот атрибут используется, чтобы помочь пользователю найти необходимый пакет.

  • AnyAttribute* — Элемент Dependency принимает открытый набор атрибутов, который будет предоставляться во время выполнения в виде словаря пар "имя-значение".

Элемент Assets

Этот элемент содержит список тегов для каждого элемента расширения или содержимого <Asset> , доступного в этом пакете.

• <Asset> — Этот элемент содержит следующие атрибуты и элементы:

  • Type — тип расширения или содержимого, представленного этим элементом. Каждый <Asset> элемент должен иметь один Typeэлемент , но несколько <Asset> элементов могут иметь один и тот же Type. Этот атрибут должен быть представлен в виде полного имени в соответствии с соглашениями о пространстве имен. Известные типы:

    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

       Вы можете создавать собственные типы и присваивать им уникальные имена. Во время выполнения в Visual Studio код может перечислять эти пользовательские типы и получать доступ к ней через API диспетчера расширений.

  • Path — относительный путь к файлу или папке в пакете, который содержит ресурс.

  • TargetVersion — диапазон версий, к которому применяется данный ресурс. Используется для доставки нескольких версий ресурсов в разные версии Visual Studio. Требуется Visual Studio 2017.3 или более поздней версии.

  • AnyAttribute* — открытый набор атрибутов, который предоставляется во время выполнения в виде словаря пар "имя-значение".

    <AnyElement>* — Между начальным и конечным тегами <Asset> разрешено любое структурированное содержимое. Все элементы предоставляются в виде списка объектов XmlElement. Расширения VSIX могут определять метаданные структурированного типа в файле манифеста и перечислять их во время выполнения.

Синтаксис заполнителя для манифестов расширений

Файл .vsixmanifest определяет сборку для пакета VSIX. При запросе сборки Visual Studio анализирует манифест для создания скрипта сборки, который создается с помощью MSBuild. Вы можете задать определенные значения во время сборки с помощью заполнителей, которые вычисляются перед сборкой пакета VSIX. Заполнители используются для ссылки на проекты, на которые ссылается проект VSIX, свойства MSBuild и целевые объекты MSBuild, чаще всего целевые объекты, представляющие выходные группы проекта. Группы выходных данных проекта представляют коллекции файлов, связанных с проектом, и некоторые из них можно включить в пакет VSIX. Например, PkgDefProjectOutputGroup, BuiltProjectOutputGroup или SatelliteDllsProjectOutputGroup.

Чтобы сослаться на свойство, определенное в проекте VSIX, используйте тот же синтаксис, что и в самом файле проекта, $(PropertyName).

Специальный маркер %CurrentProject% ссылается на проект VSIX. Вы можете ссылаться на другие проекты, на которые ссылается проект VSIX, используя NameProjectReference элемент в файле проекта VSIX, окруженный символами канала (|). Например, |ProjectTemplate1|.

На целевой объект MSBuild можно ссылаться по имени проекта (свойству Name ссылки на проект в проекте VSIX), а затем по имени целевого объекта. Например, чтобы сослаться на целевой Version объект в одном из проектов, на которые ссылается пакет VSIX, используйте синтаксис |ProjectName;Version|. Целевой Outputs объект должен иметь значение, соответствующее контексту, в котором он используется; манифест VSIX содержит места, где подстановка строковых значений и коллекций элементов подходит. Например, строка версии в манифесте может быть заменена следующим образом:

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

В этом случае в проекте VSIX должен быть целевой GetVsixVersion объект, который должен возвращать простую строку. Например,

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

Заполнители используются для создания правильного файла манифеста VSIX с помощью проекта VSIX в стиле пакета SDK. Предположим, вы указали целевую версию Visual Studio со свойством TargetFramework:

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

На основе целевой платформы сборка VSIX преобразует значения, определенные в файле манифеста расширения, следующим образом. Для следующего синтаксиса в файле манифеста:

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

Выходные данные, используемые в коде MSBuild проекта VSIX:

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

И для следующего кода в манифесте расширения:

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

Код сборки проекта:

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

Эта функция также используется в файлах манифеста VSIX, создаваемых Visual Studio для ссылки на группы выходных данных проекта по имени ссылки на проект, а затем имени целевого объекта MSBuild, разделенного точкой с запятой. Например, строка |%CurrentProject%;PkgDefProjectOutputGroup| означает выходную группу PkgDef, которая ссылается .pkgdef на файлы, связанные с текущим проектом VSIX. Некоторые целевые ProjectOutputGroup объекты, определенные в файле сборки системы Microsoft.Common.CurrentVersion.targets, используются в манифестах VSIX, созданных Visual Studio. Дополнительные целевые объекты выходной группы проекта, доступные в проекте VSIX, определены в Microsoft.VsSDK.targets. В следующей таблице показаны определенные группы выходных данных проекта:

ProjectOutputGroup	Описание
BuiltProjectOutputGroup	Файлы, представляющие выходные данные сборки.
ContentFilesProjectOutputGroup	Не двоичные файлы, связанные с проектом, например HTML- и CSS-файлы.
DebugSymbolsProjectOutputGroup	Файлы символов (.pdb) для отладки расширения в экспериментальном экземпляре Visual Studio.
DocumentationFilesProjectOutputGroup	XML-файлы документации.
PkgDefProjectOutputGroup	Файлы определения пакета (.pkgdef)
PriFilesOutputGroup	Файлы .pri ресурсов, связанные с проектом UWP.
SatelliteDllsProjectOutputGroup	Вспомогательные сборки для локализованных ресурсов.
SDKRedistOutputGroup	Распространяемые папки из пакетов SDK, на которые ссылается проект.
SGenFilesOutputGroup	Файлы GenerateSerializationAssemblies, созданные целевым объектом и задачей GenerateSerializationAssemblies.
SourceFilesProjectOutputGroup	Файлы исходного кода.
TemplateProjectOutputGroup	Шаблоны проектов.

Система сборки заполняет эти группы выходных данных соответствующими файлами в соответствии с логикой сборки по умолчанию. В пользовательской сборке можно добавить элементы в группы выходных данных проекта, задав BeforeTargets атрибут в целевом объекте для одного из указанных выше целевых объектов, а в целевом объекте следуйте коду для перечисленных выше целевых объектов в качестве примеров использования BuiltProjectOutputGroupKeyOutput задачи для задания выходных данных.

В расширенных сценариях можно ссылаться на целевой объект сборки или определить пользовательский целевой объект, который требуется вызвать, и использовать описанный здесь синтаксис для вставки значений для любого элемента в манифесте VSIX. Целевой объект должен иметь соответствующий выходной параметр, соответствующий ожиданиям контекста, в котором он используется. Если ожидается коллекция файлов, таких как встроенные выходные данные проекта, требуется целевой объект, который выводит необходимые элементы MSBuild . При создании собственных целевых объектов можно использовать ранее созданные целевые объекты группы выходных данных проекта.

Пример манифеста

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

См. также раздел

• Отправка расширений Visual Studio