MSBuild Toolset (ToolsVersion)MSBuild Toolset (ToolsVersion)

MSBuild 使用工作、目標和工具的工具組建置應用程式。MSBuild uses a Toolset of tasks, targets, and tools to build an application. 一般而言,MSBuild 工具組包括 microsoft.common.tasks 檔案、microsoft.common.targets 檔案和編譯器,例如 csc.exevbc.exeTypically, a MSBuild Toolset includes a microsoft.common.tasks file, a microsoft.common.targets file, and compilers such as csc.exe and vbc.exe. 大部分的工具組都可用來將應用程式編譯為多個版本的 .NET Framework 和多個系統平台。Most Toolsets can be used to compile applications to more than one version of the .NET Framework and more than one system platform. 不過,MSBuild 2.0 工具組僅能以 .NET Framework 2.0 為使用目標。However, the MSBuild 2.0 Toolset can be used to target only the .NET Framework 2.0.

ToolsVersion 屬性ToolsVersion attribute

在專案檔之 Project 項目的 ToolsVersion 屬性中指定工具組。Specify the Toolset in the ToolsVersion attribute on the Project element in the project file. 下列範例會指定應該使用 MSBuild "Current" 工具組來建置專案。The following example specifies that the project should be built by using the MSBuild "Current" Toolset.

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

在專案檔之 Project 項目的 ToolsVersion 屬性中指定工具組。Specify the Toolset in the ToolsVersion attribute on the Project element in the project file. 下列範例會指定應該使用 MSBuild 15.0 工具組組建專案。The following example specifies that the project should be built by using the MSBuild 15.0 Toolset.

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

Note

某些專案類型會使用 sdk 屬性,而非 ToolsVersion 屬性。Some project types use the sdk attribute instead of ToolsVersion. 如需詳細資訊,請參閱套件、中繼資料和架構,以及適用於 .NET Core 之 csproj 格式的新增項目For more information, see Packages, metadata, and frameworks and Additions to the csproj format for .NET Core.

ToolsVersion 屬性如何運作How the ToolsVersion attribute works

當您在 Visual Studio 中建立專案,或者升級現有專案時,名為 ToolsVersion 的屬性會自動併入專案檔,且其值會對應至 Visual Studio 版本中所包含的 MSBuild 版本。When you create a project in Visual Studio, or upgrade an existing project, an attribute named ToolsVersion is automatically included in the project file and its value corresponds to the version of MSBuild that is included in the Visual Studio edition. 如需詳細資訊,請參閱 Framework 目標概觀For more information, see Framework targeting overview.

當在專案檔中定義 ToolsVersion 值時,MSBuild 會使用該值來判定可用於該專案的工具組屬性值。When a ToolsVersion value is defined in a project file, MSBuild uses that value to determine the values of the Toolset properties that are available to the project. 一個工具組屬性為 $(MSBuildToolsPath),它會指定 .NET Framework 工具的路徑。One Toolset property is $(MSBuildToolsPath), which specifies the path of the .NET Framework tools. 僅需要該工具組屬性 (或 $(MSBuildBinPath))。Only that Toolset property (or $(MSBuildBinPath)), is required.

從 Visual Studio 2013 開始,MSBuild 工具組版本就與 Visual Studio 版本號碼相同。Starting in Visual Studio 2013, the MSBuild Toolset version is the same as the Visual Studio version number. MSBuild 預設為 Visual Studio 中的這個工具組,且位於命令列上,與專案檔中指定的工具組版本無關。MSBuild defaults to this Toolset within Visual Studio and on the command line, regardless of the Toolset version specified in the project file. 您可以使用 -ToolsVersion 旗標覆寫此行為。This behavior can be overridden by using the -ToolsVersion flag. 如需詳細資訊,請參閱覆寫 ToolsVersion 設定For more information, see Override ToolsVersion settings.

在下列範例中,MSBuild 會使用 MSBuildToolsPath 保留屬性,尋找 Microsoft.CSharp.targets 檔案。In the following example, MSBuild finds the Microsoft.CSharp.targets file by using the MSBuildToolsPath reserved property.

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

透過定義自訂工具組,您就可以修改 MSBuildToolsPath 的值。You can modify the value of MSBuildToolsPath by defining a custom Toolset. 如需詳細資訊,請參閱標準和自訂工具組的組態For more information, see Standard and custom Toolset configurations.

當您在命令列上建置方案並針對 msbuild.exe 指定 ToolsVersion 時,所有專案及其專案對專案相依性都會根據該 ToolsVersion 建置,即使方案中的每個專案都指定其自己的 ToolsVersion 也是如此。When you build a solution on the command line and specify a ToolsVersion for msbuild.exe, all projects and their project-to-project dependencies are built according to that ToolsVersion, even if each project in the solution specifies its own ToolsVersion. 若要根據專案來定義 ToolsVersion 值,請參閱覆寫 ToolsVersion 設定To define the ToolsVersion value on a per project basis, see Overriding ToolsVersion settings.

ToolsVersion 屬性也用於專案移轉。The ToolsVersion attribute is also used for project migration. 例如,如果您在 Visual Studio 2010 中開啟 Visual Studio 2008 專案,則會上傳專案檔,以包括 ToolsVersion="4.0"。For example, if you open a Visual Studio 2008 project in Visual Studio 2010, the project file is updated to include ToolsVersion="4.0". 如果您隨後嘗試在 Visual Studio 2008 中開啟該專案,它不會識別已升級的 ToolsVersion,因此會像該屬性仍設為 3.5 那樣建置專案。If you then try to open that project in Visual Studio 2008, it doesn't recognize the upgraded ToolsVersion and therefore builds the project as though the attribute was still set to 3.5.

Visual Studio 2010 和 Visual Studio 2012 使用 4.0 的 ToolsVersion。Visual Studio 2010 and Visual Studio 2012 use a ToolsVersion of 4.0. Visual Studio 2013 使用 12.0 的 ToolsVersion。Visual Studio 2013 uses a ToolsVersion of 12.0. Visual Studio 2015 使用 ToolsVersion 14.0,而 Visual Studio 2017 使用 ToolsVersion 15.0。Visual Studio 2015 uses ToolsVersion 14.0, and Visual Studio 2017 uses ToolsVersion 15.0. 在許多情況下,專案無需修改,即可在多種版本的 Visual Studio 中開啟。In many cases, you can open the project in multiple versions of Visual Studio without modification. Visual Studio 一律使用正確的工具組,但是如果所使用的版本與專案檔中的版本不符的話,您會收到通知。Visual Studio always uses the correct Toolset, but you will be notified if the version used does not match the version in the project file. 幾乎在所有的情況下,此警告都是良性的,因為工具組在大部分情況下都相容。In almost all cases, this warning is benign as the Toolsets are compatible in most cases.

子工具組 (將在本主題稍後說明) 可讓 MSBuild 根據執行建置的內容,自動切換要使用的工具組。Sub-toolsets, which are described later in this topic, allow MSBuild to automatically switch which set of tools to use based on the context in which the build is being run. 例如,MSBuild 在 Visual Studio 2012 中執行時使用的工具組,比在 Visual Studio 2010 中執行時更新,您不需要明確變更專案檔。For example, MSBuild uses a newer set of tools when it's run in Visual Studio 2012 than when it's run in Visual Studio 2010, without your having to explicitly change the project file.

工具組實作Toolset implementation

選取組成工具組的各種工具、目標和工作的路徑,即可實作工具組。Implement a Toolset by selecting the paths of the various tools, targets, and tasks that make up the Toolset. MSBuild 所定義之工具組中的工具來自下列來源:The tools in the Toolset that MSBuild defines come from the following sources:

  • .NET Framework 資料夾。The .NET Framework folder.

  • 其他 Managed 工具。Additional managed tools.

    Managed 工具包括 ResGen.exeTlbImp.exeThe managed tools include ResGen.exe and TlbImp.exe.

MSBuild 會提供兩種方法來存取工具組:MSBuild provides two ways to access the Toolset:

工具組屬性會指定工具的路徑。Toolset properties specify the paths of the tools. 自 Visual Studio 2017 起,MSBuild 不再具有固定位置。Starting in Visual Studio 2017, MSBuild no longer has a fixed location. 根據預設,其位於相對於 Visual Studio 安裝位置的 MSBuild\15.0\Bin 資料夾。By default, it is located in the MSBuild\15.0\Bin folder relative to the Visual Studio installation location. 在先前的版本中,MSBuild 會使用專案檔中的 ToolsVersion 屬性值來尋找對應的登錄機碼,然後使用登錄機碼中的資訊設定工具組屬性。In earlier versions, MSBuild uses the value of the ToolsVersion attribute in the project file to locate the corresponding registry key, and then uses the information in the registry key to set the Toolset properties. 例如,如果 ToolsVersion 的值為 12.0,MSBuild 會根據以下登錄機碼設定工具組屬性:HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0For example, if ToolsVersion has the value 12.0, then MSBuild sets the Toolset properties according to this registry key: HKLM\Software\Microsoft\MSBuild\ToolsVersions\12.0.

以下為工具組屬性:These are Toolset properties:

  • MSBuildToolsPath 會指定 MSBuild 二進位檔的路徑。MSBuildToolsPath specifies the path of the MSBuild binaries.

  • SDK40ToolsPath 會指定 MSBuild 4.x (可能是 4.0 或 4.5) 之其他 Managed 工具的路徑。SDK40ToolsPath specifies the path of additional managed tools for MSBuild 4.x (which could be 4.0 or 4.5).

  • SDK35ToolsPath 會指定 MSBuild 3.5 之其他 Managed 工具的路徑。SDK35ToolsPath specifies the path of additional managed tools for MSBuild 3.5.

或者,您可以呼叫 ToolLocationHelper 類別的方法,即可以程式設計方式判定工具組。Alternately, you can determine the Toolset programmatically by calling the methods of the ToolLocationHelper class. 該類別包括下列方法:The class includes these methods:

子工具組Sub-toolsets

若為 15.0 之前的 MSBuild 版本,MSBuild 會使用登錄機碼來指定基本工具的路徑。For versions MSBuild prior to 15.0, MSBuild uses a registry key to specify the path of the basic tools. 如果機碼具有子機碼,MSBuild 會使用它指定包含其他工具之子工具組的路徑。If the key has a subkey, MSBuild uses it to specify the path of a sub-toolset that contains additional tools. 在此情況下,該工具組的定義方式為組合在兩個機碼中定義的屬性定義。In this case, the Toolset is defined by combining the property definitions that are defined in both keys.

Note

如果工具組屬性名稱衝突,為子機碼路徑定義的值會覆寫為根機碼路徑定義的值。If Toolset property names collide, the value that's defined for the subkey path overrides the value that's defined for the root key path.

如果 VisualStudioVersion 建置屬性存在,子工具組會變為使用中。Sub-toolsets become active in the presence of the VisualStudioVersion build property. 此屬性會採用下列其中一個值:This property may take one of these values:

  • "10.0" 會指定 .NET Framework 4 子工具組"10.0" specifies the .NET Framework 4 sub-toolset

  • "11.0" 會指定 .NET Framework 4.5 子工具組"11.0" specifies the .NET Framework 4.5 sub-toolset

  • "12.0" 會指定 .NET Framework 4.5.1 子工具組"12.0" specifies the .NET Framework 4.5.1 sub-toolset

子工具組 10.0 和 11.0 應該與 ToolsVersion 4.0 搭配使用。Sub-toolsets 10.0 and 11.0 should be used with ToolsVersion 4.0. 在更新的版本中,子工具組版本應該與 ToolsVersion 相符。In later versions, the sub-toolset version and the ToolsVersion should match.

在建置期間,MSBuild 會自動判定並設定 VisualStudioVersion 屬性的預設值 (如果尚未定義的話)。During a build, MSBuild automatically determines and sets a default value for the VisualStudioVersion property if it's not already defined.

MSBuild 會提供 ToolLocationHelper 方法的多載,這些方法可加入 VisualStudioVersion 列舉值做為參數MSBuild provides overloads for the ToolLocationHelper methods that add a VisualStudioVersion enumerated value as a parameter

子工具組已引進 .NET Framework 4.5。Sub-toolsets were introduced in the .NET Framework 4.5.

另請參閱See also