尋找及使用 MSBuild 版本

2025-06-12

若要確保從應用程式的程式設計組建符合在 Visual Studio 或 MSBuild.exe內完成的組建，您可能需要載入與特定 Visual Studio 版本一起安裝的相同 MSBuild 元件版本，並使用該版本 Visual Studio 內可用的相同 SDK。或者，當您建立將在可能已安裝各種 MSBuild、.NET 和 Visual Studio 版本的機器上執行的組建應用程式時，您可能也想要尋找並使用一致的 MSBuild 版本。 Microsoft.Build.Locator API 可簡化此程式。

使用 Microsoft.Build.Locator

Microsoft.Build.Locator 套件與應用程式在用戶端電腦、虛擬機或容器內執行的情況有關，無論是在已安裝 Visual Studio 的環境中，還是只安裝 .NET SDK 的環境中，例如當使用 dotnet build 命令行要求組建時。在任何情況下，您的應用程式都需要尋找所需的 MSBuild 版本。該版本的 MSBuild 可以是符合 Visual Studio、MSBuild.exe或 dotnet build的版本，或特定的一致版本，不論應用程式可能使用環境中的各種計算機組態為何。

警告

Microsoft.Build.Locator 套件包含 .NET Framework 和 .NET Core 的元件（也適用於 .NET 5 和更新版本）。在 .NET Framework 應用程式中，會使用 Microsoft.Build.Locator 的 .NET Framework 版本，並在 .NET Core 應用程式中使用 .NET Core 版本。不過，.NET Core 版本只能尋找使用 .NET Core 建置的 MSBuild 實例、.NET SDK 安裝中 dotnet.exe 所使用的 MSBuild，而不是 Visual Studio 安裝或 Visual Studio 建置工具安裝。 Microsoft.Build.Locator 的 .NET Framework 版本只能看到 Visual Studio 安裝、Visual Studio Build Tools 安裝，而不是 .NET SDK 安裝。因此，您可能需要在兩個不同的目標架構組態中建置工具，以兩者為目標。

如果您使用應用重新發佈 Microsoft.Build.Locator.dll，則不需要發佈其他 MSBuild 元件。

使用定位器 API 需要專案中的一些變更，如下所述。若要查看更新專案所需的變更範例，請參閱 MSBuildLocator 存放庫中對範例專案所做的提交記錄。

變更 MSBuild 引用

若要確保 MSBuild 從中央位置載入，您不得將其元件與應用程式一起分發。

變更專案以避免從中央位置載入 MSBuild 的機制取決於您參考 MSBuild 的方式。

使用 NuGet 套件（推薦）

這些指示假設您使用 PackageReference 樣式的 NuGet 參考。

將您的專案檔案變更為引用來自其 NuGet 套件的 MSBuild 元件。指定 ExcludeAssets=runtime，告訴 NuGet 只有在建置時才需要這些元件，且不要複製到輸出目錄中。

MSBuild 套件的主要和次要版本必須小於或等於您想要支援的 Visual Studio 最低版本。例如，如果您想要支援 Visual Studio 2017 和更新版本，請參考套件版本 15.1.548。

例如，您可以使用這個 XML：

<ItemGroup>
  <PackageReference Include="Microsoft.Build" Version="15.1.548" ExcludeAssets="runtime" />
  <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.1.548" ExcludeAssets="runtime" />
</ItemGroup>

使用延伸模組元件

如果您無法使用 NuGet 套件，您可以參考隨 Visual Studio 散發的 MSBuild 元件。如果您直接參考 MSBuild，請將 Copy Local 設定為 False，以確保它不會複製到輸出目錄。在項目檔中，此設定類似於下列程式代碼：

    <Reference Include="Microsoft.Build, Version=15.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
      <Private>False</Private>
    </Reference>

注意

如果您要從 15 之前的 MSBuild 版本進行更新，MSBuild 需要特定元件的系結重新導向（Microsoft.Build 元件），但如果您參考 Microsoft.Build.Locator 套件，您可確保應用程式會自動使用必要的系結重新導向至 15.1.0.0 版。系結會重新導向至此版本支援 MSBuild 15.x、16.x 和 17.x。

確定輸出是乾淨的

建置您的專案並檢查輸出目錄，以確定它不包含 Microsoft.Build.Locator.dll以外的任何 Microsoft.Build.*.dll 元件，在下一個步驟中新增。

新增 Microsoft.Build.Locator 的套件參考

新增 Microsoft.Build.Locator的 NuGet 套件參考。

    <PackageReference Include="Microsoft.Build.Locator">
      <Version>1.1.2</Version>
    </PackageReference>

請勿為 Microsoft.Build.Locator 套件指定 ExcludeAssets=runtime。

呼叫 MSBuild 之前先註冊實例

當您建立組建應用程式以供一般使用時，您不知道應用程式執行的計算機可能會安裝哪些版本的 Visual Studio、.NET 和 MSBuild。 MSBuildLocator 的目的是要尋找適當的 MSBuild 安裝，以在具有各種安裝環境的電腦上使用。 MSBuildLocator 可讓您指定一些邏輯來判斷要使用的 MSBuild，但身為應用程式的開發人員需要判斷它所需的 MSBuild 版本或可接受的版本，或者為使用者指定版本提供一種方式，並包含邏輯，將該選擇轉譯為 MSBuildLocator API 的適當呼叫。

將呼叫新增至定位器 API 的最簡單方法是在應用程式啟動程式代碼中新增對 MSBuildLocator.RegisterInstance 的呼叫。其中一個範例是挑選最新版本，如下所示，但您的應用程式可能有自己的需求。

您無法在呼叫 MSBuildLocator 的方法中參考任何 MSBuild 類型（來自 Microsoft.Build 命名空間）。例如，您無法使用如下的程式代碼：

void ThisWillFail()
{
    // Register the most recent version of MSBuild
    RegisterInstance(MSBuildLocator.QueryVisualStudioInstances().OrderByDescending(
       instance => instance.Version).First());
    Project p = new Project(SomePath); // Could be any MSBuild type
    // Code that uses the MSBuild type
}

請改為撰寫如下的程式代碼：

void MethodThatDoesNotDirectlyCallMSBuild()
{
    var instance = ... // select which of the installed instances to use
    
    // Register a specific instance of MSBuild
    MSBuildLocator.RegisterInstance(instance);
    MethodThatCallsMSBuild();
}

void MethodThatCallsMSBuild()
{
    Project p = new Project(SomePath);
    // Code that uses the MSBuild type
}

若要指定 MSBuild 實例，您可以使用所需的自定義邏輯，選擇 MSBuildLocator.QueryVisualStudioInstances 的結果並傳遞至 MSBuildLocator.RegisterInstance。

藉由參閱 MSBuild API 參考資料，瞭解 MSBuild API：

共用方式為