Введение в NuGetAn introduction to NuGet

Ключевой инструмент для любой современной платформы разработки — это механизм, с помощью которого разработчики могут создавать, передавать друг другу и использовать полезный код.An essential tool for any modern development platform is a mechanism through which developers can create, share, and consume useful code. Часто такой код распределен по "пакетам", включающим скомпилированный код (в виде библиотек DLL) и другое содержимое, необходимое использующим эти пакеты проектам.Often such code is bundled into "packages" that contain compiled code (as DLLs) along with other content needed in the projects that consume these packages.

Для .NET (в том числе .NET Core) механизмом совместного использования кода, поддерживаемым Майкрософт, является NuGet, который определяет, как создаются, размещаются и используются пакеты для .NET, а также предоставляет средства для каждой из этих ролей.For .NET (including .NET Core), the Microsoft-supported mechanism for sharing code is NuGet, which defines how packages for .NET are created, hosted, and consumed, and provides the tools for each of those roles.

Проще говоря, пакет NuGet представляет собой отдельный ZIP-файл с расширением .nupkg, который содержит скомпилированный код (DLL), другие файлы, связанные с этим кодом, и описательный манифест, включающий такие сведения, как номер версии пакета.Put simply, a NuGet package is a single ZIP file with the .nupkg extension that contains compiled code (DLLs), other files related to that code, and a descriptive manifest that includes information like the package's version number. Разработчики, у которых есть код, к которому нужно предоставить общий доступ, создают пакеты и публикуют их на закрытых или открытых узлах.Developers with code to share create packages and publish them to a public or private host. Потребители получают эти пакеты из соответствующих узлов, добавляют их в свои проекты, а затем вызывают функции пакета в коде своего проекта.Package consumers obtain those packages from suitable hosts, add them to their projects, and then call a package's functionality in their project code. При этом NuGet сам обрабатывает все промежуточные данные.NuGet itself then handles all of the intermediate details.

Так как NuGet поддерживает закрытые узлы наряду с открытым узлом nuget.org, с помощью пакетов NuGet вы можете делиться кодом, используемым в рамках организации или рабочей группы.Because NuGet supports private hosts alongside the public nuget.org host, you can use NuGet packages to share code that's exclusive to an organization or a work group. Пакеты NuGet также являются удобным способом факторизовать свой код для использования только в собственных проектах.You can also use NuGet packages as a convenient way to factor your own code for use in nothing but your own projects. Иными словами, пакет NuGet является совместно используемой единицей кода, однако не требует и не подразумевает какого-либо определенного способа предоставления общего доступа.In short, a NuGet package is a shareable unit of code, but does not require nor imply any particular means of sharing.

Поток пакетов между создателями, узлами и потребителямиThe flow of packages between creators, hosts, and consumers

Выполняя роль общедоступного узла, NuGet обслуживает центральный репозиторий с более чем 100 000 уникальных пакетов на сайте nuget.org. Ежедневно эти пакеты используют миллионы разработчиков .NET и .NET Core.In its role as a public host, NuGet itself maintains the central repository of over 100,000 unique packages at nuget.org. These packages are employed by millions of .NET/.NET Core developers every day. NuGet также позволяет размещать пакеты в частном порядке в облаке (например, в Azure DevOps), в частной сети или даже в вашей локальной файловой системе.NuGet also enables you to host packages privately in the cloud (such as on Azure DevOps), on a private network, or even on just your local file system. Таким образом эти пакеты доступны только тем разработчикам, у которых есть доступ к узлу, что позволяет сделать их доступными для отдельных групп потребителей.By doing so, those packages are available to only those developers that have access to the host, giving you the ability to make packages available to a specific group of consumers. Эти возможности описаны в разделе Размещение своих веб-каналов NuGet.The options are explained on Hosting your own NuGet feeds. С помощью параметров конфигурации можно также контролировать, какие узлы могут быть доступны любому компьютеру, тем самым гарантируя, что пакеты получают из определенных источников, а не из общего репозитория, такого как nuget.org.Through configuration options, you can also control exactly which hosts can be accessed by any given computer, thereby ensuring that packages are obtained from specific sources rather than a public repository like nuget.org.

Независимо от своей природы, узел выступает в качестве точки подключения между создателями и потребителями пакета.Whatever its nature, a host serves as the point of connection between package creators and package consumers. Создатели разрабатывают полезные пакеты NuGet и публикуют их на узле.Creators build useful NuGet packages and publish them to a host. Потребители ищут полезные и совместимые пакеты на доступных узлах, скачивая эти пакеты и включая их в свои проекты.Consumers then search for useful and compatible packages on accessible hosts, downloading and including those packages in their projects. После установки в проекте API пакеты становятся доступны остальной части кода проекта.Once installed in a project, the packages' APIs are available to the rest of the project code.

Связь между создателями, узлами и потребителями пакета

Совместимость пакета с разными целевыми платформамиPackage targeting compatibility

"Совместимый" пакет означает, что он содержит сборки, созданные по меньшей мере для одной целевой платформы .NET, совместимой с целевой платформой используемого проекта.A "compatible" package means that it contains assemblies built for at least one target .NET framework that's compatible with the consuming project's target framework. Разработчики могут создавать пакеты, которые относятся к одной платформе, как и элементы управления универсальной платформы Windows (UWP), или они могут поддерживать более широкий набор целевых объектов.Developers can create packages that are specific to one framework, as with UWP controls, or they can support a wider range of targets. Для максимальной совместимости пакета разработчики используют версию .NET Standard, которую поддерживают все проекты .NET и .NET Core.To maximize a package's compatibility, developers target .NET Standard, which all .NET and .NET Core projects can consume. Это наиболее эффективное средство как для создателей, так и для потребителей, так как единый пакет (обычно содержащий единую сборку) подходит для всех потребляющих проектов.This is the most efficient means for both creators and consumers, as a single package (usually containing a single assembly) works for all consuming projects.

Разработчики пакетов, которым требуется API вне .NET Standard, с другой стороны, создают отдельные сборки для различных требуемых версий .NET Framework, которые они будут поддерживать, и включают все эти сборки в один пакет (который называется пакетом многоплатформенного нацеливания).Package developers who require APIs outside of .NET Standard, on the other hand, create separate assemblies for the different target frameworks they want to support and include all of those assemblies in the same package (which is called "multi-targeting"). Когда потребитель устанавливает такой пакет, NuGet извлекает только сборки, нужные в проекте.When a consumer installs such a package, NuGet extracts only those assemblies that are needed by the project. Это сводит к минимуму занимаемое пакетом место в конечном приложении или сборках, создаваемых данным проектом.This minimizes the package's footprint in the final application and/or assemblies produced by that project. Пакет настройки для различных версий, конечно, сложнее в обслуживании.A multi-targeting package is, of course, more difficult for its creator to maintain.

Примечание

Применение .NET Standard отменяет предыдущий подход использования различных целей переносной библиотеки классов (PCL).Targeting .NET Standard supersedes the previous approach of using various portable class library (PCL) targets. Таким образом, эта документация посвящена созданию пакетов для .NET Standard.This documentation therefore focuses on creating packages for .NET Standard.

Средства NuGetNuGet tools

Кроме поддержки размещения, NuGet также предоставляет широкий набор средств, используемых как создателями, так и потребителями.In addition to hosting support, NuGet also provides a variety of tools used by both creators and consumers. Сведения о получении конкретных средств см. в разделе Установка клиентских средств NuGet.See Installing NuGet client tools for how to obtain specific tools.

СредствоTool ПлатформыPlatforms Применимые сценарииApplicable Scenarios ОписаниеDescription
dotnet CLIdotnet CLI ВсеAll Создание, потреблениеCreation, Consumption Средство CLI для библиотек .NET Core и .NET Standard, а также для проектов в стиле пакета SDK, нацеленных на .NET Framework (см. раздел Атрибут SDK).CLI tool for .NET Core and .NET Standard libraries, and for SDK-style projects that target .NET Framework (see SDK attribute). Предоставляет определенные возможности CLI NuGet непосредственно внутри цепочки инструментов .NET Core.Provides certain NuGet CLI capabilities directly within the .NET Core tool chain. Как и CLI nuget.exe, CLI dotnet не взаимодействует с проектами Visual Studio.As with the nuget.exe CLI, the dotnet CLI does not interact with Visual Studio projects.
Интерфейс командной строки nuget.exenuget.exe CLI ВсеAll Создание, потреблениеCreation, Consumption Средство CLI для библиотек .NET Framework и проектов со стилем, отличным от пакета SDK, нацеленных на библиотеки .NET Standard.CLI tool for .NET Framework libraries and non-SDK-style projects that target .NET Standard libraries. Предоставляет все функциональные возможности NuGet, при этом часть команд относится к создателям пакета, часть — только к потребителям, а остальные — ко всем.Provides all NuGet capabilities, with some commands applying specifically to package creators, some applying only to consumers, and others applying to both. Например, создатели пакета используют команду nuget pack для создания пакета из различных сборок и связанных файлов, потребители пакета используют nuget install для включения пакетов в папку проекта, при этом все используют nuget config для задания переменных конфигурации NuGet.For example, package creators use the nuget pack command to create a package from various assemblies and related files, package consumers use nuget install to include packages in a project folder, and everyone uses nuget config to set NuGet configuration variables. Как независящее от платформы средство, интерфейс командной строки NuGet не взаимодействует с проектами Visual Studio.As a platform-agnostic tool, the NuGet CLI does not interact with Visual Studio projects.
Консоль диспетчера пакетовPackage Manager Console Visual Studio в WindowsVisual Studio on Windows ПотреблениеConsumption Предоставляет команды PowerShell для установки пакетов и управления ими в проектах Visual Studio.Provides PowerShell commands for installing and managing packages in Visual Studio projects.
Пользовательский интерфейс диспетчера пакетовPackage Manager UI Visual Studio в WindowsVisual Studio on Windows ПотреблениеConsumption Предоставляет удобный пользовательский интерфейс для установки пакетов и управления ими в проектах Visual Studio.Provides an easy-to-use UI for installing and managing packages in Visual Studio projects.
Управление пользовательским интерфейсом NuGetManage NuGet UI Visual Studio для MacVisual Studio for Mac ПотреблениеConsumption Предоставляет удобный пользовательский интерфейс для установки пакетов и управления ими в проектах Visual Studio для Mac.Provide an easy-to-use UI for installing and managing packages in Visual Studio for Mac projects.
MSBuildMSBuild WindowsWindows Создание, потреблениеCreation, Consumption Предоставляет возможность создавать и восстанавливать используемые в проекте пакеты напрямую с помощью цепочки инструментов MSBuild.Provides the ability to create packages and restore packages used in a project directly through the MSBuild tool chain.

Как видите, средства NuGet, с которыми вы работаете, в значительной степени зависят от того, создаете, потребляете или публикуете вы пакеты, а также от используемой платформы.As you can see, the NuGet tools you work with depend greatly on whether you're creating, consuming, or publishing packages, and the platform on which you're working. Создатели пакета обычно также являются потребителями, так как берут за основу функции, имеющиеся в других пакетах NuGet.Package creators are typically also consumers, as they build on top of functionality that exists in other NuGet packages. Конечно же, те пакеты, в свою очередь, могут зависеть еще от каких-либо.And those packages, of course, may in turn depend on still others.

Дополнительные сведения см. в статье Рабочий процесс создания пакета и Рабочий процесс использования пакета.For more information, start with the Package creation workflow and Package consumption workflow articles.

Управление зависимостямиManaging dependencies

Возможность легко брать за основу работу других — это одна из наиболее мощных функций системы управления пакетами.The ability to easily build on the work of others is one of most powerful features of a package management system. Соответственно, значительная часть работы NuGet заключается в управлении этим деревом или "схемой" зависимостей от имени проекта.Accordingly, much of what NuGet does is managing that dependency tree or "graph" on behalf of a project. Проще говоря, вам нужно заботиться только о тех пакетах, которые вы используете непосредственно в проекте.Simply said, you need only concern yourself with those packages that you're directly using in a project. Если эти пакеты используют другие пакеты (которые, в свою очередь, также используют пакеты), все эти зависимости нижнего уровня обрабатывает NuGet.If any of those packages themselves consume other packages (which can, in turn, consume still others), NuGet takes care of all those down-level dependencies.

На следующем рисунке показан проект, зависящий от пяти пакетов, которые, в свою очередь, зависят от нескольких других.The following image shows a project that depends on five packages, which in turn depend on a number of others.

Пример графа зависимостей NuGet для проекта .NET

Обратите внимание, что некоторые пакеты встречаются на графе зависимостей несколько раз.Notice that some packages appear multiple times in the dependency graph. Например, существует три разных потребителя пакета B, и каждый из них может также указывать другую версию этого пакета (не показано).For example, there are three different consumers of package B, and each consumer might also specify a different version for that package (not shown). Это обычное дело, особенно для широко используемых пакетов.This is a common occurrence, especially for widely-used packages. NuGet выполняет всю работу, чтобы определить, какая именно версия пакета B отвечает потребностям всех потребителей.NuGet fortunately does all the hard work to determine exactly which version of package B satisfies all consumers. Затем NuGet делает то же самое для всех других пакетов, независимо от того, насколько глубока схема зависимостей.NuGet then does the same for all other packages, no matter how deep the dependency graph.

Дополнительные сведения о том, как NuGet выполняет эту задачу, см. в разделе Разрешение зависимостей.For more details on how NuGet performs this service, see Dependency resolution.

Отслеживание ссылок и восстановление пакетовTracking references and restoring packages

Так как проекты можно легко перемещать между компьютерами разработчиков, репозиториями управления исходным кодом, серверами сборки и т. д., крайне непрактично хранить двоичные сборки из пакетов NuGet напрямую привязанными к проекту.Because projects can easily move between developer computers, source control repositories, build servers, and so forth, it's highly impractical to keep the binary assemblies of NuGet packages directly bound to a project. В этом случае каждая копия проекта будет излишне раздутой (и, следовательно, расходовать пространство в репозиториях системы управления исходным кодом).Doing so would make each copy of the project unnecessarily bloated (and thereby waste space in source control repositories). Кроме того, обновить двоичные файлы пакета до новой версии будет очень сложно, так как обновление будет применяться ко всем копиям проекта.It would also make it very difficult to update package binaries to newer versions as updates would have to be applied across all copies of the project.

Вместо этого NuGet поддерживает простой список ссылок на пакеты, от которых зависит проект, включая зависимости верхнего и нижнего уровня.NuGet instead maintains a simple reference list of the packages upon which a project depends, including both top-level and down-level dependencies. То есть при установке пакета с некоторого узла в проект NuGet записывает идентификатор пакета и номер версии в этот список ссылок.That is, whenever you install a package from some host into a project, NuGet records the package identifier and version number in the reference list. (При удалении пакет, конечно же, убирается из этого списка.) Затем в NuGet можно восстановить все связанные пакеты по запросу, как описано в статье о восстановлении пакета.(Uninstalling a package, of course, removes it from the list.) NuGet then provides a means to restore all referenced packages upon request, as described on Package restore.

Список ссылок NuGet создается при установке пакета и может использоваться для восстановления пакетов в другом месте.

С помощью одного только списка ссылок NuGet может переустановить, то есть восстановить, все эти пакеты с открытых и (или) закрытых узлов в любой момент времени.With only the reference list, NuGet can then reinstall—that is, restore—all of those packages from public and/or private hosts at any later time. При фиксации проекта в системе управления исходным кодом или предоставления его для общего доступа каким-либо иным образом нужно включить только список ссылок и исключить какие-либо двоичные файлы пакета (см. раздел Пропуск пакетов NuGet в системах управления исходным кодом.)When committing a project to source control, or sharing it in some other way, you include only the reference list and exclude any package binaries (see Packages and source control.)

Компьютер, принимающий проект, например сервер сборки, получающий копию проекта в рамках работы системы автоматического развертывания, просто запрашивает у NuGet восстановление зависимости всякий раз, когда они понадобятся.The computer that receives a project, such as a build server obtaining a copy of the project as part of an automated deployment system, simply asks NuGet to restore dependencies whenever they're needed. Системы сборки, такие как Azure DevOps, предоставляют шаги "Восстановление NuGet" именно для этой цели.Build systems like Azure DevOps provide "NuGet restore" steps for this exact purpose. Аналогично, когда разработчики получают копию проекта (например, при клонировании репозитория), они могут вызвать такие команды, как nuget restore (CLI NuGet), dotnet restore (CLI dotnet) или Install-Package (консоль диспетчера пакетов), чтобы получить все необходимые пакеты.Similarly, when developers obtain a copy of a project (as when cloning a repository), they can invoke command like nuget restore (NuGet CLI), dotnet restore (dotnet CLI), or Install-Package (Package Manager Console) to obtain all the necessary packages. Visual Studio, со своей стороны, автоматически восстанавливает пакеты при создании проекта (при условии, что включено автоматическое восстановление, как описано в статье Восстановление пакетов).Visual Studio, for its part, automatically restores packages when building a project (provided that automatic restore is enabled, as described on Package restore).

Очевидно, что основная роль NuGet, связанная с разработчиками, заключается в обслуживании этого списка ссылок от имени проекта и предоставлении средств для эффективного восстановления (и обновления) таких указанных в ссылках пакетов.Clearly, then, NuGet's primary role where developers are concerned is maintaining that reference list on behalf of your project and providing the means to efficiently restore (and update) those referenced packages. Этот список хранится в одном из двух указанных ниже форматов управления пакетами:This list is maintained in one of two package management formats, as they're called:

  • PackageReference (также известном как "Ссылки на пакет в файлах проекта"): (NuGet 4.0 и более поздних версий) ведет список зависимостей верхнего уровня проекта непосредственно в файле проекта, поэтому отдельный файл не требуется.PackageReference (or "package references in project files") | (NuGet 4.0+) Maintains a list of a project's top-level dependencies directly within the project file, so no separate file is needed. Связанный файл obj/project.assets.json создается динамически. Этот файл позволяет управлять общей схемой зависимостей пакетов, которые проект использует со всеми зависимостями нижнего уровня.An associated file, obj/project.assets.json, is dynamically generated to manage the overall dependency graph of the packages that a project uses along with all down-level dependencies. В проектах .NET Core всегда используется формат PackageReference.PackageReference is always used by .NET Core projects.

  • packages.config: (NuGet 1.0+) XML-файл, содержащий неструктурированный список всех зависимостей в проекте, включая зависимости других установленных пакетов.packages.config: (NuGet 1.0+) An XML file that maintains a flat list of all dependencies in the project, including the dependencies of other installed packages. Установленные или восстановленные пакеты хранятся в папке packages.Installed or restored packages are stored in a packages folder.

Применение конкретного формата управления пакетами зависит от типа проекта и доступной версии Visual Studio и NuGet.Which package management format is employed in any given project depends on the project type, and the available version of NuGet (and/or Visual Studio). Чтобы проверить, какой формат используется, просто найдите packages.config в корневом каталоге проекта после установки первого пакета.To check what format is being used, simply look for packages.config in the project root after installing your first package. Если этот файл отсутствует, найдите в файле проекта элемент <PackageReference>.If you don't have that file, look in the project file directly for a <PackageReference> element.

При наличии возможности выбора рекомендуем использовать PackageReference.When you have a choice, we recommend using PackageReference. Файл packages.config используется в устаревших версиях и больше не применяется в активной разработке.packages.config is maintained for legacy purposes and is no longer under active development.

Совет

Различные команды интерфейса командной строки nuget.exe, например nuget install, не добавляют автоматически пакет в список ссылок.Various nuget.exe CLI commands, like nuget install, do not automatically add the package to the reference list. Этот список обновляется при установке пакета с помощью диспетчера пакетов Visual Studio (пользовательского интерфейса или консоли) и интерфейса командной строки dotnet.exe.The list is updated when installing a package with the Visual Studio Package Manager (UI or Console), and with dotnet.exe CLI.

Что еще делает NuGet?What else does NuGet do?

Мы уже выучили следующие характеристики NuGet:So far you've learned the following characteristics of NuGet:

  • NuGet предоставляет центральный репозиторий nuget.org с поддержкой частного размещения.NuGet provides the central nuget.org repository with support for private hosting.
  • NuGet предоставляет разработчикам средства для создания, публикации и использования пакетов.NuGet provides the tools developers need for creating, publishing, and consuming packages.
  • Самое главное, NuGet ведет список ссылок для пакетов, используемых в проекте, а также позволяет восстанавливать и обновлять пакеты из этого списка.Most importantly, NuGet maintains a reference list of packages used in a project and the ability to restore and update those packages from that list.

Чтобы обеспечить эффективную работу этих процессов, NuGet осуществляет некоторые оптимизации в фоновом режиме.To make these processes work efficiently, NuGet does some behind-the-scenes optimizations. В частности, NuGet управляет кэшем пакета и папкой глобальных пакетов, что позволяет упростить установку и повторною установку.Most notably, NuGet manages a package cache and a global packages folder to shortcut installation and reinstallation. Кэш позволяет избежать загрузки пакета, который уже установлен на компьютере.The cache avoids downloading a package that's already been installed on the machine. Папка глобальных пакетов позволяет в нескольких проектах совместно использовать один установленный пакет, тем самым уменьшая общий размер пакетов NuGet на компьютере.The global packages folder allows multiple projects to share the same installed package, thereby reducing NuGet's overall footprint on the computer. Это очень удобно, когда вы часто восстанавливаете большее количество пакетов, например, как на сервере сборки.The cache and global packages folder are also very helpful when you're frequently restoring a larger number of packages, as on a build server. Дополнительные сведения об этих механизмах см. в статье Управление папкой установки глобальных пакетов, кэшем и временными папками.For more details on these mechanisms, see Managing the global packages and cache folders.

В рамках отдельного проекта NuGet управляет общей схемой зависимостей, что включает в себя разрешение нескольких ссылок на различные версии одного пакета.Within an individual project, NuGet manages the overall dependency graph, which again includes resolving multiple references to different versions of the same package. Довольно часто проект зависит от одного или нескольких пакетов, имеющих такие же зависимости.It's quite common that a project takes a dependency on one or more packages that themselves have the same dependencies. Некоторые из наиболее полезных пакетов служебных программ на сайте nuget.org используются многими другими пакетами.Some of the most useful utility packages on nuget.org are employed by many other packages. В общей схеме зависимостей вы легко можете иметь десять различных ссылок на разные версии одного пакета.In the entire dependency graph, then, you could easily have ten different references to different versions of the same package. Чтобы избежать переноса нескольких версий этого пакета в само приложение, NuGet определяет, какую отдельную версию могут использовать все потребители.To avoid bringing multiple versions of that package into the application itself, NuGet sorts out which single version can be used by all consumers. (Дополнительные сведения см. в разделе Принципы разрешения зависимостей пакетов в NuGet.)(For more information, see Dependency Resolution.)

Кроме того, NuGet обслуживает все спецификации, связанные со структурированием пакетов (включая локализацию и отладочные символы) и ссылками на них (включая диапазоны версий и предварительные версии). NuGet также имеет различные API для работы со своими службами программно и предоставляет поддержку разработчикам, которые пишут расширения Visual Studio и шаблоны проектов.Beyond that, NuGet maintains all the specifications related to how packages are structured (including localization and debug symbols) and how they are referenced (including version ranges and pre-release versions.) NuGet also provides various APIs to work with its services programmatically, and provides support for developers who write Visual Studio extensions and project templates.

Если изучить содержание этой документации, можно найти все указанные возможности и заметки о выпуске, отсылающие к самому начальному этапу развития NuGet.Take a moment to browse the table of contents for this documentation, and you see all of these capabilities represented there, along with release notes dating back to NuGet's beginnings.

Другие видео о NuGet см. на Channel 9 и YouTube.Find more NuGet videos on Channel 9 and YouTube.

Комментарии, вклады и проблемыComments, contributions, and issues

Мы убедительно просим вас оставлять комментарии и вносить вклад в эту документацию. Просто выберите команды Отзывы и Изменить вверху любой страницы или посетите репозиторий документации и список проблем с документацией на сайте GitHub.Finally, we very much welcome comments and contributions to this documentation—just select the Feedback and Edit commands on the top of any page, or visit the docs repository and docs issue list on GitHub.

Мы также рады вкладам в сам NuGet через различные репозитории GitHub. Сведения о проблемах NuGet приведены по адресу https://github.com/NuGet/home/issues.We also welcome contributions to NuGet itself through its various GitHub repositories; NuGet issues can be found on https://github.com/NuGet/home/issues.

Надеемся, что вам понравится работать с NuGet.Enjoy your NuGet experience!