Migración de packages.config a PackageReference

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

Ventajas de usar 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 (a través del nodo PackageReference) se gestionan directamente dentro de los archivos de proyecto en lugar de usar un archivo packages.config independiente.
• Vista desordenada de las dependencias de nivel superior: a diferencia de packages.config, PackageReference enumera solo los paquetes NuGet que instaló directamente en el proyecto. Como resultado, la interfaz de usuario del Administrador de paquetes NuGet y el archivo del proyecto no están desordenados con dependencias de nivel inferior.
• Mejoras de rendimiento: al usar PackageReference, los paquetes se mantienen en la carpeta global-packages (como se describe en Administración de los paquetes globales y las carpetas de caché en lugar de en una packages carpeta dentro de la solución). Como resultado, PackageReference funciona 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 permite hacer referencia condicional a un paquete NuGet y elegir referencias de paquete por plataforma de destino, configuración, plataforma u otras dinámicas.

Limitaciones

• PackageReference de NuGet no está disponible en Visual Studio 2015 ni en 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 obtener más información, consulte Problemas de compatibilidad de paquetes.

Además, hay algunas diferencias en el funcionamiento de PackageReferences en comparación con packages.config. Por ejemplo, PackageReference no admite restricciones en versiones de actualización , pero PackageReference agrega compatibilidad con versiones flotantes.

Problemas conocidos

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

Cuestión

Cuando se abre un proyecto por primera vez, Es posible que NuGet no se haya inicializado hasta que se realice una operación de NuGet. Esto hace que la opción de migración no aparezca en el menú contextual del botón derecho en packages.config o References.

Solución

Realice cualquiera de las siguientes acciones de NuGet:

• Abra la interfaz de usuario del Administrador de paquetes: haga clic con el botón derecho y References seleccione Manage NuGet Packages...
• Abra la consola del Administrador de paquetes- Desde Tools > NuGet Package Manager, seleccione Package Manager Console
• Ejecutar 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
• Compila el proyecto, lo que también desencadena la restauración de NuGet.

Ahora debería poder 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 de ASP.NET y C++.

Pasos de migración

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 Referencias o en el packages.config archivo y seleccione Migrar packages.config a PackageReference....

3. El migrador analiza las referencias del paquete NuGet del proyecto e intenta clasificarlos 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 transitiva y resuelve las dependencias dinámicamente, lo que significa que las dependencias transitivas no se deben instalar 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 transitivamente (los de las buildcarpetas , buildCrossTargeting, contentFileso analyzers ) y los marcados como una dependencia de desarrollo (developmentDependency = "true").

5. Revise 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 principio de la migración. El informe se guarda en la carpeta de copia de seguridad.

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

Cómo revertir a packages.config

1. Cierre el proyecto migrado.

2. Copie el archivo del proyecto y packages.config de la copia de seguridad (normalmente <solution_root>\MigrationBackup\<unique_guid>\<project_name>\) en 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 desde el comando de 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 copiar los metadatos del paquete de un .nuspec archivo en las propiedades de MSBuild y, a continuación, puede usar msbuild -t:pack para crear el paquete. Si usa Visual Studio 2022 o versiones anteriores, también deberá instalar el paquete NuGet.Build.Tasks.Pack. Desde Visual Studio 2026, el paquete está integrado en MSBuild.

Problemas de compatibilidad de paquetes

Algunos aspectos admitidos en packages.config no se admiten en PackageReference. El migrador analiza y detecta estos problemas. Es posible que cualquier paquete que tenga uno o varios de los siguientes problemas no se comporte según lo previsto después de la migración.

Se ignoran los scripts "install.ps1" cuando se instala el paquete después de la migración.

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

• Posible impacto: los paquetes que dependen de estos scripts para configurar algún comportamiento en el proyecto de destino podrían no funcionar según lo previsto.

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

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

• Posible impacto: Los recursos en 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 .xdt los archivos se omiten al instalar o desinstalar un paquete.

• Posible impacto: las transformaciones XDT no se aplican a ningún archivo XML del proyecto, normalmente, web.config.install.xdt y web.config.uninstall.xdt, lo que significa que el archivo del web.config proyecto no se actualiza cuando el paquete está instalado o desinstalado.

Los ensamblados de la raíz de 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 lib la carpeta 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 al marco de destino del proyecto e instala los ensamblados coincidentes en el proyecto.

• Posible impacto: es posible que los paquetes que no tengan una subcarpeta que coincida con el moniker de la plataforma de destino (TFM) correspondiente al marco de destino del proyecto no se comporten según lo previsto después de la transición o se produzca un error en la instalación durante la migración.

¿Ha encontrado un problema? ¡Reporta!

Si experimenta un problema con la experiencia de migración, envíe un problema en el repositorio de GitHub de NuGet.