Compartilhar via

Migrar do ASP.NET Core 1.x para 2.0

Por Scott Addie

Neste artigo, explicamos como atualizar um projeto do ASP.NET Core 1.x existente para ASP.NET Core 2.0. Migrar seu aplicativo para o ASP.NET Core 2.0 permite que você aproveite muitos novos recursos e melhorias de desempenho.

Os aplicativos ASP.NET Core 1.x existentes são baseados em modelos de projeto específicos de versão. À medida que a estrutura do ASP.NET Core evolui, os modelos de projeto e o código inicial contidos neles também evoluem. Além de atualizar a estrutura do ASP.NET Core, você precisa atualizar o código do aplicativo.

Pré-requisitos

Consulte Introdução ao ASP.NET Core.

Atualizar o Identificador da Plataforma de Destino (TFM)

Os projetos direcionados ao .NET Core devem usar o TFM de uma versão maior ou igual ao .NET Core 2.0. Procure o nó <TargetFramework> no arquivo .csproj e substitua seu conteúdo por netcoreapp2.0.

<TargetFramework>netcoreapp2.0</TargetFramework>

Os projetos direcionados ao .NET Framework devem usar o TFM de uma versão maior ou igual ao .NET Framework 4.6.1. Procure o nó <TargetFramework> no arquivo .csproj e substitua seu conteúdo por net461.

<TargetFramework>net461</TargetFramework>

Observação

O .NET Core 2.0 oferece uma área de superfície muito maior do que o .NET Core 1.x. Se você está direcionando especificamente o .NET Framework por causa de APIs ausentes no .NET Core 1.x, direcionar para o .NET Core 2.0 é uma solução provável.

Se o arquivo de projeto contiver <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, consulte este problema do GitHub.

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

Se sua solução depender de um arquivo global.json para apontar para uma versão específica do SDK do .NET Core, atualize a sua propriedade version para usar a versão 2.0 instalada em seu computador.

{
  "sdk": {
    "version": "2.0.0"
  }
}

Referências do pacote de atualização

O .csproj arquivo em um projeto 1.x lista cada pacote NuGet usado pelo projeto.

Em um projeto do ASP.NET Core 2.0 direcionado ao .NET Core 2.0, uma única referência de metapacote no .csproj arquivo substitui a coleção de pacotes:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>

Todos os recursos do ASP.NET Core 2.0 e Entity Framework Core 2.0 estão incluídos no metapacote.

Projetos ASP.NET Core 2.0 direcionados ao .NET Framework devem continuar a referenciar pacotes individuais do NuGet. Atualize o atributo Version de cada nó <PackageReference /> para 2.0.0.

Por exemplo, aqui está a lista de <PackageReference /> nós usados em um projeto típico do ASP.NET Core 2.0 voltado para o .NET Framework:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

O pacote Microsoft.Extensions.CommandLineUtils foi desativado. Ele ainda está disponível, mas sem suporte.

Atualizar as ferramentas da CLI do .NET

No arquivo .csproj, atualize o atributo Version de cada nó <DotNetCliToolReference /> para 2.0.0.

Por exemplo, aqui está a lista de ferramentas da CLI usadas em um projeto típico do ASP.NET Core 2.0 direcionado ao .NET Core 2.0:

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

Renomear a propriedade Fallback de Destino do Pacote

O arquivo de um projeto 1.x .csproj usava um nó e uma variável PackageTargetFallback:

<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>

Renomeie o nó e a variável para AssetTargetFallback:

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>

Atualizar método Principal no Program.cs

Em projetos 1.x, o método de Main se parecia com este: Program.cs

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore1App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .UseApplicationInsights()
                .Build();

            host.Run();
        }
    }
}

Em projetos 2.0, o método de Main foi simplificado: Program.cs

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

A adoção desse novo padrão 2.0 é altamente recomendada e é necessária para que os recursos do produto , como as Migrações Principais do EF (Entity Framework) funcionem. Por exemplo, a execução Update-Database na janela console do Gerenciador de Pacotes ou dotnet ef database update na linha de comando (em projetos convertidos em ASP.NET Core 2.0) gera o seguinte erro:

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

Adicionar provedores de configuração

Em projetos 1.x, a adição de provedores de configuração a um aplicativo foi realizada por meio do Startup construtor. As etapas envolviam a criação de uma instância de ConfigurationBuilder, carregando provedores aplicáveis (variáveis de ambiente, configurações de aplicativo etc.) e inicializando um membro de IConfigurationRoot.

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

public IConfigurationRoot Configuration { get; }

O exemplo anterior carrega o membro Configuration com configurações de appsettings.json bem como qualquer arquivo appsettings.{Environment}.json que corresponda à propriedade IHostingEnvironment.EnvironmentName. O local desses arquivos está no mesmo caminho que Startup.cs.

Em projetos 2.0, o código de configuração padrão inerente aos projetos 1.x é executado nos bastidores. Por exemplo, variáveis de ambiente e configurações de aplicativo são carregadas na inicialização. O código equivalente Startup.cs é reduzido à IConfiguration inicialização com a instância injetada:

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

Para remover os provedores padrão adicionados por WebHostBuilder.CreateDefaultBuilder, invoque o método Clear na propriedade IConfigurationBuilder.Sources dentro de ConfigureAppConfiguration. Para adicionar provedores de volta, utilize o ConfigureAppConfiguration método em Program.cs:

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureAppConfiguration((hostContext, config) =>
        {
            // delete all default configuration providers
            config.Sources.Clear();
            config.AddJsonFile("myconfig.json", optional: true);
        })
        .Build();

A configuração usada pelo CreateDefaultBuilder método no snippet de código anterior pode ser vista aqui.

Para obter mais informações, consulte Configuração no ASP.NET Core.

Mover o código de inicialização do banco de dados

Em projetos 1.x usando EF Core 1.x, um comando como dotnet ef migrations add realiza o seguinte:

  1. Instancia uma Startup instância
  2. Invoca o método ConfigureServices para registrar todos os serviços com injeção de dependências (tipos DbContext incluídos)
  3. Executa suas tarefas requisitas

Em projetos 2.0 usando EF Core 2.0, Program.BuildWebHost é invocado para obter os serviços de aplicativo. Ao contrário de 1.x, isso tem o efeito colateral adicional da invocação Startup.Configure. Se o aplicativo 1.x invocou o código de inicialização do banco de dados em seu Configure método, podem ocorrer problemas inesperados. Por exemplo, se o banco de dados ainda não existir, o código de propagação será executado antes da execução do EF Core comando Migrações. Esse problema fará com que um dotnet ef migrations list comando falhe se o banco de dados ainda não existir.

Considere o seguinte código de inicialização de semente 1.x no método Configure de Startup.cs:

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

SeedData.Initialize(app.ApplicationServices);

Em projetos 2.0, mova a chamada SeedData.Initialize para o método Main de Program.cs:

var host = BuildWebHost(args);

using (var scope = host.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    try
    {
        // Requires using RazorPagesMovie.Models;
        SeedData.Initialize(services);
    }
    catch (Exception ex)
    {
        var logger = services.GetRequiredService<ILogger<Program>>();
        logger.LogError(ex, "An error occurred seeding the DB.");
    }
}

host.Run();

A partir da versão 2.0, é uma má prática fazer qualquer coisa em BuildWebHost, exceto construir e configurar o host da Web. Qualquer coisa relacionada à execução do aplicativo deve ser tratada fora de BuildWebHost — normalmente no método Main de Program.cs.

Examinar Razor a configuração de compilação do modo de exibição

O tempo de inicialização do aplicativo mais rápido e os pacotes publicados menores são de extrema importância para você. Por esses motivos, Razor a compilação de exibição é habilitada por padrão no ASP.NET Core 2.0.

A definição da MvcRazorCompileOnPublish propriedade como true não é mais necessária. A menos que você esteja desabilitando a compilação de exibição, a propriedade poderá ser removida do .csproj arquivo.

Ao direcionar o .NET Framework, você ainda precisa referenciar explicitamente o pacote NuGet Microsoft.AspNetCore.Mvc.Razor.ViewCompilation em seu arquivo .csproj.

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />

Contar com recursos de "light-up" do Application Insights

A configuração fácil da instrumentação de desempenho de aplicativos é importante. Agora você pode contar com os novos recursos "light-up" do Application Insights disponíveis nas ferramentas do Visual Studio 2017.

ASP.NET projetos do Core 1.1 criados no Visual Studio 2017 adicionaram o Application Insights por padrão. Se você não estiver usando o SDK do Application Insights diretamente, fora de Program.cs e Startup.cs, siga estas etapas:

  1. Se estiver direcionando o .NET Core, remova o seguinte <PackageReference /> nó do .csproj arquivo:

    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />

  2. Se estiver direcionando para o .NET Core, remova a invocação do método de extensão de UseApplicationInsights em Program.cs.

    public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

  3. Remova a chamada da API cliente do Application Insights de _Layout.cshtml. Ele compreende as duas seguintes linhas de código:

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)

Se você estiver usando o SDK do Application Insights diretamente, continue a fazê-lo. O metapacote 2.0 inclui a versão mais recente do Application Insights, portanto, um erro de downgrade de pacote será exibido se você estiver fazendo referência a uma versão mais antiga.

Adotar melhorias na autenticação/Identity

ASP.NET Core 2.0 tem um novo modelo de autenticação e várias alterações significativas no ASP.NET Core Identity. Se você criou seu projeto com contas de usuário individuais habilitadas, ou se adicionou manualmente autenticação ou Identity, veja Migração da Autenticação e Identity para o ASP.NET Core 2.0.

Recursos adicionais