Справочник по файлу 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>
.
Идентификатор пакета без учета регистра, который должен быть уникальным в пределах сайта nuget.org или иной коллекции, в которой находится пакет. Идентификаторы не должны содержать пробелов или символов, которые недопустимы в URL-адресах, и в них должны соблюдаться общие правила касательно пространств имен .NET. Инструкции см. в разделе Выбор уникального идентификатора пакета.
При отправке пакета в nuget.org id
поле ограничено 128 символами.
Версия пакета, указываемая согласно шаблону основной_номер.дополнительный_номер.исправление. Номер версии может включать в себя суффикс предварительной версии, как описано в разделе Управление версиями пакета.
При отправке пакета в nuget.org version
поле ограничено 64 символами.
Описание пакета для отображения пользовательского интерфейса.
При отправке пакета в nuget.org description
поле ограничено 4000 символами.
Разделенный запятыми список авторов пакетов.
При authors
отправке пакета в nuget.org игнорируются и owners
из nuspec. Сведения о настройке владения пакетами на nuget.org см. в разделе "Управление владельцами пакетов" на nuget.org.
Важно!
владельцы устарели. Вместо этого используйте авторов.
Разделенный запятыми список владельцев пакетов.
Элемент owners
nuspec игнорируется при отправке пакета в nuget.org. Сведения о настройке владения пакетами на nuget.org см. в разделе "Управление владельцами пакетов" на nuget.org.
URL-адрес для домашней страницы пакета, часто указываемый при отображении пользовательского интерфейса, также как и nuget.org.
При отправке пакета в nuget.org projectUrl
поле ограничено 4000 символами.
Важно!
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 устарел. Вместо этого используйте значок.
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>
Для эквивалента 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 ознакомьтесь с файлом чтения.
Логическое значение, указывающее, должен ли клиент просить потребителя принять условия лицензии перед установкой пакета.
(Версия 2.8 и более поздние) Логическое значение, указывающее, помечен ли пакет как зависимость только для разработки, что позволяет запретить его включение в качестве зависимости в другие пакеты. При использовании PackageReference (NuGet 4.8+) этот флажок также указывает на исключение ресурсов времени компиляции из компиляции. Сведения о поддержке DevelopmentDependency для PackageReference
Важно!
summary
не рекомендуется. Вместо этого используйте description
.
Краткое описание пакета для отображения пользовательского интерфейса. Если этот элемент опущен, используется сокращенная версия элемента description
.
При отправке пакета в nuget.org summary
поле ограничено 4000 символами.
(Версия 1.5 и более поздние) Описание изменений, внесенных в этом выпуске пакета NuGet; часто используется в пользовательском интерфейсе как вкладка Обновления диспетчера пакетов Visual Studio вместо описания пакета.
При отправке пакета в nuget.org releaseNotes
поле ограничено 35 000 символами.
(Версия 1.5 и более поздние) Сведения об авторских правах для пакета.
При отправке пакета в nuget.org copyright
поле ограничено 4000 символами.
Идентификатор языкового стандарта для пакета. См. раздел Создание локализованных пакетов.
Список разделенных пробелами тегов и ключевых слов, описывающих пакет NuGet и помогающих находить пакеты NuGet с помощью функций поиска и фильтрации.
При отправке пакета в nuget.org tags
поле ограничено 4000 символами.
(Версия 3.3 и более поздние) Только для внутреннего использования в NuGet.
Метаданные репозитория, состоящие из четырех необязательных атрибутов: 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 символами.
Понятное название пакета, которое может использоваться в некоторых дисплеях пользовательского интерфейса. (nuget.org и диспетчер пакетов в Visual Studio не отображают название)
При отправке пакета в nuget.org поле ограничено 256 символами, title
но не используется для каких-либо целей отображения.
(Версия 3.5 и более поздние) Пустая коллекция или без нескольких элементов <packageType>
, определяющих тип пакета, если он отличается от обычного пакета зависимостей. Каждый элемент packageType имеет атрибуты name и version. См. раздел Указание типа пакета.
Коллекция из нуля или более элементов <dependency>
, задающих зависимости для пакета. Каждый элемент dependency имеет атрибуты id, version, include (версия 3.x и более поздние) и exclude (версия 3.x и более поздние). См. раздел Зависимости далее.
(Версия 1.2 и более поздние) Коллекция из одного или более элементов <frameworkAssembly>
, идентифицирующих ссылки на сборки .NET Framework, необходимые для этого пакета, что гарантирует добавление ссылок в проекты, использующие пакет. Каждый элемент frameworkAssembly имеет атрибуты assemblyName и targetFramework. См. раздел Указание ссылок на сборки платформы в глобальном кэше сборок ниже.
(Версия 1.5 и более поздние) Коллекция из нуля или более элементов <reference>
, задающие имена сборок в папке lib
пакета, которые добавляются в качестве ссылок проекта. Каждый элемент reference имеет атрибут file. Коллекция <references>
также может содержать элемент <group>
с атрибутом targetFramework, который, в свою очередь, содержит элементы <reference>
. Если этот элемент опущен, включаются все ссылки в папке lib
. См. раздел Указание явных ссылок на сборки ниже.
(Версия 3.3 и более поздние) Коллекция элементов <files>
, которые идентифицируют файлы содержимого, включаемые в потребляющий проект. Эти файлы задаются с набором атрибутов, который описывает их использование в системе проекта. См. раздел Указание включаемых в пакет файлов ниже.
Узел <package>
может содержать узел как одноуровневый <files>
<metadata>
элемент и <contentFiles>
дочерний <metadata>
элемент, чтобы указать, какие сборки и файлы содержимого следует включить в пакет. Дополнительные сведения см. далее в разделах Включение файлов сборки и Включение файлов содержимого этой статьи.
Указывает минимальную версию клиента 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 groups
TFM. Если целевые платформы, объявленные в 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>
.
Чтобы обеспечить максимальную совместимость с потребляющими проектами, в идеальном случае файлы содержимого следует задавать в проекте с использованием обоих элементов.
Для файлов содержимого следует использовать тот же формат, что и для файлов сборки, однако необходимо указать в качестве базовой сборки 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)
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/_._
<?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
, в котором не задаются зависимости или файлы
<?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