Практическое руководство. Информация об использовании пакетов SDK проекта MSBuildHow to: Use MSBuild project SDKs

В версии MSBuildMSBuild 15.0 представлена новая концепция "пакет SDK проекта", которая упрощает применение пакетов разработки программного обеспечения, требующих импортировать свойства и целевые объекты.MSBuildMSBuild 15.0 introduced the concept of the "project SDK", which simplifies using software development kits that require properties and targets to be imported.

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

На этапе оценки проекта MSBuildMSBuild добавляет неявные директивы импорта в начале и конце кода проекта:During evaluation of the project, MSBuildMSBuild adds implicit imports at the top and bottom of your project:

<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>

Ссылка на пакет SDK проектаReference a project SDK

Есть три разных способа указать ссылку на пакет SDK проекта:There are three ways to reference a project SDK:

  1. Используйте атрибут Sdk в элементе <Project/>.Use the Sdk attribute on the <Project/> element:

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

    При этом в начале и конце кода проекта добавляются неявные директивы импорта, как описано выше.An implicit import is added to the top and bottom of the project as discussed above.

    Чтобы указать определенную версию пакета SDK, ее можно добавить в атрибут Sdk.To specify a specific version of the SDK you may append it to the Sdk attribute:

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

    Note

    Сейчас это единственный способ добавить ссылку на пакет SDK для проекта в Visual Studio для Mac.This is currently the only supported way to reference a project SDK in Visual Studio for Mac.

  2. Используйте элемент <Sdk/> верхнего уровня.Use the top-level <Sdk/> element:

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

    При этом в начале и конце кода проекта добавляются неявные директивы импорта, как описано выше.An implicit import is added to the top and bottom of the project as discussed above. Атрибут Version не является обязательным.The Version attribute is not required.

  3. Используйте элемент <Import/> в любом месте кода проекта.Use the <Import/> element anywhere in your project:

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

    Явное включение директив импорта позволяет самостоятельно контролировать порядок добавления элементов.Explicitly including the imports in your project allows you full control over the order.

    Если вы используете элемент <Import/>, можно указать необязательный атрибут Version.When using the <Import/> element, you can specify an optional Version attribute as well. Например, так: <Import Project="Sdk.props" Sdk="My.Custom.Sdk" Version="1.2.3" />.For example, you can specify <Import Project="Sdk.props" Sdk="My.Custom.Sdk" Version="1.2.3" />.

Как разрешаются ссылки на пакеты SDK проектаHow project SDKs are resolved

При оценке директив импорта MSBuildMSBuild динамически разрешает путь к пакету SDK проекта, используя указанные значения имени и версии.When evaluating the import, MSBuildMSBuild dynamically resolves the path to the project SDK based on the name and version you specified. Также MSBuildMSBuild использует список зарегистрированных распознавателей SDK. Это подключаемые модули, которые отвечают за расположение пакетов SDK на компьютере.MSBuildMSBuild also has a list of registered SDK resolvers which are plug-ins that locate project SDKs on your machine. Далее следует список этих подключаемых модулей.These plug-ins include:

  1. Распознаватель на основе NuGet, который опрашивает настроенные каналы пакетов в поисках пакетов NuGet с указанными значениями идентификатора и версии пакета SDK.A NuGet-based resolver that queries your configured package feeds for NuGet packages that match the ID and version of the SDK you specified.
    Этот распознаватель применяется только в том случае, если вы указали необязательное значение версии. Его можно использоваться для любых пользовательских пакетов SDK проекта.This resolver is only active if you specified an optional version and it can be used for any custom project SDK.
  2. Распознаватель .NET CLI, который разрешает пакеты SDK, установленные совместно с .NET CLI.A .NET CLI resolver that resolves SDKs that are installed with .NET CLI.
    Этот распознаватель находит только пакеты SDK проекта, входящие в состав этого продукта, например Microsoft.NET.Sdk и Microsoft.NET.Sdk.Web.This resolver locates project SDKs such as Microsoft.NET.Sdk and Microsoft.NET.Sdk.Web which are part of the product.
  3. Распознаватель по умолчанию, который разрешает пакеты SDK, установленные совместно с MSBuild.A default resolver that resolves SDKs that were installed with MSBuild.

Распознаватель пакетов SDK на основе NuGet позволяет указывать версию в файле global.json, благодаря чему вы можете управлять версией пакета SDK проекта в одном месте, а не в каждом проекте отдельно.The NuGet-based SDK resolver supports specifying a version in your global.json that allows you to control the project SDK version in one place rather than in each individual project:

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

При сборке проекта может использоваться только одна версия каждого пакета SDK проекта.Only one version of each project SDK can be used during a build. Если вы укажете ссылки на две разные версии одного пакета SDK проекта, MSBuild выдаст следующее предупреждение.If you are referencing two different versions of the same project SDK, MSBuild will emit a warning. Рекомендуем не указывать в проектах версию, если она уже указана в файле global.json.It is recommended to not specify a version in your projects if a version is specified in your global.json.

См. такжеSee also