共用方式為


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.exeTlbImp.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 類別的方法,即可以程式設計方式判定工具組。 該類別包括下列方法: