VSIX 擴充架構 2.0 參考

  • 發行項

適用于：yesVisual Studio no Visual Studio for Mac no Visual Studio Code

VSIX 部署資訊清單檔描述 VSIX 套件的內容。 檔案格式是由架構所控管。 此架構 2.0 版支援新增自訂類型和屬性。 資訊清單的架構是可延伸的。 資訊清單載入器會忽略它不了解的 XML 元素和屬性。

重要

Visual Studio 2015 可以載入 Visual Studio 2010、Visual Studio 2012 或 Visual Studio 2013 格式的 VSIX 檔案。

套件資訊清單架構

資訊清單 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> 包含下列元素：

  • <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」 指定已安裝傳統 VSIX 延伸模組 (1.0 版) 範圍設定為個別 Visual Studio SKU。 這是預設值。

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

      • [ - 包含最低版本。

      • ] - 包含最大版本。

      • ( - 最低版本獨佔。

      • ) - 獨佔版本上限。

      • 單一版本 # - 僅指定版本。

      重要

      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 延伸模組可以在資訊清單檔中定義結構化類型特定中繼資料，並在執行時間加以列舉。

資訊清單範例

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

另請參閱