共用方式為

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>* - 指令清單架構具有足夠的彈性，可允許任何其他元素。 指令清單載入器無法辨識的任何子項目都會在Extension Manager API 中公開為額外的 XmlElement 物件。 使用這些子元素，VSIX 延伸模組可以在指令清單檔案中定義其他數據，Visual Studio 中執行的程式代碼可以在運行時間存取。 請參閱 Microsoft.VisualStudio.ExtensionManager.IExtension.AdditionalElements。

元數據元素

本節是套件、其身分識別和廣告資訊的元數據。 <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> - 這個專案會指定延伸模組管理員 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 延伸模組可以在指令清單檔中定義其他數據，並在運行時間加以列舉。

安裝專案

本節會定義此套件的安裝方式，以及其可安裝到的應用程式 SKU。 本節包含下列屬性：

  • Experimental - 如果您有目前為所有使用者安裝的擴充功能，但您要在同一部計算機上開發更新的版本，請將此屬性設定為 true。 例如，如果您已為所有使用者安裝 MyExtension 1.0，但您想要在同一部電腦上偵錯 MyExtension 2.0，請設定 Experimental=“true”。 此屬性可在 Visual Studio 2015 Update 1 和更新版本中取得。

  • Scope - 這個屬性可以接受 「Global」 或 「ProductExtension」 值：

    • “Global” 指定安裝未限定於特定 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]，其中

      • [ - 包含最低版本。

      • ] - 包含最大版本。

      • （ - 最低版本獨佔。

      • ） - 最大版本獨佔。

      • 單一版本 # - 只有指定的版本。

      重要

      VSIX 架構 2.0 版是在 Visual Studio 2012 中引進的。 若要使用此架構，您必須在計算機上安裝Visual Studio 2012或更新版本，並使用屬於該產品的 VSIXInstaller.exe。 您可以使用 Visual Studio 2012 或更新版本的 VSIXInstaller，以舊版 Visual Studio 為目標，但只能使用較新版本的安裝程式。

      您可以在 Visual Studio 組建編號和發行日期找到 Visual Studio 2017 版本號碼。

      表示 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]，其中：

      • [ - 包含最低版本。

      • ] - 包含最大版本。

      • （ - 最低版本獨佔。

      • ） - 最大版本獨佔。

      • 單一版本 # - 只有指定的版本。

    • 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 專案檔中，參考 VSIX 專案中NameProjectReference參考的其他專案。 例如： |ProjectTemplate1| 。

您可以依專案名稱來參考 MSBuild 目標（ Name VSIX 專案中的項目參考屬性），然後參考目標名稱。 例如，若要參考 Version VSIX 套件中所參考其中一個項目的目標，請使用 語法 |ProjectName;Version|。 目標應該有符合 Outputs 其使用內容的值;VSIX 指令清單包含替代字串值和專案集合的位置。 例如，指令清單中的 Version 字串可能會取代如下：

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

另請參閱