Andrey on .NET

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

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

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

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

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. Обратите внимание, что шаблон не рекурсивный по умолчанию.

Автоматическое создание .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> может включать в себя следующие дочерние элементы:

Элемент

Описание

(обязательный) Уникальный идентификатор установочного пакета. Правила его создания аналогичны правилам присвоения названий пространствам имен .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 проекта.

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

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 и старше позволяет библиотекам добавлять свои источники установочных пакетов в виде файлов конфигурации, которые имеют следующие пути и имена:

%ProgramData%\NuGet\Config\*.config
%ProgramData%\NuGet\Config\{IDE}\*.config
%ProgramData%\NuGet\Config\{IDE}\{Version}\*.config
%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 файлов

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

Про C#, .NET, ASP.NET, Core, MVC, Azure, EF, IoC и другие умные слова

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