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

Файл .nuspec представляет собой манифест в формате XML и содержит метаданные пакета.A .nuspec file is an XML manifest that contains package metadata. Этот манифест используется при построении пакета и содержит дополнительные сведения для его потребителей.This manifest is used both to build the package and to provide information to consumers. Манифест всегда включается в пакет.The manifest is always included in a package.

В этом разделе.In this topic:

Общая форма и схемаGeneral form and schema

Текущий файл схемы nuspec.xsd представлен в репозитории GitHub для NuGet.The current nuspec.xsd schema file can be found in the NuGet GitHub repository.

В рамках этой схемы файл .nuspec имеет следующую общую форму:Within this schema, a .nuspec file has the following general form:

<?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.For a clear visual representation of the schema, open the schema file in Visual Studio in Design mode and click on the XML Schema Explorer link. Также можно открыть этот файл в виде кода. Для этого щелкните правой кнопкой мыши в редакторе и выберите команду Показать в обозревателе схемы XML.Alternately, open the file as code, right-click in the editor, and select Show XML Schema Explorer. В любом случае при развертывании большинства узлов схема будет иметь примерно следующий вид:Either way you get a view like the one below (when mostly expanded):

Обозреватель схемы Visual Studio с открытым файлом nuspec.xsd

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

Следующие элементы являются минимальным требованием для пакета, однако, несмотря на это, рекомендуется добавить дополнительные элементы метаданных, чтобы оптимизировать работу с вашим пакетом для разработчиков.Although the following elements are the minimum requirements for a package, you should consider adding the optional metadata elements to improve the overall experience developers have with your package.

Эти элементы должны использоваться внутри элемента <metadata>.These elements must appear within a <metadata> element.

idid

Идентификатор пакета без учета регистра, который должен быть уникальным в пределах сайта nuget.org или иной коллекции, в которой находится пакет.The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package resides in. Идентификаторы не должны содержать пробелов или символов, которые недопустимы в URL-адресах, и в них должны соблюдаться общие правила касательно пространств имен .NET.IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules. Инструкции см. в разделе Выбор уникального идентификатора пакета.See Choosing a unique package identifier for guidance.

versionversion

Версия пакета, указываемая согласно шаблону основной_номер.дополнительный_номер.исправление.The version of the package, following the major.minor.patch pattern. Номер версии может включать в себя суффикс предварительной версии, как описано в разделе Управление версиями пакета.Version numbers may include a pre-release suffix as described in Package versioning.

Описаниеdescription

Подробное описание пакета для отображения пользовательского интерфейса.A long description of the package for UI display.

authorsauthors

Разделенный запятыми список авторов пакетов, совпадающих с именами профилей на сайте nuget.org. Они отображаются в коллекции NuGet на сайте nuget.org и используются для перекрестных ссылок на пакеты тех же авторов.A comma-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.

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

заголовокtitle

Понятный заголовок пакета, обычно используемый при отображении пользовательского интерфейса, как на сайте nuget.org и в диспетчере пакетов Visual Studio.A human-friendly title of the package, typically used in UI displays as on nuget.org and the Package Manager in Visual Studio. Если значение не указано, используется идентификатор пакета.If not specified, the package ID is used.

ownersowners

Разделенный запятыми список создателей пакета, совпадающих с именами профилей на сайте nuget.org. Часто совпадает со списком в элементе authors и игнорируется при загрузке пакета на веб-сайт nuget.org. См. раздел Управление владельцами пакетов на веб-сайте nuget.org.A comma-separated list of the package creators using profile names on nuget.org. This is often the same list as in authors, and is ignored when uploading the package to nuget.org. See Managing package owners on nuget.org.

projectUrlprojectUrl

URL-адрес для домашней страницы пакета, часто указываемый при отображении пользовательского интерфейса, также как и nuget.org.A URL for the package's home page, often shown in UI displays as well as nuget.org.

licenseUrllicenseUrl

Важно!

licenseUrl устарел.licenseUrl is being deprecated. Вместо этого используйте лицензию.Use license instead.

URL-адрес для лицензии пакета, часто указываемый при отображении пользовательского интерфейса, так же как и nuget.org.A URL for the package's license, often shown in UI displays as well as nuget.org.

лицензииlicense

Выражение SPDX лицензии или путь к файлу лицензии внутри пакета, часто отображающийся в пользовательском интерфейсе как nuget.org. Если лицензируется пакета распространенных лицензия, например BSD-2-предложение или MIT, используйте связанный идентификатор SPDX лицензии.An SPDX license expression or path to a license file within the package, often shown in UI displays as well as nuget.org. If you’re licensing the package under a common license such as BSD-2-Clause or MIT, use the associated SPDX license identifier.
Пример: <license type="expression">MIT</license>For example: <license type="expression">MIT</license>

Ниже приведен полный список SPDX лицензии идентификаторы.Here is the complete list of SPDX license identifiers. NuGet.org принимает только OSI или утверждены FSF лицензии при использовании лицензий выражение типа.NuGet.org accepts only OSI or FSF approved licenses when using license type expression.

Если ваш пакет лицензируется распространенных сразу несколько лицензий, можно указать составного лицензии с помощью SPDX выражение синтаксис версии 2.0.If your package is licensed under multiple common licenses, you can specify a composite license using the SPDX expression syntax version 2.0.
Пример: <license type="expression">BSD-2-Clause OR MIT</license>For example: <license type="expression">BSD-2-Clause OR MIT</license>

Если вы используете лицензию, которая не была назначена SPDX идентификатор или он является пользовательской лицензии, вы можете упаковать файл с текстом лицензии.If you are using a license that hasn’t been assigned an SPDX identifier, or it is a custom license, you can package a file with the license text. Пример:For example:

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

Для эквивалентных MSBuild, взгляните на упаковки выражении лицензии или файл лицензии.For the MSBuild equivalent, take a look at Packing a license expression or a license file.

Точный синтаксис выражений лицензии NuGet описан ниже в ABNF.The exact syntax of NuGet's license expressions is described below in 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)

iconUrliconUrl

URL-адрес для изображения размером 64x64 с прозрачным фоном, используемого в качестве значка для пакета при отображении пользовательского интерфейса.A URL for a 64x64 image with transparency background to use as the icon for the package in UI display. Убедитесь, что этот элемент содержит прямой URL-адрес изображения, а не URL-адрес веб-страницы, на которой содержится изображение.Be sure this element contains the direct image URL and not the URL of a web page containing the image. Например, чтобы использовать изображение из GitHub, используйте необработанного файла, URL-адрес, например https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.For example, to use an image from GitHub, use the raw file URL like https://github.com/<username>/<repository>/raw/<branch>/<logo.png>.

requireLicenseAcceptancerequireLicenseAcceptance

Логическое значение, указывающее, должен ли клиент просить потребителя принять условия лицензии перед установкой пакета.A Boolean value specifying whether the client must prompt the consumer to accept the package license before installing the package.

developmentDependencydevelopmentDependency

(Версия 2.8 и более поздние) Логическое значение, указывающее, помечен ли пакет как зависимость только для разработки, что позволяет запретить его включение в качестве зависимости в другие пакеты.(2.8+) A Boolean value specifying whether the package is be marked as a development-only-dependency, which prevents the package from being included as a dependency in other packages. С помощью PackageReference (NuGet 4.8 +) этот флаг также означает, что исключает средств компиляции от компиляции.With PackageReference (NuGet 4.8+), this flag also means that it will exclude compile-time assets from compilation. См. в разделе DevelopmentDependency поддержка формата PackageReferenceSee DevelopmentDependency support for PackageReference

сводкаsummary

Краткое описание пакета для отображения пользовательского интерфейса.A short description of the package for UI display. Если этот элемент опущен, используется сокращенная версия элемента description.If omitted, a truncated version of description is used.

releaseNotesreleaseNotes

(Версия 1.5 и более поздние) Описание изменений, внесенных в этом выпуске пакета NuGet; часто используется в пользовательском интерфейсе как вкладка Обновления диспетчера пакетов Visual Studio вместо описания пакета.(1.5+) A description of the changes made in this release of the package, often used in UI like the Updates tab of the Visual Studio Package Manager in place of the package description.

(Версия 1.5 и более поздние) Сведения об авторских правах для пакета.(1.5+) Copyright details for the package.

языкlanguage

Идентификатор языкового стандарта для пакета.The locale ID for the package. См. раздел Создание локализованных пакетов.See Creating localized packages.

тегиtags

Список разделенных пробелами тегов и ключевых слов, описывающих пакет NuGet и помогающих находить пакеты NuGet с помощью функций поиска и фильтрации.A space-delimited list of tags and keywords that describe the package and aid discoverability of packages through search and filtering.

обслуживаниюserviceable

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

репозиторийrepository

Репозиторий метаданных, состоящий из четыре необязательных атрибута: тип и URL-адрес (4.0 или более поздней), и ветви и фиксации (4.6 или более поздней).Repository metadata, consisting of four optional attributes: type and url (4.0+), and branch and commit (4.6+). Эти атрибуты позволяют сопоставлять файла nupkg в репозиторий, построении, с потенциально могут стать как описано, как отдельные ветви или фиксации, который создан пакет.These attributes allow you to map the .nupkg to the repository that built it, with the potential to get as detailed as the individual branch or commit that built the package. Это должен быть общедоступным URL-адрес, который может вызываться напрямую по для управления версиями.This should be a publicly available url that can be invoked directly by a version control software. Он не должно быть HTML-страницы, как это предназначено для компьютера.It should not be an html page as this is meant for the computer. Для связывания страницу проекта, используйте projectUrl , вместо этого поле.For linking to project page, use the projectUrl field, instead.

MinClientVersionminClientVersion

Указывает минимальную версию клиента NuGet, который может установить этот пакет с использованием nuget.exe и диспетчера пакетов Visual Studio.Specifies the minimum version of the NuGet client that can install this package, enforced by nuget.exe and the Visual Studio Package Manager. Используется во всех случаях, когда пакет зависит от конкретных функций в файле .nuspec, которые были добавлены в определенной версии клиента NuGet.This is used whenever the package depends on specific features of the .nuspec file that were added in a particular version of the NuGet client. Например, для пакета, использующего атрибут developmentDependency, атрибуту minClientVersion необходимо присвоить значение "2.8".For example, a package using the developmentDependency attribute should specify "2.8" for minClientVersion. Аналогичным образом, для пакета, использующего элемент contentFiles (см. следующий раздел), атрибуту minClientVersion необходимо присвоить значение "3.3".Similarly, a package using the contentFiles element (see the next section) should set minClientVersion to "3.3". Также обратите внимание, что клиенты NuGet версий, предшествующих 2.5, не распознают этот флаг и поэтому всегда отклоняют установку пакета независимо от значения атрибута minClientVersion.Note also that because NuGet clients prior to 2.5 do not recognize this flag, they always refuse to install the package no matter what minClientVersion contains.

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

PackageTypespackageTypes

(Версия 3.5 и более поздние) Пустая коллекция или без нескольких элементов <packageType>, определяющих тип пакета, если он отличается от обычного пакета зависимостей.(3.5+) A collection of zero or more <packageType> elements specifying the type of the package if other than a traditional dependency package. Каждый элемент packageType имеет атрибуты name и version.Each packageType has attributes of name and version. См. раздел Указание типа пакета.See Setting a package type.

зависимостиdependencies

Коллекция из нуля или более элементов <dependency>, задающих зависимости для пакета.A collection of zero or more <dependency> elements specifying the dependencies for the package. Каждый элемент dependency имеет атрибуты id, version, include (версия 3.x и более поздние) и exclude (версия 3.x и более поздние).Each dependency has attributes of id, version, include (3.x+), and exclude (3.x+). См. раздел Зависимости далее.See Dependencies below.

frameworkAssembliesframeworkAssemblies

(Версия 1.2 и более поздние) Коллекция из одного или более элементов <frameworkAssembly>, идентифицирующих ссылки на сборки .NET Framework, необходимые для этого пакета, что гарантирует добавление ссылок в проекты, использующие пакет.(1.2+) A collection of zero or more <frameworkAssembly> elements identifying .NET Framework assembly references that this package requires, which ensures that references are added to projects consuming the package. Каждый элемент frameworkAssembly имеет атрибуты assemblyName и targetFramework.Each frameworkAssembly has assemblyName and targetFramework attributes. См. раздел Указание ссылок на сборки платформы в глобальном кэше сборок ниже.See Specifying framework assembly references GAC below. |

ссылкиreferences

(Версия 1.5 и более поздние) Коллекция из нуля или более элементов <reference>, задающие имена сборок в папке lib пакета, которые добавляются в качестве ссылок проекта.(1.5+) A collection of zero or more <reference> elements naming assemblies in the package's lib folder that are added as project references. Каждый элемент reference имеет атрибут file.Each reference has a file attribute. Коллекция <references> также может содержать элемент <group> с атрибутом targetFramework, который, в свою очередь, содержит элементы <reference>.<references> can also contain a <group> element with a targetFramework attribute, that then contains <reference> elements. Если этот элемент опущен, включаются все ссылки в папке lib.If omitted, all references in lib are included. См. раздел Указание явных ссылок на сборки ниже.See Specifying explicit assembly references below.

contentFilescontentFiles

(Версия 3.3 и более поздние) Коллекция элементов <files>, которые идентифицируют файлы содержимого, включаемые в потребляющий проект.(3.3+) A collection of <files> elements that identify content files to include in the consuming project. Эти файлы задаются с набором атрибутов, который описывает их использование в системе проекта.These files are specified with a set of attributes that describe how they should be used within the project system. См. раздел Указание включаемых в пакет файлов ниже.See Specifying files to include in the package below.

файлыfiles

<package> Узел может содержать <files> узел как одноуровневый элемент <metadata>и <contentFiles> дочерний элемент в <metadata>, чтобы указать, какие файлы сборки и содержимого, следует включить в пакет.The <package> node may contain a <files> node as a sibling to <metadata>, and a <contentFiles> child under <metadata>, to specify which assembly and content files to include in the package. Дополнительные сведения см. далее в разделах Включение файлов сборки и Включение файлов содержимого этой статьи.See Including assembly files and Including content files later in this topic for details.

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

При создании пакета команда nuget pack заменяет маркеры с разделителями $ в узле <metadata> файла .nuspec значениями из файла проекта или параметра -properties команды pack.When creating a package, the nuget pack command replaces $-delimited tokens in the .nuspec file's <metadata> node with values that come from either a project file or the pack command's -properties switch.

Маркеры задаются в командной строке следующим образом: nuget pack -properties <name>=<value>;<name>=<value>.On the command line, you specify token values with nuget pack -properties <name>=<value>;<name>=<value>. Например, вы можете использовать маркер, такой как $owners$ и $desc$, в файле .nuspec и предоставить значения во время упаковки следующим образом:For example, you can use a token such as $owners$ and $desc$ in the .nuspec and provide the values at packing time as follows:

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

Чтобы использовать значения из проекта, укажите маркеры, описываемые в следующей таблице (AssemblyInfo ссылается на файл в Properties, например AssemblyInfo.cs или AssemblyInfo.vb).To use values from a project, specify the tokens described in the table below (AssemblyInfo refers to the file in Properties such as AssemblyInfo.cs or AssemblyInfo.vb).

Чтобы использовать эти маркеры, выполните команду nuget pack с файлом проекта, а не просто с файлом .nuspec.To use these tokens, run nuget pack with the project file rather than just the .nuspec. Например, при использовании следующей команды маркеры $id$ и $version$ в файле .nuspec заменяются значениями проекта AssemblyName и AssemblyVersion:For example, when using the following command, the $id$ and $version$ tokens in a .nuspec file are replaced with the project's AssemblyName and AssemblyVersion values:

nuget pack MyProject.csproj

Как правило, при наличии проекта вы изначально создаете файл .nuspec с использованием команды nuget spec MyProject.csproj, которая автоматически включает некоторые из этих стандартных маркеров.Typically, when you have a project, you create the .nuspec initially using nuget spec MyProject.csproj which automatically includes some of these standard tokens. Тем не менее, если в проекте отсутствуют значения для обязательных элементов .nuspec, команда nuget pack завершается сбоем.However, if a project lacks values for required .nuspec elements, then nuget pack fails. Кроме того, при изменении значений проекта необходимо выполнить перестроение до создания пакета. Это можно легко сделать с помощью параметра build команды pack.Furthermore, if you change project values, be sure to rebuild before creating the package; this can be done conveniently with the pack command's build switch.

За исключением элемента $configuration$, значения в проекте используются в приоритетном порядке относительно любых значений, назначенных тому же маркеру в командной строке.With the exception of $configuration$, values in the project are used in preference to any assigned to the same token on the command line.

ТокенToken Источник значенияValue source ЗначениеValue
$id$$id$ Файл проектаProject file AssemblyName (заголовок) из файла проектаAssemblyName (title) from the project file
$version$$version$ AssemblyInfoAssemblyInfo AssemblyInformationalVersion, если присутствует, в противном случае AssemblyVersionAssemblyInformationalVersion if present, otherwise AssemblyVersion
$authors$$authors$ AssemblyInfoAssemblyInfo AssemblyCompanyAssemblyCompany
$title$$title$ AssemblyInfoAssemblyInfo AssemblyTitleAssemblyTitle
$description$$description$ AssemblyInfoAssemblyInfo AssemblyDescriptionAssemblyDescription
$copyright$$copyright$ AssemblyInfoAssemblyInfo AssemblyCopyrightAssemblyCopyright
$configuration$$configuration$ DLL-файл сборкиAssembly DLL Конфигурация, используемая для построения сборки, по умолчанию используется тип отладки.Configuration used to build the assembly, defaulting to Debug. Обратите внимание, что для создания пакета с помощью конфигурации выпуска в командной строке всегда используется параметр -properties Configuration=Release.Note that to create a package using a Release configuration, you always use -properties Configuration=Release on the command line.

Маркеры также можно использовать для разрешения путей при включении файлов сборок и файлов содержимого.Tokens can also be used to resolve paths when you include assembly files and content files. Маркеры имеют те же имена, что и свойства MSBuild, что позволяет выбирать файлы для включения в зависимости в текущей конфигурации построения.The tokens have the same names as the MSBuild properties, making it possible to select files to be included depending on the current build configuration. Например, если вы используете следующие маркеры в файле .nuspec:For example, if you use the following tokens in the .nuspec file:

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

И выполняете построение сборки, для которой AssemblyName имеет значение LoggingLibrary с конфигурацией Release в MSBuild, в файле .nuspec в пакете будут присутствовать следующие строки:And you build an assembly whose AssemblyName is LoggingLibrary with the Release configuration in MSBuild, the resulting lines in the .nuspec file in the package is as follows:

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

Dependencies-элементDependencies element

Элемент <dependencies> внутри элемента <metadata> содержит любое число элементов <dependency>, идентифицирующих другие пакеты, от которых зависит пакет верхнего уровня.The <dependencies> element within <metadata> contains any number of <dependency> elements that identify other packages upon which the top-level package depends. Ниже перечислены атрибуты каждого элемента <dependency>:The attributes for each <dependency> are as follows:

АтрибутAttribute ОписаниеDescription
id Идентификатор пакета зависимости, например EntityFramework и NUnit, являющийся именем пакета nuget.org, показан на странице пакета (обязательно).(Required) The package ID of the dependency, such as "EntityFramework" and "NUnit", which is the name of the package nuget.org shows on a package page.
version Диапазон версий, которые допустимы в качестве зависимости (обязательно).(Required) The range of versions acceptable as a dependency. Точный синтаксис см. в разделе Управление версиями пакета.See Package versioning for exact syntax.
includeinclude Разделенный запятыми список тегов включения или исключения (см. ниже), определяющий зависимости, включаемые в конечный пакет.A comma-delimited list of include/exclude tags (see below) indicating of the dependency to include in the final package. Значение по умолчанию — all.The default value is all.
excludeexclude Разделенный запятыми список тегов включения или исключения (см. ниже), определяющий зависимости, исключаемые из конечного пакета.A comma-delimited list of include/exclude tags (see below) indicating of the dependency to exclude in the final package. Значение по умолчанию — build,analyzers которого может быть возможна перезапись.The default value is build,analyzers which can be over-written. Но content/ ContentFiles исключаются также неявно в окончательный пакет, который не может быть возможна перезапись.But content/ ContentFiles are also implicitly excluded in the final package which can't be over-written. Теги в свойстве exclude имеют приоритет перед тегами в свойстве include.Tags specified with exclude take precedence over those specified with include. Например, include="runtime, compile" exclude="compile" равносильно include="runtime".For example, include="runtime, compile" exclude="compile" is the same as include="runtime".
Тег включения или исключенияInclude/Exclude tag Затрагиваемые папки пакетаAffected folders of the target
contentFilescontentFiles ContentContent
исполняющая средаruntime Runtime, Resources и FrameworkAssembliesRuntime, Resources, and FrameworkAssemblies
compilecompile liblib
выполнить сборкуbuild build (свойства и цели MSBuild)build (MSBuild props and targets)
в машинном кодеnative в машинном кодеnative
Нетnone НетNo folders
всеall Все папкиAll folders

Например, следующие строки указывают зависимости от PackageA версии 1.1.0 или более поздней и PackageB версии 1.x.For example, the following lines indicate dependencies on PackageA version 1.1.0 or higher, and PackageB version 1.x.

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

Следующие строки указывают зависимости от тех же пакетов и включают папки contentFiles и build для PackageA, а также все папки, кроме native и compile, для PackageB"The following lines indicate dependencies on the same packages, but specify to include the contentFiles and build folders of PackageA and everything but the native and compile folders of 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 файл.Note: When creating a .nuspec from a project using nuget spec, dependencies that exist in that project are automatically included in the resulting .nuspec file.

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

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

В качестве альтернативы простому неструктурированному списку зависимости могут задаваться в соответствии с профилем платформы целевого проекта с использованием элементов <group> в элементе <dependencies>.As an alternative to a single flat list, dependencies can be specified according to the framework profile of the target project using <group> elements within <dependencies>.

Каждый элемент group имеет атрибут targetFramework и содержит ноль или более элементов <dependency>.Each group has an attribute named targetFramework and contains zero or more <dependency> elements. Эти зависимости устанавливаются вместе в том случае, если целевая платформа совместима с профилем платформы проекта.Those dependencies are installed together when the target framework is compatible with the project's framework profile.

Элемент <group> без атрибута targetFramework используется в качестве установленного по умолчанию или резервного списка зависимостей.The <group> element without a targetFramework attribute is used as the default or fallback list of dependencies. Точное описание идентификаторов платформы см. в разделе Целевые платформы.See Target frameworks for the exact framework identifiers.

Важно!

Формат группы не может смешиваться с неструктурированным списком.The group format cannot be intermixed with a flat list.

В следующем примере приводятся различные варианты элемента <group>:The following example shows different variations of the <group> element:

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

    <group targetFramework="net40">
        <dependency id="jQuery" />
        <dependency id="WebActivator" />
    </group>

    <group targetFramework="sl30">
    </group>
</dependencies>

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

Элемент <references> явно задает сборки, на которые целевой проект должен ссылаться при использовании пакета.The <references> element explicitly specifies the assemblies that the target project should reference when using the package. Если этот элемент присутствует, NuGet добавляет ссылки только на указанные в списке сборки, но не на какие-либо другие сборки в папке lib проекта.When this element is present, NuGet add references to only the listed assemblies; it does not add references for any other assemblies in the package's lib folder.

Например, следующий элемент <references> указывает NuGet на необходимость добавлять ссылки только на сборки xunit.dll и xunit.extensions.dll, даже если в пакете есть другие сборки:For example, the following <references> element instructs NuGet to add references to only xunit.dll and xunit.extensions.dll even if there are additional assemblies in the package:

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

Явные ссылки обычно применяются для сборок, используемых только во время разработки.Explicit references are typically used for design-time only assemblies. При использовании контрактов для кода сборки контракта должны располагаться рядом со сборками среды выполнения, которые они расширяют, чтобы среда Visual Studio могла находить их. При этом не требуются ссылки на сборки контракта из проекта и эти сборки не нужно копировать в папку bin проекта.When using Code Contracts, for example, contract assemblies need to be next to the runtime assemblies that they augment so that Visual Studio can find them, but the contract assemblies need not be referenced by the project or copied into the project's bin folder.

Аналогичным образом, явные ссылки можно использовать для платформ модульного тестирования, таких как XUnit, сборки средств которых должны располагаться рядом со сборками среды выполнения, но не требуют включения в ссылки проекта.Similarly, explicit references can be used for unit test frameworks, such as XUnit, which needs its tools assemblies located next to the runtime assemblies, but does not need them included as project references.

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

В качестве альтернативы простому неструктурированному списку ссылки могут задаваться в соответствии с профилем платформы целевого проекта с использованием элементов <group> в элементе <references>.As an alternative to a single flat list, references can be specified according to the framework profile of the target project using <group> elements within <references>.

Каждый элемент group имеет атрибут targetFramework и содержит ноль или более элементов <reference>.Each group has an attribute named targetFramework and contains zero or more <reference> elements. Эти ссылки добавляются в проект в том случае, если целевая платформа совместима с профилем платформы проекта.Those references are added to a project when the target framework is compatible with the project's framework profile.

Элемент <group> без атрибута targetFramework используется в качестве установленного по умолчанию или резервного списка ссылок.The <group> element without a targetFramework attribute is used as the default or fallback list of references. Точное описание идентификаторов платформы см. в разделе Целевые платформы.See Target frameworks for the exact framework identifiers.

Важно!

Формат группы не может смешиваться с неструктурированным списком.The group format cannot be intermixed with a flat list.

В следующем примере приводятся различные варианты элемента <group>:The following example shows different variations of the <group> element:

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

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

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

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

Сборки платформы входят в состав .NET Framework и должны находиться в глобальном кэше сборок любого заданного компьютера.Framework assemblies are those that are part of the .NET framework and should already be in the global assembly cache (GAC) for any given machine. Идентифицируя такие сборки с помощью элемента <frameworkAssemblies>, пакет может гарантировать, что ссылки, отсутствующие в проекте, будут при необходимости добавлены в него.By identifying those assemblies within the <frameworkAssemblies> element, a package can ensure that required references are added to a project in the event that the project doesn't have such references already. Естественно, напрямую в пакет такие сборки не включаются.Such assemblies, of course, are not included in a package directly.

Элемент <frameworkAssemblies> содержит ноль или более элементов <frameworkAssembly>, каждый из которых задает следующие атрибуты:The <frameworkAssemblies> element contains zero or more <frameworkAssembly> elements, each of which specifies the following attributes:

АтрибутAttribute Описание:Description
имя_сборкиassemblyName Полное имя сборки (обязательно).(Required) The fully qualified assembly name.
targetFrameworktargetFramework Указывает целевую платформу, к которой применяется эта ссылка (необязательно).(Optional) Specifies the target framework to which this reference applies. Если этот атрибут опущен, указывает, что ссылка применяется ко всем платформам.If omitted, indicates that the reference applies to all frameworks. Точное описание идентификаторов платформы см. в разделе Целевые платформы.See Target frameworks for the exact framework identifiers.

В следующем примере показаны ссылка на System.Net для всех целевых платформ и ссылка на System.ServiceModel только для платформы .NET Framework 4.0:The following example shows a reference to System.Net for all target frameworks, and a reference to System.ServiceModel for .NET Framework 4.0 only:

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

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

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

Если вы придерживаетесь соглашений, описываемых в разделе Создание пакета, вам не нужно явно задавать список файлов в файле .nuspec.If you follow the conventions described in Creating a Package, you do not have to explicitly specify a list of files in the .nuspec file. Команда nuget pack автоматически выбирает необходимые файлы.The nuget pack command automatically picks up the necessary files.

Важно!

Когда пакет устанавливается в проекте, NuGet автоматически добавляет ссылки на библиотеки DLL сборок в пакете, кроме тех из них, в именах которых есть .resources.dll, так как они считаются локализованными вспомогательными сборками.When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, excluding those that are named .resources.dll because they are assumed to be localized satellite assemblies. По этой причине следует избегать использования .resources.dll в именах файлов пакета, которые содержат важный код.For this reason, avoid using .resources.dll for files that otherwise contain essential package code.

Чтобы обойти такое автоматическое поведение и явно управлять включением сборок в пакет, поместите элемент <files> в качестве дочернего для <package> (на одном уровне с <metadata>), указывая каждый файл с помощью элемента <file>.To bypass this automatic behavior and explicitly control which files are included in a package, place a <files> element as a child of <package> (and a sibling of <metadata>), identifying each file with a separate <file> element. Пример:For example:

<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> также используется для включения неизменяемых файлов содержимого при установке пакета.With NuGet 2.x and earlier, and projects using packages.config, the <files> element is also used to include immutable content files when a package is installed. В NuGet версии 3.3 и более поздних и проектах PackageReference используется элемент <contentFiles>.With NuGet 3.3+ and projects PackageReference, the <contentFiles> element is used instead. Дополнительные сведения см. в разделе Включение файлов содержимого.See Including content files below for details.

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

Каждый элемент <file> задает указанные ниже атрибуты:Each <file> element specifies the following attributes:

АтрибутAttribute ОписаниеDescription
srcsrc Расположение файла или файлов, которые требуется включить, с учетом исключений, задаваемых атрибутом exclude.The location of the file or files to include, subject to exclusions specified by the exclude attribute. Если не указан абсолютный путь, этот путь задается относительно файла .nuspec.The path is relative to the .nuspec file unless an absolute path is specified. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
targettarget Относительный путь к папке в пакете, куда помещаются файлы исходного кода. Должен начинаться с lib, content, build или tools.The relative path to the folder within the package where the source files are placed, which must begin with lib, content, build, or tools. См. раздел Создание файла NUSPEC на основе рабочего каталога, соответствующего соглашениям.See Creating a .nuspec from a convention-based working directory.
excludeexclude Разделенный точками с запятой список файлов или шаблонов файлов, которые исключаются из расположения src.A semicolon-delimited list of files or file patterns to exclude from the src location. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.

ПримерыExamples

Одна сборкаSingle assembly

Source file:
    library.dll

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

Packaged result:
    lib\library.dll

Одна сборка, относящаяся к целевой платформеSingle assembly specific to a target framework

Source file:
    library.dll

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

Packaged result:
    lib\net40\library.dll

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

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-файлы для разных платформDLLs for different frameworks

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

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

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)

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

Файлы содержимого — это неизменяемые файлы, которые пакету необходимо включить в проект.Content files are immutable files that a package needs to include in a project. Такие файлы не подлежат изменению проектом, который потребляет их.Being immutable, they are not intended to be modified by the consuming project. Примеры файлов содержимого:Example content files include:

  • Изображения, внедряемые в качестве ресурсовImages that are embedded as resources
  • Файлы исходного кода, которые уже были скомпилированыSource files that are already compiled
  • Скрипты, которые необходимо включить в выходные данные построения проектаScripts that need to be included with the build output of the project
  • Файлы конфигурации для пакета, которые необходимо включить в проект, но не требуется изменять в рамках отдельного проектаConfiguration files for the package that need to be included in the project but don't need any project-specific changes

Файлы содержимого включаются в проект с помощью элемента <files>, задающего папку content в атрибуте target.Content files are included in a package using the <files> element, specifying the content folder in the target attribute. Тем не менее такие файлы игнорируются при установке пакета в проект с использованием PackageReference, в которых вместо этого используется элемент <contentFiles>.However, such files are ignored when the package is installed in a project using PackageReference, which instead uses the <contentFiles> element.

Чтобы обеспечить максимальную совместимость с потребляющими проектами, в идеальном случае файлы содержимого следует задавать в проекте с использованием обоих элементов.For maximum compatibility with consuming projects, a package ideally specifies the content files in both elements.

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

Для файлов содержимого следует использовать тот же формат, что и для файлов сборки, однако необходимо указать в качестве базовой сборки content в атрибуте target, как показано в следующих примерах.For content files, simply use the same format as for assembly files, but specify content as the base folder in the target attribute as shown in the following examples.

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

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

Файлы содержимого со структурой каталоговContent files with directory structure

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

Файлы содержимого, относящиеся к целевой платформеContent file specific to a target framework

Source file:
    css\cool\style.css

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

Packaged result:
    content\style.css

Файлы содержимого, копируемые в папку с точкой в имениContent file copied to a folder with dot in name

В этом случае NuGet определяет, что расширение в атрибуте target не соответствует расширению в src и обрабатывает такую часть имени в атрибуте target как папку:In this case, NuGet sees that the extension in target does not match the extension in src and thus treats that part of the name in target as a folder:

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

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

Чтобы включить файлы без расширения, используйте подстановочные знаки * или **:To include files without an extension, use the * or ** wildcards:

Source file:
    flags\installed

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

Packaged result:
    flags\installed

Файлы содержимого с глубоким путем и глубоким целевым объектомContent files with deep path and deep target

В этом случае из-за совпадения расширений файлов для исходного и целевого объектов NuGet предполагает, что целевой объект задает имя файла, а не папки:In this case, because the file extensions of the source and target match, NuGet assumes that the target is a file name and not a folder:

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

Переименование файла содержимого в пакетеRenaming a content file in the package

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

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

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 для файлов содержимогоUsing the contentFiles element for content files

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

По умолчанию пакет помещает содержимое в папку contentFiles (см. ниже), а команда nuget pack включает все файлы в этой папке с использованием установленных по умолчанию атрибутов.By default, a package places content in a contentFiles folder (see below) and nuget pack included all files in that folder using default attributes. В этом случае включать узел contentFiles в файл .nuspec не требуется.In this case it's not necessary to include a contentFiles node in the .nuspec at all.

Чтобы управлять включаемыми файлами, элемент <contentFiles> задает коллекцию элементов <files>, которая точно определяет включаемые файлы.To control which files are included, the <contentFiles> element specifies is a collection of <files> elements that identify the exact files include.

Эти файлы задаются с набором атрибутов, который описывает их использование в системе проекта:These files are specified with a set of attributes that describe how they should be used within the project system:

АтрибутAttribute ОписаниеDescription
includeinclude Расположение файла или файлов, которые требуется включить, с учетом исключений, задаваемых атрибутом exclude (обязательно).(Required) The location of the file or files to include, subject to exclusions specified by the exclude attribute. Если не указан абсолютный путь, этот путь задается относительно файла .nuspec.The path is relative to the .nuspec file unless an absolute path is specified. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
excludeexclude Разделенный точками с запятой список файлов или шаблонов файлов, которые исключаются из расположения src.A semicolon-delimited list of files or file patterns to exclude from the src location. Допускается использовать подстановочный знак *. Наличие сдвоенного подстановочного знака ** подразумевает выполнение рекурсивного поиска в папке.The wildcard character * is allowed, and the double wildcard ** implies a recursive folder search.
buildActionbuildAction Действие построения, назначаемое элементу содержимого для MSBuild, например Content, None, Embedded Resource, Compile и т. д. Значение по умолчанию — Compile.The build action to assign to the content item for MSBuild, such as Content, None, Embedded Resource, Compile, etc. The default is Compile.
copyToOutputcopyToOutput Логическое значение, указывающее, следует ли копировать элементы содержимого сборки (или публикация) выходную папку.A Boolean indicating whether to copy content items to the build (or publish) output folder. Значение по умолчанию – false.The default is false.
flattenflatten Логическое значение, указывающее на необходимость копировать элементы содержимого в одну папку в выходных данных построения (true) или сохранить структуру папок пакета (false).A Boolean indicating whether to copy content items to a single folder in the build output (true), or to preserve the folder structure in the package (false). Этот параметр применяется, только если для параметра copyToOutput установлено значение true.This flag only works when copyToOutput flag is set to true. Значение по умолчанию – false.The default is false.

При установке пакета NuGet применяет дочерние элементы <contentFiles> в порядке сверху вниз.When installing a package, NuGet applies the child elements of <contentFiles> from top to bottom. Если одному файлу соответствует несколько записей, применяются все записи.If multiple entries match the same file then all entries are applied. При обнаружении конфликтов для одного атрибута запись верхнего уровня переопределяет записи на нижних уровнях.The top-most entry overrides the lower entries if there is a conflict for the same attribute.

Структура папки пакетаPackage folder structure

Структурирование содержимого в проекте пакета осуществляется по следующему шаблону:The package project should structure content using the following pattern:

/contentFiles/{codeLanguage}/{TxM}/{any?}
  • Элемент codeLanguages может иметь значение cs, vb, fs, any или любой другой эквивалент заданного $(ProjectLanguage) в нижнем регистреcodeLanguages may be cs, vb, fs, any, or the lowercase equivalent of a given $(ProjectLanguage)
  • Элемент TxM представляет любой допустимый моникер целевой платформы, поддерживаемой NuGet (см. раздел Целевые платформы).TxM is any legal target framework moniker that NuGet supports (see Target frameworks).
  • В конце этого синтаксиса может добавляться любая структура папок.Any folder structure may be appended to the end of this syntax.

Пример:For example:

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

Для пустых папок можно использовать ., чтобы отказаться от предоставления содержимого для определенных комбинаций языка и моникера целевой платформы, например:Empty folders can use . to opt out of providing content for certain combinations of language and TxM, for example:

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

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

<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>

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

Простой файл .nuspec, в котором не задаются зависимости или файлыA simple .nuspec that does not specify dependencies or files

<?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 с зависимостямиA .nuspec with dependencies

<?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 с файламиA .nuspec with files

<?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 со сборками платформыA .nuspec with framework assemblies

<?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>

В этом примере для целевых объектов проекта устанавливаются следующие компоненты:In this example, the following are installed for specific project targets:

  • .NET4 -> System.Web, System.Net.NET4 -> System.Web, System.Net
  • Клиентский профиль .NET4 -> System.Net.NET4 Client Profile -> System.Net
  • Silverlight 3 -> System.JsonSilverlight 3 -> System.Json
  • Silverlight 4 -> System.Windows.Controls.DomainServicesSilverlight 4 -> System.Windows.Controls.DomainServices
  • WindowsPhone -> Microsoft.Devices.SensorsWindowsPhone -> Microsoft.Devices.Sensors