Teilen über

Migrieren von ASP.NET Core 1.x zu 2.0

Von Scott Addie

In diesem Artikel führen wir Sie durch die Aktualisierung eines vorhandenen ASP.NET Core 1.x-Projekts auf ASP.NET Core 2.0. Durch die Migration Ihrer Anwendung zu ASP.NET Core 2.0 können Sie viele neue Features und Leistungsverbesserungen nutzen.

Vorhandene ASP.NET Core 1.x-Anwendungen basieren auf versionsspezifischen Projektvorlagen. Da sich das ASP.NET Core-Framework weiterentwickelt, entwickeln sich auch die Projektvorlagen und der darin enthaltene Startcode weiter. Zusätzlich zum Aktualisieren des ASP.NET Core-Frameworks müssen Sie den Code für Ihre Anwendung aktualisieren.

Voraussetzungen

Weitere Informationen finden Sie unter "Erste Schritte mit ASP.NET Core".

Aktualisieren des Zielframeworkmonikers (Target Framework Moniker, TFM)

Projekte für .NET Core sollten die TFM einer Version verwenden, die größer oder gleich .NET Core 2.0 ist. Suchen Sie nach dem <TargetFramework> Knoten in der .csproj Datei, und ersetzen Sie den inneren Text durch netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

Projekte für .NET Framework sollten die TFM einer Version verwenden, die größer oder gleich .NET Framework 4.6.1 ist. Suchen Sie nach dem <TargetFramework> Knoten in der .csproj Datei, und ersetzen Sie den inneren Text durch net461:

<TargetFramework>net461</TargetFramework>

Hinweis

.NET Core 2.0 bietet eine wesentlich größere Fläche als .NET Core 1.x. Wenn Sie .NET Framework ausschließlich deshalb verwenden, weil APIs in .NET Core 1.x fehlen, könnte die Ausrichtung auf .NET Core 2.0 funktionieren.

Wenn die Projektdatei enthält <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, lesen Sie dieses GitHub-Problem.

Aktualisieren der .NET Core SDK-Version in „global.json“

Wenn Ihre Lösung von einer global.json Datei abhängt, die auf eine bestimmte .NET Core SDK-Version abzielt, aktualisieren Sie deren version Eigenschaft zum Verwenden der auf Ihrem Computer installierten Version 2.0:

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

Aktualisieren von Paketverweisen

Die .csproj Datei in einem 1.x-Projekt listet jedes NuGet-Paket auf, das vom Projekt verwendet wird.

In einem ASP.NET Core 2.0-Projekt für .NET Core 2.0 ersetzt ein einzelner Metapackageverweis in der .csproj Datei die Sammlung von Paketen:

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

Alle Features von ASP.NET Core 2.0 und Entity Framework Core 2.0 sind im Metapaket enthalten.

ASP.NET Core 2.0-Projekte für .NET Framework sollten weiterhin auf einzelne NuGet-Pakete verweisen. Aktualisieren Sie das Version Attribut jedes <PackageReference /> Knotens auf 2.0.0.

Hier ist beispielsweise die Liste der <PackageReference /> Knoten, die in einem typischen ASP.NET Core 2.0-Projekt für .NET Framework verwendet werden:

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

Das Paket Microsoft.Extensions.CommandLineUtils wurde zurückgezogen. Es ist weiterhin verfügbar, aber nicht unterstützt.

Aktualisieren von .NET CLI-Tools

Aktualisieren Sie in der .csproj Datei das Version Attribut jedes <DotNetCliToolReference /> Knotens auf 2.0.0.

Hier ist beispielsweise die Liste der CLI-Tools, die in einem typischen ASP.NET Core 2.0-Projekt für .NET Core 2.0 verwendet werden:

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

Package Target Fallback-Eigenschaft umbenennen

Die .csproj Datei eines 1.x-Projekts hat einen Knoten und eine PackageTargetFallback Variable verwendet:

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

Benennen Sie sowohl den Knoten als auch die Variable in AssetTargetFallback um.

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

Update Main-Methode in Program.cs

In 1.x-Projekten sah die Main Methode von Program.cs so aus:

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

In 2.0 Projekten wurde die Main Methode Program.cs vereinfacht:

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

Die Einführung dieses neuen 2.0-Musters wird dringend empfohlen und ist erforderlich, damit Produktfeatures wie Entity Framework (EF) Core Migrationen funktionieren. Beispielsweise führt das Ausführen von Update-Database über das Paket-Manager-Konsolenfenster oder von dotnet ef database update über die Befehlszeile (bei Projekten, die in ASP.NET Core 2.0 konvertiert wurden) zu folgendem Fehler:

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.

Hinzufügen von Konfigurationsanbietern

In 1.x-Projekten wurde das Hinzufügen von Konfigurationsanbietern zu einer App über den Startup Konstruktor durchgeführt. Die Schritte umfassen das Erstellen einer Instanz von ConfigurationBuilder, das Laden anwendbarer Anbieter (Umgebungsvariablen, App-Einstellungen usw.) und das Initialisieren eines Mitglieds von 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; }

Im vorherigen Beispiel wird das Configuration-Element sowohl mit Konfigurationseinstellungen von appsettings.json als auch mit jeder appsettings.{Environment}.json-Datei geladen, die der IHostingEnvironment.EnvironmentName-Eigenschaft entspricht. Der Speicherort dieser Dateien befindet sich im selben Pfad wie Startup.cs.

In 2.0-Projekten wird der 1.x-Projektbausteinkonfigurationscode hinter den Kulissen ausgeführt. Umgebungsvariablen und App-Einstellungen werden beispielsweise beim Start geladen. Der entsprechende Startup.cs Code wird durch die Initialisierung mit der eingefügten Instanz auf IConfiguration reduziert.

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

public IConfiguration Configuration { get; }

Rufen Sie zum Entfernen der Standardanbieter, die von WebHostBuilder.CreateDefaultBuilder hinzugefügt wurden, die Clear-Methode auf der IConfigurationBuilder.Sources-Eigenschaft innerhalb von ConfigureAppConfiguration auf. Um Anbieter wieder hinzuzufügen, verwenden Sie die ConfigureAppConfiguration Methode in 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();

Die konfiguration, die von der CreateDefaultBuilder Methode im vorherigen Codeausschnitt verwendet wird, ist hier zu sehen.

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

Verschieben des Datenbankinitialisierungscodes

In 1.x-Projekten mit EF Core 1.x wird ein Befehl wie dotnet ef migrations add folgt ausgeführt:

  1. Instanziiert eine Startup Instanz
  2. Ruft die ConfigureServices Methode auf, um alle Dienste mit Abhängigkeitseinfügung (einschließlich DbContext Typen) zu registrieren.
  3. Führt die erforderlichen Aufgaben aus

In 2.0-Projekten, die EF Core 2.0 verwenden, wird Program.BuildWebHost aufgerufen, um die Anwendungsdienste zu erhalten. Im Gegensatz zu 1.x hat dies die zusätzliche Nebenwirkung des Aufrufens Startup.Configure. Wenn Ihre 1.x-App den Datenbankinitialisierungscode in der Configure Methode aufgerufen hat, können unerwartete Probleme auftreten. Wenn die Datenbank beispielsweise noch nicht vorhanden ist, wird der Seedingcode vor der Ausführung des EF Core Migrationsbefehls ausgeführt. Dieses Problem führt dazu, dass ein dotnet ef migrations list Befehl fehlschlägt, wenn die Datenbank noch nicht vorhanden ist.

Berücksichtigen Sie den folgenden Initialisierungs-Code für Seed 1.x in der Methode Configure von Startup.cs:

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

SeedData.Initialize(app.ApplicationServices);

Verschieben Sie in 2.0 Projekten den SeedData.Initialize Aufruf an die Main Methode von 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();

Ab 2.0 ist es schlechte Praxis, in BuildWebHost etwas anderes zu tun, außer den Webhost zu erstellen und zu konfigurieren. Alles, was die Ausführung der Anwendung betrifft, sollte außerhalb von BuildWebHost behandelt werden – in der Regel in der Main-Methode von Program.cs.

Überprüfen Sie die Razor Ansichtskompilierungseinstellung

Schnellere Anwendungsstartzeit und kleinere veröffentlichte Bundles sind für Sie von größter Bedeutung. Aus diesen Gründen Razor ist die Ansichtskompilierung in ASP.NET Core 2.0 standardmäßig aktiviert.

Das Festlegen der MvcRazorCompileOnPublish Eigenschaft auf "true" ist nicht mehr erforderlich. Sofern Sie die Ansichtskompilierung nicht deaktivieren, wird die Eigenschaft möglicherweise aus der .csproj Datei entfernt.

Bei der Verwendung des .NET Framework als Zielplattform müssen Sie weiterhin explizit das NuGet-Paket Razor in Ihrer Datei referenzieren.

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

Verlassen Sie sich auf Die "Light-up"-Features von Application Insights

Die mühelose Einrichtung der Anwendungsleistungsinstrumentation ist wichtig. Sie können sich jetzt auf die neuen "Light-up"-Features von Application Insights verlassen, die im Visual Studio 2017-Tool verfügbar sind.

ASP.NET Core 1.1-Projekte, die in Visual Studio 2017 erstellt wurden, enthalten standardmäßig Application Insights. Wenn Sie das Application Insights SDK nicht direkt verwenden, außerhalb von Program.cs und Startup.cs, führen Sie die folgenden Schritte aus:

  1. Wenn Sie .NET Core verwenden, entfernen Sie den folgenden <PackageReference /> Knoten aus der .csproj Datei:

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

  2. Wenn sie auf .NET Core ausgerichtet sind, entfernen Sie den Aufruf der UseApplicationInsights Erweiterungsmethode von Program.cs:

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

    host.Run();
}

  3. Entfernen Sie den clientseitigen Application Insights-API-Aufruf von _Layout.cshtml. Sie umfasst die folgenden beiden Codezeilen:

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

Wenn Sie das Application Insights SDK direkt verwenden, fahren Sie damit fort. Das Metapaket 2.0 enthält die neueste Version von Application Insights, sodass ein Paketdowngradefehler angezeigt wird, wenn Sie auf eine ältere Version verweisen.

Authentifizierungs/Identity Verbesserungen übernehmen

ASP.NET Core 2.0 verfügt über ein neues Authentifizierungsmodell und eine Reihe erheblicher Änderungen an ASP.NET Core Identity. Wenn Sie Ihr Projekt mit aktivierten einzelnen Benutzerkonten erstellt haben oder die Authentifizierung manuell hinzugefügt haben, siehe Identity.

Weitere Ressourcen