Добавление файлов контента в nuget-пакетах

Привет! Меня зовут Александр, я старший разработчик в команде, которая занимается оцифровкой документов. Когда мы разрабатываем пакеты библиотек компонентов, иногда возникает необходимость дополнить исполняемый код определенным контентом. Нередко этот контент нужен именно в виде отдельных файлов, а не встроенных ресурсов. Примерами таких задач могут быть различные пакеты .NET-оболочек, которым обычно необходимы исходные библиотеки. Нам же понадобились специальные шрифты во внутрикорпоративной библиотеке конвертации документов.

Мы видели два варианта решения проблемы:

1. Встроить шрифты как embedded-ресурсы и копировать их при инициализации библиотеки в целевую папку.

2. Добавить файлы в nuget-пакет.

Первое решение — это фактически хардкод. Если пользователь библиотеки захочет использовать свои шрифты вместо наших, мы все равно будем добавлять их в папку приложения при каждом запуске. Поэтому мы решили добавить файлы шрифтов в nuget-пакет.

Опишу решение и подводные камни, на которые наткнулся в процессе работы. На Хабре уже есть одна статья на эту тему. Я хотел бы подробнее рассказать о своем решении и обсудить некоторые моменты, которые не были разобраны в том материале.

Первая попытка (неудачная)

Сначала я решил установить для всех файлов свойства Build Action — None и Copy to Output Directory — Copy if never. Это решение отлично работает при прямых ссылках на проекты в солюшене, но в nuget-пакетах шрифты оказались доступны только в пакетах, которые напрямую ссылались на пакет со шрифтами.

Например, у нас есть nuget-пакет LibA, содержащий шрифты. LibA используется в nuget-пакете LibB, и при добавлении LibB в проект шрифты остаются доступны. LibB используется в nuget-пакете LibC, и при добавлении LibC в проект шрифты не добавляются.

Вторая попытка (удачная)

После долгого изучения MSDN и StackOverflow я пришел к выводу, что лучше сделать все вручную. То есть написать .nuspec-файл с описанием пакета и .props-файл с логикой, которая должна будет выполниться при сборке проекта.

Добавляем в проект папку buildTransitive, складываем в нее шрифты, .nuspec- и .props-файлы. Папку я назвал buildTransitive, потому что в пакете будет папка с таким же именем. Она нужна, чтобы каждый последующий пакет в цепочке ссылок имел доступ к шрифтам. Больше о ней можно узнать из документации.

Добавляем ссылки на .props и .nuspec в файле проекта.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NuspecFile>buildTransitive\LibA.nuspec</NuspecFile> 
  </PropertyGroup>
  ...
  <Import Project="buildTransitive\LibA.props" />
</Project>

Открываем .nuspec-файл и описываем, какие файлы куда положить в нашем пакете.

<files>
    <file src="LibA.props" target="buildTransitive" />
    <file src="fonts\**" target="buildTransitive\fonts" />
    <file src="..\bin\Debug\net6.0\LibA.dll" target="lib\net6.0\LibA.dll" />   
</files>

В этом случае мы копируем файлы LibA.props и папку fonts в папку пакета buildTransitive, а собранный файл проекта — в папку пакета lib\net6.0\LibA.dll.

Внимание! Всегда используйте обратный слеш в путях! Иначе можно получить разный результат при сборке под Windows и Linux. Более подробно ситуация описана здесь.

Описываем логику копирования файлов шрифтов при сборке в .props-файле.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <None Include="$(MSBuildThisFileDirectory)fonts\**" >
      <Link>fonts\%(RecursiveDir)%(Filename)%(Extension)</Link>
      <PackageCopyToOutputDirectory>PreserveNewest</PackageCopyToOutputDirectory>
      <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <Visible>False</Visible>
    </None>
  </ItemGroup>
</Project>

В этом скрипте содержимое папки fonts из пакета при сборке будет рекурсивно скопировано в папку fonts в выходном каталоге.

Дополняем функциональность

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

Многие IDE позволяют заполнить данные об авторе, компании, описании пакета и так далее. В идеале эти метаданные о nuget-пакете нужно получать из файла проекта. Дополнительные переменные можно передать при сборке билда. В моем случае это была версия пакета.

Чтобы передать данные из файла проекта в .nuspec, используем тег NuspecProperties. В результате файл проекта будет выглядеть так:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>disable</ImplicitUsings>
    <Nullable>disable</Nullable>
    <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
    <Version>$(PkgVersion)</Version>
    <Authors>Authors list</Authors>
    <Description>Project description</Description>
    <NuspecFile>buildTransitive\LibA.nuspec</NuspecFile>
    <NuspecProperties>$(NuspecProperties);PackageId=$(MSBuildProjectName)</NuspecProperties>
    <NuspecProperties>$(NuspecProperties);PackageAuthors=$(Authors)</NuspecProperties>
    <NuspecProperties>$(NuspecProperties);PackageDescription=$(Description)</NuspecProperties>
  </PropertyGroup>
  <Target Name="NuspecProperties" AfterTargets="Build">
    <PropertyGroup>
      <NuspecProperties>$(NuspecProperties);PackageVersion=$(Version)</NuspecProperties>
      <NuspecProperties>$(NuspecProperties);PackageTargetPath=$(TargetPath)</NuspecProperties>
    </PropertyGroup>
  </Target>
  <Import Project="buildTransitive\LibA.props" />
</Project>

Номер версии будет передан при сборке в переменной PkgVersion и записан в тег Version. Переменные из .nuspec передаются в переменную NuspecProperties парами «ключ — значение» и разделяются точкой с запятой. При этом данные о версии и конечном пути к выходному файлу сборки записываются после билда.

Если не передать версию в переменной PkgVersion и запустить сборку проекта, ее номер будет 1.0.0.

Сборка проекта на билд-машине запускается с помощью команды:

- dotnet build $ SOLUTION_FILE_PATH -c Release --no-restore -p:PkgVersion=$PACKAGE_VERSION --output outDir

В этом случае, если в файле проекта тег GeneratePackageOnBuild установлен в true, будет выполнена сборка проекта и создан nuget-пакет. Если тег GeneratePackageOnBuild установить в false и разделить операции dotnet build и dotnet pack, данные из файла проекта не попадут в .nuspec-файл.

Пример .nuspec-файла с добавленными переменными, объявленными в файле проекта:

<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>
    <id>$PackageId$</id>
    <version>$PackageVersion$</version>
    <authors>$PackageAuthors$</authors>
    <description>$PackageDescription$</description>
    <dependencies>
      <group targetFramework="net6.0" />
    </dependencies>
  </metadata>
  <files>
    <file src="LibA.props" target="buildTransitive" />
    <file src="fonts\**" target="buildTransitive\fonts" />
    <file src="$PackageTargetPath$" target="lib\net6.0\LibA.dll" />
  </files>
</package>

На этом все. Надеюсь, моя статья поможет кому-то сэкономить время и нервы! Тестовый проект можно посмотреть на GitHub.

Дополнительная информация

В моем тестовом проекте, который содержит шрифты, нет ссылок на другие пакеты. Если добавить ссылку на другой nuget-пакет, она будет записана в файл проекта и ее придется вручную прописать в .nuspec. Чтобы избежать ручной поддержки целостности ссылок, в рабочем проекте я вынес шрифты в отдельную сборку, в которой нет ничего кроме шрифтов, создал отдельный пакет и ссылался на него из других проектов.

Если при сборке нужно посмотреть значения переменных из файла проекта, это можно сделать с помощью тега Message.

<Project Sdk="Microsoft.NET.Sdk">
  ...
  <Target Name="Log" AfterTargets="Build">
    <Message Importance="High" Text="----------Build Variables-------------" />
    <Message Importance="High" Text="MSBuildProjectName = $(MSBuildProjectName)" />
    <Message Importance="High" Text="TargetPath = $(TargetPath)" />
    <Message Importance="High" Text="NuspecProperties = $(NuspecProperties)" />
    <Message Importance="High" Text="----------Build Variables-------------" />
  </Target>
  ...
</Project>

Если у вас остались вопросы или вы хотите поделиться опытом работы с nuget-пакетами, добро пожаловать в комментарии.