Restauración de paquetes con Restauración de paquetes NuGet

  • Artículo

Restauración de paquetes NuGet restaura todas las dependencias de un proyecto que aparecen en un archivo de proyecto o en un archivo packages.config. Puede restaurar los paquetes manualmente con nuget restore, dotnet restore, msbuild -t:restore o a través de Visual Studio. Los comandos dotnet build y dotnet run restauran automáticamente los paquetes, y puede configurar Visual Studio para restaurar paquetes automáticamente cuando compila un proyecto.

Para promover un entorno de desarrollo más limpio y reducir el tamaño del repositorio, la restauración de paquetes hace que todas las dependencias de un proyecto estén disponibles sin tener que almacenarlas en el control de código fuente. Si desea configurar el repositorio de control de código fuente para excluir los archivos binarios del paquete, vea el artículo sobre los paquetes y el control de código fuente.

Comportamiento de Restauración de paquetes

Restauración de paquetes intenta instalar todas las dependencias del paquete en el estado que coincida con los elementos <PackageReference> de un archivo de proyecto, como .csproj, o los elementos <package> de un archivo packages.config. La Restauración de paquetes primero instala las dependencias directas de un proyecto según sea necesario y, luego, instala todas las dependencias de los paquetes a lo largo del gráfico de dependencias completo.

Si un paquete necesario aún no está instalado, NuGet primero intenta recuperarlo de los paquetes globales locales o de las carpetas de caché HTTP. Si el paquete no está en las carpetas locales, NuGet intenta descargarlo desde todos los orígenes configurados en Visual Studio en Herramientas>Opciones>Administrador de paquetes NuGet>Orígenes del paquete.

Durante la restauración, NuGet ignora el orden de los orígenes de los paquetes y utiliza el paquete del primer origen que responde a las solicitudes. Si se produce un error en la restauración, NuGet no indica el error hasta después de comprobar todos los orígenes y solo informa del error del último origen de la lista. El error implica que el paquete no estaba presente en ninguno de los orígenes, aunque no muestre los otros errores individualmente.

Para obtener más información sobre el comportamiento de NuGet, consulte las configuraciones comunes de NuGet.

Restaurar paquetes

Si las referencias del paquete en el archivo del proyecto o el archivo packages.config son correctas, utilice la herramienta que prefiera para restaurar los paquetes:

Después de completar una restauración correctamente:

  • Para los proyectos que utilizan <PackageReference>, el paquete está presente en la carpeta global-packages local y se vuelve a crear el archivo obj/project.assets.json del proyecto.
  • Para los proyectos que utilizan packages.config, el paquete aparece en la carpeta packages del proyecto.
  • Ahora el proyecto debería compilarse correctamente.

Si las referencias de los paquetes en su archivo de proyecto o en su archivo packages.config son incorrectas y no coinciden con el estado deseado, instale o actualice los paquetes correctos en lugar de utilizar Restauración de paquetes.

Si le faltan paquetes o errores relacionados con paquetes después de ejecutar Restauración de paquetes, como iconos de error en Explorador de soluciones, siga las instrucciones de Solución de problemas de errores de Restauración de paquetes, o reinstale o actualice los paquetes. En Visual Studio, la consola del administrador de paquetes proporciona varias opciones para volver a instalar los paquetes. Para más información, consulte Utilizar paquetes de aplicaciones.

Restauración de paquetes en Visual Studio

En Visual Studio en Windows, puede restaurar paquetes de forma automática o manual. En primer lugar, configure Restauración de paquetes a través de Herramientas>Opciones>Administrador de paquetes NuGet.

Configuración de las opciones de restauración de paquetes de Visual Studio

Configure las opciones de Restauración de paquetes a continuación en Herramientas>Opciones>Administrador de paquetes NuGet>General.

Screenshot that shows the NuGet Package Manager options.

Permitir a NuGet descargar los paquetes que falten

Seleccione Permitir a NuGet descargar los paquetes que falten para habilitar la restauración de paquetes y el comando Restaurar paquetes NuGet. Esta selección establece el ajuste packageRestore/enabled como True en la sección packageRestore del archivo NuGet.Config global, en %AppData%\Roaming\NuGet en Windows o ~/.nuget/NuGet/ en Mac o Linux.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Nota:

Para invalidar de forma global la opción packageRestore/enabled, puede establecer la variable de entorno EnableNuGetPackageRestore como True o False antes de abrir Visual Studio o iniciar una compilación.

Para habilitar o deshabilitar Restauración de paquetes para todos los usuarios de un ordenador, puede agregar las opciones de configuración al archivo NuGet.Config global en Windows en %ProgramData%\NuGet\Config, a veces en una carpeta de Visual Studio <IDE>\<Version>\<SKU> determinada, o en Mac/Linux en ~/.local/share. Después, los usuarios individuales pueden habilitar la restauración de forma selectiva cuando sea necesario en un nivel de proyecto. Para obtener más información sobre la manera en que NuGet prioriza varios archivos de configuración, consulte las configuraciones comunes de NuGet.

Importante

Si edita el valor packageRestore en NuGet.Config directamente, reinicie Visual Studio para que en Opciones se muestren los valores actuales.

Comprobar automáticamente si faltan paquetes durante la compilación

Seleccione Comprobar automáticamente si faltan paquetes durante la compilación en Visual Studio para restaurar automáticamente los paquetes que faltan al ejecutar una compilación desde Visual Studio. Esta configuración no afecta a las compilaciones que se ejecutan desde la línea de comandos de MSBuild. Esta selección establece el valor packageRestore/automatic como True en la sección packageRestore del archivo NuGet.Config.

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

Para los proyectos que no son de estilo SDK, debe seleccionar Permitir que NuGet descargue paquetes que faltan, así como Comprobar automáticamente si faltan paquetes durante la compilación en Visual Studio en Opciones para habilitar la restauración automática.

Elección del formato predeterminado de administración de paquetes

NuGet tiene dos formatos de administración de paquetes, PackageReference y packages.config. Seleccione el formato que desea utilizar en la lista desplegable en Administración de paquetes. También puede seleccionar si desea permitir la selección de formato en la primera instalación del paquete.

Nota:

  • Si un proyecto no admite ambos formatos de administración de paquetes, NuGet usa el formato de administración de paquetes que sea compatible con el proyecto, que puede no ser el predeterminado que configuró en las opciones. Después, NuGet no solicitará la selección en la primera instalación, incluso si seleccionó esa opción.

  • Si utiliza la consola del Administrador de paquetes para instalar el primer paquete de un proyecto, NuGet no solicita la selección de formato, aunque la opción esté seleccionada en Opciones.

Restaurar paquetes de forma manual o automática

Después de habilitar la restauración de paquetes en Opciones, puede hacer clic con el botón derecho en la solución en Explorador de soluciones y seleccionar Restaurar paquetes NuGet para restaurar paquetes en cualquier momento.

Si habilitó la restauración automática en Opciones, la restauración del paquete se produce automáticamente cuando crea un proyecto a partir de una plantilla o compila un proyecto. En NuGet 4.0 y versiones posteriores, la restauración también se produce automáticamente al realizar cambios en un proyecto de estilo SDK.

Para los proyectos que utilizan <PackageReference>, puede ver las referencias de paquete en Explorador de soluciones de Visual Studio, en Dependencias>Paquetes. Los paquetes que no se instalan correctamente al restaurar o ejecutar manualmente una compilación muestran iconos de error en Explorador de soluciones. Haga clic con el botón derecho en el proyecto, seleccione Administrar paquetes NuGet y utilice el Administrador de paquetes NuGet para desinstalar y reinstalar los paquetes afectados. Para obtener más información, consulte Cómo volver a instalar y actualizar paquetes.

Si ve el error Este proyecto hace referencia a los paquetes NuGet que faltan en este ordenador o Uno o varios paquetes de NuGet se deben restaurar, pero no pudieron restaurarse porque no se ha concedido el consentimiento, compruebe que haya habilitado la restauración automática. Para proyectos anteriores, consulte Migración a la restauración automática de paquetes. Consulte también Solución de errores de restauración de paquetes.

Restauración mediante la CLI de dotnet

El comando dotnet restore restaura los paquetes que el archivo de proyecto enumera con <PackageReference>. Para obtener más información, vea Referencias de paquete en un archivo del proyecto.

.NET Core 2.0 y posteriores y los comandos dotnet build y dotnet run restauran los paquetes automáticamente. A partir de NuGet 4.0, dotnet restore ejecuta el mismo código que nuget restore.

Para restaurar un paquete con dotnet restore:

  1. Abra una línea de comandos y cambie al directorio que contiene el archivo del proyecto.
  2. Ejecute dotnet restore.

Importante

Para agregar una referencia de paquete que falta al archivo del proyecto, utilice dotnet add package, que también ejecuta restore.

Restauración con la CLI de NuGet

El comando de restauración de la CLI de NuGet descarga e instala los paquetes que faltan. El comando funciona en proyectos que usan PackageReference o packages.config para las referencias de paquete.

Al igual que install, el comando restore solo agrega paquetes al disco, pero no modifica el archivo de proyecto o packages.config. Para agregar dependencias del proyecto, use la interfaz de usuario o la consola de Visual Studio Administrador de paquetes.

Para restaurar los paquetes, ejecute el siguiente comando:

nuget restore <projectPath>

El comando restore usa un archivo de solución o un archivo package.config en la ruta de acceso del proyecto especificada.

Por ejemplo, para restaurar todos los paquetes de MySolution.sln en el directorio actual, ejecute:

nuget restore MySolution.sln

Nota:

En el caso de los proyectos que no son de estilo SDK que usan PackageReference, use msbuild -t:restore para restaurar paquetes en su lugar.

Restauración con MSBuild

Puede utilizar msbuild -t:restore para restaurar paquetes en NuGet 4. y versiones posteriores y MSBuild 15.1 y versiones posteriores, que se incluyen con Visual Studio 2017 y versiones posteriores.

Este comando restaura paquetes en proyectos que utilizan PackageReference para referencias de paquetes. A partir de la versión 16.5 de MSBuild, el comando también admite referencias de paquete packages.config cuando se usa con -p:RestorePackagesConfig=true.

Para utilizar la restauración de MSBuild:

  1. Abra un símbolo del sistema para desarrolladores buscando el símbolo del sistema para desarrolladores e inicie el símbolo del sistema desde el menú Inicio de Windows, que configura todas las rutas de acceso necesarias para MSBuild.

  2. Cambie a la carpeta del proyecto y escriba msbuild -t:restore.

  3. Una vez completada la restauración, escriba msbuild para recompilar el proyecto. Asegúrese de que la salida de MSBuild indique que la compilación se ha completado correctamente.

Nota:

Puede utilizar msbuild -restore para ejecutar restore, volver a cargar el proyecto y compilarlo, ya que la compilación es el objetivo predeterminado. Para obtener más información, consulte Restaurar y compilar con un comando de MSBuild.

Restauración con Azure Pipelines o Azure DevOps Server

Al crear una definición de compilación en Azure Pipelines, puede incluir la tarea NuGet CLI restore o dotnet CLI restore en la definición antes de cualquier tarea de compilación. Algunas plantillas de compilación incluyen la tarea restore de forma predeterminada.

Tanto Azure DevOps Server como TFS 2013 y versiones posteriores restauran los paquetes automáticamente durante la compilación, siempre y cuando utilice una plantilla de Team Build para TFS 2013 o versiones posteriores. También puede incluir un paso de compilación para ejecutar una opción de restauración de la línea de comandos, o bien migrar la plantilla de compilación a una versión posterior. Para obtener más información, consulte Configurar la restauración de paquetes con Team Foundation Build.

Restricción de las versiones del paquete

La restauración de NuGet mediante cualquier método respeta las restricciones de versión que especifique en packages.config o en el archivo del proyecto.

  • En packages.config, puede especificar un intervalo allowedVersions en la dependencia. Para obtener más información, consulte Restricciones de las versiones de actualización. Por ejemplo:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • En un archivo de proyecto, puede especificar el intervalo de versiones en la propiedad Version de la dependencia. Por ejemplo:

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

En ambos casos, utilice la notación que se describe en Package versioning (Control de versiones de paquetes).

Restauración forzada a partir de orígenes de paquetes remotos

De manera predeterminada, las operaciones de restauración de NuGet utilizan paquetes de las carpetas global-packages y http-cache locales, como se describe en Administración de las carpetas de paquetes globales, de caché y temporales. Para evitar el uso de estos paquetes locales, utilice las opciones a continuación.

Para borrar todas las cachés locales:

  • IEn Visual Studio, seleccione el botón Borrar todas las cachés de NuGet en Herramientas>Opciones>Administrador de paquetes NuGet>General.
  • En la CLI de dotnet, utilice dotnet nuget locals all --clear.
  • En la CLI de NuGet, utilice nuget locals all -clear.

Para evitar el uso de paquetes en la carpeta global-packages:

  • Borre la carpeta con nuget locals global-packages -clear o dotnet nuget locals global-packages --clear.
  • Establezca temporalmente la variable de entorno NUGET_PACKAGES en otra carpeta.
  • Cree un archivo NuGet.Config que establezca globalPackagesFolder para PackageReference, o repositoryPath para packages.config, en una carpeta diferente. Para obtener más información, vea los valores de configuración.
  • Solo MSBuild: especifique otra carpeta con la propiedad RestorePackagesPath.

Para evitar el uso de paquetes en la caché HTTP:

  • Borre la memoria caché con nuget locals http-cache -clear o dotnet nuget locals http-cache --clear.
  • Establezca temporalmente la variable de entorno NUGET_HTTP_CACHE_PATH en otra carpeta.
  • Para nuget restore, utilice la opción -NoHttpCache, o para dotnet restore, utilice la opción --no-http-cache. Estas opciones no afectan a las operaciones de restauración mediante la consola o el Administrador de paquetes de Visual Studio.

Migración a la restauración automática de paquetes

Las versiones anteriores de NuGet admitían una restauración de paquetes integrada de MSBuild. Los proyectos que utilizan la restauración de paquetes integrada en MSBuild en desuso deben migrar a la restauración automática de paquetes.

Estos proyectos suelen contener una carpeta .nuget con tres archivos: NuGet.config, nuget.exe y NuGet.targets. El archivo NuGet.targets hace que NuGet utilice el enfoque integrado de MSBuild, por lo que debe eliminarse.

Para migrar a la restauración automática de paquetes, realice lo siguiente:

  1. Habilite la restauración automática de paquetes.
  2. Cierre Visual Studio.
  3. Elimine los archivos .nuget/nuget.exe y .nuget/NuGet.targets.
  4. Para cada archivo del proyecto, elimine el elemento <RestorePackages> y todas las referencias a NuGet.targets.

Para probar la restauración automática de paquetes, realice lo siguiente:

  1. Quite la carpeta paquetes de la solución.
  2. Abra la solución en Visual Studio e inicie una compilación. La restauración automática de paquetes debe descargar e instalar los paquetes de dependencia, sin agregarlos al control de código fuente.

Pasos siguientes