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

2025-05-05

W tym artykule przeprowadzimy Cię przez proces aktualizowania istniejącego projektu ASP.NET Core 1.x do ASP.NET Core 2.0. Migrowanie aplikacji do platformy 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, rozwijają się również szablony projektów i zawarty w nich kod początkowy. Oprócz zaktualizowania platformy ASP.NET Core należy zaktualizować kod aplikacji.

Wymagania wstępne

Zobacz Wprowadzenie do ASP.NET Core.

Aktualizacja monikera platformy docelowej

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

<TargetFramework>netcoreapp2.0</TargetFramework>

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

<TargetFramework>net461</TargetFramework>

Uwaga / Notatka

Platforma .NET Core 2.0 oferuje znacznie większy obszar powierzchni niż .NET Core 1.x. Jeśli wybierasz platformę .NET Framework z powodu brakujących interfejsów API na platformie .NET Core 1.x, wybranie platformy .NET Core 2.0 najprawdopodobniej się sprawdzi.

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

Zaktualizuj wersję .NET Core SDK w 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 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 pojedyncze 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ą zawarte w metapakiecie.

projekty ASP.NET Core 2.0 przeznaczone dla platformy .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.

Na przykład poniżej przedstawiono listę węzłów używanych <PackageReference /> 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 ona nadal dostępna, ale nieobsługiwana.

Aktualizacja narzędzi CLI platformy .NET

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

Na przykład poniżej przedstawiono 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 Fallback 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>

Aktualizacja metody Main w Program.cs

W projektach 1.x metoda MainProgram.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 metody 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 w wersji 2.0 jest zdecydowanie zalecane i jest wymagane, aby funkcje produktu, takie jak Migracje podstawowe programu Entity Framework (EF) działały . Na przykład uruchomienie Update-Database z poziomu okna konsoli menedżera pakietów lub dotnet ef database update wiersza polecenia (w projektach przekonwertowanych na ASP.NET Core 2.0) powoduje wygenerowanie następującego błędu:

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 instancji ConfigurationBuilder, ładowaniem odpowiednich dostawców (zmiennych środowiskowych, ustawień aplikacji itp.) i inicjowaniem członka 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; }

W poprzednim przykładzie element członkowski Configuration jest ładowany z ustawieniami konfiguracji, appsettings.json a także z dowolnego appsettings.{Environment}.json pliku zgodnego z właściwością IHostingEnvironment.EnvironmentName . Lokalizacja tych plików znajduje się w tej samej ścieżce co Startup.cs.

W projektach 2.0, szablonowy kod konfiguracji, związany z projektami 1.x, działa w tle. Na przykład zmienne środowiskowe i ustawienia aplikacji są ładowane podczas uruchamiania. Równoważny Startup.cs kod jest zmniejszany do IConfiguration inicjowania przy użyciu wprowadzonego wystąpienia:

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

public IConfiguration Configuration { get; }

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

Konfiguracja używana przez metodę CreateDefaultBuilder w poprzednim fragmencie kodu jest widoczna 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 EF Core 1.x polecenie takie jak dotnet ef migrations add wykonuje następujące czynności:

Tworzy wystąpienie Startup
Wywołuje metodę ConfigureServices w celu zarejestrowania wszystkich usług przez iniekcję zależności (w tym typów DbContext)
Wykonuje swoje wymagane zadania

W projektach 2.0 z użyciem EF Core w wersji 2.0, wywoływana jest Program.BuildWebHost, aby uzyskać usługi aplikacji. W przeciwieństwie do wersji 1.x, daje 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 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 inicjalizacji seeda 1.x w metodzie ConfigureStartup.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 metody MainProgram.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 jest zalecane wykonywanie żadnych czynności w BuildWebHost, poza kompilowaniem i konfigurowaniem hosta internetowego. Wszystko, co dotyczy uruchamiania aplikacji, powinno być obsługiwane poza BuildWebHost — zazwyczaj w metodzie MainProgram.cs.

Sprawdź ustawienie kompilacji widoku Razor

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 programie ASP.NET Core 2.0.

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

W przypadku targetowania platformy .NET Framework, nadal należy jawnie odwołać się do pakietu NuGetu Microsoft.AspNetCore.Mvc.Razor.ViewCompilation w swoim pliku .csproj.

<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.

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

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

W przypadku celowania w platformę .NET Core, usuń wywołanie metody rozszerzenia z UseApplicationInsights:

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 usługi _Layout.cshtml. 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, kontynuuj to. Metapakiet w wersji 2.0 zawiera najnowszą wersję usługi Application Insights, więc błąd obniżania poziomu pakietu pojawia się, jeśli odwołujesz się do starszej wersji.

Adoptowanie ulepszeń uwierzytelniania/Identity

ASP.NET Core 2.0 ma nowy model uwierzytelniania i szereg znaczących zmian w ASP.NET Core Identity. Jeśli utworzyłeś projekt z włączonymi indywidualnymi kontami użytkowników, lub jeśli ręcznie dodałeś uwierzytelnianie lub Identity, zobacz Migracja uwierzytelniania i Identity do ASP.NET Core 2.0.

Dodatkowe zasoby

Istotne zmiany w systemie ASP.NET Core 2.0

Udostępnij za pośrednictwem

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

Wymagania wstępne

Aktualizacja monikera platformy docelowej

Zaktualizuj wersję .NET Core SDK w global.json.

Aktualizowanie odwołań do pakietów

Aktualizacja narzędzi CLI platformy .NET

Zmienianie nazwy właściwości Fallback elementu docelowego pakietu

Aktualizacja metody Main w Program.cs

Dodawanie dostawców konfiguracji

Przenoszenie kodu inicjowania bazy danych

Sprawdź ustawienie kompilacji widoku Razor

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

Adoptowanie ulepszeń uwierzytelniania/Identity

Dodatkowe zasoby

Opinia

Dodatkowe zasoby