Incluir un paquete NuGet en el proyectoIncluding a NuGet package in your project

NuGet es el administrador de paquetes más popular para el desarrollo de .NET y está integrado en Visual Studio para Mac y Visual Studio en Windows.NuGet is the most popular package manager for .NET development and is built in to Visual Studio for Mac and Visual Studio on Windows. Puede buscar y agregar paquetes a proyectos de Xamarin.iOS y Xamarin.Android mediante cualquier IDE.You can search for and add packages to your Xamarin.iOS and Xamarin.Android projects using either IDE.

En este documento se analiza cómo incluir un paquete NuGet en un proyecto y se muestra la cadena de herramientas que hace que el proceso se desarrolle sin problemas.This document looks at how to include a NuGet package in a project and demonstrates the tool chain that makes the process seamless.

NuGet en Visual Studio para MacNuGet in Visual Studio for Mac

Para mostrar la funcionalidad del paquete NuGet, primero se crea una nueva aplicación y se le agrega un paquete.To demonstrate the NuGet package functionality we'll first walk through creating a new application and adding a package to it. Luego se tratan las características del IDE que ayudan a administrar paquetes.Then we'll discuss the IDE features that help manage packages.

Crear un proyecto nuevoCreate a new project

En primer lugar, cree un proyecto denominado HelloNuget como se muestra a continuación.First, create a project named HelloNuget as illustrated below. Este ejemplo muestra la plantilla de aplicación de vista única de iOS, aunque cualquier tipo de proyecto compatible funcionaría:This example shows the iOS Single View Application template, but any supported project type would work:

Crear nuevo proyecto de iOS

Adición de un paqueteAdding a Package

Con el proyecto abierto en Visual Studio para Mac, haga clic con el botón derecho en la carpeta Paquetes del Panel de solución y seleccione Agregar paquetes...:With the project open in Visual Studio for Mac, right-click on the Packages folder in the Solution Pad and select Add Packages...:

Acción contextual de adición de nuevo paquete NuGet

Con esto se abre la ventana Agregar paquetes...This launches the Add Packages... window. Asegúrese de que la lista desplegable Origen esté establecida en nuget.org:Ensure that the Source drop-down, is set to nuget.org:

Lista desplegable Origen

Cuando la ventana se abre, carga una lista de paquetes del origen de paquetes predeterminado: nuget.org. Los resultados iniciales presentan el siguiente aspecto:When the window opens it will load a list of packages from the default package source: nuget.org. The initial results look like this:

Lista de paquetes NuGet

Use el cuadro de búsqueda de la esquina superior derecha para buscar un paquete determinado, por ejemplo azure.Use the search box in the top-right corner to find a specific package, for example azure. Cuando encuentre un paquete que quiera usar, selecciónelo y haga clic en el botón Agregar paquete para iniciar la instalación.When you've found a package that you wish to use, select it and click the Add Package button to begin installation.

Adición del paquete NuGet AzureAdd Azure NuGet Package

Una vez que el paquete se ha descargado, se agrega al proyecto.Once the package has been downloaded it will be added to your project. La solución cambia de este modo:The solution will change as follows:

  • El nodo Referencias contiene una lista de todos los ensamblados que forman parte de un paquete NuGet.The References node will contain a list of all the assemblies that are part of a NuGet package.
  • El nodo Paquetes muestra cada paquete NuGet descargado.The Packages node displays each NuGet package that you have downloaded. Puede actualizar esta lista o quitar un paquete de ella.You can update or remove a package from this list.
  • Se agrega un archivo packages.config al proyecto.A packages.config file will be added to the project. El IDE usa este archivo XML para realizar un seguimiento de a qué versiones del paquete se hace referencia en este proyecto.This XML file is used by the IDE to track which package versions are referenced in this project. Este archivo no se debe editar manualmente, sino que debe mantenerse en el control de versiones.This file should not be hand-edited, but you should keep it in version control. Tenga en cuenta que se puede usar un archivo project.json en lugar de un archivo packages.config.Note that a project.json file can be used instead of a packages.config file. El archivo project.json es un nuevo formato de archivo de paquete presentado con NuGet 3 que admite la restauración transitiva.The project.json file is a new package file format introduced with NuGet 3, which supports transitive restore. Puede ver información más detallada sobre project.json en la documentación de NuGet.More detailed information on project.json can be found in the NuGet documentation. Hay que agregar el archivo project.json manualmente y cerrar el proyecto y volverlo a abrir antes de usar el archivo project.json en Visual Studio para Mac.The project.json file needs to be added manually and the project closed and re-opened before the project.json file is used in Visual Studio for Mac.

Uso de paquetes NuGetUsing NuGet Packages

Una vez agregado el paquete NuGet y actualizadas las referencias del proyecto, puede programar con las API como haría con cualquier referencia de proyecto.Once the NuGet package has been added and the project references updated you can program against the APIs as you would with any project reference.

Asegúrese de agregar cualquier directiva using necesaria a la parte superior del archivo:Ensure that you add any required using directives to the top of your file:

using Newtonsoft.Json;

La mayoría de los paquetes NuGet proporcionan información adicional, como un Léame o un vínculo de página de proyecto al origen de NuGet.Most NuGet provide additional information, such as a README or Project page link to the Nuget source. Normalmente puede encontrar un vínculo a este en el texto del paquete en la página Agregar paquetes:You can normally find a link to this in the package blurb on the Add Packages page:

Vínculo a la página Ver proyectoView Project Page link

Actualizaciones de paquetesPackage Updates

Las actualizaciones de paquetes se pueden hacer todas a la vez, al hacer clic con el botón derecho en el nodo Paquetes o individualmente en cada componente.Package updates can be done either all at once, by right-clicking on the Packages node, or individually on each component.

Haga clic con el botón derecho en Paquetes para acceder al menú contextual:Right-click on Packages to access the context menu:

Menú Paquetes

  • Agregar paquetes: abre la ventana para agregar más paquetes al proyecto.Add Packages - Opens the window to add more packages to the project.
  • Actualizar: comprueba el servidor de origen de cada paquete y descarga las versiones más recientes.Update - Checks the source server for each package and downloads any newer versions.
  • Restaurar: descarga todos los paquetes que faltan (sin actualizar los paquetes existentes a versiones más recientes).Restore - Downloads any missing packages (without updating existing packages to newer versions).

Las opciones Actualizar y Restaurar también están disponibles en el nivel de solución y afectan a todos los proyectos de esta.Update and Restore options are also available at the Solution level, and affect all the projects in the solution.

También puede hacer clic con el botón derecho en paquetes individuales para acceder a un menú contextual:You can also right-click on individual packages to access a context menu:

Menú Paquetes

  • Número de versión: el número de versión es un elemento de menú deshabilitado que solo se proporciona con fines informativos.Version Number - The version number is a disabled menu item - it is provided for informational purposes only.
  • Actualizar: comprueba el servidor de origen y descarga una versión más reciente (si la hubiera).Update - Checks the source server and downloads a newer version (if it exists).
  • Quitar: quita el paquete de este proyecto y quita los ensamblados correspondientes de las referencias del proyecto.Remove - Removes the package from this project and removes the relevant assemblies from the project's References.

Adición de orígenes de paquetesAdding Package Sources

Los paquetes disponibles para instalar se recuperan inicialmente de nuget.org. Pero puede agregar otras ubicaciones de paquetes a Visual Studio para Mac.Packages available for installation are initially retrieved from nuget.org. However, you can add other package locations to Visual Studio for Mac. Esto puede ser útil para probar los paquetes NuGet propios en desarrollo o para usar un servidor NuGet privado dentro de la empresa u organización.This can be useful for testing your own NuGet packages under development, or to use a private NuGet server inside your company or organization.

En Visual Studio para Mac, vaya a Visual Studio > Preferencias... > NuGet > Orígenes para ver y editar la lista de orígenes de paquetes.In Visual Studio for Mac, navigate to Visual Studio > Preferences... > NuGet > Sources to view and edit the list of package sources. Tenga en cuenta que los orígenes pueden ser un servidor remoto (especificado por una dirección URL) o un directorio local.Note that sources can be a remote server (specified by a URL) or a local directory.

Orígenes de paquetes

Haga clic en Agregar para configurar un nuevo origen.Click Add to set-up a new source. Escriba un nombre descriptivo y la dirección URL (o ruta de acceso de archivo) al origen del paquete.Enter a friendly name and the URL (or file path) to the package source. Si el origen es un servidor web seguro, escriba también el nombre de usuario y la contraseña, de lo contrario, deje en blanco estas entradas:If the source is a secure web server, enter the username and password as well, otherwise leave these entries blank:

Adición de orígenes de paquetes

Al buscar paquetes se pueden seleccionar orígenes diferentes:Different sources can then be selected when searching for packages:

Adición de orígenes de paquetes

Control de versionesVersion Control

En la documentación de NuGet se trata el uso de NuGet sin confirmar paquetes en el control de código fuente.The NuGet documentation discusses using NuGet without committing packages to source control. Si prefiere no almacenar archivos binarios e información sin usar en el control de código fuente, puede configurar Visual Studio para Mac de modo que restaure automáticamente los paquetes desde el servidor.If you prefer not to store binaries and unused information in source control, you can configure the Visual Studio for Mac to automatically restore packages from the server. Esto significa que cuando un desarrollador recupera el proyecto del control de código fuente por primera vez, Visual Studio para Mac descarga e instala automáticamente los paquetes necesarios.This means that when a developer retrieves the project from source control for the first time, the Visual Studio for Mac will automatically download and install the required packages.

Restauración automática de paquetes

Consulte la documentación del control de origen de su propiedad para obtener detalles sobre cómo excluir el directorio packages del seguimiento.Refer to your particular source control documentation for details on how to exclude the packages directory from being tracked.