Информация об использовании пакетов SDK проекта MSBuild

  • Статья

Вы можете ссылаться на всю инфраструктуру сборки, необходимую для стека технологий разработки, например пакет SDK для .NET, просто ссылаясь на набор свойств и целевых объектов, которые коллективно называются пакетом SDK для проекта по определенному идентификатору. Идентификатор ссылается на определенный .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>

Существует множество пакетов SDK, распределенных корпорацией Майкрософт. Пакет SDK для проекта, на который ссылается в предыдущем примере, имеет моникер Microsoft.NET.Sdk. Пакеты SDK проекта, связанные с .NET Core и .NET 5 и более поздних версий, перечислены в обзоре пакета SDK для проектов .NET.

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

Есть три разных способа указать ссылку на пакет SDK проекта:

Использование атрибута Sdk для элемента <Project/>

<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 импортируете и удаляете пакет SDK из <Project/> элемента и <Sdk/> элементов. Если этого не сделать, импорт будет дублироваться и появится предупреждение MSB4011.

Как разрешаются пакеты SDK проекта

При оценке директив импорта MSBuild динамически разрешает путь к пакету SDK проекта, используя указанные значения имени и версии. Также MSBuild использует список зарегистрированных сопоставителей SDK. Это подключаемые модули, которые отвечают за расположение пакетов SDK на компьютере. Далее следует список этих подключаемых модулей.

  • Распознаватель на основе NuGet, который опрашивает настроенные каналы пакетов в поисках пакетов NuGet с указанными значениями идентификатора и версии пакета SDK.

    Этот сопоставитель применяется только в том случае, если вы указали необязательное значение версии. Его можно использовать для любых пользовательских пакетов SDK проекта.

  • Сопоставитель пакетов SDK для .NET, который разрешает пакеты SDK для MSBuild, установленные совместно с пакетом SDK для .NET.

    Этот сопоставитель находит только пакеты SDK проекта, входящие в состав этого продукта, например Microsoft.NET.Sdk и Microsoft.NET.Sdk.Web.

  • Распознаватель по умолчанию, который разрешает пакеты SDK, установленные совместно с MSBuild.

Сопоставитель пакетов SDK на основе NuGet позволяет указывать версию в файле global.json, благодаря чему вы можете управлять версией пакета SDK проекта в одном месте, а не в каждом проекте отдельно:

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

При сборке проекта может использоваться только одна версия каждого пакета SDK проекта. Если указать ссылки на две разные версии одного пакета SDK проекта, MSBuild выдает предупреждение. Рекомендуем не указывать в проектах версию, если она уже указана в файле global.json.

Связанный контент