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

Artykuł
07/08/2022
Czas czytania: 7 min

W tym artykule przeprowadzimy Cię przez proces aktualizowania istniejącego projektu ASP.NET Core 1.x w celu ASP.NET Core 2.0. Migrowanie aplikacji do ASP.NET Core 2.0 umożliwia korzystanie z wielu nowych funkcji i ulepszeń wydajności.

Istniejące aplikacje ASP.NET Core 1.x są oparte na szablonach projektów specyficznych dla wersji. W miarę rozwoju platformy ASP.NET Core szablony projektów i kod początkowy zawarte w nich. Oprócz aktualizowania platformy ASP.NET Core należy zaktualizować kod aplikacji.

Wymagania wstępne

Zobacz Wprowadzenie do ASP.NET Core.

Aktualizacja programu Target Framework Moniker (TFM)

Projekty przeznaczone dla platformy .NET Core powinny używać programu TFM wersji nowszej lub równej .NET Core 2.0. <TargetFramework> Wyszukaj węzeł w .csproj pliku i zastąp jego tekst wewnętrzny ciągiem netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

Projekty przeznaczone dla .NET Framework powinny używać programu TFM wersji większej lub równej .NET Framework 4.6.1. <TargetFramework> Wyszukaj węzeł w .csproj pliku i zastąp jego tekst wewnętrzny ciągiem net461:

<TargetFramework>net461</TargetFramework>

Uwaga

Platforma .NET Core 2.0 oferuje znacznie większy obszar powierzchni niż .NET Core 1.x. Jeśli celujesz .NET Framework wyłącznie z powodu braku interfejsów API na platformie .NET Core 1.x, docelowa wersja platformy .NET Core 2.0 prawdopodobnie będzie działać.

Jeśli plik projektu zawiera <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>plik , zobacz ten problem z usługą GitHub.

Aktualizowanie wersji zestawu SDK platformy .NET Core w pliku global.json

Jeśli rozwiązanie opiera się na pliku global.json w celu kierowania określonej wersji zestawu SDK platformy .NET Core, zaktualizuj jej version właściwość do korzystania z wersji 2.0 zainstalowanej na maszynie:

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

Aktualizowanie odwołań do pakietu

Plik .csproj w projekcie 1.x zawiera listę każdego pakietu NuGet używanego przez projekt.

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

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

Wszystkie funkcje ASP.NET Core 2.0 i Entity Framework Core 2.0 są uwzględnione w metapakiecie.

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

Oto na przykład lista węzłów używanych <PackageReference /> w typowym projekcie ASP.NET Core 2.0 przeznaczonym .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 ona nadal dostępna, ale nieobsługiwana.

Aktualizowanie narzędzi interfejsu wiersza polecenia platformy .NET Core

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

Oto na przykład lista narzędzi interfejsu wiersza polecenia używanych w typowym projekcie 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 Rezerwowa elementu docelowego pakietu

Plik .csproj projektu 1.x używał węzła PackageTargetFallback i zmiennej:

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

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

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

Update Main, metoda w pliku Program.cs

W projektach Main 1.x metoda 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 Main 2.0 metoda 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();
    }
}

Wdrożenie tego nowego wzorca 2.0 jest zdecydowanie zalecane i jest wymagane, aby funkcje produktu, takie jak Migracje podstawowe platformy Entity Framework (EF) działały . Na przykład uruchomienie Update-Database z okna Konsoli Menedżera pakietów lub dotnet ef database update z wiersza polecenia (w projektach przekonwertowanych na 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 1.x dodanie dostawców konfiguracji do aplikacji zostało wykonane za pośrednictwem konstruktora Startup . Kroki związane z tworzeniem wystąpienia programu ConfigurationBuilder, ładowanie odpowiednich dostawców (zmiennych środowiskowych, ustawień aplikacji itp.) i inicjowanie elementu członkowskiego programu 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 Configuration element członkowski z ustawieniami konfiguracji, appsettings.json a także z dowolnego appsettings.{Environment}.json pliku pasującego do IHostingEnvironment.EnvironmentName właściwości. Lokalizacja tych plików znajduje się w tej samej ścieżce co Startup.cs.

W projektach w wersji 2.0 kod konfiguracji kotła związany z projektami 1.x jest uruchamiany w tle. Na przykład zmienne środowiskowe i ustawienia aplikacji są ładowane podczas uruchamiania. Równoważny Startup.cs kod jest zredukowany do IConfiguration inicjowania z wstrzykniętym wystąpieniem:

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

public IConfiguration Configuration { get; }

Aby usunąć domyślnych dostawców dodanych przez WebHostBuilder.CreateDefaultBuilderprogram , wywołaj metodę Clear we IConfigurationBuilder.Sources właściwości wewnątrz ConfigureAppConfigurationelementu . Aby dodać dostawców z powrotem, użyj ConfigureAppConfiguration metody 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 poprzednim fragmencie kodu można zobaczyć tutaj.

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

Przenoszenie kodu inicjowania bazy danych

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

Startup Tworzy wystąpienie
Wywołuje metodę rejestrowania ConfigureServices wszystkich usług za pomocą iniekcji zależności (w tym DbContext typów)
Wykonuje swoje wymagane zadania

W projektach 2.0 korzystających z programu EF Core 2.0 Program.BuildWebHost wywoływane jest uzyskiwanie usług aplikacji. W przeciwieństwie do 1.x, ma to dodatkowy efekt uboczny wywołania Startup.Configure. Jeśli aplikacja 1.x wywołała kod inicjowania bazy danych w swojej Configure metodzie, mogą wystąpić nieoczekiwane problemy. Jeśli na przykład baza danych jeszcze nie istnieje, kod rozmieszczania jest uruchamiany przed wykonaniem polecenia EF Core Migrations. Ten problem powoduje dotnet ef migrations list niepowodzenie polecenia, jeśli baza danych jeszcze nie istnieje.

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

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

SeedData.Initialize(app.ApplicationServices);

W projektach 2.0 przenieś wywołanie SeedData.Initialize do Main metody 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 źle jest wykonywać wszystkie czynności z BuildWebHost wyjątkiem kompilacji i konfigurowania hosta internetowego. Wszystko, co dotyczy uruchamiania aplikacji, powinno być obsługiwane poza BuildWebHost — zwykle w Main metodzie Program.cs.

Przeglądanie Razor ustawienia kompilacji widoku

Krótszy czas uruchamiania aplikacji i mniejsze opublikowane pakiety mają dla Ciebie największe znaczenie. Z tych powodów Razor kompilacja widoku jest domyślnie włączona w ASP.NET Core 2.0.

MvcRazorCompileOnPublish Ustawienie właściwości true nie jest już wymagane. Jeśli nie wyłączysz kompilacji widoku, właściwość może zostać usunięta .csproj z pliku.

Podczas określania wartości docelowej .NET Framework nadal musisz jawnie odwołać się do pliku Microsoft.AspNetCore.Mvc.Razor. Pakiet NuGet ViewCompilation w .csproj pliku:

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

Polegaj na funkcjach "light-up" usługi Application Insights

Ważna jest bezproblemowa konfiguracja instrumentacji wydajności aplikacji. Teraz możesz polegać na nowych funkcjach "light-up" usługi Application Insights dostępnych w narzędziu programu Visual Studio 2017.

ASP.NET Core 1.1 projektów utworzonych w programie Visual Studio 2017 domyślnie dodano usługę Application Insights. Jeśli nie korzystasz bezpośrednio z zestawu SDK usługi Application Insights, poza elementami Program.cs i Startup.cswykonaj następujące kroki:

W przypadku określania wartości docelowej dla platformy .csproj .NET Core usuń następujący <PackageReference /> węzeł z pliku:
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

W przypadku określania wartości docelowej dla platformy UseApplicationInsights .NET Core usuń wywołanie metody rozszerzenia z elementu 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 po stronie klienta usługi Application Insights z _Layout.cshtmlusługi . Składa się z następujących dwóch wierszy kodu:
```
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)
```

Jeśli używasz bezpośrednio zestawu SDK usługi Application Insights, przejdź do tego celu. Metapakiet w wersji 2.0 zawiera najnowszą wersję usługi Application Insights, więc błąd obniżenia poziomu pakietu pojawia się, jeśli odwołujesz się do starszej wersji.

Wdrażanie uwierzytelniania/Identity ulepszeń

ASP.NET Core 2.0 ma nowy model uwierzytelniania i wiele znaczących zmian w ASP.NET Core Identity. Jeśli projekt został utworzony z włączonymi indywidualnymi kontami użytkowników lub jeśli ręcznie dodano uwierzytelnianie lub Identity, zobacz Migrowanie uwierzytelniania i Identity do ASP.NET Core 2.0.

Dodatkowe zasoby

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