Справочник по файлу NUSPEC

Файл .nuspec представляет собой манифест в формате XML и содержит метаданные пакета. Этот манифест используется при построении пакета и содержит дополнительные сведения для его потребителей. Манифест всегда включается в пакет.

В этом разделе:

• Общая форма и схема
• Замена маркеров (при использовании с проектом Visual Studio)
• Зависимости
• Явные ссылки на сборку
• Ссылки на сборку платформы
• Включение файлов сборки
• Включение файлов содержимого
• Примеры файлов nuspec

Совместимость типов проекта

• Используется для проектов, не относящихся .nuspec к nuget.exe pack пакету SDK, которые используются packages.config.

• .nuspec Файл не требуется для создания пакетов для проектов в стиле ПАКЕТА SDK (обычно проекты .NET Core и .NET Standard, использующие атрибут SDK). (Обратите внимание, что при создании пакета создается объект .nuspec .)

  Если вы создаете пакет с помощью dotnet.exe pack или msbuild pack targetрекомендуется включить все свойства , которые обычно находятся в .nuspec файле проекта. Однако вместо этого можно использовать файл для упаковки с помощью dotnet.exe илиmsbuild pack target..nuspec

• Для проектов, перенесенных из packages.config PackageReference, .nuspec файл не требуется для создания пакета. Вместо этого используйте msbuild -t:pack.

Общая форма и схема

Файл nuspec.xsd схемы можно найти в репозитории NuGet GitHub. Обратите внимание, что этот файл представляет только последнюю схему для .nuspec файла. Официально опубликованные версии не существуют, а версия этого файла не соответствует какой-либо конкретной версии NuGet.

В рамках этой схемы файл .nuspec имеет следующую общую форму:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <!-- Required elements-->
        <id></id>
        <version></version>
        <description></description>
        <authors></authors>

        <!-- Optional elements -->
        <!-- ... -->
    </metadata>
    <!-- Optional 'files' node -->
</package>

Чтобы получить наглядное представление схемы, откройте файл в режиме конструктора Visual Studio и щелкните ссылку Обозреватель схемы XML. Также можно открыть этот файл в виде кода. Для этого щелкните правой кнопкой мыши в редакторе и выберите команду Показать в обозревателе схемы XML. В любом случае при развертывании большинства узлов схема будет иметь примерно следующий вид:

Все имена XML-элементов в nuspec-файле чувствительны к регистру, как и для XML в целом. Например, использование элемента <description> метаданных правильно и <Description> неправильно. Правильный регистр для каждого имени элемента описан ниже.

Внимание

.nuspec Хотя файл содержит ссылку на схему (xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"), NuGet-Team никогда не опубликовал файл схемы, который можно использовать для автоматической проверки схемы.

Обязательные элементы метаданных

Следующие элементы являются минимальным требованием для пакета, однако, несмотря на это, рекомендуется добавить дополнительные элементы метаданных, чтобы оптимизировать работу с вашим пакетом для разработчиков.

Эти элементы должны использоваться внутри элемента <metadata>.

id

Идентификатор пакета без учета регистра, который должен быть уникальным в пределах сайта nuget.org или иной коллекции, в которой находится пакет. Идентификаторы не должны содержать пробелов или символов, которые недопустимы в URL-адресах, и в них должны соблюдаться общие правила касательно пространств имен .NET. Инструкции см. в разделе Выбор уникального идентификатора пакета.

При отправке пакета в nuget.org id поле ограничено 128 символами.

версия

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

При отправке пакета в nuget.org version поле ограничено 64 символами.

описание

Описание пакета для отображения пользовательского интерфейса.

При отправке пакета в nuget.org description поле ограничено 4000 символами.

authors

Разделенный запятыми список авторов пакетов. При authors отправке пакета в nuget.org игнорируются и owners из nuspec. Сведения о настройке владения пакетами на nuget.org см. в разделе "Управление владельцами пакетов" на nuget.org.

Необязательные элементы метаданных

owners

Внимание

владельцы устарели. Вместо этого используйте авторов.

Разделенный запятыми список владельцев пакетов. Элемент owners nuspec игнорируется при отправке пакета в nuget.org. Сведения о настройке владения пакетами на nuget.org см. в разделе "Управление владельцами пакетов" на nuget.org.

projectUrl

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

При отправке пакета в nuget.org projectUrl поле ограничено 4000 символами.

licenseUrl

Внимание

licenseUrl устарел. Вместо этого используйте лицензию.

URL-адрес лицензии пакета часто отображается в таких интерфейсах, как nuget.org.

При отправке пакета в nuget.org licenseUrl поле ограничено 4000 символами.

лицензия

Поддержка NuGet 4.9.0 и более поздних версий

Выражение лицензии SPDX или путь к файлу лицензии в пакете, часто отображаемое в UIs, например nuget.org. Если вы лицензируете пакет с общей лицензией, например MIT или BSD-2-Предложение, используйте связанный идентификатор лицензии SPDX. Рассмотрим пример.

<license type="expression">MIT</license>

Примечание.

NuGet.org принимает только выражения лицензии, утвержденные инициативой Open Source или Free Software Foundation.

Если пакет лицензирован в нескольких общих лицензиях, можно указать составную лицензию с помощью синтаксиса выражения SPDX версии 2.0. Например:

<license type="expression">BSD-2-Clause OR MIT</license>

Если вы используете пользовательскую лицензию, которая не поддерживается выражениями лицензий, можно упаковить .txt или .md файл с текстом лицензии. Например:

<package>
  <metadata>
    ...
    <license type="file">LICENSE.txt</license>
    ...
  </metadata>
  <files>
    ...
    <file src="licenses\LICENSE.txt" target="" />
    ...
  </files>
</package>

Для эквивалента MSBuild ознакомьтесь с примером упаковки выражения лицензии или файла лицензии.

Точный синтаксис выражений лицензий NuGet описан ниже в ABNF.

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

iconUrl

Внимание

iconUrl устарел. Вместо этого используйте значок.

URL-адрес изображения 128x128 с прозрачностью фона, который будет использоваться в качестве значка пакета в пользовательском интерфейсе. Убедитесь, что этот элемент содержит прямой URL-адрес изображения, а не URL-адрес веб-страницы, на которой содержится изображение. Например, чтобы использовать изображение из GitHub, используйте URL-адрес необработанного файла, например имя пользователя,репозиторий>/<raw>/<branch>/<logo.png>.https://github.com/<

При отправке пакета в nuget.org iconUrl поле ограничено 4000 символами.

значок

Поддержка NuGet 5.3.0 и более поздних версий

Это путь к файлу изображения в пакете, который часто отображается в таких интерфейсах, как nuget.org как значок пакета. Размер файла изображения ограничен 1 МБ. Поддерживаемые форматы файлов включают JPEG и PNG. Рекомендуется разрешение изображений 128x128.

Например, при создании пакета с помощью nuget.exe вы добавите следующее в nuspec:

<package>
  <metadata>
    ...
    <icon>images\icon.png</icon>
    ...
  </metadata>
  <files>
    ...
    <file src="..\icon.png" target="images\" />
    ...
  </files>
</package>

Пример nuspec значка пакета.

Для эквивалента MSBuild ознакомьтесь с файлом изображения значка упаковки.

Совет

Чтобы обеспечить обратную совместимость с клиентами и источниками, которые еще не поддерживаются icon, укажите оба icon и iconUrl. Visual Studio поддерживает icon пакеты, поступающие из источника на основе папок.

Файл сведений

Поддерживается в NuGet 5.10.0( предварительная версия 2 и выше)

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

Например, вы добавите следующее в nuspec, чтобы упаковать файл readme с проектом:

<package>
  <metadata>
    ...
    <readme>docs\readme.md</readme>
    ...
  </metadata>
  <files>
    ...
    <file src="..\readme.md" target="docs\" />
    ...
  </files>
</package>

Для эквивалента MSBuild ознакомьтесь с файлом чтения.

requireLicenseAcceptance

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

developmentDependency

(Версия 2.8 и более поздние) Логическое значение, указывающее, помечен ли пакет как зависимость только для разработки, что позволяет запретить его включение в качестве зависимости в другие пакеты. При использовании PackageReference (NuGet 4.8+) этот флажок также указывает на исключение ресурсов времени компиляции из компиляции. Сведения о поддержке DevelopmentDependency для PackageReference

Итоги

Внимание

summary не рекомендуется. Вместо этого используйте description.

Краткое описание пакета для отображения пользовательского интерфейса. Если этот элемент опущен, используется сокращенная версия элемента description.

При отправке пакета в nuget.org summary поле ограничено 4000 символами.

releaseNotes

(Версия 1.5 и более поздние) Описание изменений, внесенных в этом выпуске пакета NuGet; часто используется в пользовательском интерфейсе как вкладка Обновления диспетчера пакетов Visual Studio вместо описания пакета.

При отправке пакета в nuget.org releaseNotes поле ограничено 35 000 символами.

copyright

(Версия 1.5 и более поздние) Сведения об авторских правах для пакета.

При отправке пакета в nuget.org copyright поле ограничено 4000 символами.

язык

Идентификатор языкового стандарта для пакета. См. раздел Создание локализованных пакетов.

tags

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

При отправке пакета в nuget.org tags поле ограничено 4000 символами.

serviceable

(Версия 3.3 и более поздние) Только для внутреннего использования в NuGet.

Linux

Метаданные репозитория, состоящие из четырех необязательных атрибутов: type и url (4.0+) и commit branch (4.6+). Эти атрибуты позволяют сопоставить репозиторий .nupkg , созданный им, с потенциалом получить как подробное имя отдельной ветви и /или зафиксировать хэш SHA-1, создающий пакет. Это должен быть общедоступный URL-адрес, который можно вызвать непосредственно программным обеспечением управления версиями. Это не должна быть html-страница, так как это предназначено для компьютера. Для связывания со страницей projectUrl проекта используйте поле.

Например:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <repository type="git" url="https://github.com/NuGet/NuGet.Client.git" branch="dev" commit="e1c65e4524cd70ee6e22abe33e6cb6ec73938cb3" />
        ...
    </metadata>
</package>

При отправке пакета в nuget.org type атрибут ограничен 100 символами, а url атрибут ограничен 4000 символами.

title

Понятное название пакета, которое может использоваться в некоторых дисплеях пользовательского интерфейса. (nuget.org и диспетчер пакетов в Visual Studio не отображают название)

При отправке пакета в nuget.org поле ограничено 256 символами, title но не используется для каких-либо целей отображения.

Элементы коллекции

packageTypes

(Версия 3.5 и более поздние) Пустая коллекция или без нескольких элементов <packageType>, определяющих тип пакета, если он отличается от обычного пакета зависимостей. Каждый элемент packageType имеет атрибуты name и version. См. раздел Указание типа пакета.

dependencies

Коллекция из нуля или более элементов <dependency>, задающих зависимости для пакета. Каждый элемент dependency имеет атрибуты id, version, include (версия 3.x и более поздние) и exclude (версия 3.x и более поздние). См. раздел Зависимости далее.

frameworkAssemblies

(Версия 1.2 и более поздние) Коллекция из одного или более элементов <frameworkAssembly>, идентифицирующих ссылки на сборки .NET Framework, необходимые для этого пакета, что гарантирует добавление ссылок в проекты, использующие пакет. Каждый элемент frameworkAssembly имеет атрибуты assemblyName и targetFramework. См. раздел Указание ссылок на сборки платформы в глобальном кэше сборок ниже.

ссылки

(Версия 1.5 и более поздние) Коллекция из нуля или более элементов <reference>, задающие имена сборок в папке lib пакета, которые добавляются в качестве ссылок проекта. Каждый элемент reference имеет атрибут file. Коллекция <references> также может содержать элемент <group> с атрибутом targetFramework, который, в свою очередь, содержит элементы <reference>. Если этот элемент опущен, включаются все ссылки в папке lib. См. раздел Указание явных ссылок на сборки ниже.

contentFiles

(Версия 3.3 и более поздние) Коллекция элементов <files>, которые идентифицируют файлы содержимого, включаемые в потребляющий проект. Эти файлы задаются с набором атрибутов, который описывает их использование в системе проекта. См. раздел Указание включаемых в пакет файлов ниже.

files

Узел <package> может содержать узел как одноуровневый <files> <metadata>элемент и <contentFiles> дочерний <metadata>элемент, чтобы указать, какие сборки и файлы содержимого следует включить в пакет. Дополнительные сведения см. далее в разделах Включение файлов сборки и Включение файлов содержимого этой статьи.

Атрибуты метаданных

minClientVersion

Указывает минимальную версию клиента NuGet, который может установить этот пакет с использованием nuget.exe и диспетчера пакетов Visual Studio. Используется во всех случаях, когда пакет зависит от конкретных функций в файле .nuspec, которые были добавлены в определенной версии клиента NuGet. Например, для пакета, использующего атрибут developmentDependency, атрибуту minClientVersion необходимо присвоить значение "2.8". Аналогичным образом, для пакета, использующего элемент contentFiles (см. следующий раздел), атрибуту minClientVersion необходимо присвоить значение "3.3". Также обратите внимание, что клиенты NuGet версий, предшествующих 2.5, не распознают этот флаг и поэтому всегда отклоняют установку пакета независимо от значения атрибута minClientVersion.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata minClientVersion="100.0.0.1">
        <id>dasdas</id>
        <version>2.0.0</version>
        <title />
        <authors>dsadas</authors>
        <owners />
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>My package description.</description>
    </metadata>
    <files>
        <file src="content\one.txt" target="content\one.txt" />
    </files>
</package>

Замена маркеров

При создании пакета nuget pack команда заменяет маркеры с разделителями $-разделителями в .nuspec файлах <metadata> и <files> узлах значениями, поступающими из файла проекта или pack переключателя команды -properties .

Маркеры задаются в командной строке следующим образом: nuget pack -properties <name>=<value>;<name>=<value>. Например, вы можете использовать маркер, такой как $owners$ и $desc$, в файле .nuspec и предоставить значения во время упаковки следующим образом:

nuget pack MyProject.csproj -properties
    owners=janedoe,harikm,kimo,xiaop;desc="Awesome app logger utility"

Чтобы использовать значения из проекта, укажите маркеры, описываемые в следующей таблице (AssemblyInfo ссылается на файл в Properties, например AssemblyInfo.cs или AssemblyInfo.vb).

Чтобы использовать эти маркеры, выполните команду nuget pack с файлом проекта, а не просто с файлом .nuspec. Например, при использовании следующей команды маркеры $id$ и $version$ в файле .nuspec заменяются значениями проекта AssemblyName и AssemblyVersion:

nuget pack MyProject.csproj

Как правило, при наличии проекта вы изначально создаете файл .nuspec с использованием команды nuget spec MyProject.csproj, которая автоматически включает некоторые из этих стандартных маркеров. Тем не менее, если в проекте отсутствуют значения для обязательных элементов .nuspec, команда nuget pack завершается сбоем. Кроме того, при изменении значений проекта необходимо выполнить перестроение до создания пакета. Это можно легко сделать с помощью параметра build команды pack.

За исключением элемента $configuration$, значения в проекте используются в приоритетном порядке относительно любых значений, назначенных тому же маркеру в командной строке.

Маркер	Источник значения	Значение
$id$	Файл проекта	AssemblyName (title) из файла проекта
$version$	AssemblyInfo	AssemblyInformationalVersion, если присутствует, в противном случае AssemblyVersion
$author$	AssemblyInfo	AssemblyCompany
$title$	AssemblyInfo	AssemblyTitle
$description$	AssemblyInfo	AssemblyDescription
$copyright$	AssemblyInfo	AssemblyCopyright
$configuration$	DLL-файл сборки	Конфигурация, используемая для построения сборки, по умолчанию используется тип отладки. Обратите внимание, что для создания пакета с помощью конфигурации выпуска в командной строке всегда используется параметр -properties Configuration=Release.

Маркеры также можно использовать для разрешения путей при включении файлов сборок и файлов содержимого. Маркеры имеют те же имена, что и свойства MSBuild, что позволяет выбирать файлы для включения в зависимости в текущей конфигурации построения. Например, если вы используете следующие маркеры в файле .nuspec:

<files>
    <file src="bin\$configuration$\$id$.pdb" target="lib\net40" />
</files>

И выполняете построение сборки, для которой AssemblyName имеет значение LoggingLibrary с конфигурацией Release в MSBuild, в файле .nuspec в пакете будут присутствовать следующие строки:

<files>
    <file src="bin\Release\LoggingLibrary.pdb" target="lib\net40" />
</files>

Элемент зависимостей

Элемент <dependencies> внутри элемента <metadata> содержит любое число элементов <dependency>, идентифицирующих другие пакеты, от которых зависит пакет верхнего уровня. Ниже перечислены атрибуты каждого элемента <dependency>:

Атрибут	Description
id	Идентификатор пакета зависимости, например EntityFramework и NUnit, являющийся именем пакета nuget.org, показан на странице пакета (обязательно).
version	Диапазон версий, которые допустимы в качестве зависимости (обязательно). Точный синтаксис см. в разделе Управление версиями пакета. Плавающие версии не поддерживаются.
include	Разделенный запятыми список тегов включения или исключения (см. ниже), определяющий зависимости, включаемые в конечный пакет. Значение по умолчанию — all.
исключение	Разделенный запятыми список тегов включения или исключения (см. ниже), определяющий зависимости, исключаемые из конечного пакета. Значение по умолчанию — build,analyzers это значение, которое можно переписать. Но content/ ContentFiles также неявно исключены в окончательном пакете, который нельзя переписать. Теги в свойстве exclude имеют приоритет перед тегами в свойстве include. Например, include="runtime, compile" exclude="compile" — это тоже самое, что и include="runtime".

При отправке пакета в nuget.org атрибут каждой зависимости id ограничен 128 символами, а version атрибут ограничен 256 символами.

Тег включения или исключения	Затрагиваемые папки пакета
contentFiles	Содержимое
среда выполнения	Runtime, Resources и FrameworkAssemblies
compile	lib
сборка	build (свойства и цели MSBuild)
платформы	платформы
ничего	Нет
all	Все папки

Например, следующие строки указывают зависимости от PackageA версии 1.1.0 или более поздней и PackageB версии 1.x.

<dependencies>
    <dependency id="PackageA" version="1.1.0" />
    <dependency id="PackageB" version="[1,2)" />
</dependencies>

Следующие строки указывают зависимости от тех же пакетов и включают папки contentFiles и build для PackageA, а также все папки, кроме native и compile, для PackageB"

<dependencies>
    <dependency id="PackageA" version="1.1.0" include="contentFiles, build" />
    <dependency id="PackageB" version="[1,2)" exclude="native, compile" />
</dependencies>

Внимание

При создании .nuspec проекта с помощью nuget specзависимостей, которые существуют в этом проекте, не включаются в полученный .nuspec файл автоматически. Вместо этого используйте nuget pack myproject.csprojи получите nuspec-файл из созданного NUPKG-файла . Этот nuspec содержит зависимости.

Группы зависимостей

Версия 2.0 и более поздние

В качестве альтернативы простому неструктурированному списку зависимости могут задаваться в соответствии с профилем платформы целевого проекта с использованием элементов <group> в элементе <dependencies>.

Каждый элемент group имеет атрибут targetFramework и содержит ноль или более элементов <dependency>. Эти зависимости устанавливаются вместе, если целевая платформа совместима с профилем платформы проекта.

Элемент <group> без атрибута targetFramework используется в качестве установленного по умолчанию или резервного списка зависимостей. Точное описание идентификаторов платформы см. в разделе Целевые платформы.

Внимание

Формат группы не может смешиваться с неструктурированным списком.

Примечание.

Формат Moniker Целевой платформы (TFM), используемый в lib/ref папке, отличается по сравнению с используемым в dependency groupsTFM. Если целевые платформы, объявленные в dependencies group папке файла, lib/ref не имеют точных совпадений .nuspec , pack команда вызовет предупреждение NuGet NU5128.

В следующем примере приводятся различные варианты элемента <group>:

<dependencies>
    <group>
        <dependency id="RouteMagic" version="1.1.0" />
    </group>

    <group targetFramework=".NETFramework4.7.2">
        <dependency id="jQuery" version="1.6.2" />
        <dependency id="WebActivator" version="1.4.4" />
    </group>

    <group targetFramework="netcoreapp3.1">
    </group>
</dependencies>

Явные ссылки на сборку

Элемент <references> используется проектами, использующими packages.config для явного указания сборок, на которые должен ссылаться целевой проект при использовании пакета. Явные ссылки обычно применяются для сборок, используемых только во время разработки. Дополнительные сведения см. на странице выбора сборок, на которые ссылаются проекты .

Например, следующий элемент <references> указывает NuGet на необходимость добавлять ссылки только на сборки xunit.dll и xunit.extensions.dll, даже если в пакете есть другие сборки:

<references>
    <reference file="xunit.dll" />
    <reference file="xunit.extensions.dll" />
</references>

Группы ссылок

В качестве альтернативы простому неструктурированному списку ссылки могут задаваться в соответствии с профилем платформы целевого проекта с использованием элементов <group> в элементе <references>.

Каждый элемент group имеет атрибут targetFramework и содержит ноль или более элементов <reference>. Эти ссылки добавляются в проект в том случае, если целевая платформа совместима с профилем платформы проекта.

Элемент <group> без атрибута targetFramework используется в качестве установленного по умолчанию или резервного списка ссылок. Точное описание идентификаторов платформы см. в разделе Целевые платформы.

Внимание

Формат группы не может смешиваться с неструктурированным списком.

В следующем примере приводятся различные варианты элемента <group>:

<references>
    <group>
        <reference file="a.dll" />
    </group>

    <group targetFramework="net45">
        <reference file="b45.dll" />
    </group>

    <group targetFramework="netcore45">
        <reference file="bcore45.dll" />
    </group>
</references>

Ссылки на сборку платформы

Сборки платформы входят в состав .NET Framework и должны находиться в глобальном кэше сборок любого заданного компьютера. Идентифицируя такие сборки с помощью элемента <frameworkAssemblies>, пакет может гарантировать, что ссылки, отсутствующие в проекте, будут при необходимости добавлены в него. Естественно, напрямую в пакет такие сборки не включаются.

Элемент <frameworkAssemblies> содержит ноль или более элементов <frameworkAssembly>, каждый из которых задает следующие атрибуты:

Атрибут	Description
имя_сборки	Полное имя сборки (обязательно).
targetFramework	Указывает целевую платформу, к которой применяется эта ссылка (необязательно). Если этот атрибут опущен, указывает, что ссылка применяется ко всем платформам. Точное описание идентификаторов платформы см. в разделе Целевые платформы.

В следующем примере показаны ссылка на System.Net для всех целевых платформ и ссылка на System.ServiceModel только для платформы .NET Framework 4.0:

<frameworkAssemblies>
    <frameworkAssembly assemblyName="System.Net"  />

    <frameworkAssembly assemblyName="System.ServiceModel" targetFramework="net40" />
</frameworkAssemblies>

Включение файлов сборки

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

Внимание

Когда пакет устанавливается в проекте, NuGet автоматически добавляет ссылки на библиотеки DLL сборок в пакете, кроме тех из них, в именах которых есть .resources.dll, так как они считаются локализованными вспомогательными сборками. По этой причине следует избегать использования .resources.dll в именах файлов пакета, которые содержат важный код.

Чтобы обойти такое автоматическое поведение и явно управлять включением сборок в пакет, поместите элемент <files> в качестве дочернего для <package> (на одном уровне с <metadata>), указывая каждый файл с помощью элемента <file>. Например:

<files>
    <file src="bin\Debug\*.dll" target="lib" />
    <file src="bin\Debug\*.pdb" target="lib" />
    <file src="tools\**\*.*" exclude="**\*.log" />
</files>

В NuGet версии 2.x и более ранних в проектах, использующих packages.config, элемент <files> также используется для включения неизменяемых файлов содержимого при установке пакета. В NuGet версии 3.3 и более поздних и проектах PackageReference используется элемент <contentFiles>. Дополнительные сведения см. в разделе Включение файлов содержимого.

Атрибуты элементов файла

Каждый элемент <file> задает указанные ниже атрибуты:

Атрибут	Description
src	Расположение файла или файлов, которые требуется включить, с учетом исключений, задаваемых атрибутом exclude. Если не указан абсолютный путь, этот путь задается относительно файла .nuspec. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.
целевой объект	Относительный путь к папке в пакете, куда помещаются файлы исходного кода. Должен начинаться с lib, content, build или tools. См. раздел Создание файла NUSPEC на основе рабочего каталога, соответствующего соглашениям.
exclude	Разделенный точками с запятой список файлов или шаблонов файлов, которые исключаются из расположения src. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.

Примеры

Одна сборка

Source file:
    library.dll

.nuspec entry:
    <file src="library.dll" target="lib" />

Packaged result:
    lib\library.dll

Одна сборка, относящаяся к целевой платформе

Source file:
    library.dll

.nuspec entry:
    <file src="assemblies\net40\library.dll" target="lib\net40" />

Packaged result:
    lib\net40\library.dll

Набор DLL-файлов с использованием подстановочного знака

Source files:
    bin\release\libraryA.dll
    bin\release\libraryB.dll

.nuspec entry:
    <file src="bin\release\*.dll" target="lib" />

Packaged result:
    lib\libraryA.dll
    lib\libraryB.dll

DLL-файлы для разных платформ

Source files:
    lib\net40\library.dll
    lib\net20\library.dll

.nuspec entry (using ** recursive search):
    <file src="lib\**" target="lib" />

Packaged result:
    lib\net40\library.dll
    lib\net20\library.dll

Исключение файлов

Source files:
    \tools\fileA.bak
    \tools\fileB.bak
    \tools\fileA.log
    \tools\build\fileB.log

.nuspec entries:
    <file src="tools\*.*" target="tools" exclude="tools\*.bak" />
    <file src="tools\**\*.*" target="tools" exclude="**\*.log" />

Package result:
    (no files)

Включение файлов содержимого

Файлы содержимого — это неизменяемые файлы, которые пакету необходимо включить в проект. Такие файлы не подлежат изменению проектом, который потребляет их. Примеры файлов содержимого:

• Изображения, внедряемые в качестве ресурсов
• Файлы исходного кода, которые уже были скомпилированы
• Скрипты, которые необходимо включить в выходные данные построения проекта
• Файлы конфигурации для пакета, которые необходимо включить в проект, но не требуется изменять в рамках отдельного проекта

Файлы содержимого включаются в проект с помощью элемента <files>, задающего папку content в атрибуте target. Тем не менее такие файлы игнорируются при установке пакета в проект с использованием PackageReference, в которых вместо этого используется элемент <contentFiles>.

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

Использование элемента files для файлов содержимого

Для файлов содержимого следует использовать тот же формат, что и для файлов сборки, однако необходимо указать в качестве базовой сборки content в атрибуте target, как показано в следующих примерах.

Базовые файлы содержимого

Source files:
    css\mobile\style1.css
    css\mobile\style2.css

.nuspec entry:
    <file src="css\mobile\*.css" target="content\css\mobile" />

Packaged result:
    content\css\mobile\style1.css
    content\css\mobile\style2.css

Файлы содержимого со структурой каталогов

Source files:
    css\mobile\style.css
    css\mobile\wp7\style.css
    css\browser\style.css

.nuspec entry:
    <file src="css\**\*.css" target="content\css" />

Packaged result:
    content\css\mobile\style.css
    content\css\mobile\wp7\style.css
    content\css\browser\style.css

Файлы содержимого, относящиеся к целевой платформе

Source file:
    css\cool\style.css

.nuspec entry
    <file src="css\cool\style.css" target="Content" />

Packaged result:
    content\style.css

Файлы содержимого, копируемые в папку с точкой в имени

В этом случае NuGet определяет, что расширение в атрибуте target не соответствует расширению в src и обрабатывает такую часть имени в атрибуте target как папку:

Source file:
    images\picture.png

.nuspec entry:
    <file src="images\picture.png" target="Content\images\package.icons" />

Packaged result:
    content\images\package.icons\picture.png

Файлы содержимого без расширений

Чтобы включить файлы без расширения, используйте подстановочные знаки * или **:

Source file:
    flags\installed

.nuspec entry:
    <file src="flags\**" target="flags" />

Packaged result:
    flags\installed

Файлы содержимого с глубоким путем и глубоким целевым объектом

В этом случае из-за совпадения расширений файлов для исходного и целевого объектов NuGet предполагает, что целевой объект задает имя файла, а не папки:

Source file:
    css\cool\style.css

.nuspec entry:
    <file src="css\cool\style.css" target="Content\css\cool" />
    or:
    <file src="css\cool\style.css" target="Content\css\cool\style.css" />

Packaged result:
    content\css\cool\style.css

Переименование файла содержимого в пакете

Source file:
    ie\css\style.css

.nuspec entry:
    <file src="ie\css\style.css" target="Content\css\ie.css" />

Packaged result:
    content\css\ie.css

Исключение файлов

Source file:
    docs\*.txt (multiple files)

.nuspec entry:
    <file src="docs\*.txt" target="content\docs" exclude="docs\admin.txt" />
    or
    <file src="*.txt" target="content\docs" exclude="admin.txt;log.txt" />

Packaged result:
    All .txt files from docs except admin.txt (first example)
    All .txt files from docs except admin.txt and log.txt (second example)

Использование элемента contentFiles для файлов содержимого

NuGet 4.0 и более поздней версии с PackageReference

По умолчанию пакет помещает содержимое в папку contentFiles (см. ниже), а команда nuget pack включает все файлы в этой папке с использованием установленных по умолчанию атрибутов. В этом случае включать узел contentFiles в файл .nuspec не требуется.

Чтобы управлять включаемыми файлами, элемент <contentFiles> задает коллекцию элементов <files>, которая точно определяет включаемые файлы.

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

Атрибут	Description
include	Расположение файла или файлов, которые требуется включить, с учетом исключений, задаваемых атрибутом exclude (обязательно). Путь относительно contentFiles папки, если не указан абсолютный путь. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.
exclude	Разделенный точками с запятой список файлов или шаблонов файлов, которые исключаются из расположения src. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.
buildAction	Действие сборки, назначающее элементу содержимого для MSBuild, например Content, None, Embedded Resourceи Compileт. д. Значение по умолчанию — Compile.
copyToOutput	Логическое значение, указывающее, следует ли копировать элементы содержимого в папку выходных данных сборки (или публикации). Значение по умолчанию — false.
flatten	Логическое значение, указывающее на необходимость копировать элементы содержимого в одну папку в выходных данных построения (true) или сохранить структуру папок пакета (false). Этот параметр применяется, только если для параметра copyToOutput установлено значение true. Значение по умолчанию — false.

При установке пакета NuGet применяет дочерние элементы <contentFiles> в порядке сверху вниз. Если одному файлу соответствует несколько записей, применяются все записи. При обнаружении конфликтов для одного атрибута запись верхнего уровня переопределяет записи на нижних уровнях.

Структура папки пакета

Структурирование содержимого в проекте пакета осуществляется по следующему шаблону:

/contentFiles/{codeLanguage}/{TxM}/{any?}

• Элемент codeLanguages может иметь значение cs, vb, fs, any или любой другой эквивалент заданного $(ProjectLanguage) в нижнем регистре
• Элемент TxM представляет любой допустимый моникер целевой платформы, поддерживаемой NuGet (см. раздел Целевые платформы).
• В конце этого синтаксиса может добавляться любая структура папок.

Например:

Language- and framework-agnostic:
    /contentFiles/any/any/config.xml

net45 content for all languages
    /contentFiles/any/net45/config.xml

C#-specific content for net45 and up
    /contentFiles/cs/net45/sample.cs

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

/contentFiles/vb/any/code.vb
/contentFiles/cs/any/.

Пример раздела contentFiles

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        ...
        <contentFiles>
            <!-- Embed image resources -->
            <files include="any/any/images/dnf.png" buildAction="EmbeddedResource" />
            <files include="any/any/images/ui.png" buildAction="EmbeddedResource" />

            <!-- Embed all image resources under contentFiles/cs/ -->
            <files include="cs/**/*.png" buildAction="EmbeddedResource" />

            <!-- Copy config.xml to the root of the output folder -->
            <files include="cs/uap/config/config.xml" buildAction="None" copyToOutput="true" flatten="true" />

            <!-- Copy run.cmd to the output folder and keep the directory structure -->
            <files include="cs/commands/run.cmd" buildAction="None" copyToOutput="true" flatten="false" />

            <!-- Include everything in the scripts folder except exe files -->
            <files include="cs/net45/scripts/*" exclude="**/*.exe"  buildAction="None" copyToOutput="true" />
        </contentFiles>
        </metadata>
</package>

Справочные группы платформы

Только версия 5.1+ wih PackageReference

Ссылки на платформу — это концепция .NET Core, представляющая общие платформы, такие как WPF или Windows Forms. Указав общую платформу, пакет гарантирует, что все его зависимости платформы включены в проект ссылки.

Для каждого <group> элемента требуется targetFramework атрибут и ноль или несколько <frameworkReference> элементов.

В следующем примере показан nuspec, созданный для проекта WPF .NET Core. Обратите внимание, что не рекомендуется создавать nuspecs, содержащие ссылки на платформу. Вместо этого рекомендуется использовать пакет целевых объектов , который автоматически выводит их из проекта.

<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <dependencies>
      <group targetFramework=".NETCoreApp3.1" />
    </dependencies>
    <frameworkReferences>
      <group targetFramework=".NETCoreApp3.1">
        <frameworkReference name="Microsoft.WindowsDesktop.App.WPF" />
      </group>
    </frameworkReferences>
  </metadata>
</package>

Примеры файлов nuspec

Простой файл .nuspec, в котором не задаются зависимости или файлы

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.2.3</version>
        <authors>Kim Abercrombie, Franck Halmaert</authors>
        <description>Sample exists only to show a sample .nuspec file.</description>
        <language>en-US</language>
        <projectUrl>http://xunit.codeplex.com/</projectUrl>
        <license type="expression">MIT</license>
    </metadata>
</package>

Файл .nuspec с зависимостями

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>sample</id>
        <version>1.0.0</version>
        <authors>Microsoft</authors>
        <dependencies>
            <dependency id="another-package" version="3.0.0" />
            <dependency id="yet-another-package" version="1.0.0" />
        </dependencies>
    </metadata>
</package>

Файл .nuspec с файлами

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>routedebugger</id>
        <version>1.0.0</version>
        <authors>Jay Hamlin</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Route Debugger is a little utility I wrote...</description>
    </metadata>
    <files>
        <file src="bin\Debug\*.dll" target="lib" />
    </files>
</package>

Файл .nuspec со сборками платформы

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>PackageWithGacReferences</id>
        <version>1.0</version>
        <authors>Author here</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>
            A package that has framework assemblyReferences depending
            on the target framework.
        </description>
        <frameworkAssemblies>
            <frameworkAssembly assemblyName="System.Web" targetFramework="net40" />
            <frameworkAssembly assemblyName="System.Net" targetFramework="net40-client, net40" />
            <frameworkAssembly assemblyName="Microsoft.Devices.Sensors" targetFramework="sl4-wp" />
            <frameworkAssembly assemblyName="System.Json" targetFramework="sl3" />
        </frameworkAssemblies>
    </metadata>
</package>

В этом примере для целевых объектов проекта устанавливаются следующие компоненты:

• . NET4 ->System.Web, System.Net
• . Профиль клиента NET4 —>System.Net
• Silverlight 3 ->System.Json
• WindowsPhone —>Microsoft.Devices.Sensors