標準和自訂工具組的設定Standard and custom Toolset configurations

MSBuild 工具組包含工作、目標和工具的參考,可用以組建應用程式專案。An MSBuild Toolset contains references to tasks, targets, and tools that you can use to build an application project. MSBuild 包含標準的工具組,但您也可以建立自訂工具組。MSBuild includes a standard Toolset, but you can also create custom Toolsets. 如需如何指定工具組的相關資訊,請參閱工具組 (ToolsVersion)For information about how to specify a Toolset, see Toolset (ToolsVersion)

標準工具組設定Standard Toolset configurations

MSBuild 16.0 包含下列標準工具組:MSBuild 16.0 includes the following standard Toolsets:

ToolsVersionToolsVersion 工具組路徑 (如 MSBuildToolsPath 或 MSBuildBinPath 組建屬性中所指定)Toolset path (as specified in the MSBuildToolsPath or MSBuildBinPath build property)
2.02.0 *<Windows 安裝路徑>\Microsoft.Net\Framework\v2.0.50727\*<Windows installation path>\Microsoft.Net\Framework\v2.0.50727\
3.53.5 <Windows 安裝路徑>\Microsoft.NET\Framework\v3.5\<Windows installation path>\Microsoft.NET\Framework\v3.5\
4.04.0 <Windows 安裝路徑>\Microsoft.NET\Framework\v4.0.30319\<Windows installation path>\Microsoft.NET\Framework\v4.0.30319\
目前Current <Visual Studio 安裝路徑>\MSBuild\Current\bin<Visual Studio installation path>\MSBuild\Current\bin

ToolsVersion 值決定 Visual Studio 產生的專案使用哪一個工具組。The ToolsVersion value determines which Toolset is used by a project that Visual Studio generates. 在 Visual Studio 2019 中,預設值是 "Current" (不論專案檔中指定何種版本),但您可以在命令提示字元中使用 /toolsversion 參數來覆寫該屬性。In Visual Studio 2019, the default value is "Current" (no matter what the version specified in the project file), but you can override that attribute by using the /toolsversion switch at a command prompt. 如需此屬性的相關資訊以及指定 ToolsVersion 的其他方式,請參閱覆寫 ToolsVersion 設定For information about this attribute and other ways to specify the ToolsVersion, see Overriding ToolsVersion settings.

MSBuild 15.0 包含下列標準工具組:MSBuild 15.0 includes the following standard Toolsets:

ToolsVersionToolsVersion 工具組路徑 (如 MSBuildToolsPath 或 MSBuildBinPath 組建屬性中所指定)Toolset path (as specified in the MSBuildToolsPath or MSBuildBinPath build property)
2.02.0 *<Windows 安裝路徑>\Microsoft.Net\Framework\v2.0.50727\*<Windows installation path>\Microsoft.Net\Framework\v2.0.50727\
3.53.5 <Windows 安裝路徑>\Microsoft.NET\Framework\v3.5\<Windows installation path>\Microsoft.NET\Framework\v3.5\
4.04.0 <Windows 安裝路徑>\Microsoft.NET\Framework\v4.0.30319\<Windows installation path>\Microsoft.NET\Framework\v4.0.30319\
15.015.0 <Visual Studio 安裝路徑>\MSBuild\15.0\bin<Visual Studio installation path>\MSBuild\15.0\bin

ToolsVersion 值決定 Visual Studio 產生的專案使用哪一個工具組。The ToolsVersion value determines which Toolset is used by a project that Visual Studio generates. 在 Visual Studio 2017 中,預設值是 "15.0" (不論專案檔中指定何種版本),但您可以在命令提示字元使用 /toolsversion 參數覆寫該屬性。In Visual Studio 2017, the default value is "15.0" (no matter what the version specified in the project file), but you can override that attribute by using the /toolsversion switch at a command prompt. 如需此屬性的相關資訊以及指定 ToolsVersion 的其他方式,請參閱覆寫 ToolsVersion 設定For information about this attribute and other ways to specify the ToolsVersion, see Overriding ToolsVersion settings.

Visual Studio 2017 及更新版本不會使用登錄機碼作為 MSBuild 的路徑。Visual Studio 2017 and later versions do not use a registry key for the path to MSBuild. 若為與 Visual Studio 2017 一同安裝,且為 15.0 版之前的 MSBuild,下列登錄機碼會指定 MSBuild.exe 的安裝路徑。For versions of MSBuild prior to 15.0 that are installed with Visual Studio 2017, the following registry keys specify the installation path of MSBuild.exe.

登錄機碼Registry key 機碼名稱Key name 字串索引鍵值String key value
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ MSBuild\ToolsVersions\2.0\\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ MSBuild\ToolsVersions\2.0\ MSBuildToolsPathMSBuildToolsPath .NET Framework 2.0 安裝路徑.NET Framework 2.0 Install Path
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ MSBuild\ToolsVersions\3.5\\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ MSBuild\ToolsVersions\3.5\ MSBuildToolsPathMSBuildToolsPath .NET Framework 3.5 安裝路徑.NET Framework 3.5 Install Path
\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ MSBuild\ToolsVersions\4.0\\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ MSBuild\ToolsVersions\4.0\ MSBuildToolsPathMSBuildToolsPath .NET Framework 4 安裝路徑.NET Framework 4 Install Path

子工具組Sub-toolsets

如果前一份表格中的登錄機碼有子機碼,則 MSBuild 會用它來判斷覆寫父工具組中路徑的子工具組路徑。If the registry key in the previous table has a subkey, MSBuild uses it to determine the path of a sub-toolset that overrides the path in the parent Toolset. 以下列子機碼為例:The following subkey is an example:

\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\12.0\12.0\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSBuild\ToolsVersions\12.0\12.0

如果基底工具組和選取的子工具組中都定義了任何屬性,則系統會使用子工具組中的屬性定義。If any properties are defined in both the base Toolset and the selected sub-toolset, the property definitions in the sub-toolset are used. 例如,MSBuild 4.0 工具組定義 SDK40ToolsPath 指向 7.0A SDK,但 MSBuild 4.0\11.0 工具組定義同一屬性指向 8.0A SDK。For example, the MSBuild 4.0 Toolset defines SDK40ToolsPath to point to the 7.0A SDK, but the MSBuild 4.0\11.0 Toolset defines the same property to point to the 8.0A SDK. 如未設定 VisualStudioVersionSDK40ToolsPath 會指向 7.0A,但若 VisualStudioVersion 設為 11.0,則屬性會改指向 8.0A。If VisualStudioVersion is unset, SDK40ToolsPath would point to 7.0A, but if VisualStudioVersion is set to 11.0, the property would instead point to 8.0A.

VisualStudioVersion 組建屬性會指出子工具組是否成為作用中。The VisualStudioVersion build property indicates whether a sub-toolset becomes active. 例如,VisualStudioVersion 值為 "12.0" 會指定 MSBuild 12.0 子工具組。For example, a VisualStudioVersion value of "12.0" specifies the MSBuild 12.0 sub-toolset. 如需詳細資訊,請參閱工具組 (ToolsVersion) 的<子工具組>一節。For more information, see the Sub-toolsets section of Toolset (ToolsVersion).

Note

建議您避免變更這些設定。We recommend that you avoid changing these settings. 但您可以新增自己的設定,並定義全電腦的自訂工具組定義,如下節所述。Nevertheless, you can add your own settings and define computer-wide custom Toolset definitions, as the next section describes.

自訂工具組定義Custom Toolset definitions

當標準工具組無法滿足您的組建需求時,您可以建立自訂的工具組。When a standard Toolset does not fulfill your build requirements, you can create a custom Toolset. 例如,您可能有個組建置實驗室案例,必須使用個別的系統組建 Visual C++Visual C++ 專案。For example, you may have a build lab scenario in which you must have a separate system for building Visual C++Visual C++ projects. 使用自訂工具組,您就可以在建立專案或執行 MSBuild.exe 時,將自訂值指派給 ToolsVersion 屬性。By using a custom Toolset, you can assign custom values to the ToolsVersion attribute when you create projects or run MSBuild.exe. 透過這樣做,您也可以使用 $(MSBuildToolsPath) 屬性匯入該目錄的 .targets 檔案,以及定義您自己的自訂工具組屬性,這些屬性可用於使用該工具組的任何專案。By doing this, you can also use the $(MSBuildToolsPath) property to import .targets files from that directory, as well as defining your own custom Toolset properties that can be used for any project that uses that Toolset.

MSBuild.exe (如果使用 MSBuild 引擎,則為裝載 MSBuild 引擎的自訂工具) 的設定檔中指定自訂工具組。Specify a custom Toolset in the configuration file for MSBuild.exe (or for the custom tool that hosts the MSBuild engine if that is what you are using). 例如,如果您想要定義名為 MyCustomToolset 的工具組,MSBuild.exe 的設定檔可以包含下列工具組定義。For example, the configuration file for MSBuild.exe could include the following Toolset definition if you wished to define a toolset named MyCustomToolset.

<msbuildToolsets default="MyCustomToolset">
   <toolset toolsVersion="MyCustomToolset">
      <property name="MSBuildToolsPath"
        value="C:\SpecialPath" />
   </toolset>
</msbuildToolsets>

也必須在組態檔中定義 <msbuildToolsets>,如下所示。<msbuildToolsets> must also be defined in the configuration file, as follows.

<configSections>
   <section name="msbuildToolsets"
       Type="Microsoft.Build.BuildEngine.ToolsetConfigurationSection,
       Microsoft.Build, Version=15.1.0.0, Culture=neutral,
       PublicKeyToken=b03f5f7f11d50a3a"
   </section>
</configSections>

Note

為正確讀取,<configSections> 必須在 <configuration> 區段的第一個小節中。To be read correctly, <configSections> must be the first subsection in the <configuration> section.

ToolsetConfigurationSection 是可供任何 MSBuild 主機自訂組態使用的自訂組態區段。ToolsetConfigurationSection is a custom configuration section that can be used by any MSBuild host for custom configuration. 如果使用自訂的工具組,主機除提供組態檔項目以外,不必執行任何作業來初始化組建引擎。If you use a custom Toolset, a host does not have to do anything to initialize the build engine except provide the configuration file entries. 在登錄中定義項目,您就可以指定全電腦的工具組,套用至 MSBuild.exeVisual StudioVisual Studio 和所有 MSBuild 主機。By defining entries in the registry, you can specify computer-wide Toolsets that apply to MSBuild.exe, Visual StudioVisual Studio, and all hosts of MSBuild.

Note

如果組態檔定義的 ToolsVersion 設定已在登錄中定義,這兩個定義不會合併。If a configuration file defines settings for a ToolsVersion that was already defined in the registry, the two definitions are not merged. 組態檔中的定義優先,ToolsVersion 的登錄設定則予以忽略。The definition in the configuration file takes precedence and the settings in the registry for that ToolsVersion are ignored.

下列屬性專門針對專案中使用的 ToolsVersion 值:The following properties are specific to the value of ToolsVersion that is used in projects:

  • $(MSBuildBinPath) 設定為 ToolsPath 值,是在登錄或定義 ToolsVersion 的組態檔中指定。$(MSBuildBinPath) is set to the ToolsPath value that is specified either in the registry or in the configuration file where the ToolsVersion is defined. 登錄或組態檔中的 $(MSBuildToolsPath) 設定會指定核心工作和目標的位置。The $(MSBuildToolsPath) setting in the registry or the configuration file specifies the location of the core tasks and targets. 在專案檔中,這會對應至 $(MSBuildBinPath) 屬性,也會對應至 $(MSBuildToolsPath) 屬性。In the project file, this maps to the $(MSBuildBinPath) property, and also to the $(MSBuildToolsPath) property.

  • $(MSBuildToolsPath) 是保留的屬性,由組態檔中指定的 MSBuildToolsPath 屬性提供。$(MSBuildToolsPath) is a reserved property that is supplied by the MSBuildToolsPath property that is specified in the configuration file. (這個屬性會取代 $(MSBuildBinPath)(This property replaces $(MSBuildBinPath). 不過,為相容性之故會執行 $(MSBuildBinPath)。)自訂工具組必須定義 $(MSBuildToolsPath)$(MSBuildBinPath),但不能同時定義兩者,除非它們有相同的值。However, $(MSBuildBinPath) is carried forward for compatibility.) A custom Toolset must define either $(MSBuildToolsPath) or $(MSBuildBinPath) but not both, unless they both have the same value.

    您也可以使用新增 MSBuildToolsPath 屬性時所用的相同語法,在組態檔中新增自訂的工具版本特定屬性。You can also add custom, ToolsVersion-specific properties to the configuration file by using the same syntax that you use to add the MSBuildToolsPath property. 為使專案檔能夠使用這些自訂屬性,請使用和組態檔指定的值名稱相同的名稱。To make these custom properties available to the project file, use the same name as the name of the value that is specified in the configuration file. 您可以在設定檔中定義工具組,但不能定義子工具組。You may define Toolsets but not sub-toolsets in the configuration file.

另請參閱See also