Uso del Asistente para actualización de .NET heredado

Artículo
06/08/2023

En este artículo, aprenderá a instalar y ejecutar la versión anterior de la herramienta de interfaz de línea de comandos (CLI) del Asistente para actualización de .NET. A partir de la versión 0.5.2, el código base de la herramienta de la CLI del Asistente para actualización de .NET se fusionó mediante cambio de base en la extensión de Visual Studio. Esto significa que hay dos herramientas diferentes de la CLI, la versión anterior a la 0.5.2, que se conoce como versión heredada, y la versión 0.5.2+, la versión actual.

La versión heredada tiene alguna funcionalidad que aún no está disponible en la nueva versión, como el análisis de las actualizaciones de nivel de solución o comandos, pero también carece de las mejoras introducidas en la nueva versión (0.5.2+). Por lo tanto, es posible que quiera usarla hasta que la versión actual aumente en funcionalidad y ámbito.

Sugerencia

La versión heredada de la herramienta puede actualizar los archivos de solución.

Instalación de la versión heredada

La versión heredada de la herramienta se instala de la misma manera que la versión actual, excepto que se especifica la versión 0.4.421302:

dotnet tool install upgrade-assistant -g --version 0.4.421302

Importante

Es posible que se produzca un error al instalar esta herramienta si ha configurado orígenes de fuente NuGet adicionales. Use el parámetro --ignore-failed-sources para tratar esos errores como advertencias en lugar de errores:

dotnet tool install upgrade-assistant -g --ignore-failed-sources --version 0.4.421302

Analizar la aplicación

La versión heredada de la herramienta incluye un modo de análisis que realiza un ensayo simplificado de actualización de la aplicación. Esta herramienta puede aportar información sobre cambios que pueden ser necesarios antes del inicio de la actualización. Abra un terminal y desplácese hasta la carpeta en la que se encuentra el proyecto o la solución de destino. Ejecute el comando upgrade-assistant analyze y pase el nombre del proyecto o la solución que va a actualizar.

Por ejemplo, esta es la salida después de ejecutar el modo de análisis con la aplicación WPF de .NET Framework:

> upgrade-assistant analyze .\WebSiteRatings.sln

[15:39:00 INF] Loaded 9 extensions
[15:39:02 INF] Using MSBuild from C:\Program Files\dotnet\sdk\7.0.201\
[15:39:02 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
[15:39:05 INF] Writing output to C:\code\migration\AnalysisReport.sarif
[15:39:06 INF] Recommending Windows TFM net7.0-windows for project WebSiteRatings.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:06 INF] Marking assembly reference System.Configuration for removal based on package mapping configuration System.Configuration
[15:39:06 INF] Adding package System.Configuration.ConfigurationManager based on package mapping configuration System.Configuration
[15:39:08 INF] Package EntityFramework, Version=6.2.0 does not support the target(s) net7.0-windows but a newer version (6.4.4) does.
[15:39:09 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:10 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Recommending Windows TFM net7.0-windows for project StarVoteControl.csproj because the project either has Windows-specific dependencies or builds to a WinExe
[15:39:13 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added
[15:39:13 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs
[15:39:13 INF] Running analyzers on WebSiteRatings
[15:39:14 INF] Identified 0 diagnostics in project WebSiteRatings
[15:39:14 INF] Running analyzers on StarVoteControl
[15:39:15 INF] Identified 0 diagnostics in project StarVoteControl
[15:39:15 INF] Analysis Complete, the report is available at C:\code\migration\AnalysisReport.sarif

Hay bastante información de diagnóstico interno en la salida, pero parte de esa información resulta útil. Tenga en cuenta que el modo de análisis indica que, durante una actualización, el moniker de la plataforma de destino del proyecto (TFM) se establecerá en net7.0-windows en lugar de en net7.0. Esta recomendación se realiza porque los proyectos a los que hace referencia la solución son proyectos de WPF, una tecnología solo de Windows. Es probable que una aplicación de consola se actualice directamente a TFM net7.0, a menos que use alguna biblioteca o código específicos de Windows.

Ejecución del asistente para actualización

Abra un terminal y desplácese hasta la carpeta en la que se encuentra el proyecto o la solución de destino. Ejecute el comando upgrade-assistant upgrade y pase el nombre del proyecto o la solución que va a actualizar.

Cuando se ejecuta la herramienta, muestra una lista de los pasos que realiza para actualizar el proyecto. A medida que se completa cada paso, proporciona un conjunto de comandos enumerados que permiten al usuario aplicar u omitir el paso siguiente. Puede proporcionar otras opciones, como:

Obtener más información sobre el paso.
Cambiar de proyecto.
Ajustar la configuración de registro.
Detener la actualización y salir.

Si se presiona Intro sin elegir un número, se selecciona el primer elemento de la lista.

Con la iniciación de cada paso la herramienta puede proporcionar información sobre las acciones previstas si lo aplica.

Actualización de una solución

Al actualizar una solución que contiene varios proyectos, debe seleccionar qué proyecto de la solución es el punto de entrada. En función del proyecto de punto de entrada, se crea un gráfico de dependencias para determinar qué proyectos se van a actualizar y en qué orden. Si la solución contiene proyectos que no forman parte del gráfico de dependencias, se omitirán y tendrá que actualizar estos proyectos por separado. Las dependencias se actualizan primero y, a continuación, el proyecto de punto de entrada.

El siguiente paso consiste en elegir el proyecto que se va a actualizar. Debería ver una salida similar al siguiente fragmento de código:

Upgrade Steps

1. [Next step] Select an entrypoint
2. Select project to upgrade

Choose a command:
   1. Apply next step (Select an entrypoint)
   2. Skip next step (Select an entrypoint)
   3. See more step details
   4. Configure logging
   5. Exit

Sugerencia

Preste atención a la salida de cada paso, ya que puede contener información sobre algo que la herramienta no puede actualizar. En función de la complejidad de la aplicación, es posible que tenga más trabajo de actualización para realizar una vez finalizada la herramienta.

Actualización del proyecto

Una vez seleccionado un proyecto, aparece una lista de los pasos de actualización. El primer paso está seleccionado, que consiste en realizar una copia de seguridad del proyecto. La lista de pasos es similar al siguiente fragmento de código:

[15:50:50 INF] Initializing upgrade step Back up project

Upgrade Steps

Entrypoint: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj
Current Project: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj

1. [Next step] Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
4. Update TFM
5. Update NuGet Packages
    a. Duplicate reference analyzer
    b. Package map reference analyzer
    c. Target compatibility reference analyzer
    d. Upgrade assistant reference analyzer
    e. Windows Compatibility Pack Analyzer
    f. MyDotAnalyzer reference analyzer
    g. Newtonsoft.Json reference analyzer
    h. Windows App SDK package analysis
    i. Transitive reference analyzer
6. Add template files
7. Update WCF service to CoreWCF (Preview)
8. Upgrade app config files
    a. Convert Application Settings
    b. Convert Connection Strings
    c. Disable unsupported configuration sections
9. Update source code
    a. Apply fix for UA0002: Types should be upgraded
    b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
10. Move to next project

Choose a command:
   1. Apply next step (Back up project)
   2. Skip next step (Back up project)
   3. See more step details
   4. Select different project
   5. Configure logging
   6. Exit

Cada paso detalla primero lo que se va a hacer y, a continuación, le pide que lo haga. Cualquier paso que no se aplique se omite cuando la herramienta llega a él. Por ejemplo, si la herramienta procesa 7. Actualizar el servicio WCF a CoreWCF (versión preliminar), pero la aplicación no define un servicio WCF, se omite y se procesa el paso 8. A su vez, si el paso 8 no se aplica, también se omite. Es posible que vea muchos pasos omitidos, ya que la herramienta intenta encontrar el siguiente paso que se aplica.

Pasos finales

Tras actualizar los proyectos, tiene que compilarlos y probarlos. Lo más probable es que haya que hacer más trabajo para finalizar la actualización. Es posible que la versión de .NET Framework de la aplicación tuviera referencias a bibliotecas que en realidad el proyecto no está usando y se llevaron. Analice cada referencia y determine si es necesaria o no. Es posible que la herramienta también haya agregado o actualizado una referencia al paquete NuGet a una versión incorrecta.

Por último, busque formas de modernizar la aplicación. Para ejemplos, consulte Modernizaciones después de actualizar a .NET desde .NET Framework.