Reinstalación y actualización de paquetes NuGet en Visual Studio

  • Article

A veces, las referencias de paquete pueden interrumpirse dentro de un proyecto de Visual Studio. El hecho de desinstalar y volver a instalar la misma versión del paquete a menudo restaura las referencias para que funcionen. La actualización de un paquete, que instala una versión actualizada, también puede resolver el problema. En este artículo se describe cómo volver a instalar y actualizar paquetes NuGet para solucionar las referencias de paquetes rotos y los proyectos rotos.

Nota:

Las instrucciones de este artículo solo se aplican a los proyectos que usan el formato de administración packages.config. En el caso de los proyectos PackageReference, una operación de restauración corrige automáticamente las referencias rotas.

Escenarios comunes

Estos son algunos escenarios comunes en los que puede encontrar referencias de paquete rotas en el proyecto de Visual Studio.

Escenario Descripción Resolución
Referencias rotas después de restaurar paquetes Abre el proyecto de Visual Studio y restaura paquetes NuGet, pero las referencias de paquetes rotos permanecen. Para corregir las referencias, intente reinstalar cada paquete por separado.
Proyecto roto debido a archivos eliminados Los archivos de paquete eliminados (archivos que faltan) hacen que el proyecto se interrumpa. NuGet no impide la eliminación de elementos que agregue de paquetes. Puede ser fácil modificar accidentalmente el contenido instalado desde un paquete e interrumpir el proyecto. Para restaurar el proyecto, intente volver a instalar los paquetes afectados.
Proyecto roto después de actualizar paquetes Una actualización del paquete interrumpe el proyecto. Las actualizaciones complementarias de un paquete de dependencias suelen provocar este tipo de error. Para restaurar el estado de la dependencia a su funcionamiento anterior, intente reinstalar el paquete dependiente específico.
Referencias rotas después de redestinar o actualizar el proyecto Un proceso de redestinación o actualización de un proyecto provoca referencias de paquete rotas. Después de redestinar el proyecto, NuGet muestra un error de compilación. Las advertencias de compilación enumeran los paquetes que podrían tener que volver a instalarse. O, después de actualizar el proyecto, NuGet muestra un error en el registro de actualización de proyectos. El archivo de registro enumera los paquetes que podrían tener que volver a instalarse. Para resolver problemas debido a un cambio en la plataforma de destino, intente reinstalar uno o varios paquetes.
Cambios de paquetes en desarrollo Los autores de paquetes a menudo necesitan volver a instalar la misma versión del paquete que están desarrollando actualmente para probar sus cambios. En Visual Studio, la consola del administrador de paquetes NuGet proporciona muchas opciones flexibles para actualizar y volver a instalar los paquetes. Para volver a instalar un paquete en desarrollo, puede usar el comando Update-Package -reinstall.

Opciones de implementación

Tiene varias opciones para actualizar y volver a instalar paquetes NuGet. Entre los métodos comunes se incluyen las opciones de la interfaz de usuario del administrador de paquetes NuGet, la consola del administrador de paquetes de NuGet y la CLI (interfaz de la línea de comandos) de NuGet.

Interfaz de usuario del administrador de paquetes

Además de la interfaz de consola, la interfaz de usuario del administrador de paquetes también proporciona opciones de menú para instalar, actualizar y desinstalar paquetes.

  • Para actualizar un paquete, abra la pestaña Actualizaciones, elija uno o varios paquetes y seleccione Actualizar.

  • Para volver a instalar un paquete, desinstale primero el paquete y vuelva a instalarlo. Abra la pestaña Instalados, elija un paquete, registre su nombre y seleccione Desinstalar. Vaya a la pestaña Examinar, busque el nombre del paquete, elíjalo y, luego, seleccione Instalar.

Consola del administrador de paquetes

Para acceder a la consola del administrador de paquetes, vaya a Herramientas>Administrador de paquetes NuGet>Consola del administrador de paquetes.

  • Para actualizar un paquete, la consola del administrador de paquetes proporciona el comando Update-Package.

  • Para volver a instalar un paquete, puede usar el mismo comando con el parámetro -reinstall. Este enfoque es la opción más sencilla, si es compatible con la configuración.

Para obtener más información, consulte las secciones Update-Package command (Comando Update-Package) y Package reinstall considerations (Consideraciones sobre la reinstalación de paquetes).

CLI de NuGet

La CLI de NuGet, nuget.exe, es la utilidad de línea de comandos para Windows que proporciona todas las funcionalidades de NuGet.

  • Para actualizar un paquete instalado, ejecute el comando nuget update.

  • Para volver a instalar todos los paquetes NuGet, elimine la carpeta del paquete y, a continuación, ejecute el comando nuget install.

  • Para volver a instalar un único paquete, elimine la carpeta del paquete y, a continuación, ejecute el comando nuget install <id>, donde el argumento <id> es el identificador del paquete específico.

Nota:

Para la CLI de dotnet, no es necesario el procedimiento equivalente. Al ejecutar el comando dotnet restore, la CLI de dotnet usa NuGet para determinar las dependencias y descargar los paquetes NuGet necesarios. Para obtener más información, consulte Restauración de paquetes NuGet con la CLI de dotnet.

Restricciones en las versiones de actualización

De forma predeterminada, al volver a instalar o actualizar un paquete siempre se instala la última versión disponible del origen del paquete. Sin embargo, los proyectos que usan el formato de administración packages.config pueden limitar específicamente el intervalo de versiones del paquete NuGet permitido.

Supongamos que la aplicación solo funciona con la versión 1.x de un paquete, pero no con la versión 2.0 o posterior, debido a un cambio importante en la API del paquete. Para garantizar que la aplicación funcione según lo previsto, restrinja las actualizaciones del paquete NuGet a solo las versiones 1.x. La limitación ayuda a evitar actualizaciones accidentales que podrían interrumpir la aplicación.

Para establecer una restricción, abra el archivo packages.config en un editor de texto. Busque la dependencia que desea limitar y agregue el atributo allowedVersions con el intervalo de versiones deseado.

En el ejemplo siguiente se muestra cómo restringir las actualizaciones a la versión 1.x estableciendo el atributo allowedVersions en [1,2):

<?xml version="1.0" encoding="utf-8"?>
<packages>
    <package id="ExamplePackage" version="1.1.0" allowedVersions="[1,2)" />

    <!-- ... -->
</packages>

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

Comando Update-Package

El comando Update-Package de la consola del administrador de paquetes es la manera más fácil de reinstalar un paquete y solucionar las referencias rotas. Sin embargo, este enfoque no se puede usar en todos los escenarios. Puede usar el comando para actualizar un paquete instalado, pero no para realizar una instalación inicial. Si intenta actualizar o reinstalar un paquete que aún no está instalado en la configuración, el comando devuelve un error. Asegúrese de revisar la sección Consideraciones de reinstalación del paquete antes de trabajar con el comando.

Al actualizar paquetes de un proyecto o una solución con PackageReference, se actualiza siempre a la versión más reciente del paquete (excepto los paquetes de versiones preliminares). Los proyectos que usan el formato de administración packages.config pueden limitar las versiones de actualización, como se describe en Restringir las versiones de actualización.

En las secciones siguientes se proporcionan ejemplos para trabajar con el comando.

Volver a instalar las opciones del paquete

A continuación se muestra un uso básico del comando para realizar una reinstalación. Para identificar un paquete NuGet específico, puede usar el parámetro opcional -Id.

# Reinstall the package named <package_name>
Update-Package -Id <package_name> –reinstall

Usar el comando Update-Package es más fácil que quitar un paquete e intentar buscar el mismo paquete en la galería de NuGet con la misma versión.

Actualizar las opciones del paquete

El mismo comando sin el parámetro -reinstall actualiza un paquete a una versión más reciente, si procede. El comando devuelve un error si el paquete especificado aún no está instalado en un proyecto.

# Update the package named <package_name>
Update-Package <package_name>

Opciones de proyecto y solución

De forma predeterminada, el comando Update-Package afecta a todos los proyectos de una solución. Para limitar la acción a un proyecto específico, use el parámetro -ProjectName. Proporcione el nombre del proyecto tal como aparece en el Explorador de soluciones de Visual Studio.

El comando siguiente vuelve a instalar un paquete NuGet para un proyecto específico de la solución. El nombre del paquete NuGet específico que se va a reinstalar se proporciona en el parámetro <package_name>.

# Reinstall the package named <package_name> in MyProject only
Update-Package <package_name> -ProjectName MyProject -reinstall

Si desea reinstalar todos los paquetes del proyecto, use el parámetro -ProjectName sin especificar ningún paquete determinado. Puede seguir este mismo enfoque para actualizar los paquetes del proyecto, como se muestra en este ejemplo:

# Update all packages in MyProject only
Update-Package -ProjectName MyProject

Para actualizar todos los paquetes de una solución, use solo el comando Update-Package, sin ningún otro argumento ni parámetro.

Importante

Asegúrese de usar cuidadosamente el siguiente formato del comando. El proceso de comando puede tardar mucho tiempo en realizar todas las actualizaciones.

# Update all packages in all projects in the solution
Update-Package

Consideraciones sobre la reinstalación de paquetes

Si piensa usar el comando Update-Package para reinstalar paquetes, revise las consideraciones siguientes para garantizar la compatibilidad con el escenario de configuración.

  • Es posible que los paquetes y sus dependencias no admitan una plataforma de destino de proyecto redestinado.
  • Cuando el atributo requireReinstallation se establece en true, Visual Studio emite advertencias de compilación para los paquetes afectados.
  • La reinstalación de un paquete y las restricciones de versión pueden presentar problemas de compatibilidad de versiones de dependencia.
  • La reinstalación de un paquete específico puede hacer que los paquetes dependientes se interrumpan.

El paquete no admite la plataforma de destino del proyecto

Si redestina la plataforma de destino del proyecto, es posible que uno o varios paquetes no admitan la nueva configuración de destino.

Normalmente, volver a instalar un paquete con el comando Update-Package –reinstall <package_name> funciona. Se desinstala un paquete instalado en una plataforma de destino antigua y se instala el mismo paquete en la nueva plataforma de destino del proyecto.

En algunos casos, puede que haya un paquete que no sea compatible con la nueva plataforma de destino. Estos son algunos de los problemas que pueden surgir:

  • Si un paquete es compatible con las bibliotecas de clases portables (PCL) y redestina el proyecto a una combinación de plataformas que ya no son compatibles con el paquete, las referencias al paquete no estarán presentes después de la reinstalación.

  • Este problema puede suceder en el caso de los paquetes que usa directamente o de los paquetes instalados como dependencias. Cualquier paquete que use directamente podría admitir la nueva plataforma de destino, mientras que sus dependencias no.

  • Si la reinstalación de los paquetes después de la redestinación de la aplicación genera errores de compilación o errores en tiempo de ejecución, es posible que deba revertir la plataforma de destino o buscar paquetes alternativos que admitan correctamente la nueva plataforma de destino.

atributo requireReinstallation establecido en true

Después de volver a establecer la plataforma de destino del proyecto o actualizar paquetes NuGet, NuGet podría añadir el atributo requireReinstallation al archivo packages.config del proyecto. Si NuGet detecta paquetes afectados durante la redestinación o la actualización de un proceso, agrega un atributo requireReinstallation="true" al archivo packages.config para todas las referencias de paquetes afectadas. Como resultado, cada compilación posterior del proyecto en Visual Studio genera advertencias de compilación para esos paquetes. Las advertencias se presentan como recordatorio para volver a instalar el paquete afectado.

Incompatibilidad de la versión de dependencia del paquete

El comando Update-Package –reinstall vuelve a instalar la misma versión de un paquete instalado y la versión más reciente de las dependencias. Para solucionar los problemas de incompatibilidad de versiones, puede establecer restricciones de intervalo de versiones para controlar la configuración. NuGet se adhiere a las restricciones y actualiza las dependencias del paquete a versiones más recientes solo cuando sea necesario para solucionar un problema.

  • Si la configuración de restricciones hace que una dependencia vuelva a una versión anterior durante la reinstalación del paquete, puede solucionar el problema con el comando Update-Package <dependency_name>. Este comando vuelve a instalar la dependencia especificada sin afectar al paquete dependiente.

  • También puede usar el comando Update-Package –reinstall <packageName> -ignoreDependencies. Esta opción vuelve a instalar la misma versión del paquete original, pero no vuelve a instalar las dependencias. Use este método si la actualización de las dependencias del paquete podría producir un estado de configuración interrumpido.

Paquete dependiente roto

Al reinstalar un paquete específico, los paquetes instalados que dependen del paquete reinstalado no se actualizan. Las versiones de estos otros paquetes instalados siguen siendo las mismas. Como resultado, volver a instalar una dependencia puede interrumpir un paquete dependiente.