Migrace z ASP.NET Core 1.x na 2.0

Článek
11/06/2024

V tomto článku vás provedeme aktualizací existujícího projektu ASP.NET Core 1.x na ASP.NET Core 2.0. Migrace aplikace na ASP.NET Core 2.0 umožňuje využívat mnoho nových funkcí a vylepšení výkonu.

Existující aplikace ASP.NET Core 1.x jsou založené na šablonách projektů specifických pro konkrétní verzi. Společně s vývojem architektury ASP.NET Core se vyvíjejí i šablony projektů a počáteční kód v nich obsažený. Kromě aktualizace architektury ASP.NET Core musíte také aktualizovat kód pro vaši aplikaci.

Požadavky

Informace najdete v tématu Začínáme s ASP.NET Core.

Aktualizace monikeru cílové architektury (TFM)

Projekty, které cílí na .NET Core, by měly používat TFM ve verzi verze vyšší nebo rovné .NET Core 2.0. V souboru .csproj vyhledejte uzel <TargetFramework> a jeho vnitřní text nahraďte netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

Projekty, které cílí na .NET Framework, by měly používat TFM ve verzi verze vyšší nebo rovné .NET Framework 4.6.1. V souboru .csproj vyhledejte uzel <TargetFramework> a jeho vnitřní text nahraďte net461:

<TargetFramework>net461</TargetFramework>

Poznámka:

.NET Core 2.0 má mnohem větší záběr než .NET Core 1.x. Pokud na .NET Framework cílíte výhradně kvůli chybějícím rozhraním API v .NET Core 1.x, je pravděpodobné, že cílení na .NET Core 2.0 bude fungovat.

Pokud soubor projektu obsahuje <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, projděte si tento problém na GitHubu.

Aktualizace verze sady .NET Core SDK v global.json

Pokud vaše řešení spoléhá na global.json soubor, který cílí na konkrétní verzi sady .NET Core SDK, aktualizujte jeho version vlastnost tak, aby používala verzi 2.0 nainstalovanou na vašem počítači:

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

Aktualizace odkazů na balíčky

Soubor .csproj v projektu 1.x uvádí všechny balíčky NuGet používané tímto projektem.

V projektu ASP.NET Core 2.0, který cílí na .NET Core 2.0, je kolekce balíčků nahrazena jedním odkazem na metabalíček v souboru .csproj:

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

Součástí tohoto metabalíčku jsou všechny funkce technologií ASP.NET Core 2.0 a Entity Framework Core 2.0.

Projekty ASP.NET Core 2.0, které cílí na rozhraní .NET Framework, by měly nadále odkazovat na jednotlivé balíčky NuGet. Aktualizujte atribut Version všech uzlů <PackageReference /> na 2.0.0.

Tady je například seznam uzlů <PackageReference /> používaných v typickém projektu ASP.NET Core 2.0, který cílí na .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>

Balíček Microsoft.Extensions.CommandLineUtils byl vyřazený z provozu. Je stále dostupný, ale nepodporuje se.

Aktualizace nástrojů .NET CLI

V souboru .csproj aktualizujte atribut Version všech uzlů <DotNetCliToolReference /> na 2.0.0.

Tady je například seznam nástrojů CLI používaných v typickém projektu ASP.NET Core 2.0, který cílí na .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>

Přejmenování vlastnosti Package Target Fallback

Soubor .csproj projektu 1.x použil proměnnou a uzel PackageTargetFallback:

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

Přejmenujte uzel i proměnnou na AssetTargetFallback:

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

Aktualizace metody Main v souboru Program.cs

V projektech 1.x vypadala metoda Main v souboru Program.cs takto:

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();
        }
    }
}

V projektech 2.0 byla metoda Main v souboru Program.cs zjednodušena:

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();
    }
}

Přijetí tohoto nového vzoru 2.0 se důrazně doporučuje a je nutné pro fungování funkcí produktu, jako jsou příkazy Migrations na platformě Entity Framework (EF). Například spuštění příkazu Update-Database z okna konzoly Správce balíčků nebo dotnet ef database update z příkazového řádku (u projektů převedených na ASP.NET Core 2.0) vygeneruje následující chybu:

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.

Přidání zprostředkovatelů konfigurace

V projektech 1.x bylo přidání zprostředkovatelů konfigurace do aplikace provedeno prostřednictvím konstruktoru Startup. Jednotlivé kroky zahrnovaly vytvoření instance ConfigurationBuilder, načtení příslušných zprostředkovatelů (proměnné prostředí, nastavení aplikace atd.) a inicializaci člena 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; }

Předchozí příklad načte člena Configuration s nastavením konfigurace ze souboru appsettings.json a také z libovolného souboru appsettings.{Environment}.json odpovídajícího vlastnosti IHostingEnvironment.EnvironmentName. Umístění těchto souborů je ve stejné cestě jako Startup.cs.

V projektech verze 2.0 běží na pozadí často používaný konfigurační kód, který je vlastní projektům verze 1.x. Například proměnné prostředí a nastavení aplikace se načtou při spuštění. Ekvivalentní kód Startup.cs se sníží omezí na inicializaci IConfiguration s vloženou instancí:

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

public IConfiguration Configuration { get; }

Pokud chcete odebrat výchozí zprostředkovatele přidané WebHostBuilder.CreateDefaultBuilder, vyvolejte metodu Clear pro vlastnost IConfigurationBuilder.Sources uvnitř ConfigureAppConfiguration. Pokud chcete přidat zprostředkovatele zpět, využijte metodu ConfigureAppConfiguration v 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();

Konfiguraci použitou metodou CreateDefaultBuilder v předchozím fragmentu kódu najdete tady.

Další informace najdete v tématu Konfigurace v ASP.NET Core.

Přesun inicializačního kódu databáze

V projektech 1.x používajících EF Core 1.x je například následující příkaz dotnet ef migrations add :

Vytvoří instanci Startup.
Vyvolá metodu ConfigureServices pro registraci všech služeb s injektáží závislostí (včetně typů DbContext).
Plní požadované úkoly.

Ve 2.0 projektech používajících EF Core verzi 2.0 Program.BuildWebHost je vyvolána k získání aplikačních služeb. Na rozdíl od verze 1.x má jako vedlejší účinek vyvolání Startup.Configure. Pokud aplikace 1.x vyvolala inicializační kód databáze v metodě Configure, může dojít k neočekávaným problémům. Pokud například databáze ještě neexistuje, počáteční kód se spustí před spuštěním EF Core příkazu Migrations. Tento problém způsobí selhání příkazu dotnet ef migrations list, pokud databáze ještě neexistuje.

Zvažte následující inicializační kód 1.x v metodě Configure v Startup.cs:

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

SeedData.Initialize(app.ApplicationServices);

V projektech 2.0 přesuňte volání SeedData.Initialize do metody Mainv 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();

Od verze 2.0 není vhodné dělat v BuildWebHost cokoli kromě sestavení a konfigurace webového hostitele. Cokoli, co se týká spuštění aplikace, by se mělo zpracovat mimo BuildWebHost, zpravidla v metodě Main v Program.cs.

Kontrola nastavení kompilace zobrazení pro Razor

Rychlejší spouštění aplikací a menší publikované balíčky jsou pro vás nesmírně důležité. Z těchto důvodů je ve výchozím nastavení v ASP.NET Core 2.0 povolená Razorkompilace zobrazení.

Nastavení vlastnosti MvcRazorCompileOnPublishna true už se nevyžaduje. Pokud nezakážete kompilaci zobrazení, může být tato vlastnost ze souboru .csproj odebrána.

Při cílení na rozhraní .NET Framework je stále potřeba v souboru .csproj explicitně odkazovat na balíček NuGet Microsoft.AspNetCore.Mvc.Razor.ViewCompilation:

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

Možnost spolehnout se na funkce pro usnadnění v Application Insights

Snadné nastavení instrumentace výkonu aplikace je velmi důležité. Teď se můžete spolehnout na nové funkce pro usnadnění v Application Insights, které jsou dostupné v nástrojích sady Visual Studio 2017.

Do projektů ASP.NET Core 1.1 vytvořených v sadě Visual Studio 2017 byla ve výchozím nastavení přidána funkce Application Insights. Pokud sadu Application Insights SDK nepoužíváte přímo, mimo Program.cs a Startup.cs, postupujte takto:

Pokud cílíte na .NET Core, odeberte ze souboru .csproj následující uzel <PackageReference />:
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

Pokud cílíte na .NET Core, odeberte z Program.cs vyvolání metody rozšíření UseApplicationInsights:

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

    host.Run();
}

Odeberte volání rozhraní API Application Insights na straně klienta z _Layout.cshtml. Skládá se ze dvou řádků kódu:

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

Pokud sadu Application Insights SDK používáte přímo, pokračujte v tom. Metabalíček 2.0 obsahuje nejnovější verzi Application Insights, takže pokud odkazujete na starší verzi, zobrazí se chyba downgradu balíčku.

Vylepšení pro ověřování a Identity

ASP.NET Core 2.0 má nový model ověřování a řadu významných změn v ASP.NET Core Identity. Pokud jste projekt vytvořili s povolenými individuálními uživatelskými účty nebo pokud jste ručně přidali ověřování nebo Identity, přečtěte si téma Migrace ověřování a Identity do ASP.NET Core 2.0.

Další materiály

Změny způsobující chybu v ASP.NET Core 2.0

Sdílet prostřednictvím

Migrace z ASP.NET Core 1.x na 2.0

Požadavky

Aktualizace monikeru cílové architektury (TFM)

Aktualizace verze sady .NET Core SDK v global.json

Aktualizace odkazů na balíčky

Aktualizace nástrojů .NET CLI

Přejmenování vlastnosti Package Target Fallback

Aktualizace metody Main v souboru Program.cs

Přidání zprostředkovatelů konfigurace

Přesun inicializačního kódu databáze

Kontrola nastavení kompilace zobrazení pro Razor

Možnost spolehnout se na funkce pro usnadnění v Application Insights

Vylepšení pro ověřování a Identity

Další materiály

Další materiály