Migrar do ASP.NET Core 2.1 para 2.2

Por Scott Addie

Esse artigo explica como atualizar um projeto existente do ASP.NET Core 2.1 para o ASP.NET Core 2.2.

Pré-requisitos

Aviso

Se você usar o Visual Studio 2017, confira problema de dotnet/sdk nº 3124 para obter informações sobre as versões do SDK do .NET Core que não funcionam com o Visual Studio.

Atualizar TFM (Moniker da Estrutura de Destino)

Projetos direcionados ao .NET Core devem usar o TFM de uma versão maior ou igual ao .NET Core 2.2. No arquivo de projeto, atualize o texto interno do nó do <TargetFramework> com netcoreapp2.2:

<TargetFramework>netcoreapp2.2</TargetFramework>

Projetos direcionados ao .NET Framework devem usar o TFM de uma versão maior ou igual ao .NET Framework 4.6.1:

<TargetFramework>net461</TargetFramework>

Adotar o modelo de hospedagem em processo do IIS

Para adotar o modelo de hospedagem em processo para o IIS, adicione a propriedade <AspNetCoreHostingModel> com um valor de InProcess a <PropertyGroup> um no arquivo de projeto:

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

Não há suporte para o modelo de hospedagem em processo para aplicativos ASP.NET Core direcionados ao .NET Framework.

Para obter mais informações, confira Módulo do ASP.NET Core (ANCM) para o IIS.

Atualizar um arquivo de web.config personalizado

Para projetos que usam um arquivo deweb.config personalizado na raiz do projeto para gerar o arquivo deweb.config publicado:

  • Na entrada <handlers> que adiciona o módulo ASP.NET Core (name="aspNetCore"), altere o valor do atributo modules de AspNetCoreModule para AspNetCoreModuleV2.
  • No elemento <aspNetCore>, adicione o atributo de modelo de hospedagem (hostingModel="InProcess").

Para obter mais informações sobre o arquivo web.config, consulte Módulo do ASP.NET Core (ANCM) para o IIS.

Referências do pacote de atualização

Se for direcionado ao .NET Core, remova o atributo de referência do metapacote Version no arquivo de projeto. A inclusão de um atributo Version resulta no seguinte aviso:

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 mais, consulte Metapacote Microsoft.AspNetCore.App para ASP.NET Core.

A referência de metapacote deve ser semelhante ao seguinte nó do <PackageReference />:

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

Se for direcionado ao .NET Framework, atualize o atributo Version de cada referência de pacote para 2.2.0 ou posterior. Aqui estão as referências de pacote em um projeto típico ASP.NET Core 2.2 direcionado 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>

Se estiver fazendo referência ao pacote Microsoft.AspNetCore.Razor.Design, atualize seu atributo Version para 2.2.0 ou posterior. Não fazer isso resultará no erro:

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.

Atualizar a versão do SDK do .NET Core no global.json

Se a solução depender de um arquivo global.json para direcionar uma versão específica do SDK do .NET Core, atualize sua propriedade version para a versão 2.2 instalada no computador:

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

Atualizar configurações de inicialização

Se estiver usando o Visual Studio Code, atualize o arquivo de configurações de inicialização do projeto (.vscode/launch.json). O caminho program deve referenciar o novo 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}"
        }
    ]
}

Atualizar a configuração Kestrel

Se o aplicativo chamar UseKestrel chamando CreateDefaultBuilder no método CreateWebHostBuilder da classe Program, chame ConfigureKestrel para configurar o servidor Kestrel em vez de UseKestrel para evitar conflitos com o modelo de hospedagem em processo do IIS:

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

Se o aplicativo não chamar CreateDefaultBuilder e compilar o host manualmente na classe Program, chame UseKestrelantes de chamar 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 obter mais informações, consulte Kestrelservidor Web no ASP.NET Core.

Atualizar versão de compatibilidade

Atualize a versão de compatibilidade emStartup.ConfigureServices para Version_2_2:

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

Atualizar a política do CORS

No ASP.NET Core 2.2, o middleware CORS responderá com uma origem curinga (*) se uma política permitir qualquer origem e permitir credenciais. Não há suporte para credenciais quando uma origem curinga (*) é especificada e os navegadores não permitem a solicitação CORS. Para obter mais informações, incluindo opções para corrigir o problema no cliente, consulte os documentos da Web do MDN.

Para corrigir esse problema no servidor, execute uma das seguintes ações:

  • Modifique a política cors para não permitir mais credenciais. Ou seja, remova a chamada a AllowCredentials ao configurar a política.
  • Se as credenciais forem necessárias para que a solicitação CORS seja bem-sucedida, modifique a política para especificar hosts permitidos. Por exemplo, use builder.WithOrigins("https://api.example1.com", "https://example2.com") em vez de AllowAnyOrigin.

Atualizar imagens do Docker

A tabela a seguir mostra as alterações de marca de imagem do 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

Altere as linhas FROM no Dockerfile para usar as novas marcas de imagem na coluna 2.2 da tabela anterior.

Compile manualmente no Visual Studio ao usar a hospedagem em processo do IIS

A experiência de criação automática do Visual Studio na solicitação do navegador não funciona com o modelo de hospedagem em processo do IIS. Você deve recompilar manualmente o projeto ao usar a hospedagem em processo. Melhorias nessa experiência estão planejadas para uma versão futura do Visual Studio.

Atualizar código de log

O código de configuração de log recomendado não foi alterado de 2.1 para 2.2, mas alguns padrões de codificação 1.x que ainda funcionavam na versão 2.1 não funcionam mais na versão 2.2.

Se o aplicativo fizer o carregamento de inicialização, filtragem e configuração do provedor de log na classe Startup, mova esse código para Program.Main:

  • Inicialização do provedor:

    Exemplo 1.x:

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

    Exemplo 2.2:

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

    Exemplo 1.x:

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

    Exemplo 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)
                );
            })
            // ...
    }
    
  • Carregamento de configuração:

    Exemplo 1.x:

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

    Exemplo 2.2:

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

Para obter mais informações, consulte Fazendo login no .NET Core e no ASP.NET Core

Módulo do ASP.NET Core (ANCM)

Se o Módulo do ASP.NET Core (ANCM) não foi um componente selecionado quando o Visual Studio foi instalado ou se uma versão anterior do ANCM foi instalada no sistema, baixe o Instalador de Pacote de Hospedagem do .NET Core (download direto) mais recente e execute o instalador. Para obter mais informações, consulte Hospedagem.

Recursos adicionais