Migración de packages.config a PackageReference

  • Artículo

Visual Studio 2017 versión 15.7, y versiones posteriores, admite la migración de un proyecto desde el formato de administración packages.config al formato PackageReference.

Ventajas del uso de PackageReference

  • Administrar todas las dependencias del proyecto en un solo lugar: al igual que las referencias de proyecto a proyecto y las referencias de ensamblado, las referencias de paquetes NuGet (mediante el nodo PackageReference) se administran directamente dentro de los archivos de proyecto en lugar de usar un archivo packages.config independiente.
  • Vista despejada de las dependencias de nivel superior: a diferencia de packages.config, PackageReference solo enumera los paquetes NuGet que se instalaron directamente en el proyecto. Como resultado, la interfaz de usuario del administrador de paquetes NuGet y el archivo de proyecto no están abarrotadas con las dependencias de nivel inferior.
  • Mejoras de rendimiento: cuando se utiliza PackageReference, los paquetes se mantienen en la carpeta global-packages (tal como se describe en Administración de las carpetas de paquetes globales, de caché y temporales) en lugar de en una carpeta packages dentro de la solución. Por consiguiente, PackageReference se ejecuta más rápido y consume menos espacio en disco.
  • Control preciso sobre las dependencias y el flujo de contenido: el uso de las características existentes de MSBuild le permite hacer referencia condicionalmente a un paquete NuGet y elegir referencias de paquetes por plataforma de destino, configuración, plataforma u otras tablas dinámicas.

Limitaciones

  • PackageReference de NuGet no está disponible en Visual Studio 2015 y versiones anteriores. Los proyectos migrados solo se pueden abrir en Visual Studio 2017 y versiones posteriores.
  • La migración no está disponible actualmente para proyectos de C++ y ASP.NET.
  • Es posible que algunos paquetes no sean totalmente compatibles con PackageReference. Para más información, consulte los problemas de compatibilidad de paquetes.

Además, hay diferencias en el modo en que PackageReferences funciona en comparación con packages.config. Por ejemplo, PackageReference no admite la restricción de versiones de actualización, pero agrega compatibilidad con versiones flotantes.

Problemas conocidos

  1. La opción Migrate packages.config to PackageReference... no está disponible en el menú contextual.

Problema

Cuando se abre un proyecto por primera vez, NuGet puede no inicializarse hasta que se realiza una operación de NuGet. Esto da lugar a que la opción de migración no aparezca en el menú contextual en packages.config o References.

Solución alternativa

Realice cualquiera de las siguientes acciones de NuGet:

  • Abra la UI del administrador de paquetes; haga clic con el botón derecho en References y seleccione Manage NuGet Packages....
  • Abra la consola del administrador de paquetes; en Tools > NuGet Package Manager, seleccione Package Manager Console.
  • Ejecute la restauración de NuGet; haga clic con el botón derecho en el nodo de la solución en el Explorador de soluciones y seleccione Restore NuGet Packages.
  • Compile el proyecto, una acción que también desencadena la restauración de NuGet.

Ahora debería ver la opción de migración. Tenga en cuenta que esta opción no se admite y no se mostrará para los tipos de proyecto ASP.NET y C++.

Pasos de migración

Nota:

Antes de comenzar la migración, Visual Studio crea una copia de seguridad del proyecto para revertir a packages.config si fuera necesario.

  1. Abra una solución que contenga el proyecto mediante packages.config.

  2. En el Explorador de soluciones, haga clic con el botón derecho en el nodo References o en el archivo packages.config y seleccione Migrar packages.config a PackageReference....

  3. El migrador analiza las referencias del paquete NuGet del proyecto e intenta categorizarlas en Dependencias de nivel superior (paquetes NuGet que instaló directamente) y Dependencias transitivas (paquetes que se instalaron como dependencias de paquetes de nivel superior).

    Nota:

    PackageReference admite la restauración de paquetes transitivos y resuelve las dependencias dinámicamente, lo que significa que no es necesario instalar las dependencias transitivas explícitamente.

  4. (Opcional) Puede optar por tratar un paquete NuGet clasificado como una dependencia transitiva como una dependencia de nivel superior seleccionando la opción Nivel superior para el paquete. Esta opción se establece automáticamente para los paquetes que contienen recursos que no fluyen de forma transitiva (los de las carpetas build, buildCrossTargeting, contentFiles o analyzers) y los marcados como una dependencia de desarrollo (developmentDependency = "true").

  5. Revise todos los problemas de compatibilidad de paquetes.

  6. Seleccione Aceptar para iniciar la migración.

  7. Al final de la migración, Visual Studio proporciona un informe con una ruta de acceso a la copia de seguridad, la lista de paquetes instalados (dependencias de nivel superior), una lista de paquetes a los que se hace referencia como dependencias transitivas y una lista de problemas de compatibilidad identificados al iniciarse la migración. El informe se guarda en la carpeta de copia de seguridad.

  8. Valide que la solución se compila y se ejecuta. Si tiene problemas, presente un problema en GitHub.

Reversión a packages.config

  1. Cierre el proyecto migrado.

  2. Copie el archivo de proyecto y packages.config de la copia de seguridad (normalmente <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) a la carpeta del proyecto. Elimine la carpeta obj si existe en el directorio raíz del proyecto.

  3. Abra el proyecto.

  4. Abra la Consola del Administrador de paquetes mediante el menú Herramientas > Administrador de paquetes NuGet > Consola del Administrador de paquetes.

  5. Ejecute el siguiente comando en la consola:

    update-package -reinstall

Creación de un paquete después de la migración

Una vez completada la migración, se recomienda agregar una referencia al paquete NuGet nuget.build.tasks.pack y luego usar msbuild -t:pack para crear el paquete. Aunque en algunos escenarios podría usar dotnet.exe pack en lugar de msbuild -t:pack, no se recomienda.

Problemas de compatibilidad de paquetes

Algunos aspectos que se admitían en packages.config no se admiten en PackageReference. El migrador analiza y detecta estos problemas. Es posible que los paquetes que tengan uno o varios de los problemas siguientes no tengan el comportamiento esperado después de la migración.

Los scripts "install.ps1" se omiten cuando el paquete se instala después de la migración

  • Descripción: con PackageReference, los scripts de PowerShell install.ps1 y uninstall.ps1 no se ejecutan durante la instalación o desinstalación de un paquete.

  • Impacto potencial: es posible que los paquetes que dependen de estos scripts para configurar algún comportamiento en el proyecto de destino no funcionen según lo esperado.

Los recursos "content" no están disponibles cuando el paquete se instala después de la migración

  • Descripción: los recursos de la carpeta content de un paquete no se admiten con PackageReference y se omiten. PackageReference agrega compatibilidad para contentFiles para tener una mejor compatibilidad transitiva y contenido compartido.

  • Impacto potencial: los recursos de content no se copian en el proyecto y el código del proyecto que depende de la presencia de esos recursos requiere refactorización.

Las transformaciones XDT no se aplican cuando el paquete se instala después de la actualización

  • Descripción: las transformaciones XDT no se admiten con PackageReference, y los archivos .xdt se omiten al instalar o desinstalar un paquete.

  • Impacto potencial: las transformaciones XDT no se aplican a ningún archivo XML de proyecto, normalmente web.config.install.xdt y web.config.uninstall.xdt, lo que significa que el archivo web.config del proyecto no se actualiza cuando el paquete se instala o se desinstala.

Los ensamblados de la raíz lib se omiten cuando el paquete se instala después de la migración

  • Descripción: con PackageReference, se omiten los ensamblados presentes en la raíz de la carpeta lib sin una subcarpeta específica de la plataforma de destino. NuGet busca una subcarpeta que coincida con el moniker de la plataforma de destino (TFM) correspondiente a la plataforma de destino del proyecto e instala los ensamblados coincidentes en el proyecto.

  • Impacto potencial: es posible que los paquetes que no tengan una subcarpeta que coincida con el moniker de la plataforma de destino (TFM) correspondiente a la plataforma de destino del proyecto no se comporten según lo esperado después de la transición o no se puedan instalar durante la migración.

¿Encontró un problema? ¡Notifíquelo!

Si tiene algún problema con la experiencia de migración, registre un problema en el repositorio NuGet de GitHub.