使用 MSBuild 项目 SDK

只需通过按其特定 ID 引用一组属性和目标(统称为“项目 SDK”)来引用开发技术堆栈所需的所有生成基础结构(如 .NET SDK)。 ID 引用一组包含属性定义的特定 .props 文件和包含目标定义的 .targets 文件。 可以使用顶级项目节点上的 Sdk 属性来引用项目 SDK。

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net46</TargetFramework>
    </PropertyGroup>
</Project>

在项目评估期间,MSBuild 会在项目文件的顶部和底部添加隐式导入:

<Project>
    <!-- Implicit top import -->
    <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />

    <PropertyGroup>
        <TargetFramework>net46</TargetFramework>
    </PropertyGroup>

    <!-- Implicit bottom import -->
    <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
</Project>

Microsoft 分发了许多 SDK。 上一示例中引用的项目 SDK 具有名字对象 Microsoft.NET.Sdk。 与 .NET Core 和 .NET 5 及更高版本关联的项目 SDK 在 .NET 项目 SDK 概览中列出。

引用项目 SDK

可通过三种方法引用项目 SDK:

使用 <Project/> 元素的 Sdk 属性

<Project Sdk="My.Custom.Sdk">
    ...
</Project>

将隐式导入添加到项目的顶部和底部,如前面所述。

若要指定特定版本的 SDK,可以将其追加到 Sdk 属性:

<Project Sdk="My.Custom.Sdk/1.2.3">
    ...
</Project>

使用顶级 <Sdk/> 元素

<Project>
    <Sdk Name="My.Custom.Sdk" Version="1.2.3" />
    ...
</Project>

将隐式导入添加到项目的顶部和底部,如前面所述。

不需要 Version 属性。

在项目任意位置使用 <Import/> 元素

<Project>
    <PropertyGroup>
        <MyProperty>Value</MyProperty>
    </PropertyGroup>
    <Import Project="Sdk.props" Sdk="My.Custom.Sdk" />
    ...
    <Import Project="Sdk.targets" Sdk="My.Custom.Sdk" />
</Project>

在项目中显式包含导入时,可完全控制顺序。

使用 <Import/> 元素时,你还可以指定一个可选的 Version 属性。 例如,你可以指定 <Import Project="Sdk.props" Sdk="My.Custom.Sdk" Version="1.2.3" />

警告

如果更改项目以使用 <Import/> 元素,请确保同时添加 .props.targets 导入,并从 <Project/> 元素和 <Sdk/> 元素中删除 SDK。 如果不这样做,会导致导入加倍并出现 MSB4011 警告。

如何解析项目 SDK

导入评估时,MSBuild 将基于名称和你指定的版本动态解析到项目 SDK 的路径。 此外,MSBuild 还具有已注册的 SDK 解析程序,它是在计算机上查找项目 SDK 的插件。 这些插件包括:

  • 基于 NuGet 的解析程序,用于查询为 NuGet 包配置的包源是否匹配所指定 SDK 的 ID 和版本。

    仅当指定了可选版本时,此解析程序才处于活动状态。 它可用于任何自定义项目 SDK。

  • .NET SDK 解析程序,用于解析随 .NET SDK 一起安装的 MSBuild SDK。

    此解析程序查找项目 SDK,如 Microsoft.NET.SdkMicrosoft.NET.Sdk.Web,这些项目是该产品的一部分。

  • 默认解析程序,用于解析随 MSBuild 一起安装的 SDK。

基于 NuGet 的 SDK 解析程序支持在 global.json 文件中指定版本,可使你在一个位置而不是在每个项目中控制项目 SDK 版本:

{
    "msbuild-sdks": {
        "My.Custom.Sdk": "5.0.0",
        "My.Other.Sdk": "1.0.0-beta"
    }
}

在生成期间,只能使用每个项目 SDK 的一个版本。 如果你引用同一项目 SDK 的两个不同版本,MSBuild 会发出警告。 如果在 global.json 文件中指定了版本,则不建议在项目中指定版本