Una introducción a NuGetAn introduction to NuGet

Una herramienta esencial para cualquier plataforma de desarrollo moderna es un mecanismo a través del cual los desarrolladores pueden crear, compartir y consumir código útil.An essential tool for any modern development platform is a mechanism through which developers can create, share, and consume useful code. A menudo, este código se integra en "paquetes" que contienen código compilado (como archivos DLL) y otro contenido necesario en los proyectos que utilizan estos paquetes.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.

En .NET (incluido .NET Core), el mecanismo compatible con Microsoft para compartir código es NuGet, que define cómo se crean, hospedan y consumen paquetes en .NET, y ofrece las herramientas para cada uno de esos roles.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.

Desde un punto de vista sencillo, un paquete NuGet es un archivo ZIP con la extensión .nupkg que contiene código compilado (archivos DLL), otros archivos relacionados con ese código y un manifiesto descriptivo que incluye información como el número de versión del paquete.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. Los programadores con código para compartir crean paquetes y los publican en un host público o privado.Developers with code to share create packages and publish them to a public or private host. Los consumidores de paquetes obtienen esos paquetes de los hosts adecuados, los agregan a sus proyectos y, después, llaman a la funcionalidad de un paquete en el código del proyecto.Package consumers obtain those packages from suitable hosts, add them to their projects, and then call a package's functionality in their project code. Después, el propio NuGet controla todos los detalles intermedios.NuGet itself then handles all of the intermediate details.

Dado que NuGet admite hosts privados junto al host de nuget.org público, puede usar paquetes NuGet para compartir código que es exclusivo de una organización o un grupo de trabajo.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. También puede utilizar paquetes NuGet como una manera cómoda de tener su propio código para usarlo nada más que en sus propios proyectos.You can also use NuGet packages as a convenient way to factor your own code for use in nothing but your own projects. En resumen, un paquete NuGet es una unidad de código que se puede compartir, pero no requiere ni implica ningún medio concreto de uso compartido.In short, a NuGet package is a shareable unit of code, but does not require nor imply any particular means of sharing.

El flujo de paquetes entre creadores, hosts y consumidoresThe flow of packages between creators, hosts, and consumers

En su rol de host público, NuGet mantiene el repositorio central de más de 100 000 paquetes únicos en nuget.org. Millones de desarrolladores de .NET/.NET Core usan estos paquetes a diario.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 también permite hospedar paquetes de forma privada en la nube (por ejemplo, en Visual Studio Team Services), en una red privada o incluso en el sistema de archivos local.NuGet also enables you to host packages privately in the cloud (such as on Visual Studio Team Services), on a private network, or even on just your local file system. Así, los paquetes solo están a disposición de los desarrolladores que tengan acceso al host, lo que le ofrece la posibilidad de poner paquetes a disposición de un grupo determinado de consumidores.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. Las opciones se explican en Hospedar sus propias fuentes de NuGet.The options are explained on Hosting your own NuGet feeds. Mediante opciones de configuración, puede también controlar exactamente qué hosts pueden tener acceso a un equipo determinado, lo que garantiza que los paquetes se obtienen de orígenes específicos y no de un repositorio público como 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.

Con independencia de su naturaleza, un host actúa como un punto de conexión entre los creadores y los consumidores de paquetes.Whatever its nature, a host serves as the point of connection between package creators and package consumers. Los creadores compilan paquetes NuGet útiles y los publican en un host.Creators build useful NuGet packages and publish them to a host. Después, los consumidores buscan paquetes útiles y compatibles en hosts accesibles, los descargan y los incluyen en sus proyectos.Consumers then search for useful and compatible packages on accessible hosts, downloading and including those packages in their projects. Una vez instalados en un proyecto, las API de los paquetes están disponibles para el resto del código del proyecto.Once installed in a project, the packages' APIs are available to the rest of the project code.

Relación entre los creadores, hosts y consumidores del paquete

Compatibilidad de destino de paquetesPackage targeting compatibility

Un paquete "compatible" implica que contiene ensamblados compilados para al menos una plataforma .NET de destino que es compatible con la plataforma de destino del proyecto de consumo.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. Los desarrolladores pueden crear paquetes que son específicos de una plataforma, como ocurre con los controles UWP, o pueden admitir una gama más amplia de destinos.Developers can create packages that are specific to one framework, as with UWP controls, or they can support a wider range of targets. Para maximizar la compatibilidad de un paquete, los desarrolladores lo destinan a .NET Standard, que todos los proyectos de .NET y .NET Core pueden consumir.To maximize a package's compatibility, developers target .NET Standard, which all .NET and .NET Core projects can consume. Se trata del medio más eficaz tanto para los creadores como para los consumidores, ya que un único paquete (que normalmente contiene un único ensamblado) funciona para todos los proyectos de consumo.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.

Los desarrolladores de paquetes que requieren las API fuera de .NET Standard, por otra parte, crean ensamblados independientes para las diferentes plataformas de destino que van a admitir e incluyen todos los ensamblados en el mismo paquete (lo que se denomina "compatibilidad con múltiples versiones").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"). Cuando un consumidor instala ese paquete, NuGet extrae solo los ensamblados que son necesarios para el proyecto.When a consumer installs such a package, NuGet extracts only those assemblies that are needed by the project. Esto reduce la superficie del paquete en la aplicación final y los ensamblados que produce ese proyecto.This minimizes the package's footprint in the final application and/or assemblies produced by that project. Obviamente, un paquete de compatibilidad con múltiples versiones resulta más difícil de mantener para su creador.A multi-targeting package is, of course, more difficult for its creator to maintain.

Nota

.NET Standard como destino sustituye al enfoque anterior de usar diversos destinos de "biblioteca de clases portable" (PCL).Targeting .NET Standard supercedes the previous approach of using various portable class library (PCL) targets. Esta documentación, por tanto, se centra en la creación de paquetes para .NET Standard.This documentation therefore focuses on creating packages for .NET Standard.

Herramientas de NuGetNuGet tools

Además de la compatibilidad con el hospedaje, NuGet también proporciona una variedad de herramientas que usan tanto creadores como consumidores.In addition to hosting support, NuGet also provides a variety of tools used by both creators and consumers. Vea Instalación de las herramientas del cliente NuGet para saber cómo obtener herramientas específicas.See Installing NuGet client tools for how to obtain specific tools.

HerramientaTool PlataformasPlatforms Escenarios aplicablesApplicable Scenarios DescripciónDescription
CLI de nuget.exenuget.exe CLI TodasAll Creación, ConsumoCreation, Consumption Proporciona todas las funcionalidades de NuGet, con algunos comandos que se aplican de forma específica a los creadores del paquete, otros solo a los consumidores y otros a ambos.Provides all NuGet capabilities, with some commands applying specifically to package creators, some applying only to consumers, and others applying to both. Por ejemplo, los creadores de paquetes usan el comando nuget pack para crear un paquete a partir de varios ensamblados y archivos relacionados, los consumidores de paquetes usan nuget install para incluir los paquetes en una carpeta de proyecto y todos usan nuget config para establecer variables de configuración de 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. Como herramienta independiente de la plataforma, la CLI de NuGet no interactúa con proyectos de Visual Studio.As a platform-agnostic tool, the NuGet CLI does not interact with Visual Studio projects.
CLI de dotnetdotnet CLI TodasAll Creación, ConsumoCreation, Consumption Ofrece determinadas funcionalidades de la CLI de NuGet directamente en la cadena de herramientas de .NET Core.Provides certain NuGet CLI capabilities directly within the .NET Core tool chain. Al igual que con la CLI de NuGet, la CLI de dotnet no interactúa con proyectos de Visual Studio.As with the NuGet CLI, the dotnet CLI does not interact with Visual Studio projects.
Consola del Administrador de paquetesPackage Manager Console Visual Studio en WindowsVisual Studio on Windows ConsumoConsumption Ofrece comandos de PowerShell para instalar y administrar paquetes en proyectos de Visual Studio.Provides PowerShell commands for installing and managing packages in Visual Studio projects.
Interfaz de usuario del administrador de paquetesPackage Manager UI Visual Studio en WindowsVisual Studio on Windows ConsumoConsumption Ofrece una interfaz de usuario fácil de usar para instalar y administrar paquetes en proyectos de Visual Studio.Provides an easy-to-use UI for installing and managing packages in Visual Studio projects.
Administrar la interfaz de usuario de NuGetManage NuGet UI Visual Studio para MacVisual Studio for Mac ConsumoConsumption Ofrece una interfaz de usuario fácil de usar para instalar y administrar paquetes en proyectos de Visual Studio para Mac.Provide an easy-to-use UI for installing and managing packages in Visual Studio for Mac projects.
MSBuildMSBuild WindowsWindows Creación, ConsumoCreation, Consumption Ofrece la posibilidad de crear y restaurar los paquetes que se usan en un proyecto directamente a través de la cadena de herramientas de MSBuild.Provides the ability to create packages and restore packages used in a project directly through the MSBuild tool chain.

Como puede ver, las herramientas de NuGet con las que trabaja dependen en gran medida de si se crean, consumen o publican paquetes, así como de la plataforma en la que se trabaja.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. Los creadores de paquetes también suelen ser consumidores, dado que se basan en la funcionalidad que existe en otros paquetes NuGet.Package creators are typically also consumers, as they build on top of functionality that exists in other NuGet packages. Y esos paquetes, por supuesto, pueden a su vez depender de otros.And those packages, of course, may in turn depend on still others.

Para obtener más información, comience por los artículos Flujo de trabajo de creación de paquetes y Flujo de trabajo de consumo de paquetes.For more information, start with the Package creation workflow and Package consumption workflow articles.

Administración de dependenciasManaging dependencies

La posibilidad de basarse en el trabajo de otros usuarios fácilmente es una de las características más eficaces de un sistema de administración de paquetes.The ability to easily build on the work of others is one of most powerful features of a package management system. En consecuencia, gran parte de lo que hace NuGet consiste en administrar ese "gráfico" o árbol de dependencias en nombre de un proyecto.Accordingly, much of what NuGet does is managing that dependency tree or "graph" on behalf of a project. Dicho simplemente, solo se tiene que preocupar por los paquetes que use directamente en un proyecto.Simply said, you need only concern yourself with those packages that you're directly using in a project. Si alguno de esos paquetes consume otros paquetes (que, a su vez, pueden consumir otros), NuGet se encarga de todas esas dependencias de nivel inferior.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.

En la imagen siguiente se muestra un proyecto que depende de cinco paquetes que, a su vez, dependen de otros varios.The following image shows a project that depends on five packages, which in turn depend on a number of others.

Un gráfico de dependencias de NuGet de ejemplo para un proyecto de .NET

Tenga en cuenta que algunos paquetes aparecen varias veces en el gráfico de dependencias.Notice that some packages appear multiple times in the dependency graph. Por ejemplo, hay tres consumidores diferentes del paquete B, y es posible que cada consumidor también especifique una versión diferente de ese paquete (no se muestra).For example, there are three different consumers of package B, and each consumer might also specify a different version for that package (not shown). Se trata de un hecho frecuente, especialmente para los paquetes más ampliamente utilizados.This is a common occurrence, especially for widely-used packages. Afortunadamente, NuGet se encarga del trabajo duro de determinar exactamente qué versión del paquete B satisface a todos los consumidores.NuGet fortunately does all the hard work to determine exactly which version of package B satisfies all consumers. NuGet hace después lo mismo con los demás paquetes, con independencia de la profundidad que alcance el gráfico de dependencias.NuGet then does the same for all other packages, no matter how deep the dependency graph.

Para obtener más información sobre cómo realiza NuGet este servicio, vea Resolución de dependencias.For more details on how NuGet performs this service, see Dependency resolution.

Seguimiento de referencias y restauración de paquetesTracking references and restoring packages

Dado que los proyectos se pueden mover fácilmente entre equipos de desarrolladores, repositorios de control de código fuente, servidores de compilación, etc., no resulta práctico mantener los ensamblados binarios de los paquetes NuGet enlazados directamente a un proyecto.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. De hacerlo, se produciría un sobredimensionamiento innecesario de cada copia del proyecto (y, por tanto, se desperdiciaría espacio en los repositorios de control de código fuente).Doing so would make each copy of the project unnecessarily bloated (and thereby waste space in source control repositories). Además, sería muy difícil actualizar los archivos binarios del paquete a versiones más recientes, ya que habría que aplicar las actualizaciones en todas las copias del proyecto.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.

En lugar de ello, NuGet mantiene una lista de referencias simples de los paquetes en los que se basa un proyecto, que incluye las dependencias de nivel superior y de nivel inferior.NuGet instead maintains a simple reference list of the packages upon which a project depends, including both top-level and down-level dependencies. Es decir, siempre que se instala un paquete de algún host en un proyecto, NuGet registra el identificador y el número de versión del paquete en la lista de referencias.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. (Al desinstalar un paquete, evidentemente se quita de la lista). NuGet después ofrece un medio para restaurar todos los paquetes a los que se hace referencia previa solicitud, tal y como se describe en Restauración de paquetes.(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.

Una lista de referencias de NuGet se crea al instalar el paquete y se puede usar para restaurar los paquetes en otro lugar

Solo con la lista de referencias, NuGet puede reinstalar (es decir, restaurar) todos los paquetes de hosts públicos y privados en cualquier momento posterior.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. Al confirmar un proyecto en el control de código fuente o compartirlo de alguna otra manera, solo se incluye la lista de referencias, no los archivos binarios del paquete (vea Paquetes y control de código fuente).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.)

El equipo que recibe un proyecto, como un servidor de compilación que obtiene una copia del proyecto como parte de un sistema de implementación automatizada, simplemente solicita a NuGet que restaure las dependencias cuando sea necesario.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. Los sistemas de compilación como Visual Studio Team Services proporcionan pasos de "restauración de NuGet" para este propósito exacto.Build systems like Visual Studio Team Services provide "NuGet restore" steps for this exact purpose. De forma similar, cuando los desarrolladores obtienen una copia de un proyecto (como al clonar un repositorio), pueden invocar un comando como nuget restore (CLI de NuGet), dotnet restore (CLI de dotnet), o Install-Package (consola del Administrador de paquetes) para obtener todos los paquetes necesarios.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, por su parte, restaura automáticamente los paquetes al compilar un proyecto (siempre que la restauración automática esté habilitada, tal y como se describe en Restauración de paquetes).Visual Studio, for its part, automatically restores packages when building a project (provided that automatic restore is enabled, as described on Package restore).

Claramente, el rol principal de NuGet que interesa a los desarrolladores es que mantenga esa lista de referencias en nombre del proyecto y que proporcione los medios para restaurar de forma eficaz (y actualizar) los paquetes a los que se hace referencia.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. Esta lista se mantiene en uno de los dos formatos de administración de paquetes, que se denominan:This list is maintained in one of two package management formats, as they're called:

  • packages.config: (NuGet 1.0 y versiones posteriores) un archivo XML que mantiene una lista plana de todas las dependencias del proyecto, incluidas las dependencias de otros paquetes instalados.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. Los paquetes instalados o restaurados se almacenan en una carpeta packages.Installed or restored packages are stored in a packages folder.

  • PackageReference (o "referencias de paquetes en archivos de proyecto") | (NuGet 4.0 y versiones posteriores) mantiene una lista de las dependencias de nivel superior de un proyecto directamente en el archivo de proyecto, por lo que no se necesita un archivo independiente.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. Se genera dinámicamente un archivo asociado, obj/project.assets.json, que administra el gráfico de dependencias general de los paquetes que un proyecto utiliza con todas las dependencias de nivel inferior.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. Siempre se utiliza PackageReference en los proyectos de .NET Core.PackageReference is always used by .NET Core projects.

El formato de administración de paquetes que se usa en un proyecto determinado depende del tipo de proyecto y la versión disponible de NuGet (y/o Visual Studio).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). Para comprobar qué formato se usa, solo hay que buscar packages.config en la raíz del proyecto después de instalar el primer paquete.To check what format is being used, simply look for packages.config in the project root after installing your first package. Si no ve ese archivo, busque directamente un elemento <PackageReference> en el archivo de proyecto.If you don't have that file, look in the project file directly for a <PackageReference> element.

Si se puede elegir, se recomienda utilizar PackageReference.When you have a choice, we recommend using PackageReference. packages.config se mantiene con fines de herencia y ya no está en desarrollo activo.packages.config is maintained for legacy purposes and is no longer under active development.

Sugerencia

Diversos comandos de la CLI de nuget.exe, como nuget install, no agregan automáticamente el paquete a la lista de referencia.Various nuget.exe CLI commands, like nuget install, do not automatically add the package to the reference list. La lista se actualiza al instalar un paquete con el Administrador de paquetes de Visual Studio (interfaz de usuario o consola) y con la CLI de dotnet.exe.The list is updated when installing a package with the Visual Studio Package Manager (UI or Console), and with dotnet.exe CLI.

¿Qué más hace NuGet?What else does NuGet do?

Hasta ahora ha aprendido las siguientes características de NuGet:So far you've learned the following characteristics of NuGet:

  • NuGet ofrece el repositorio central nuget.org con compatibilidad de hospedaje privado.NuGet provides the central nuget.org repository with support for private hosting.
  • NuGet proporciona a los desarrolladores las herramientas que necesitan para crear, publicar y consumir paquetes.NuGet provides the tools developers need for creating, publishing, and consuming packages.
  • Y lo más importante, NuGet mantiene una lista de referencias de los paquetes que se usan en un proyecto y permite restaurar y actualizar los paquetes de esa lista.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.

Para que estos procesos funcionen de forma eficaz, NuGet realiza algunas optimizaciones en segundo plano.To make these processes work efficiently, NuGet does some behind-the-scenes optimizations. En concreto, NuGet administra una caché de paquetes y una carpeta de paquetes globales para abreviar la instalación y reinstalación.Most notably, NuGet manages a package cache and a global packages folder to shortcut installation and reinstallation. La caché evita descargar un paquete que ya se ha instalado en el equipo.The cache avoids downloading a package that's already been installed on the machine. La carpeta de paquetes globales permite que varios proyectos compartan el mismo paquete instalado, lo que reduce el consumo general de NuGet en el equipo.The global packages folder allows multiple projects to share the same installed package, thereby reducing NuGet's overall footprint on the computer. Las carpetas de paquetes globales y de caché resultan muy útiles cuando a menudo se restaura un mayor número de paquetes, por ejemplo, en un servidor de compilación.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. Para obtener más detalles sobre estos mecanismos, vea Administración de paquetes globales y carpetas de caché.For more details on these mechanisms, see Managing the global packages and cache folders.

Dentro de un proyecto individual, NuGet administra el gráfico general de dependencias, que incluye volver a resolver varias referencias a las distintas versiones del mismo paquete.Within an individual project, NuGet manages the overall dependency graph, which again includes resolving multiple references to different versions of the same package. Es bastante común que un proyecto tenga una relación de dependencia con uno o varios paquetes que, a su vez, tienen las mismas dependencias.It's quite common that a project takes a dependency on one or more packages that themselves have the same dependencies. Algunos de los paquetes de utilidad más prácticos de nuget.org se usan en otros muchos paquetes.Some of the most useful utility packages on nuget.org are employed by many other packages. En el gráfico de dependencias completo, podría tener fácilmente diez referencias distintas a versiones diferentes del mismo paquete.In the entire dependency graph, then, you could easily have ten different references to different versions of the same package. Para no incluir varias versiones de ese paquete en la propia aplicación, NuGet determina la única versión que pueden usar todos los consumidores.To avoid bringing multiple versions of that package into the application itself, NuGet sorts out which single version can be used by all consumers. (Para obtener más información, vea Inserción de dependencias).(For more information, see Dependency Resolution.)

Además, NuGet mantiene todas las especificaciones relacionadas con la estructura de los paquetes (incluida la localización y los símbolos de depuración) y cómo se hace referencia a ellos (incluidos los intervalos de versiones y versiones preliminares). NuGet ofrece también varias API para trabajar con sus servicios mediante programación, así como compatibilidad para los desarrolladores que crean plantillas de proyecto y extensiones de 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.

Dedique un momento a examinar la tabla de contenido de esta documentación, y podrá ver todas estas funcionalidades representadas, junto con notas de la versión que se remontan a los inicios de 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.

Comentarios, contribuciones y problemasComments, contributions, and issues

Por último, agradecemos mucho los comentarios y las contribuciones a esta documentación; simplemente seleccione los comandos Comentarios y Editar del principio de la página o visite el repositorio de documentos y la lista de problemas de documentos en 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.

También agradecemos las contribuciones a NuGet a través de los distintos repositorios de GitHub; pueden verse problemas de NuGet en 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.

Disfrute de su experiencia con NuGet.Enjoy your NuGet experience!