Файлы .props и .targets MSBuild в пакете

Статья
08/10/2023

Помимо классических сборок, пакеты NuGet могут иногда добавлять целевые объекты или свойства пользовательских сборок в проекты, использующие этот пакет. Для этого необходимо добавить допустимый файл MSBuild в виде <package_id>.targets или <package_id>.props (например, Contoso.Utility.UsefulStuff.targets) в папки сборки проекта.

Папки сборки

По мере развития NuGet добавлялись различные папки для файлов сборки .props и .targets.

Папка	Версия NuGet	Использование
сборка	2.5 и выше	Логика сборки для каждой платформы проекта.
buildMultiTargeting	4.0+	Логика сборки для `outer build` для проектов, предназначенных для нескольких платформ. Только PackageReference.
buildTransitive	5.0 и выше	Логика сборки для ресурсов, которые транзитивно передаются в любой принимающий проект. См. об этой функции. Только PackageReference.

Папка сборки для конкретной платформы

Все три папки сборки выполняют одинаковые действия при определении наиболее подходящего файла в зависимости от целевой платформы проекта.

Файлы в корневой папке сборки (build/<package_id>.targets и build/<package_id>.props) подходят для всех целевых платформ.

Чтобы предоставить файлы для определенных платформ, сначала поместите их в соответствующие вложенные папки, например следующие:

    \build
        \netstandard1.4
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets
        \net462
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets

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

Обратите внимание, что, если в пакете в папках lib и ref нет файлов и файлы есть только в папке сборки для конкретной платформы, такой пакет будет совместим со всеми проектами. При создании таких пакетов последние версии инструментов вызывают предупреждение NU5127.

Проекты, использующие пакеты с файлами сборки

Проекты PackageReference

.props и .targets не добавляются в файл проекта, но доступны в {projectName}.nuget.g.targets и {projectName}.nuget.g.props. Эти файлы автоматически создаются во время восстановления.

Если проект предназначен более чем для одной платформы, импорт в эти файлы зависит от имени целевой платформы.

Файлы MSBuild .props и .targets для работы с несколькими платформами можно поместить в папку \buildMultiTargeting. Во время импорта необходимо задать условие, при котором свойство MSBuild $(TargetFramework) является пустым.

Проекты packages.config

Когда NuGet устанавливает пакет с \build файлом, он добавляет элементы MSBuild <Import> в файл проекта, указывая на .targets и .props файла. (.props добавляется в верхней части файла проекта; .targets добавляется в нижней части.) Для каждой целевой платформы добавляется отдельный условный элемент MSBuild <Import> .

Разработка пакетов с файлами .props и .targets MSBuild

Чтобы включить в пакет файлы .props и .targets MSBuild, можно использовать любое из следующих средств.

Руководство по содержимому файлов .props и .targets MSBuild

NuGet не ограничивает разработку файлов .props и .targets, так как они могут различаться в зависимости от потребностей разработчика пакета и целевых проектов.

Однако в файлах пакетов .props и .targets не следует выполнять некоторые действия, например нельзя указывать свойства и элементы, которые влияют на восстановление, так как они будут автоматически исключены.

Далее приведены некоторые примеры свойств, которые нельзя добавлять или обновлять: TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker, AssetTargetFallback и т. д.
Далее приведены некоторые примеры элементов, которые нельзя добавлять или обновлять: PackageReference, PackageVersion, PackageDownload и т. д.

Поделиться через