MSBuild Toolset (ToolsVersion)

  • 發行項

MSBuild 工具組包括 microsoft.common.tasks 檔案、microsoft.common.targets 檔案和編譯器，例如 csc.exe 和 vbc.exe。 大部分的工具組都可用來將應用程式編譯為多個版本的 .NET Framework 和多個系統平台。 不過，MSBuild 2.0 工具組僅能以 .NET Framework 2.0 為使用目標。

Visual Studio 2019 和更新版本中，Visual Studio 2019 和 MSBuild 專案檔中 Project 元素上的 MSBuild ToolsVersion 屬性會被視為過時；您可以安全地刪除它。 本文說明其在舊版 MSBuild 中或自訂工具組的使用。 請參閱標準和自訂工具組的設定。

ToolsVersion 屬性

在專案檔之 Project 項目的 ToolsVersion 屬性中指定工具組。 下列範例會指定應該使用 MSBuild "Current" 工具組來建置專案。

<Project ToolsVersion="Current" ... </Project>

注意

某些專案類型會使用 sdk 屬性，而非 ToolsVersion 屬性。 如需詳細資訊，請參閱.NET Core 的 csproj 格式新增。

ToolsVersion 屬性如何運作

當您在 Visual Studio 中建立專案，或者升級現有專案時，名為 ToolsVersion 的屬性會自動併入專案檔，且其值會對應至 Visual Studio 版本中所包含的 MSBuild 版本。 如需詳細資訊，請參閱 Framework 目標概觀。

當在專案檔中定義 ToolsVersion 值時，MSBuild 會使用該值來判定可用於該專案的工具組屬性值。 一個工具組屬性為 $(MSBuildToolsPath)，它會指定 .NET Framework 工具的路徑。 僅需要該工具組屬性 (或 $(MSBuildBinPath))。

從 Visual Studio 2013 開始，MSBuild 工具組版本就與 Visual Studio 版本號碼相同。 MSBuild 預設為 Visual Studio 中的這個工具組，且位於命令列上，與專案檔中指定的工具組版本無關。 您可以使用 -ToolsVersion 旗標覆寫此行為。 如需詳細資訊，請參閱覆寫 ToolsVersion 設定。

在下列範例中，MSBuild 會使用 MSBuildToolsPath 保留屬性，尋找 Microsoft.CSharp.targets 檔案。

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

透過定義自訂工具組，您就可以修改 MSBuildToolsPath 的值。 如需詳細資訊，請參閱標準和自訂工具組的組態。

當您在命令列上建置方案並針對 msbuild.exe 指定 ToolsVersion 時，所有專案及其專案對專案相依性都會根據該 ToolsVersion 建置，即使方案中的每個專案都指定其自己的 ToolsVersion 也是如此。 若要根據專案來定義 ToolsVersion 值，請參閱覆寫 ToolsVersion 設定。

ToolsVersion 屬性也用於專案移轉。 例如，如果您在 Visual Studio 2010 中開啟 Visual Studio 2008 專案，則會上傳專案檔，以包括 ToolsVersion="4.0"。 如果您隨後嘗試在 Visual Studio 2008 中開啟該專案，它不會識別已升級的 ToolsVersion，因此會像該屬性仍設為 3.5 那樣建置專案。

Visual Studio 2010 和 Visual Studio 2012 使用 4.0 的 ToolsVersion。 Visual Studio 2013 使用 12.0 的 ToolsVersion。 Visual Studio 2015 使用 ToolsVersion 14.0，而 Visual Studio 2017 使用 ToolsVersion 15.0。 在許多情況下，專案無需修改，即可在多種版本的 Visual Studio 中開啟。 Visual Studio 一律使用正確的工具組，但是如果所使用的版本與專案檔中的版本不符的話，您會收到通知。 幾乎在所有的情況下，此警告都是良性的，因為工具組在大部分情況下都相容。

子工具組 (將在本主題稍後說明) 可讓 MSBuild 根據執行建置的內容，自動切換要使用的工具組。 例如，MSBuild 在 Visual Studio 2012 中執行時使用的工具組，比在 Visual Studio 2010 中執行時更新，您不需要明確變更專案檔。

工具組實作

選取組成工具組的各種工具、目標和工作的路徑，即可實作工具組。 MSBuild 所定義之工具組中的工具來自下列來源：

  • .NET Framework 資料夾。

  • 其他 Managed 工具。

    Managed 工具包括 ResGen.exe 和 TlbImp.exe。

MSBuild 會提供兩種方法來存取工具組：

工具組屬性會指定工具的路徑。 自 Visual Studio 2017 起，MSBuild 不再具有固定位置。 根據預設，其位於相對於 Visual Studio 安裝位置的 MSBuild\15.0\Bin 資料夾。 在先前的版本中，MSBuild 會使用專案檔中的 ToolsVersion 屬性值來尋找對應的登錄機碼，然後使用登錄機碼中的資訊設定工具組屬性。 例如，如果 ToolsVersion 的值為 12.0，MSBuild 會根據以下登錄機碼設定工具組屬性：HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0。

以下為工具組屬性：

  • MSBuildToolsPath 會指定 MSBuild 二進位檔的路徑。

  • SDK40ToolsPath 會指定 MSBuild 4.x (可能是 4.0 或 4.5) 之其他 Managed 工具的路徑。

  • SDK35ToolsPath 會指定 MSBuild 3.5 之其他 Managed 工具的路徑。

或者，您可以呼叫 ToolLocationHelper 類別的方法，即可以程式設計方式判定工具組。 該類別包括下列方法：

相關內容