Создание пакета с помощью интерфейса командной строки nuget.exe

Независимо от того, nuget.exe что ваш пакет делает или какой код он содержит, используйте один из инструментов интерфейса командной строки (CLI) или dotnet.exeдля упаковки этих функций в компонент, который можно предоставить другим разработчикам. Сведения об установке средств интерфейса командной строки NuGet см. в разделе "Установка клиентских средств NuGet". Visual Studio не включает средство CLI автоматически.

Для проектов, не относящихся к пакету SDK, обычно .NET Framework, выполните действия, описанные в этой статье, чтобы создать пакет. Для быстрого начала, которое предоставляет пошаговые инструкции по использованию Visual Studio и CLI nuget.exe, см. Краткое руководство: создание и публикация пакета с помощью Visual Studio (.NET Framework, Windows).
Для проектов .NET Core и .NET Standard, использующих формат в стиле SDK, а также для других проектов в стиле SDK, см. статью Создание пакета NuGet с помощью dotnet CLI.
Для проектов, перенесенных с packages.config на PackageReference, используйте команду msbuild -t:pack.

Технически пакет NuGet — это ZIP-файл, который был переименован в расширение .nupkg и содержимое которого соответствует определенным соглашениям. В этой статье описывается подробный процесс создания пакета, соответствующего этим соглашениям.

Упаковка начинается с скомпилированного кода (сборок), символов и других файлов, которые необходимо доставить в виде пакета. Общие сведения о процессе упаковки см. в разделе "Рабочий процесс создания пакета". Этот процесс не зависит от компиляции или создания файлов, которые отправляются в пакет. Но вы можете извлечь данные из файла проекта, чтобы сохранить скомпилированные сборки и пакеты в синхронизации.

Это важно

Эта статья относится к проектам, не связанным с SDK, обычно это проекты, отличные от .NET Core и .NET Standard проектов, использующих Visual Studio 2017 и более поздние версии, а также NuGet 4.0+.

Определите, какие сборки следует упаковать

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

Как правило, лучше всего иметь одну сборку на пакет NuGet, если каждая сборка является независимо полезной. Например, рассмотрим следующие случаи, в которых включается сборка с именемUtilities.dll , которая зависит от сборки, называемой Parser.dll:

Если Parser.dll полезно самостоятельно, создайте один пакет для Utilities.dll и один для Parser.dll. Это позволяет разработчикам использовать Parser.dll независимо от Utilities.dll.
Если Parser.dll содержит код, который используется только Utilities.dll, то можно оставить Parser.dll в одном пакете. Как правило, если ваша библиотека состоит из нескольких сборок, которые не представляют собой самостоятельной ценности, их можно объединить в один пакет.
Если Utilities.dll также зависит от Utilities.resources.dll, и Utilities.resources.dll не полезен самостоятельно, поместите оба пакета в один пакет.

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

Если библиотека содержит сборки взаимодействия с объектной моделью компонентов (COM), следуйте дополнительным рекомендациям в разделе "Создание пакетов NuGet, содержащих сборки взаимодействия COM".

Роль и структура nuspec-файла

Если вы знаете, какие файлы нужно упаковать, необходимо создать манифест пакета в XML-файле NUSPEC .

Манифест:

Описывает содержимое пакета и включается в пакет.
Приводит к созданию пакета и сообщает NuGet, как установить пакет в проект. Например, манифест определяет другие зависимости пакета, чтобы NuGet также может установить эти зависимости при установке основного пакета.
Содержит обязательные и необязательные свойства, как описано в остальной части этого раздела. Подробные сведения, включая другие свойства, не упомянутые здесь, см. в справочнике nuspec.

В манифесте требуются следующие свойства:

Идентификатор пакета, который должен быть уникальным в коллекции, в которой размещен пакет.
Определенный номер версии в форме Major.Minor.Patch[-Suffix], где -Suffix определяет предварительные версии
Название пакета должно отображаться на сайте (например, nuget.org)
Сведения о авторе
Длинное описание пакета

Следующие свойства являются общими необязательными:

Заметки о выпуске.
Сведения об авторских правах.
Краткое описание пользовательского интерфейса Package Manager в Visual Studio.
Идентификатор локали.
URL-адрес проекта.
Лицензия в виде выражения или файла. Свойство licenseUrl устарело. Вместо этого используйте элемент метаданных nuspec.license
Файл read-me.
Файл значка. Свойство iconUrl устарело. Вместо этого используйте элемент метаданных nuspec.icon
Списки зависимостей и ссылок.
Теги, помогающие в поиске коллекции.

Следующий код представляет собой типичный (но вымышленный) nuspec-файл с комментариями, описывающими свойства:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- An identifier that must be unique within the hosting gallery -->
        <id>Contoso.Utility.UsefulStuff</id>

        <!-- A package version number that's used when resolving dependencies -->
        <version>1.8.3</version>

        <!-- A comma-separated list of package authors that sometimes appears directly on the gallery -->
        <authors>Dejana Tesic, Rajeev Dey</authors>

        <!-- A project URL that provides a link for the gallery -->
        <projectUrl>http://github.com/contoso/UsefulStuff</projectUrl>

        <!-- License information that's displayed on the gallery -->
        <license type="expression">Apache-2.0</license>
        
        <!-- The location of a read-me file that's displayed in the Visual Studio Package Manager UI -->
        <readme>readme.md</readme>

        <!-- An icon that's used in the Visual Studio Package Manager UI -->
        <icon>icon.png</icon>

        <!-- 
            A property that when true, prompts the user to accept the license when
            installing the package
        -->
        <requireLicenseAcceptance>false</requireLicenseAcceptance>

        <!-- Detailed information about a particular release -->
        <releaseNotes>Bug fixes and performance improvements</releaseNotes>

        <!-- 
            A description that can be used in the Package Manager UI. The
            nuget.org gallery uses information you add in the portal. 
        -->
        <description>Core utility functions for web applications</description>

        <!-- Copyright information -->
        <copyright>Copyright ©2026 Contoso Corporation</copyright>

        <!-- Tags that appear in the gallery and can be used for tag searches -->
        <tags>web utility http json url parsing</tags>

        <!-- Dependencies that are automatically installed when the package is installed -->
        <dependencies>
            <dependency id="Newtonsoft.Json" version="9.0" />
        </dependencies>
    </metadata>

    <!-- A read-me Markdown file that's displayed in the Package Manager UI -->
    <files>
        <file src="readme.md" target="" />
        <file src="icon.png" target="" />
    </files>
</package>

Подробные сведения об объявлении зависимостей и указании номеров версий см. в разделе packages.config и управление версиями пакетов. Вы также можете использовать атрибуты include и exclude элемента dependency, чтобы указать ресурсы зависимостей, которые необходимо включить или исключить из пакета. Для получения дополнительной информации см. раздел .nuspec Reference — элемент Dependencies.

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

nuget locals -list global-packages

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

Перейдите в папку global-packages .
В этой папке перейдите в вложенную папку для любого пакета, а затем перейдите в вложенную папку для любой версии этого пакета.
В подпапке версии создайте копию NUPKG-файла и измените расширение копии на ZIP.
Откройте файл.zip и изучите nuspec-файл в нем.

Замечание

При создании файла .nuspec из проекта Visual Studio манифест содержит маркеры, которые заменяются информацией из проекта при создании пакета. Дополнительные сведения см. в разделе Создание .nuspec-файла из проекта Visual Studio.

Создание nuspec-файла

Создание полного манифеста обычно начинается с базового nuspec-файла , созданного с помощью одного из следующих методов:

Рабочий каталог, основанный на соглашении
Сборка DLL
проект Visual Studio
Новый файл со значениями по умолчанию

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

Это важно

Созданные nuspec-файлы содержат заполнители, которые необходимо изменить перед созданием пакета с помощью nuget pack команды. Эта команда завершается ошибкой, если файл .nuspec содержит заполнители.

Из рабочего каталога на основе общепринятых стандартов

Так как пакет NuGet является ZIP-файлом, который был переименован с расширением NUPKG , часто проще всего создать структуру папок, которую нужно создать в локальной файловой системе, а затем создать nuspec-файл непосредственно из этой структуры. Затем nuget pack команда автоматически добавляет все файлы в эту структуру папок, но исключает все папки, начинающиеся с периода, чтобы сохранить частные файлы в одной структуре.

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

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

Папки соответствуют следующим нормам:

Folder	Содержимое	Действие при установке пакета
(root)	Манифест пакета, папки верхнего уровня и, при необходимости, файл ReadMe в формате Markdown и изображение значка	Эта папка используется в качестве отправной точки для стандартных вложенных папок, таких как lib и build.
lib/<tfm>	Сборка (.dll), документация (.xml) и файлы символов (.pdb) для заданного идентификатора целевой платформы (TFM)	Сборки добавляются в качестве ссылок на время компиляции и время выполнения. Файлы.xml и PDB копируются в папки проекта. Сведения о создании вложенных папок, специфичных для целевой платформы, можно найти в разделе Поддержка нескольких версий .NET.
ref/<tfm>	Файлы сборок (.dll) и символов (.pdb) для заданного TFM	Сборки добавляются как ссылки только на этапе компиляции. Ничего не копируется в папку корзины проекта.
Среды выполнения	Сборка для конкретной архитектуры (.dll), файл символов (.pdb) и собственный ресурс (.pri)	Сборки добавляются в качестве ссылок только для среды выполнения. Другие файлы копируются в папки проекта. Всегда должна быть соответствующая конкретная сборка (TFM) `AnyCPU` в папке /ref/<tfm>, чтобы обеспечить соответствующую сборку во время компиляции. См. раздел Поддержка нескольких версий .NET.
содержание	Произвольные файлы	Содержимое копируется в корневой каталог проекта. Подумайте о папке содержимого в качестве корневого каталога целевого приложения, которое в конечном итоге использует пакет. Чтобы пакет добавил изображение в папку /images приложения, поместите его в папку содержимого и изображений пакета.
Построить	(3.x+) Microsoft Build Engine (MSBuild) файлы .targets и .props	Эти файлы автоматически вставляются в проект.
buildMultiTargeting	(4.0+) MSBuild .targets и .props-файлы для кроссплатформенного таргетирования	Эти файлы автоматически вставляются в проект.
buildTransitive	(5.0+) MSBuild .targets и PROPS-файлы , передаваемые транзитивно в любой потребляемый проект	Эти файлы автоматически вставляются в проект. См. страницу функции.
Инструменты	Скрипты и программы PowerShell, доступные в консоли Package Manager	Папка tools добавляется в переменную среды `PATH` только для консоли Package Manager. Он не добавляется в `PATH` значение, которое MSBuild использует при сборке проекта.

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

Если у вас есть требуемая структура папок, выполните следующую команду в этой папке, чтобы создать nuspec-файл :

nuget spec

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

из DLL сборки

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

nuget spec <assembly-name>.dll

Использование этой формы заменяет несколько заполнителей в манифесте определенными значениями из сборки. Например, <id> для свойства задано имя сборки и <version> задана версия сборки. Однако другие свойства манифеста не имеют совпадающих значений в сборке. Эти свойства по-прежнему содержат заполнители после выполнения команды.

Из проекта Visual Studio

Создание nuspec-файла из CSPROJ или VBPROJ-файла удобно, так как другие пакеты, установленные в проекте, автоматически ссылаются в качестве зависимостей. Чтобы создать манифест из файла проекта, используйте следующую команду в папке, содержащей файл проекта:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget spec

Полученный <файл project-name.nuspec> содержит маркеры, которые заменяются во время упаковки значениями из проекта, включая ссылки на все уже установленные пакеты.

Если у вас есть зависимости пакетов для включения в nuspec, вместо этого используйте nuget pack. Затем извлеките .nuspec файл из созданного .nupkg файла. Например, используйте следующую команду:

# Use in a folder that contains a project file, such as <project-name>.csproj or <project-name>.vbproj.
nuget pack myproject.csproj

Токен разграничивается символами $ на обеих сторонах свойства проекта. Например, значение <id> в манифесте, созданном таким образом, обычно имеет вид следующей строки:

<id>$id$</id>

Этот маркер заменяется AssemblyName значением из файла проекта во время упаковки. Для точного сопоставления значений проекта с токенами в файле .nuspec см. раздел Маркеры замены.

Маркеры освобождают от необходимости обновлять важные значения, такие как номер версии в файле .nuspec, при обновлении проекта. Но вы также можете заменить маркеры литеральными значениями.

При работе с проектом Visual Studio можно использовать несколько дополнительных вариантов упаковки, как описано в Run nuget pack для создания Nupkg-файла далее в этой статье.

Пакеты уровня решения

Только NuGet 2.x. Недоступно в NuGet 3.0+.

NuGet 2.x поддерживает понятие пакета на уровне решения, который устанавливает средства или дополнительные команды для консоли Package Manager (содержимое папки tools), но не добавляет ссылки, содержимое или настройки сборки для любых проектов в решении. Такие пакеты не содержат файлов в их прямых папках lib, содержимого или сборки , и ни один из их зависимостей не содержит файлов в соответствующих папках lib, содержимого или сборки .

NuGet отслеживает установленные пакеты уровня решения в packages.config-файле в папке NUGET , а не packages.config файла проекта.

Из нового файла со значениями по умолчанию

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

nuget spec [<package-name>]

Если не указано <package-name>, результирующий файл называется Package.nuspec. Если указать такое имя Contoso.Utility.UsefulStuff, файл называется Contoso.Utility.UsefulStuff.nuspec.

Результирующий nuspec-файл содержит заполнители для таких значений, как projectUrl. Прежде чем использовать файл для создания окончательного NUPKG-файла , замените заполнители соответствующими значениями.

Выберите уникальный идентификатор пакета и задайте номер версии

Идентификатор пакета (<id> элемент) и номер версии (<version> элемент) — это два наиболее важных значения манифеста, так как они однозначно определяют точный код, содержащийся в пакете.

Лучшие практики для версии пакета

Как правило, задайте версию пакета, чтобы она соответствовала библиотеке. Это руководство рекомендуется, но не является обязательным. Эта практика проста при ограничении пакета на одну сборку, как описано ранее в разделе "Выбор сборок для упаковки". Как правило, помните, что NuGet сам занимается версиями пакетов при разрешении зависимостей, а не версий сборок.
При использовании схемы нестандартной версии рассмотрите правила управления версиями NuGet, как описано в разделе "Управление версиями пакетов".

Другие ресурсы, которые полезны для понимания управления версиями, см. в следующей серии кратких записей блога:

Добавление файла read-me и других файлов

Чтобы напрямую указать файлы для включения в пакет, используйте <files> элемент в nuspec-файле, который идет после тега :

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add files from an arbitrary folder that's not necessarily in the project. -->
        <file src="..\..\SomeRoot\**\*.*" target="" />
    </files>
</package>

Подсказка

При использовании подхода рабочего каталога на основе соглашения можно поместить файл readme.md в корневой каталог пакета и другое содержимое в папку content. В манифесте не требуется <file> элементов.

Чтобы включить файл read-me в пакет, используйте readme элемент метаданных, чтобы указать целевой путь к файлу read-me. Кроме того, используйте элемент метаданных, чтобы указать исходный file путь и целевую папку файла read-me. Дополнительные сведения см. в разделе readme.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata>
        <!-- ... -->
        <readme>docs\readme.md</readme>
        <!-- ... -->
    </metadata>
    <files>
        <!-- Add a read-me file. -->
        <file src="..\readme.md" target="docs\" />
    </files>
</package>

Visual Studio отображает содержимое файла read-me в пользовательском интерфейсе Package Manager. Например, на следующем снимке экрана показан файл README для HtmlAgilityPack пакета.

Замечание

Если вы включаете пустой <files> узел в файл .nuspec, NuGet включает содержимое папки lib в пакет, но не включает никакого другого содержимого.

Включение свойств и таргетов MSBuild в пакет

В некоторых случаях может потребоваться добавить пользовательские целевые объекты сборки или свойства в проекты, использующие пакет, например запуск пользовательского средства или процесса во время сборки. Для получения дополнительной информации о пользовательских целях сборки и свойствах см. статью о MSBuild .props и .targets в пакете.

Создайте файлы <package-id>.targets или <package-id>.props, например, Contoso.Utility.UsefulStuff.targets, в папках build проекта.

Затем в файле .nuspec укажите эти файлы в узле <files>.

<?xml version="1.0"?>
<package >
    <metadata minClientVersion="2.5">
    <!-- ... -->
    </metadata>
    <files>
        <!-- In the package build folder, include everything that's in the local build folder. -->
        <file src="build\**" target="build" />

        <!-- Other files -->
        <!-- ... -->
    </files>
</package>

При добавлении пакетов в проект NuGet автоматически включает эти свойства и целевые объекты.

Запустите пакет nuget, чтобы создать NUPKG-файл

При использовании сборки или рабочего каталога на основе соглашений создайте пакет, запустив nuget pack с файлом .nuspec. В следующей команде замените <project-name> на имя вашего проекта.

nuget pack <project-name>.nuspec

При использовании проекта Visual Studio запустите nuget pack с файлом проекта. Эта команда автоматически загружает nuspec-файл проекта и заменяет все маркеры в нем соответствующими значениями в файле проекта:

nuget pack <project-name>.csproj

Замечание

Для замены маркера необходимо использовать файл проекта напрямую, так как проект является источником значений маркера. Замена токена не удается, если используется nuget pack с файлом .nuspec.

Во всех случаях nuget pack исключает папки, начинающиеся с периода, например .git или HG.

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

После nuget pack успешного выполнения у вас есть .nupkg-файл, который можно опубликовать в подходящей коллекции, как описано в «Публикация пакетов NuGet».

Подсказка

Полезный способ проверить пакет после создания пакета — открыть его в средстве обозревателя пакетов . Это средство предоставляет графическое представление содержимого пакета и его манифеста. Вы также можете переименовать полученный NUPKG-файл в файл.zip и просмотреть его содержимое напрямую.

Дополнительные параметры

С помощью различных коммутаторов nuget pack командной строки можно исключить файлы, переопределить номер версии манифеста и изменить выходную папку среди других функций. Для полного списка см. команду pack (NuGet CLI).

Ниже приведены некоторые распространенные варианты Visual Studio проектов.

Ссылки на проекты: если проект ссылается на другие проекты, можно добавить ссылки на проекты в составе пакета или в качестве зависимостей, используя -IncludeReferencedProjects этот параметр:
```
nuget pack MyProject.csproj -IncludeReferencedProjects
```
Этот процесс включения рекурсивен. Например, если MyProject.csproj ссылается на проекты B и C, а эти проекты ссылаются на D, E и F, файлы из B, C, D, E и F, включаются в пакет.

Если указанный проект включает в себя собственный nuspec-файл , NuGet добавляет этот проект в качестве зависимости. Необходимо упаковать и опубликовать этот проект отдельно.
Конфигурация сборки. По умолчанию NuGet использует конфигурацию сборки по умолчанию, установленную в файле проекта, обычно Debug. Чтобы упаковать файлы из другой конфигурации сборки, например, Release, используйте параметр -properties с указанием конфигурации.
```
nuget pack MyProject.csproj -properties Configuration=Release
```
Символы: Чтобы включить символы, которые позволяют потребителям пошагово проходить по вашему коду пакета в отладчике, используйте параметры -Symbols и -SymbolPackageFormat. -SymbolPackageFormat Для параметра укажите форматsnupkg:
```
nuget pack MyProject.csproj -symbols -SymbolPackageFormat snupkg
```

Установка тестового пакета

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

Вы можете протестировать установки вручную в Visual Studio или командной строке с помощью стандартных шагов установки package.

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

Скопируйте NUPKG-файл в локальную папку.
Добавьте папку в источники пакетов с помощью nuget sources add -name <name> -source <path> команды. Дополнительные сведения см. в команде sources (NuGet CLI). Этот локальный источник необходимо задать только один раз на любом компьютере.
Установите пакет из этого источника с помощью nuget install <package-ID> -source <name>. В этой команде <name> должно соответствовать имени источника, используемого в команде nuget sources. Указание источника инструктирует NuGet установить пакет исключительно из этого источника.
Проверьте файловую систему, чтобы проверить правильность установки файлов.

После создания пакета, который является NUPKG-файлом , его можно опубликовать в выбранной коллекции. Дополнительные сведения см. в статье "Публикация пакетов NuGet".

Вы также можете расширить возможности пакета или поддержать другие сценарии. Дополнительные сведения см. в следующих статьях:

Сведения о других типах пакетов см. в следующих статьях:

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-06

Создание пакета с помощью интерфейса командной строки nuget.exe

Определите, какие сборки следует упаковать

Роль и структура nuspec-файла

Создание nuspec-файла

Из рабочего каталога на основе общепринятых стандартов

из DLL сборки

Из проекта Visual Studio

Пакеты уровня решения

Из нового файла со значениями по умолчанию

Выберите уникальный идентификатор пакета и задайте номер версии

Рекомендации по идентификатору пакета

Лучшие практики для версии пакета

Добавление файла read-me и других файлов

Включение свойств и таргетов MSBuild в пакет

Запустите пакет nuget, чтобы создать NUPKG-файл

Дополнительные параметры

Установка тестового пакета

Связанный контент

Обратная связь

Дополнительные ресурсы