更新 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 for Managed 延伸模組為目標的 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 for extensions，與已安裝的 Visual Studio SDK 一樣可供使用。

即使您未參考任何重大變更，擴充功能也必須特別針對Visual Studio 2022 SDK 和 AMD64 編譯。

具有運行代碼的擴充功能

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

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

將項目現代化。
將原始程式碼重構為共用專案，以允許以Visual Studio 2022和舊版為目標。
新增 Visual Studio 2022 目標 VSIX 專案和套件/元件重新對應數據表。
進行必要的程式代碼調整。
測試 Visual Studio 2022 擴充功能。
發佈 Visual Studio 2022 擴充功能。

沒有執行程式代碼的延伸模組

不包含任何執行中程式代碼的延伸模組（例如專案或專案範本）不需要 遵循上述步驟，包括產生兩個不同的 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支援新增至延伸模組之前，強烈建議您清除現有專案並將其現代化：

從 packages.config 移轉至 PackageReference。

使用 PackageReference 項目取代任何直接的 Visual Studio SDK 元件參考：

-<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 2022 之前，某些不是 Visual Studio SDK 獨有的組件（例如，Newtonsoft.Json.dll），可能可以透過簡單的 <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 完成所有這些步驟：

如果您尚未這麼做，將您的專案現代化，以簡化此更新過程中後續的步驟。
針對參考 Visual Studio SDK 的每個現有專案，將新的共用專案新增至您的方案。以滑鼠右鍵按下方案，然後選取 新增專案>。
在 [[新增專案] 對話框中，搜尋 共用專案，然後選取 [共用專案] 範本。
將每個 Visual Studio SDK 參考項目的參考新增至其共用專案對應專案。
將所有原始程式碼（包括 .cs 和 .resx 檔案）從每個 Visual Studio SDK 參考專案移至其共用專案對應專案。將 source.extension.vsixmanifest 檔案保留在 VSIX 專案中。
將元數據檔案（例如版本資訊、授權和圖示）和 VSCT 檔案移至共享目錄。然後將它們新增為 VSIX 專案的連結檔案。請注意，共用目錄與共享專案不同。
- 針對元資料檔案，將 [建置動作] 設定為 [內容]。將 VSIX 中的 Include 設定為 true 。
- 針對 VSCT 檔案，將 [建置動作] 設定為 VSCTCompile。在 VSIX 中將 Include 設定為 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>
```
建置您的項目以確認您尚未引入任何錯誤。

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

新增 Visual Studio 2022 目標

本節假設您已完成將 Visual Studio 擴充功能與共用專案重構的步驟。

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

將新的 VSIX 專案新增至您的方案。此項目的目標為Visual Studio 2022。拿掉範本隨附的任何原始程式碼，但保留 source.extension.vsixmanifest 檔案。
在您的新 VSIX 專案中，新增一個參考至與您的 Visual Studio 2019 目標 VSIX 所參考的相同共享專案。
確認新的 VSIX 專案已正確建置。您可能需要新增參考以符合原始 VSIX 專案，以解決任何編譯程序錯誤。
針對 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。
針對C++專案，必須針對 AMD64 編譯延伸模組。針對受控延伸模組，請考慮將專案從建置為 任何 CPU 轉換為以 x64為目標。該變更可確保在 Visual Studio 2022 中，您的延伸模組一律會在 64 位進程中載入。 任何 CPU 也沒問題，但如果您參考任何僅限 x64 的原生二進位檔，可能會產生警告。

擴充功能中可能依賴的任何原生模組必須從 x86 映像更新為 AMD64 映像。

編輯您的 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 不會安裝您的延伸模組。

元素	價值	描述
`ProductArchitecture`	`x86`、`amd64`	這個 VSIX 支援的平臺。不區分大小寫。使用一個平台對應每個元素，並為每個 `InstallationTarget` 實例對應一個元素。對於小於 17.0 的產品版本，預設值為 `x86`，而且可以省略。針對產品 17.0 版和更新版本，此元素是必要的，而且沒有預設值。針對 Visual Studio 2022，此元素的唯一有效內容是 `amd64`。

在 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 版本，而不是其他版本。

顯示共用專案中條件式編譯的螢幕快照。

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 部署和散發方法應該反映其依賴項的方式。

問與答

Q：我的延伸模組不需要任何互作性變更，因為它只會提供數據（例如範本）。我可以建立同時包含 Visual Studio 2022 的單一延伸模組嗎？

A：是！如需相關資訊，請參閱未運行代碼的擴充功能。

Q：NuGet 相依性引進舊的互操作性組件，導致類別衝突。我該怎麼做？

A：將下列這一行新增至 .csproj 檔案，以避免元件重複：

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

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

Q：將原始程式檔切換至共用項目之後，我的命令和快捷鍵已停止在 Visual Studio 中運作。我該怎麼做？

：影像優化器範例的步驟 2.4 示範如何將 VSCT 檔案新增為連結項目，以便將它們編譯到您的 VSCT 檔案中。

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

Last updated on 2025-03-08

共用方式為