NuGet – Справочник по созданию установочных пакетов

Краткое справочное руководство по созданию установочных пакетов для NuGet. 

Обновлено до соответствия версии: 2.6.

Программа для создания установочных пакетов

NuGet.exe Command Line

Пример команды для создания пакета:

nuget pack myLibSpec.nuspec

Структура папок

  • content – папка, содержимое которой будет перенесено в корневую папку проекта (c сохранением структуры расположенных в ней подпапок);
  • lib – папка с сборками библиотеки. Каждая сборка размещается в папке, имя которой соответствует поддерживаемой её платформе:
    • .NET Framework: net11, net20, net40, net45, core50, dnx452, dnx46, dnxcore50;
    • Silverlight: sl4, sl5;
    • Windows 8 Store: Windows, Windows8, win, win8 (ранее: winRT45, .NETCore45);
    • Windows Phone 7: wp, wp7, WindowsPhone, WindowsPhone7 (ранее: silverlight3-wp);
    • Windows Phone 7.5 (Mango): wp71, WindowsPhone71 (ранее: silverilght4-wp71);
    • Windows Phone 8: wp8, WindowsPhone8
    • для для переносимых библиотек формат: portable-{framework 1}+{framework n}.
  • tools – папка для утилит, которые будут доступны из командной строки после установки проекта;
  • build – папка для файлов MSBuild. В ней располагаются {packageId}.targets и {packageId}.props, которые при установке пакета будут добавлены в MSBuild <Import>.
  • [ProjectName].nuspec – файл со описанием проекта.

Создаются только те папки, в которых есть файлы.

Начиная с версии 1.3, NuGet.exe игнорирует файлы, имена которых начинаются с точки. Это необходимо для улучшения совместной работы с системами контроля версий (Subversion и Mercurial). Но при необходимости такое поведение можно изменить, используя следующие параметры:

  • -NoDefaultExcludes – обеспечит включение всех файлов.
  • -Exclude – используется для указания шаблона имен файлов, которые будет игнорироваться. Например, чтобы исключить все .bak файлы необходимо указать -Exclude **\*.bak. Обратите внимание, что шаблон не рекурсивный по умолчанию.

Рекомендации по созданию установочного пакета

  • Для создания уникального идентификатора библиотеки следует использовать те же правила, что и для названий пространств имен в .NET.
  • Для пакетов с демонстрационными проектами и примерами следует использовать суффикс ".Sample". Сами файлы следует размещать в папках "content/Samples/[PackageId]".
  • Аналогично, для пакетов c исходным кодом устанавливается суффикс ".Source".
  • Вместе с файлом сборки библиотеки, в установочный пакет могут быть включены дополнительные DLL. Однако они не должны использоваться в других проектах. Например, Lib1.dll и Lib2.dll – две библиотеки и Lib2 может использоваться отдельно. В этом случае необходимо создать два пакета и установить между ними зависимость Lib1 от Lib2. Но если Lib2, к примеру, файл ресурсов для Lib1, то их следует разместить вместе.
  • Файл readme.txt лучше разместить в папке "content/App_Readme/[PackageId].readme.txt".

Автоматическое создание .nuspec файла для проекта

NuGet позволяет автоматически создать спецификацию установочного пакета для проекта. Для этого в папке с проектом (.csproj файлом). Необходимо выполнить команду:

nuget spec

В результате будет создан следующий "[имя-проекта].nuspec" файл:

<?xml version="1.0"?>
<package >
  <metadata>
    <id>$id$</id>
    <version>$version$</version>
    <title>$title$</title>
    <authors>$author$</authors>
    <owners>$author$</owners>
    <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>$description$</description>
    <copyright>Copyright 2011</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

Обратите внимание, что он включает ссылки на данные из самого проекта (которые содержатся в его свойствах): идентификатор, номер версии, название, описание и имя автора. При этом необходимо, чтобы сгенерированный файл располагался в папке проекта.

Создание установочного пакета на основе такой конфигурации осуществляется командой:

nuget [имя-проекта].csproj

Обратите внимание, что в качестве параметра передается именно .csproj (.vbproj) файл.

Элементы, используемые в спецификации установочного пакета (.nuspec)

Описание данных установочного пакета: <metadata>

Элемент <metadata> используется для указания информации об установочном пакете.

Начиная с версии 2.5, он поддерживает необязательный атрибут minClientVersion для указания минимальной версии NuGet. При его использовании пользователи старых версий получат сообщение о необходимости обновить пакетный менеджер. Пример использования:

<metadata minClientVersion="2.6">

Элемент <metadata> может включать в себя следующие дочерние элементы:

Элемент Описание
id (обязательный) Уникальный идентификатор установочного пакета. Правила его создания аналогичны правилам присвоения названий пространствам имен .NET.
version (обязательный) Версия в формате 1.2.3.
title Название библиотеки.
authors Список авторов библиотеки (разделитель – запятая).
owners Список создателей установочного пакета (разделитель – запятая).
description (обязательный) Описание установочного пакета.
summary Краткое описание.
language Код используемого языка (например, ru-ru или en-us и т.д.)

projectUrl

Ссылка на сайт библиотеки.
iconUrl Ссылка на иконку с логотипом библиотеки, которая будет отображена в диалоге "Add Library Package Reference". Требуемый формат: PNG, 32x32 c прозрачным фоном.
licenseUrl Ссылка на лицензионное соглашение.
dependencies

Список библиотек, от которых зависит устанавливаемый пакет. В него включаются элементы <dependency id="[id]" version="[version]" />, где:

  • id – идентификатор пакета, от которого зависит текущий
  • version – номер его требуемой или минимальной версии.

При этом номер версии можно указать в следующем формате:

Формат Требуемый диапазон
1.0 1.0 ≤ x
(,1.0] x ≤ 1.0
(,1.0) x < 1.0
[1.0] x == 1.0
(1.0) недопустимо
(1.0,) 1.0 < x
(1.0,2.0) 1.0 < x < 2.0
[1.0,2.0] 1.0 ≤ x ≤ 2.0
по-умолчанию любая версия
   
references Определяет сборки, которые при установке будут добавлены в References проекта.
tags Список ключевых слов, используемых при поиске проекта пользователями.

Зависимости создаваемого установочного пакета от других проектов

NuGet.exe умеет определять зависимости проекта библиотеки, для который создается установочный пакет, от других, расположенных в том же решении (Solution), по следующему правилу:

Если указанном проекте содержится спецификация .nuspec, то в пакет автоматически добавляется зависимость от него. Иначе все его файлы (dlls/pdb/exe и контент) становятся частью пакета, а он сам обрабатывается аналогичным образом.

Таким образом, все проекты с .nuspec становятся зависимостями, а остальные интегрируются. Разумеется, это не отменяет использование секции dependencies для сторонних установочных пакетов.

Указание включаемых файлов: <files>

Спецификация NuGet позволяет указать файлы, которые будут включены в проект. Для этого используется элемент <files>, который включает в себя элементы <file>.

<file> – включаемый файл
src Указывает путь до включаемого файла или папки. Можно использовать шаблоны с применением символов "*" и "?".
target Определяет папку, где будет размещен указанный файл или группа.
exclude Определяет файлы, которые будут проигнорированы при включении по шаблону.

Определение подключаемых сборок: <references>

По умолчанию все сборки, соответствующие текущей платформе, включаются в проект. В некоторых случаях такое поведение недопустимо. В частности, это может потребоваться при наличии design-time библиотек.

NuGet позволяет задать включаемые в проект сборки с помощью секции <references>. Она содержит указания следующего вида:

<reference file="[имя dll]" />

Начиная с версии 2.5, добавлена возможность подключать различные сборки для различных платформ. В этом случае раздел <references> примет следующий вид:

<references> 
    <group targetFramework="net45"> 
        <reference file="a.dll" />
    </group> 
    <group targetFramework="netcore45"> 
        <reference file="b.dll" /> 
    </group>
    <group>
        <reference file="c.dll" />
    </group>
</references>

При установке пакета NuGet составляет список из сборок в:

  • папке lib (с указанной платформой);
  • в разделе <references> из
    • группы для текущей платформы;
    • общей группы (без указания targetFramework).

Пример файла спецификации установочного пакета:

<?xml version="1.0" encoding="utf-8"?>
<package>
  <metadata>
    <id>MVCDemo.Attributes.Validation</id>
    <version>1.0.0</version>
    <authors>Andrey Veselov</authors>
    <description>Custom validation attributes for ASP.NET and ASP.NET MVC.</description>
    <language>en-US</language>
    <licenseUrl>http://andrey.moveax.ru/terms-of-use.aspx</licenseUrl>
    <projectUrl>http://andrey.moveax.ru/</projectUrl>
    <tags>ASP.NET MVC</tags>
    <dependencies>
      <dependency id="package1" version="3.0.0" />
      <dependency id="package2" />
    </dependencies>
    <references>
      <reference file="mvcdemo.attributes.validation.dll" />
    </references>
  </metadata>
  <files>
    <file src=".\bin\Release\*.dll" target="lib" />
    <file src=".\Scripts\Validation\*.js" target="content\Scripts\Validation" />
  </files>
</package>

Модификация конфигурационных файлов проекта

Для изменения конфигурационных файлов проекта (app.config или web.config) используются файлы с аналогичными именами и окончанием ".transform". Они размещаются в папке content и содержат код, который необходимо добавить в конфигурацию.

Например, чтобы отключить проверку данных на стороне клиента в ASP.NET MVC проекте необходимо создать файл web.config.transform с следующим содержимым:

<configuration>
  <appSettings>
    <add key="ClientValidationEnabled" value="false"/>
    <add key="UnobtrusiveJavaScriptEnabled" value="false"/>
  </appSettings>
</configuration>

Указанные параметры будут внесены в файл web.config.

Важный момент: NuGet поддерживает только операцию добавления. Удаление или модификация существующих значений не производится.

Поддержка XDT трансформаций для Web.config

Начиная с версии 2.6 NuGet позволяет производить трансформацию Web.config с использованием XDT движка. Файлы трансформаций необходимо разместить в папке Content. Поддерживается два вида файлов:

  • для операций при установке пакета: Web.config.install.xdt
  • для операции при удалении пакета: Web.config.uninstall.xdt

Описание синтаксиса XDT можно найти на сайте MSDN. Стоит отметить, что файлы т��па .transforms по прежнему поддерживаются.

Конфигурация источников установочных пакетов NuGet

NuGet 2.6 и старше позволяет библиотекам добавлять свои источники установочных пакетов в виде файлов конфигурации, которые имеют следующие пути и имена:

  1. %ProgramData%\NuGet\Config\*.config
  2. %ProgramData%\NuGet\Config\{IDE}\*.config
  3. %ProgramData%\NuGet\Config\{IDE}\{Version}\*.config
  4. %ProgramData%\NuGet\Config\{IDE}\{Version}\{SKU}\*.config

Где:

  • {IDE} – название IDE (VisualStudio);
  • {Version} – минимальная версия IDE (10.0, 11.0, 12.0);
  • {SKU} – минимальная редакция IDE.

При наличии вариантов, выбирается наиболее точно описывающей текущую среду разработки.

Пример: компания SomeCoolCompany хочет добавить данные о своем источнике установочных пакетов, которые предназначены для Visual Studio 2012 в редакциях Professional и Ultimate. Путь и имя файла конфигурации будут: %ProgramData%\NuGet\Config\VisualStudio\11.0\Pro\SomeCoolCompany.config

Пример команды для автоматической сборки пакета после создания Release версии

Данная команда указывается в списке "Post-Build Step" в свойствах проекта:

if $(ConfigurationName) == Release nuget pack "$(SolutionDir)$(ProjectName)\$(ProjectName).csproj" -Prop Configuration=Release -OutputDirectory "$(SolutionDir)nuget-packages"

В данном примере считается, что:

  • nupack.exe доступен из командной строки (прописан в path);
  • спецификация был сгенерирована на основе описания проекта (командой nuget spec) и расположена в папке с решением. Поэтому в качестве параметра указан .csproj файл. Если она была создана вручную, то необходимо заменить "\$(ProjectName).csproj" на "\[имя файла спецификации].nuspec".

Установочный пакет будет сохранен в папке nuget-packages, расположенной в папке решения.

Модификация исходных файлов библиотеки

Такая модификация может потребоваться если установочный пакет включает в себя исходный код. В этом случае к именам файлов, требующих изменений, добавляют окончание ".pp". Например: IClass.cs.pp или UserProfileModel.cs.pp и т.д.

В исходный код таких файлов могут быть добавлены переменные, представляющие свойства проекта. При этом их имена должны быть окружены знаком "$" c обеих сторон. Например:

namespace $rootnamespace$.Models {
    public struct CategoryInfo {
        .........
    }
}

Полный список таких переменных можно найти в MSDN: ProjectProperties Properties.

Подключение IntelliSense для .nuspec файлов

  1. Добавляем расширение "nuspec" в список XML файлов:
    • Открываем диалоговое окно Options, используя меню Tools > Options;
    • В разделе "Text Editor > File Extension" назначаем расширению "nuspec" редактор "Xml (Text) Editor with Encoding";
  2. Скачиваем NuSpec XSD-спецификацию для редактора (доступна в разделе "Package Schema" на странице ".nuspec File Format") и добавляем nuspec.xsd файл в проект.
  3. В элементе <package> nuspec-файла, необходимо указать атрибут: xmlns=http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd
  4. IntelliSense настроен.

Комментарии (2) -

В примере файла спецификации нода references должна, насколько я понимаю, находиться внутри ноды metadata (по крайней мере иначе у меня пакет не собирался)

@ Shaddix: Спасибо за внимательность. Поправил.

Pingbacks and trackbacks (1)+

Добавить комментарий