更新 Visual Studio 2022 的 Visual Studio 延伸模組

重要

本文中的建議可引導開發人員遷移需要重大變更才能在 Visual Studio 2019 和 Visual Studio 2022 中運作的延伸模組。 在這些情況下，建議您擁有兩個 VSIX 專案和條件式編譯。

許多延伸模組都會在 Visual Studio 2019 和 Visual Studio 2022 中運作，但不需要遵循本文中將延伸模組現代化的建議。 在 Visual Studio 2022 中試用您的延伸模組，並評估最適合延伸模組的選項。

Visual Studio 2022 是 64 位元應用程式，並在 Visual Studio SDK 中引進一些突破性變更。 本文將逐步引導您完成讓延伸模組使用目前預覽 Visual Studio 2022 所需的步驟。 然後，就可以讓使用者在 Visual Studio 2022 正式運作之前進行安裝您的延伸模組。

安裝 Visual Studio 並編譯延伸模組

從 Visual Studio 2022 下載安裝 Visual Studio 2022。

以 .NET 語言撰寫的延伸模組

以 Visual Studio 2022 為目標適用於受控延伸模組的 Visual Studio SDK 僅位於 NuGet 上：

• Microsoft.VisualStudio.Sdk (版本 17.x) 中繼套件引進了您所需的大部分或所有參考組件。
• Microsoft.VSSDK.BuildTools (版本 17.x) 套件應該從 VSIX 專案參考，以便建置符合 Visual Studio 2022 規範的 VSIX。

即使您未參考任何重大變更，延伸模組也必須使用 [任何 CPU] 或 x64 平台進行編譯。 x86 平台與 Visual Studio 2022 中的 64 位元處理程序不相容。

以 C++ 撰寫的延伸模組

一如往常，以 C++ 編譯適用於延伸模組的 Visual Studio SDK 會隨已安裝的 Visual Studio SDK 提供。

即使您未參考任何重大變更，延伸模組也必須特別針對 Visual Studio 2022 SDK 並針對 AMD64 進行編譯。

具有執行中程式碼的延伸模組

具有執行中程式碼的延伸模組必須 特別針對 Visual Studio 2022 進行編譯。 Visual Studio 2022 不會載入以舊版 Visual Studio 為目標的任何延伸模組。

了解如何將舊版 Visual Studio 的延伸模組遷移至 Visual Studio 2022：

1. 將您的專案現代化。
2. 將您的原始程式碼重構為共用專案，允許以 Visual Studio 2022 和舊版為目標。
3. 新增以 Visual Studio 2022 為目標的 VSIX 專案 和 套件/組件重新對應資料表。
4. 進行必要的程式碼調整。
5. 測試 Visual Studio 2022 延伸模組。
6. 發佈 Visual Studio 延伸模組

未含執行中程式碼的延伸模組

未包含任何執行中程式碼的延伸模組 (例如專案或項目範本)，可不用遵循上述步驟，包括產生兩個不同的 VSIX。

但請改為修改一個 VSIX，使其 source.extension.vsixmanifest 檔案宣告兩個安裝目標：

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

您可以略過本文中有關使用共用專案和多個 VSIX 的步驟。 您可以繼續測試。

注意

如果您要使用 Visual Studio 2022 撰寫 新的 Visual Studio 延伸模組，而且您也想要以 Visual Studio 2019 或舊版為目標，請參閱本指南。

MSBuild 工作

如果您撰寫 MSBuild 工作，請注意，在 Visual Studio 2022 中，可能會載入 64 位元 MSBuild.exe 處理程序。 如果您的工作需要 32 位元處理程序才能執行，請參閱設定目標和工作，確保 MSBuild 在 32 位元處理程序中載入您的工作。

將您的 VSIX 專案現代化

在將 Visual Studio 2022 支援新增至延伸模組之前，強烈建議您清除現有專案，並將其現代化：

1. 從 package.config 遷移到 PackageReference。

2. 將任何直接 Visual Studio SDK 組件參考取代為 PackageReference 項目：

   -<Reference Include="Microsoft.VisualStudio.OLE.Interop" />
   +<PackageReference Include="Microsoft.VisualStudio.OLE.Interop" Version="..." />
   

   提示

   您可以只將許多組件參考取代為中繼套件的一個PackageReference執行個體：

   -<Reference Include="Microsoft.VisualStudio.OLE.Interop" />
   -<Reference Include="Microsoft.VisualStudio.Interop" />
   -<Reference Include="Microsoft.VisualStudio.Interop.8.0" />
   +<PackageReference Include="Microsoft.VisualStudio.Sdk" Version="..." />
   

   請務必挑選符合您設為目標的最低 Visual Studio 版本的套件版本。

某些不是 Visual Studio SDK 唯一的組件 (例如 Newtonsoft.Json.dll) 可能已透過 Visual Studio 2022 之前的簡單 <Reference Include="Newtonsoft.Json" /> 參考來探索。 但在 Visual Studio 2022 中，它們反而需要套件參考。 原因是某些 Visual Studio 執行時間和 SDK 目錄已從 MSBuild 中的預設組件搜尋路徑中移除。

從直接組件參考切換至 NuGet 套件參考時，您可能會挑選其他組件參考和分析器套件，因為 NuGet 會自動安裝可轉移的結束相依性。 這通常沒問題，但在建置期間可能會產生其他警告。 請逐一查看這些警告，並儘量全部解決。 請考慮使用程式碼內 #pragma warning disable <id> 區域來隱藏您無法解決的警告。

針對多重目標使用共用專案

共用專案 是 Visual Studio 2015 中引進的專案類型。 Visual Studio 中的共用專案可讓原始程式碼檔案在多個專案之間共用，並使用條件式編譯符號和唯一的參考集以不同的方式建置。

Visual Studio 2022 需要來自所有舊版 Visual Studio 的一組不同的參考組件。 因此，我們建議您使用共用專案，以便將延伸模組廣設為 Visual Studio 2022、舊版和更新版本的目標。 這項技術可讓您共用程式碼，但提供不同的參考。

在 Visual Studio 延伸模組的內容中，您可能會有一個 Visual Studio 2022 和更新版本的 VSIX 專案，以及一個 Visual Studio 2019 和更早版本的 VSIX 專案。 每個專案只會包含 source.extension.vsixmanifest 執行個體，以及 16.x SDK 或 17.x SDK 的套件參考。 這些 VSIX 專案也會有對新的共用專案的共用專案參考，該專案會裝載可在兩個 Visual Studio 版本之間共用的所有原始程式碼。

本節假設您已經具有以 Visual Studio 2019 為目標的 VSIX 專案，而且您希望延伸模組在 Visual Studio 2022 上運作。

您可以使用 Visual Studio 2019 完成所有這些步驟：

1. 如果您尚未這麼做，請將您的專案現代化，以簡化此更新程式稍後的步驟。

2. 針對參考 Visual Studio SDK 的每個現有專案，將新的共用專案加入至您的解決方案。 以滑鼠右鍵按一下 解決方案，然後選取 [新增]> [新增專案]。

   

3. 在 [新增專案] 對話方塊中，搜尋共用專案，然後選取 [共用專案] 範本。

   

4. 將每個 Visual Studio SDK 參考專案的參考新增至其共用專案的對應項。

   

5. 將所有原始程式碼 (包括 .cs 和 .resx 檔案) 從每個 Visual Studio SDK 參考專案移至其共用專案的對應項。 讓 VSIX source.extension.vsixmanifest 檔案保持開啟。

   

6. 將中繼資料檔案 (例如版本資訊、授權和圖示) 和 VSCT 檔案移至共用目錄。 然後將這些檔案新增為 VSIX 專案的連結檔案。 請注意，共用目錄與共用專案不同。

   

   • 針對中繼資料檔案，將 [建置動作] 設定為 [內容]。 將 [包含在 VSIX] 設定為 [True]。

     

   • 針對 VSCT 檔案，將 [建置動作] 設定為 VSCTCompile。 將 [包含在 VSIX 內] 設定為 False。

     

     如果 Visual Studio 抱怨此設定不受支援，您可以藉由卸載專案並變更 Content 為 VSCTCompile 來手動變更建置動作：

     -<Content Include="..\SharedFiles\VSIXProject1Package.vsct">
     -  <Link>VSIXProject1Package.vsct</Link>
     -</Content>
     +<VSCTCompile Include="..\SharedFiles\VSIXProject1Package.vsct">
     +  <Link>VSIXProject1Package.vsct</Link>
     +  <ResourceName>Menus.ctmenu</ResourceName>
     +</VSCTCompile>
     

7. 建置您的專案以確認尚未出現任何錯誤。

您的專案現在已準備好新增 Visual Studio 2022 支援。

新增 Visual Studio 2022 目標

本節假設您已完成將 Visual Studio 延伸模組與共用專案納入考慮的步驟。

遵循下列步驟，將 Visual Studio 2022 支援新增至延伸模組。 您可以使用 Visual Studio 2019 來完成此操作。

1. 將新 VSIX 專案加入解決方案。 此專案將以 Visual Studio 2022 為目標。 拿掉範本隨附的任何原始程式碼，但保留 source.extension.vsixmanifest 檔案。

2. 在新的 VSIX 專案上，將參考新增至以 Visual Studio 2019 為目標的 VSIX 參考的相同共用專案。

   

3. 確認新 VSIX 專案已建置妥當。 您可能需要新增參考以符合原始 VSIX 專案，以解決任何編譯器錯誤。

4. 針對 Managed Visual Studio 延伸模組，請將套件參考從 16.x (或更早版本) 更新為以 Visual Studio 2022 為目標之專案檔中的 17.x 套件版本。 使用 NuGet 套件管理員或直接編輯專案檔：

   -<PackageReference Include="Microsoft.VisualStudio.SDK" Version="16.0.206" />
   +<PackageReference Include="Microsoft.VisualStudio.SDK" Version="17.0" />
   -<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="16.10.32" />
   +<PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.0" />
   

   上述程式碼中顯示的版本只是為了示範。 在您的程式碼中，使用 NuGet 網站的可用版本。

   在許多情況下，套件識別碼已變更。 如需 Visual Studio 2022 中的變更清單，請參閱 套件/組件對應表。

   以 C++ 撰寫的延伸模組還沒有可供編譯的 SDK。

5. 對於 C++ 專案，必須針對 AMD64 編譯延伸模組。 對於受控延伸模組，則考慮將專案從為 [任何 CPU] 建置變更為以 x64 為目標。 該變更可確保在 Visual Studio 2022 中您的延伸模組一律會以 64 位元處理程序載入。 任何 CPU 也沒問題，但如果您參考任何僅限 x64 的原生二進位檔，可能會出現警告。

   延伸模組在原生模組上可能擁有的任何相依性都必須從 x86 映像更新為 AMD64 映像。

6. 編輯 source.extension.vsixmanifest 檔案，以反映以 Visual Studio 2022 為目標。 設定 <InstallationTarget> 旗標以指明 Visual Studio 2022。 設定 ProductArchitecture 元素以指明 AMD64 裝載。

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

   重要

   在 Visual Studio 2019 中，此檔案的設計工具不會公開新的 ProductArchitecture 元素。 您必須使用 XML 編輯器進行這項變更。 若要存取 XML 編輯器，請移至 [方案總管]，然後選取 [開啟方式] 命令。

   ProductArchitecture 元素很重要。 Visual Studio 2022 不會在缺少該元素的情況下安裝您的延伸模組。

   元素	值	Description
   ProductArchitecture	x86, amd64	這個 VSIX 支援的平台。 不區分大小寫。 每個元素使用一個平台，而且每個 InstallationTarget 執行個體一個元素。 對於小於 17.0 的產品版本，預設值為 x86 ，而且可以省略。 對於產品 17.0 版和更新版本，此元素是必要項，而且沒有預設值。 對於 Visual Studio 2022，這個元素的唯一有效內容是 amd64。

7. 在 source.extension.vsixmanifest 中，進行任何必要的調整，以符合以 Visual Studio 2019 為目標的調整 (如果有)。

   如果您要發行兩個以不同 Visual Studio 版本為目標的延伸模組，請確定資訊清單 Identity元素中的 VSIX 識別碼對於每個延伸模組都不同。

此時，您有 Visual Studio 2022 目標延伸模組 VSIX。 您應該建置以 Visual Studio 2022 為目標的 VSIX 專案，並處理任何出現的建置斷點。 如果您在以 Visual Studio 2022 為目標的 VSIX 專案中沒有建置斷點，恭喜您！ 您已做好測試準備。

處理重大 API 變更

重大 API 變更可能需要更新在舊版 Visual Studio 上執行的程式碼。 如需如何更新程式碼的秘訣，請參閱 Visual Studio 2022 中的重大 API 變更。

當您調整程式碼時，建議您使用條件式編譯。 接著，您的程式碼可以繼續支援舊版 Visual Studio，同時新增 Visual Studio 2022 的支援。

當您取得以 Visual Studio 2022 為目標的延伸模組建置時，請繼續進行測試。

使用條件式編譯符號

如果要針對 Visual Studio 2022 和舊版使用相同的原始程式碼，即使是相同的檔案，您可能需要使用條件式編譯。 然後，您可以分叉程式碼以適應重大變更。 條件式編譯是 C#、Visual Basic 和 C++ 語言的功能。 它可以用來共用大部分的程式碼，同時容納特定位置的不同 API。

如需使用前置處理器指示詞和條件式編譯符號的詳細資訊，請參閱 C# 前置處理器指示詞。

以舊版 Visual Studio 為目標的專案需要條件式編譯符號。 然後，這個符號可以用來分叉程式碼，以使用不同的 API。 您可以在專案屬性頁面上設定條件式編譯符號：

請務必設定 [所有設定] 的編譯符號。 根據預設，您輸入的符號可能只套用於一個組態。

C# 技術

您可以使用編譯符號做為前置處理器指示詞 (#if)，如下列程式碼所示。 然後，您可以分叉程式碼來處理 Visual Studio 版本之間的重大變更。

    Guid myGuid = new Guid("{633FBA02-719B-40E7-96BF-0899767CD104}");
    uint myFlags = 0;
    IVsShell shell = await AsyncServiceProvider.GlobalProvider.GetServiceAsync<SVsShell, IVsShell>();
#if Dev16
    shell.LoadUILibrary(myGuid, myFlags, out uint ptrLib);
#else
    shell.LoadUILibrary(myGuid, myFlags, out IntPtr ptrLib);
#endif

在某些情況下，您可以使用 var 來避免命名類型，並避免對 #if 區域的需要。 前置程式碼片段也可以寫成：

    Guid myGuid = new Guid("{633FBA02-719B-40E7-96BF-0899767CD104}");
    uint myFlags = 0;
    IVsShell shell = await AsyncServiceProvider.GlobalProvider.GetServiceAsync<SVsShell, IVsShell>();
    shell.LoadUILibrary(myGuid, myFlags, out var ptrLib);

當使用 #if 語法時，請注意如何使用語言服務內容的下拉式清單來變更語法醒目提示。 另一個下拉式清單可協助語言服務將此延伸模組的目標 Visual Studio 版本，放在另一個目標 Visual Studio 版本上。

XAML 共用技術

XAML 沒有前置處理器可允許根據前置處理器符號自訂內容。 您可能需要複製並維護兩個 XAML 頁面，其內容在 Visual Studio 2022 和舊版之間有所差異。

在某些情況下，在 Visual Studio 2022 和舊版的不同組件中存在類型參考，可能仍可在一個 XAML 檔案中表示。 移除參考組件的命名空間：

-xmlns:vsui="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.14.0"
-Value="{DynamicResource {x:Static vsui:TreeViewColors.SelectedItemActiveBrushKey}}"
+Value="{DynamicResource TreeViewColors.SelectedItemActiveBrushKey}"

測試您的延伸模組

若要測試以 Visual Studio 2022 為目標的延伸模組，您必須安裝 Visual Studio 2022。 您無法在舊版 Visual Studio 上執行 64 位元延伸模組。

您可以使用 Visual Studio 2022 來建置及測試延伸模組，不論其是否以 Visual Studio 2022 或舊版為目標。 當您從 Visual Studio 2022 開啟 VSIX 專案時，會開啟 Visual Studio 的實驗執行個體。

強烈建議您使用您想要延伸模組支援的每個 Visual Studio 版本進行測試。

發佈延伸模組

您已將 Visual Studio 2022 目標新增至延伸模組，並進行測試。 現在您已準備好發佈延伸模組供世界使用。

Visual Studio Marketplace

將您的延伸模組發佈至 Visual Studio Marketplace，是讓新使用者尋找並安裝延伸模組的絕佳方式。 無論您的延伸模組是以Visual Studio 2022 獨佔為目標，還是以舊版 Visual Studio 為目標，Marketplace 都會提供支援給您。

以後 Marketplace 可讓您將多個 VSIX 上傳至一個 Marketplace 清單。 然後，您可以上傳以 Visual Studio 2022 為目標的 VSIX 和舊版 Visual Studio 的 VSIX。 當使用者使用 Visual Studio 延伸模組管理員時，使用者會自動取得他們安裝之 Visual Studio 版本的正確 VSIX。

自訂安裝程式

如果您建置 MSI 或 EXE 檔案來安裝您的延伸模組，並繁衍 vsixinstaller.exe 以安裝您的延伸模組 (一部分)，請了解 Visual Studio 2022 中的 VSIX 安裝程式已更新。 開發人員必須使用 Visual Studio 2022 隨附的 VSIX 安裝程式版本，將延伸模組安裝至該版本的 Visual Studio。

Visual Studio 2022 中的 VSIX 安裝程式也安裝適用的延伸模組，以相同電腦上 Visual Studio 2022 中存在的舊版 Visual Studio 為目標。

網路共用

您可以透過 LAN 或任何其他方式共用延伸模組。 如果您以 Visual Studio 2022 和舊版為目標，則需要個別共用多個 VSIX。 提供檔名 (或將它們放在唯一資料夾中)，以協助使用者知道根據他們安裝的 Visual Studio 版本安裝哪些 VSIX。

相依性

如果您的 VSIX 透過 <dependency> 元素將其他 VSIX 指定為相依性，則每個參考的 VSIX 都必須安裝在與 VSIX 相同的目標和產品架構中。 如果相依 VSIX 不支援以 Visual Studio 為目標的安裝，VSIX 將會失敗。

相依之 VSIX 支援的目標和架構比您多，但不能少於您的目標和架構。 這項限制表示，具有相依性的 VSIX 部署和散發方法應該鏡像其相依專案。

問與答

問題：我的延伸模組不需要任何互操作性變更，因為它只會提供資料 (例如範本)。 我可以建立同時包含 Visual Studio 2022 的單一延伸模組嗎？

A：：是的！ 如需相關資訊，請參閱未含執行中程式碼的延伸模組。

問題：NuGet 相依性引進舊的互操作性組件，並造成類別衝突。 我該怎麼做？

解答：將下列這一行新增至 .csproj 檔案，以避免重複的組件：

    <PackageReference Include="<Name of offending assembly>" ExcludeAssets="compile" PrivateAssets="all" />

此程式碼會防止套件參考從其他相依性匯入舊版的組件。

問題：將來源檔案切換至共用專案後，我的命令和快速鍵已停止在 Visual Studio 中運作。 我該怎麼做？

解答：影像最佳化工具範例的步驟 2.4 展示如何將 VSCT 檔案新增為連結的項目，以將其編譯到 VSCT 檔案中。

相關內容

逐步遵循範例 ImageOptimizer ，其中包含每個步驟的專案和程式碼變更的連結。