Migración de ASP.NET Core 2.1 a 2.2

  • Artículo

Por Scott Addie

En este artículo se explica cómo actualizar un proyecto de ASP.NET Core 2.1 existente a ASP.NET Core 2.2.

Requisitos previos

Advertencia

Si usa Visual Studio 2017, consulte dotnet/sdk problema #3124 para información sobre las versiones del SDK de .NET Core que no funcionan con Visual Studio.

Actualización del moniker de la plataforma de destino (TFM)

Los proyectos para .NET Core deben usar el TFM de una versión mayor o igual que .NET Core 2.2. En el archivo del proyecto, actualice el texto interno del nodo <TargetFramework> con netcoreapp2.2:

<TargetFramework>netcoreapp2.2</TargetFramework>

Los proyectos para .NET Framework pueden continuar usando el TFM de una versión mayor o igual que .NET Framework 4.6.1:

<TargetFramework>net461</TargetFramework>

Adopción del modelo de hospedaje en proceso de IIS

Para adoptar el modelo de hospedaje en proceso para IIS, agregue la propiedad <AspNetCoreHostingModel> con un valor de InProcess a <PropertyGroup> en el archivo de proyecto:

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

No se admite el modelo de hospedaje en proceso para aplicaciones de ASP.NET Core que tienen como destino .NET Framework.

Para obtener más información vea Módulo de ASP.NET Core (ANCM) para IIS.

Actualizar un archivo de web.config personalizado

Para los proyectos que usan un archivo web.config personalizado en la raíz del proyecto para generar su archivo web.config publicado:

  • En la entrada <handlers> que agrega el módulo ASP.NET Core (name="aspNetCore"), cambie el valor del atributo modules de AspNetCoreModule a AspNetCoreModuleV2.
  • En el elemento <aspNetCore>, agregue el atributo del modelo de hospedaje (hostingModel="InProcess").

Para saber más sobre el archivo de ejemplo web.config, vea Módulo ASP.NET Core (ANCM) para IIS.

Actualización de las referencias del paquete

Si tiene como destino .NET Core, quite el atributo de la referencia de metapaquete Version en el archivo del proyecto. La inclusión de un atributo Version da como resultado la siguiente advertencia:

A PackageReference to 'Microsoft.AspNetCore.App' specified a Version of `2.2.0`. Specifying the version of this package is not recommended. For more information, see https://aka.ms/sdkimplicitrefs

Para saber más, visite Metapaquete Microsoft.AspNetCore.All para ASP.NET Core.

La referencia de metapaquete debe ser similar al siguiente nodo <PackageReference />:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

Si tiene como destino .NET Framework, actualice el atributo de cada referencia de paquete Version a 2.2.0 o posterior. Estas son las referencias de paquete en un proyecto típico de ASP.NET Core 2.2 destinado a .NET Framework:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.HttpsPolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.2.0" />
</ItemGroup>

Si hace referencia al paquete Microsoft.AspNetCore.Razor.Design, actualice su atributo Version a 2.2.0 o posterior. Si no lo hace, se producirá el siguiente error:

Detected package downgrade: Microsoft.AspNetCore.Razor.Design from 2.2.0 to 2.1.2. Reference the package directly from the project to select a different version.

Actualización de la versión del SDK de .NET Core en global.json

Si la solución se basa en un archivo global.json para que el destino sea una versión específica del SDK de .NET Core, actualice su propiedad version para usar la versión 2.2 instalada en el equipo:

{
  "sdk": {
    "version": "2.2.100"
  }
}

Actualizar la configuración de inicio

Si usa Visual Studio Code, actualice el archivo de configuración de inicio del proyecto (.vscode/launch.json). La ruta de acceso program debe hacer referencia al nuevo TFM:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchBrowser": {
                "enabled": true,
                "args": "${auto-detect-url}",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start ${auto-detect-url}"
                },
                "osx": {
                    "command": "open"
                },
                "linux": {
                    "command": "xdg-open"
                }
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

Actualizar la configuración Kestrel

Si la aplicación llama a UseKestrel llamando CreateDefaultBuilder al método CreateWebHostBuilder de la clase Program, llame a ConfigureKestrel para configurar el servidor Kestrel en lugar de UseKestrel para evitar conflictos con el modelo de hospedaje en proceso de IIS:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

Si la aplicación no llama a CreateDefaultBuilder y compila el host manualmente en la clase Program, llame a UseKestrelantes de llamar a ConfigureKestrel:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        })
        .Build();

    host.Run();
}

Para más información, consulte Servidor web Kestrel en ASP.NET Core.

Actualizar la versión de compatibilidad

Actualice la versión de compatibilidad de Startup.ConfigureServices a Version_2_2:

services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Actualizar la directiva de CORS

En ASP.NET Core 2.2, el middleware CORS responde con un origen comodín (*) si una directiva permite cualquier origen y permite las credenciales. Las credenciales no se admiten cuando se especifica un origen comodín (*) y los exploradores no permitirán la solicitud CORS. Para obtener más información, incluidas las opciones para corregir el problema en el cliente, consulte la documentación web de MDN.

Para corregir este problema en el servidor, realice una de las siguientes acciones:

  • Modifique la directiva CORS para que ya no permita credenciales. Es decir, elimine la llamada a AllowCredentials al configurar la directiva.
  • Si las credenciales son necesarias para que la solicitud CORS se realice correctamente, modifique la directiva para especificar los hosts permitidos. Por ejemplo, use builder.WithOrigins("https://api.example1.com", "https://example2.com") en lugar de AllowAnyOrigin.

Actualización de imágenes de Docker

En la tabla siguiente se muestran los cambios en la etiqueta de la imagen de Docker:

2.1 2.2
microsoft/dotnet:2.1-aspnetcore-runtime mcr.microsoft.com/dotnet/core/aspnet:2.2
microsoft/dotnet:2.1-sdk mcr.microsoft.com/dotnet/core/sdk:2.2

Cambie las líneas FROM del Dockerfile para usar las nuevas etiquetas de imagen en la columna 2.2 de la tabla anterior.

Compilación manual en Visual Studio cuando se usa el hospedaje en proceso de IIS

La experiencia de la compilación automática de Visual Studio en la solicitud del explorador no funciona con el modelo de hospedaje en proceso de IIS. Debe recompilar manualmente el proyecto al usar el hospedaje en proceso. Las mejoras en esta experiencia están planeadas para una futura versión de Visual Studio.

Actualizar del código de registro

El código de configuración de registro recomendado no cambió de 2.1 a 2.2, pero algunos patrones de codificación 1.x que todavía funcionaban en la versión 2.1 ya no funcionan en la versión 2.2.

Si la aplicación registra la inicialización, el filtrado y la carga de configuración del proveedor en la clase Startup, mueva ese código a Program.Main:

  • Inicialización del proveedor:

    Ejemplo 1.x:

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole();
}

    Ejemplo 2.2:

    
public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole();
        })
        // ...
}

  • Filtrado:

    Ejemplo 1.x:

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(LogLevel.Information);
    // or
    loggerFactory.AddConsole((category, level) => 
        category == "A" || level == LogLevel.Critical);
}

    Ejemplo 2.2:

    public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole()
                   .AddFilter<ConsoleLoggerProvider>
                       (category: null, level: LogLevel.Information)
                   // or
                   .AddFilter<ConsoleLoggerProvider>
                       ((category, level) => category == "A" ||
                           level == LogLevel.Critical)
            );
        })
        // ...
}

  • Carga de la configuración:

    Ejemplo 1.x:

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration);
}

    Ejemplo 2.2:

    public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
        })
        // ...
}

Para obtener más información, vea Registro en .NET Core y ASP.NET Core.

Módulo ASP.NET Core (ANCM)

Si el módulo de ASP.NET Core (ANCM) no era un componente seleccionado cuando Visual Studio se instaló o si se instaló una versión anterior de ANCM en el sistema, descargue el instalador de agrupación de hospedaje de .NET Core más reciente (descarga directa) y ejecute el instalador. Para saber más, consulte Conjunto de hospedaje.

Recursos adicionales