VSIX 扩展架构 2.0 参考

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 - 此属性必须是作者选择的包的唯一 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> - 此元素指定扩展管理器 UI 中显示的用户友好包名称。 内容 DisplayName 限制为 50 个字符。

• <Description> - 此可选元素是对包及其内容（显示在扩展管理器 UI 中）的简短说明。 内容 Description 可以包含所需的任何文本，但限制为 1000 个字符。

• <MoreInfo> - 此可选元素是联机页面的 URL，其中包含此包的完整说明。 协议必须指定为 http。

• <License> - 此可选元素是包中包含的许可证文件 （.txt， .rtf） 的相对路径。

• <ReleaseNotes> - 此可选元素是包（.txt、.rtf）中包含的发行说明文件的相对路径，或者是显示发行说明的网站 URL。

• <Icon> - 此可选元素是包中包含的图像文件（png、bmp、jpeg、ico）的相对路径。 图标图像应为 32x32 像素（或将缩小到该大小），并显示在 listview UI 中。 如果未 Icon 指定任何元素，则 UI 使用默认值。

• <PreviewImage> - 此可选元素是包中包含的图像文件（png、bmp、jpeg）的相对路径。 预览图像应为 200x200 像素，并显示在详细信息 UI 中。 如果未 PreviewImage 指定任何元素，则 UI 使用默认值。

• <Tags> - 此可选元素列出了用于搜索提示的其他分号分隔文本标记。 该 Tags 元素限制为 100 个字符。

• <GettingStartedGuide> - 此可选元素是 HTML 文件的相对路径，或者是包含有关如何使用此包中的扩展或内容的网站的 URL。 本指南作为安装的一部分启动。

• <AnyElement>* - 清单架构足够灵活，可以允许任何其他元素。 清单加载程序无法识别的任何子元素都公开为 XmlElement 对象列表。 使用这些子元素，VSIX 扩展可以在清单文件中定义其他数据，并在运行时枚举它们。

Installation 元素

本部分定义可以安装此包的方式及其安装到的应用程序 SKU。 本部分包含以下属性：

• Experimental - 如果你有当前为所有用户安装的扩展，但在同一台计算机上开发更新的版本，请将此属性设置为 true。 例如，如果已为所有用户安装 MyExtension 1.0，但想要在同一台计算机上调试 MyExtension 2.0，请设置 Experimental=“true”。 此属性在 Visual Studio 2015 Update 1 及更高版本中可用。

• Scope - 此属性可以采用值“Global”或“ProductExtension”：

  • “全局”指定安装范围不限定于特定 SKU。 例如，安装扩展 SDK 时使用此值。

  • “ProductExtension”指定安装了限定为单个 Visual Studio SKU 的传统 VSIX 扩展（版本 1.0）。 这是默认值。

• AllUsers - 此可选属性指定是否为所有用户安装此包。 默认情况下，此属性为 false，它指定包是每个用户。 （将此值设置为 true 时，安装用户必须提升到管理权限级别才能安装生成的 VSIX。

• InstalledByMsi - 此可选属性指定是否由 MSI 安装此包。 MSI 安装的包由 MSI（程序和功能）安装和管理，而不是由 Visual Studio 扩展管理器进行管理。 默认情况下，此属性为 false，它指定 MSI 未安装包。

• SystemComponent - 此可选属性指定是否应将此包视为系统组件。 系统组件不会显示在扩展管理器 UI 中，并且无法更新。 默认情况下，此属性为 false，它指定包不是系统组件。

• AnyAttribute* - 该 Installation 元素接受一组开放的属性，这些属性将在运行时公开为名称-值对字典。

• <InstallationTarget> -此元素控制 VSIX 安装程序安装包的位置。 如果该属性的值 Scope 为“ProductExtension”，则包必须以 SKU 为目标，该 SKU 已将清单文件作为其内容的一部分来播发其扩展的可用性。 当属性具有显式或默认值“ProductExtension”时，Scope该<InstallationTarget>元素具有以下属性：

  • Id - 此属性标识包。 该属性遵循命名空间约定：Company.Product.Feature.Name。 该 Id 属性只能包含字母数字字符，并且限制为 100 个字符。 预期值：

    • Microsoft.VisualStudio.IntegratedShell

    • Microsoft.VisualStudio.Pro

    • Microsoft.VisualStudio。高级版

    • 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]，其中

    • [ - 最低版本（非独占）。

    • ] - 包含最大版本。

    • （ - 最低版本独占。

    • ） - 最大版本独占。

    • 单一版本 # - 仅指定版本。

    重要

    VISUAL Studio 2012 中引入了 VSIX 架构版本 2.0。 若要使用此架构，必须在计算机上安装 Visual Studio 2012 或更高版本，并使用属于该产品的 VSIXInstaller.exe。 可以使用 Visual Studio 2012 或更高版本的 VSIXInstaller 面向早期版本的 Visual Studio，但只能使用更高版本的安装程序。

    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> 元素允许在运行时公开为名称/值对字典的开放式属性集。

依赖项元素

此元素包含此包声明的依赖项列表。 如果指定了任何依赖项，则之前必须安装这些包（由它们 Id标识）。

• <Dependency> element - 此子元素具有以下属性：

  • Id - 此属性必须是依赖包的唯一 ID。 此标识值必须与此包所依赖的包的属性匹配 <Metadata><Identity>Id 。 该 Id 属性遵循命名空间约定：Company.Product.Feature.Name。 该属性只能包含字母数字字符，并且限制为 100 个字符。

  • Version - 此属性指定版本范围，其中包含此 SKU 的最低和最大支持版本。 包可以详细说明它支持的 SKU 版本。 版本范围表示法为 [12.0， 13.0]，其中：

    • [ - 最低版本（非独占）。

    • ] - 包含最大版本。

    • （ - 最低版本独占。

    • ） - 最大版本独占。

    • 单一版本 # - 仅指定版本。

  • DisplayName - 此属性是依赖包的显示名称，在 UI 元素（如对话框和错误消息）中使用。 除非 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 项目文件中的元素（用管道符号（|）括住的元素来引用 VSIX 项目中NameProjectReference引用的其他项目。 例如 |ProjectTemplate1|。

可以按项目的名称（ Name VSIX 项目中的项目引用的属性）和目标名称来引用 MSBuild 目标。 例如，若要在 VSIX 包中引用的项目之一中引用 Version 目标，请使用语法 |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>

占位符用于使用 SDK 样式的 VSIX 项目创建正确的 VSIX 清单文件。 假设使用属性“TargetFramework”指定 Visual Studio 的目标版本：

• <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|" />

VSIX 项目 MSBuild 代码中使用的输出为：

    <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" />

Visual Studio 生成的 VSIX 清单文件中也使用此功能，以按项目引用的名称引用项目输出组，然后用分号分隔 MSBuild 目标的名称来引用项目输出组。 例如，字符串 |%CurrentProject%;PkgDefProjectOutputGroup| 表示 PkgDef 输出组，该组引用 .pkgdef 与当前 VSIX 项目关联的文件。 ProjectOutputGroup系统生成文件 Microsoft.Common.CurrentVersion.targets 中定义的一些目标用于 Visual Studio 生成的 VSIX 清单中。 VSIX 项目中提供的其他项目输出组目标在 Microsoft.VsSDK.targets 中定义。 下表显示了定义的项目输出组：

ProjectOutputGroup	说明
BuiltProjectOutputGroup	表示生成输出的文件。
ContentFilesProjectOutputGroup	与项目关联的非二进制文件，如 HTML 和 CSS 文件。
DebugSymbolsProjectOutputGroup	用于在 Visual Studio 实验实例中调试扩展的符号文件（.pdb）。
DocumentationFilesProjectOutputGroup	XML 文档文件。
PkgDefProjectOutputGroup	包定义 （.pkgdef） 文件（s）。
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 扩展