Migrowanie z platformy ASP.NET Core 1.x do wersji 2.0

Artykuł
11/30/2023

W tym artykule przeprowadzimy Cię przez aktualizację istniejącego projektu platformy ASP.NET Core 1.x do wersji ASP.NET Core 2.0. Migracja aplikacji do platformy ASP.NET Core 2.0 umożliwia skorzystanie z wielu nowych funkcji i ulepszeń wydajności.

Istniejące aplikacje platformy ASP.NET Core 1.x są oparte na szablonach projektów specyficznych dla wersji. W miarę rozwoju platformy ASP.NET Core rozwijane są również szablony projektów i zawarty w nich kod początkowy. Oprócz aktualizacji platformy ASP.NET Core musisz zaktualizować kod swojej aplikacji.

Wymagania wstępne

Zobacz Wprowadzenie do platformy ASP.NET Core.

Aktualizacja monikera platformy docelowej

Projekty przeznaczone dla platformy .NET Core powinny korzystać z monikera platformy docelowej w wersji zgodnej z platformą .NET Core 2.0 lub wyższej. Wyszukaj węzeł <TargetFramework> w pliku .csproj i zastąp jego tekst wewnętrzny tekstem netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

Projekty przeznaczone dla platformy .NET Framework powinny korzystać z monikera platformy docelowej w wersji zgodnej z platformą .NET Framework 4.6.1 lub wyższej. Wyszukaj węzeł <TargetFramework> w pliku .csproj i zastąp jego tekst wewnętrzny tekstem net461:

<TargetFramework>net461</TargetFramework>

Uwaga

Platforma .NET Core 2.0 udostępnia znacznie większy obszar funkcjonalności niż platforma .NET Core 1.x. Jeśli chcesz korzystać z platformy .NET Framework tylko z powodu brakujących interfejsów API na platformie .NET Core 1.x, korzystanie z platformy .NET Core 2.0 prawdopodobnie będzie dobrym rozwiązaniem.

Jeśli plik projektu zawiera element <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, zobacz ten problem w serwisie GitHub.

Aktualizowanie wersji zestawu .NET Core SDK w programie global.json

Jeśli rozwiązanie opiera się na global.json pliku przeznaczonym dla określonej wersji zestawu .NET Core SDK, zaktualizuj jej version właściwość, aby użyć wersji 2.0 zainstalowanej na komputerze:

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

Aktualizowanie odwołań do pakietów

Plik .csproj w projekcie w wersji 1.x zawiera listę wszystkich pakietów NuGet używanych przez projekt.

W projekcie platformy ASP.NET Core 2.0 przeznaczonym dla platformy .NET Core 2.0 jedno odwołanie do metapakietu w pliku .csproj zastępuje kolekcję pakietów:

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

Wszystkie funkcje platform ASP.NET Core 2.0 i Entity Framework Core 2.0 są zawarte w tym metapakiecie.

Projekty platformy ASP.NET Core 2.0 przeznaczone dla platformy .NET Framework powinny nadal odwoływać się do poszczególnych pakietów NuGet. Zaktualizuj atrybut Version każdego węzła <PackageReference /> do wersji 2.0.0.

Na przykład poniżej podano listę węzłów <PackageReference /> używanych w typowym projekcie platformy ASP.NET Core 2.0 przeznaczonym dla platformy .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>

Pakiet Microsoft.Extensions.CommandLineUtils został wycofany. Jest on nadal dostępny, ale nie jest obsługiwany.

Aktualizowanie narzędzi interfejsu wiersza polecenia platformy .NET Core

W pliku .csproj zaktualizuj atrybut Version każdego węzła <DotNetCliToolReference /> do wersji 2.0.0.

Na przykład poniżej podano listę narzędzi interfejsu wiersza polecenia używanych w typowym projekcie platformy ASP.NET Core 2.0 przeznaczonym dla platformy .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>

Zmienianie nazwy właściwości dotyczącej rezerwowych pakietów docelowych

W pliku .csproj projektu w wersji 1.x był używany węzeł i zmienna PackageTargetFallback:

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

Zmień nazwę tego węzła i zmiennej na AssetTargetFallback:

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

Aktualizowanie metody Main w pliku Program.cs

W projektach w wersji 1.x metoda Main w pliku Program.cs wyglądała następująco:

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

W projektach w wersji 2.0 metoda Main w pliku Program.cs została uproszczona:

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

Przyjęcie tego nowego wzorca w wersji 2.0 jest wysoce zalecane i jest wymagane do działania funkcji produktu takich jak migracje platformy Entity Framework (EF) Core. Na przykład uruchomienie polecenia Update-Database w oknie konsoli menedżera pakietów lub uruchomienie polecenia dotnet ef database update w wierszu polecenia (w projektach przekonwertowanych do wersji ASP.NET Core 2.0) generuje następujący błąd:

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.

Dodawanie dostawców konfiguracji

W projektach w wersji 1.x dodawanie dostawców konfiguracji do aplikacji odbywało się za pomocą konstruktora Startup. Ta procedura obejmowała utworzenie wystąpienia obiektu ConfigurationBuilder, załadowanie odpowiednich dostawców (zmienne środowiskowe, ustawienia aplikacji itp.) oraz zainicjowanie elementu członkowskiego 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; }

Powyższy przykład ładuje element członkowski Configuration z ustawieniami konfiguracji z pliku appsettings.json, a także dowolny plik appsettings.{Environment}.json zgodny z właściwością IHostingEnvironment.EnvironmentName. Te pliki znajdują się w tej samej ścieżce co plik Startup.cs.

W projektach w wersji 2.0 kod konfiguracyjny charakterystyczny dla projektów w wersji 1.x działa w tle. Na przykład zmienne środowiskowe i ustawienia aplikacji są ładowane podczas uruchamiania. Równoważny kod w pliku Startup.cs jest ograniczony do inicjowania obiektu IConfiguration za pomocą wstrzykniętego wystąpienia:

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

public IConfiguration Configuration { get; }

Aby usunąć domyślnych dostawców dodanych przez metodę WebHostBuilder.CreateDefaultBuilder, wywołaj metodę Clear na właściwości IConfigurationBuilder.Sources wewnątrz metody ConfigureAppConfiguration. Aby ponownie dodać dostawców, użyj metody ConfigureAppConfiguration w pliku 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();

Konfigurację używaną przez metodę CreateDefaultBuilder w powyższym fragmencie kodu można znaleźć tutaj.

Aby uzyskać więcej informacji, zobacz Konfiguracja na platformie ASP.NET Core.

Przenoszenie kodu inicjowania bazy danych

W projektach 1.x korzystających z wersji EF Core 1.x polecenie, takie jak dotnet ef migrations add :

Tworzy wystąpienie obiektu Startup
Wywołuje metodę ConfigureServices, aby zarejestrować wszystkie usługi za pomocą wstrzykiwania zależności (w tym typy DbContext)
Wykonuje wymagane zadania

W projektach w wersji 2.0 przy użyciu EF Core wersji 2.0 Program.BuildWebHost jest wywoływana w celu uzyskania usług aplikacji. W przeciwieństwie do wersji 1.x, powoduje to dodatkowy efekt uboczny w postaci wywołania metody Startup.Configure. Jeśli Twoja aplikacja w wersji 1.x wywoływała kod inicjowania bazy danych w swojej metodzie Configure, mogą wystąpić nieoczekiwane problemy. Jeśli na przykład baza danych jeszcze nie istnieje, kod inicjujący zostanie uruchomiony przed wykonaniem EF Core polecenia Migrations. Ten problem powoduje, że polecenie dotnet ef migrations list kończy się niepowodzeniem, jeśli baza danych jeszcze nie istnieje.

Rozważmy następujący kod inicjowania w wersji 1.x w metodzie Configure w pliku Startup.cs:

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

SeedData.Initialize(app.ApplicationServices);

W projektach w wersji 2.0 przenieś wywołanie metody SeedData.Initialize do metody Main w pliku 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 wersji 2.0 nie zaleca się wykonywania żadnych operacji w metodzie BuildWebHost, oprócz kompilowania i konfigurowania hosta internetowego. Wszystko, co dotyczy uruchamiania aplikacji, powinno być obsługiwane poza metodą BuildWebHost — zwykle w metodzie Main w pliku Program.cs.

Sprawdzanie ustawienia kompilacji widoków aparatu Razor

Krótszy czas uruchamiania aplikacji i mniejszy rozmiar publikowanych pakietów mają duże znaczenie. Z tych powodów kompilacja widoków aparatuRazor jest domyślnie włączona na platformie ASP.NET Core 2.0.

Ustawianie właściwości MvcRazorCompileOnPublish na wartość true nie jest już wymagane. O ile nie wyłączasz kompilacji widoków, możesz usunąć tę właściwość z pliku .csproj.

W przypadku korzystania z platformy .NET Framework nadal należy jawnie odwoływać się do pakietu NuGet Microsoft.AspNetCore.Mvc.Razor.ViewCompilation w pliku .csproj:

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

Korzystanie z funkcji rozruchu w usłudze Application Insights

Duże znaczenie ma łatwa konfiguracja instrumentacji wydajności aplikacji. Teraz możesz korzystać z nowych funkcji rozruchu w usłudze Application Insights dostępnych w narzędziach programu Visual Studio 2017.

Projekty platformy ASP.NET Core 1.1 tworzone w programie Visual Studio 2017 domyślnie dodawały usługę Application Insights. Jeśli nie korzystasz z zestawu Application Insights SDK bezpośrednio, poza plikami Program.cs i Startup.cs, wykonaj następujące kroki:

Jeśli korzystasz z platformy .NET Core, usuń następujący węzeł <PackageReference /> z pliku .csproj:
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

Jeśli korzystasz z platformy .NET Core, usuń wywołanie metody rozszerzenia UseApplicationInsights z pliku Program.cs:

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

    host.Run();
}

Usuń wywołanie interfejsu API usługi Application Insights po stronie klienta z pliku _Layout.cshtml. Składa się ono z dwóch następujących wierszy kodu:
```
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)
```

Jeśli bezpośrednio korzystasz z zestawu Application Insights SDK, rób to nadal. Metapakiet w wersji 2.0 zawiera najnowszą wersję usługi Application Insights, dlatego występuje błąd zmiany na starszą wersję pakietu, jeśli odwołujesz się do starszej wersji.

Wdrażanie ulepszeń funkcji uwierzytelniania/Identity

Na platformie ASP.NET Core 2.0 wprowadzono nowy model uwierzytelniania i wiele istotnych zmian w funkcji ASP.NET Core Identity. Jeśli Twój projekt został opracowany z włączonymi indywidualnymi kontami użytkowników albo jeśli zostało ręcznie dodane uwierzytelnianie lub funkcja Identity, zobacz Migrowanie uwierzytelniania i funkcji Identity do platformy ASP.NET Core 2.0.

Dodatkowe zasoby

Zmiany powodujące niezgodność na platformie ASP.NET Core 2.0

Migrowanie z platformy ASP.NET Core 1.x do wersji 2.0

Wymagania wstępne

Aktualizacja monikera platformy docelowej

Aktualizowanie wersji zestawu .NET Core SDK w programie global.json

Aktualizowanie odwołań do pakietów

Aktualizowanie narzędzi interfejsu wiersza polecenia platformy .NET Core

Zmienianie nazwy właściwości dotyczącej rezerwowych pakietów docelowych

Aktualizowanie metody Main w pliku Program.cs

Dodawanie dostawców konfiguracji

Przenoszenie kodu inicjowania bazy danych

Sprawdzanie ustawienia kompilacji widoków aparatu Razor

Korzystanie z funkcji rozruchu w usłudze Application Insights

Wdrażanie ulepszeń funkcji uwierzytelniania/Identity

Dodatkowe zasoby

Opinia

Dodatkowe zasoby