Migrieren von ASP.NET Core 1.x zu 2.0Migrate from ASP.NET Core 1.x to 2.0

Von Scott AddieBy Scott Addie

In diesem Artikel aktualisieren wir exemplarisch ein vorhandenes ASP.NET Core 1.x-Projekt auf ASP.NET Core 2.0.In this article, we walk you through updating an existing ASP.NET Core 1.x project to ASP.NET Core 2.0. Durch Migrieren der Anwendung zu ASP.NET Core 2.0 kommen Sie in den Genuss vieler neuer Funktionen und Leistungsverbesserungen.Migrating your application to ASP.NET Core 2.0 enables you to take advantage of many new features and performance improvements.

Vorhandene ASP.NET Core 1.x-Anwendungen basieren auf versionsspezifischen Projektvorlagen.Existing ASP.NET Core 1.x applications are based off of version-specific project templates. Doch das ASP.NET Core-Framework entwickelt sich weiter. Gleiches gilt für die darin enthaltenen Projektvorlagen und den Startercode.As the ASP.NET Core framework evolves, so do the project templates and the starter code contained within them. Zusätzlich zum Aktualisieren des ASP.NET Core-Frameworks müssen Sie den Code für Ihre Anwendung aktualisieren.In addition to updating the ASP.NET Core framework, you need to update the code for your application.

VoraussetzungenPrerequisites

Weitere Informationen finden Sie unter Erste Schritte mit ASP.NET Core.See Get Started with ASP.NET Core.

Aktualisieren des Zielframeworkmonikers (Target Framework Moniker, TFM)Update Target Framework Moniker (TFM)

Auf .NET Core ausgelegte Projekte müssen den TFM einer Version größer gleich .NET Core 2.0 verwenden.Projects targeting .NET Core should use the TFM of a version greater than or equal to .NET Core 2.0. Suchen Sie den Knoten <TargetFramework> in der CSPROJ-Datei, und ersetzen Sie dessen inneren Text durch netcoreapp2.0:Search for the <TargetFramework> node in the .csproj file, and replace its inner text with netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

Auf .NET Framework ausgelegte Projekte müssen den TFM einer Version größer gleich .NET Framework 4.6.1 verwenden.Projects targeting .NET Framework should use the TFM of a version greater than or equal to .NET Framework 4.6.1. Suchen Sie den Knoten <TargetFramework> in der CSPROJ-Datei, und ersetzen Sie dessen inneren Text durch net461:Search for the <TargetFramework> node in the .csproj file, and replace its inner text with net461:

<TargetFramework>net461</TargetFramework>

Hinweis

.NET Core 2.0 bietet eine viel größere Oberfläche als .NET Core 1.x..NET Core 2.0 offers a much larger surface area than .NET Core 1.x. Wenn Sie mit .NET Framework entwickeln, nur weil APIs in .NET Core 1.x fehlen, wird das Entwickeln mit .NET Core 2.0 wahrscheinlich funktionieren.If you're targeting .NET Framework solely because of missing APIs in .NET Core 1.x, targeting .NET Core 2.0 is likely to work.

Wenn die Projektdatei <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion> enthält, lesen Sie die Informationen zu diesem GitHub-Problem.If the project file contains <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, see this GitHub issue.

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

Wenn Ihre Projektmappe von einer Datei global.json abhängig ist, um eine bestimmte .NET Core SDK-Version als Ziel anzugeben, aktualisieren Sie deren version-Eigenschaft so, dass die auf Ihrem Computer installierte Version 2.0 verwendet wird:If your solution relies upon a global.json file to target a specific .NET Core SDK version, update its version property to use the 2.0 version installed on your machine:

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

Aktualisieren von PaketverweisenUpdate package references

In der CSPROJ-Datei in einem Projekt der Version 1.x sind alle NuGet-Pakete aufgeführt, die vom Projekt verwendet werden.The .csproj file in a 1.x project lists each NuGet package used by the project.

In einem ASP.NET Core 2.0-Projekt für .NET Core 2.0 ersetzt ein einzelner Verweis des Typs metapackage in der CSPROJ-Datei die Paketsammlung:In an ASP.NET Core 2.0 project targeting .NET Core 2.0, a single metapackage reference in the .csproj file replaces the collection of packages:

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

Alle Funktionen von ASP.NET Core 2.0 und Entity Framework Core 2.0 sind in „metapackage“ enthalten.All the features of ASP.NET Core 2.0 and Entity Framework Core 2.0 are included in the metapackage.

ASP.NET Core 2.0-Projekte für .NET Framework müssen weiterhin auf einzelne NuGet-Pakete verweisen.ASP.NET Core 2.0 projects targeting .NET Framework should continue to reference individual NuGet packages. Aktualisieren Sie das Version-Attribut aller Knoten des Typs <PackageReference /> auf 2.0.0.Update the Version attribute of each <PackageReference /> node to 2.0.0.

Hier ist z.B. die Liste der <PackageReference />-Knoten in einem typischen ASP.NET Core 2.0-Projekt für .NET Framework:For example, here's the list of <PackageReference /> nodes used in a typical ASP.NET Core 2.0 project targeting .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>

Aktualisieren von .NET Core CLI-ToolsUpdate .NET Core CLI tools

Aktualisieren Sie in der CSPROJ-Datei das Version-Attribut jedes <DotNetCliToolReference />-Knotens auf 2.0.0.In the .csproj file, update the Version attribute of each <DotNetCliToolReference /> node to 2.0.0.

Hier ist z.B. die Liste der CLI-Tools in einem typischen ASP.NET Core 2.0-Projekt für .NET Core 2.0:For example, here's the list of CLI tools used in a typical ASP.NET Core 2.0 project targeting .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>

Umbenennen der „TargetFallback“-Eigenschaft des PaketsRename Package Target Fallback property

Die CSPROJ-Datei eines 1.x-Projekts hat einen Knoten des Typs PackageTargetFallback und eine Variable verwendet:The .csproj file of a 1.x project used a PackageTargetFallback node and variable:

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

Benennen Sie den Knoten und die Variable in AssetTargetFallback um:Rename both the node and variable to AssetTargetFallback:

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

Aktualisieren der „Main“-Methode in „Program.cs“Update Main method in Program.cs

In 1.x-Projekten sah die Main-Methode von Program.cs wie folgt aus:In 1.x projects, the Main method of Program.cs looked like this:

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 von Program.cs vereinfacht:In 2.0 projects, the Main method of Program.cs has been simplified:

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

Das Übernehmen dieses neuen 2.0-Musters wird dringend empfohlen und ist für Produktfunktionen wie Entity Framework Core-Migrationen (EF) erforderlich.The adoption of this new 2.0 pattern is highly recommended and is required for product features like Entity Framework (EF) Core Migrations to work. Bei Ausführung von Update-Database im Paket-Manager-Konsolenfenster oder von dotnet ef database update an der Befehlszeile (für in ASP.NET Core 2.0 konvertierte Projekte) wird der folgende Fehler generiert:For example, running Update-Database from the Package Manager Console window or dotnet ef database update from the command line (on projects converted to ASP.NET Core 2.0) generates the following error:

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 KonfigurationsanbieternAdd configuration providers

In 1.x-Projekten konnten Sie Konfigurationsanbieter einer App mit dem Startup-Konstruktor hinzufügen.In 1.x projects, adding configuration providers to an app was accomplished via the Startup constructor. Dazu mussten Sie eine Instanz von ConfigurationBuilder erstellen, die betreffenden Anbieter laden (Umgebungsvariablen, App-Einstellungen usw.) und einen Member von IConfigurationRoot initialisieren.The steps involved creating an instance of ConfigurationBuilder, loading applicable providers (environment variables, app settings, etc.), and initializing a member of 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 wurde der Configuration-Member mit Konfigurationseinstellen aus appsettings.json geladen sowie aus jeder anderen appsettings.<EnvironmentName>.json-Datei, die mit der Eigenschaft IHostingEnvironment.EnvironmentName übereinstimmt.The preceding example loads the Configuration member with configuration settings from appsettings.json as well as any appsettings.<EnvironmentName>.json file matching the IHostingEnvironment.EnvironmentName property. Diese Dateien befinden sich am gleichen Speicherort wie startup.cs.The location of these files is at the same path as Startup.cs.

In 2.0-Projekten wird der Bausteinkonfigurationsknoten, der 1.x-Projekten eigen ist, im Hintergrund ausgeführt.In 2.0 projects, the boilerplate configuration code inherent to 1.x projects runs behind-the-scenes. Umgebungsvariablen und App-Einstellungen werden beispielsweise beim Start geladen.For example, environment variables and app settings are loaded at startup. Der entsprechende Code startup.cs wird zur IConfiguration-Initialisierung mit der eingefügten Instanz reduziert:The equivalent Startup.cs code is reduced to IConfiguration initialization with the injected instance:

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

public IConfiguration Configuration { get; }

Um die von WebHostBuilder.CreateDefaultBuilder hinzugefügten Standardanbieter zu entfernen, rufen Sie die Clear-Methode in der IConfigurationBuilder.Sources-Eigenschaft in ConfigureAppConfiguration auf.To remove the default providers added by WebHostBuilder.CreateDefaultBuilder, invoke the Clear method on the IConfigurationBuilder.Sources property inside of ConfigureAppConfiguration. Um Anbieter wieder hinzuzufügen, verwenden Sie die ConfigureAppConfiguration-Methode in program.cs:To add providers back, utilize the ConfigureAppConfiguration method 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 von der CreateDefaultBuilder-Methode verwendete Konfiguration im vorherigen Codeausschnitt können Sie sich hier ansehen.The configuration used by the CreateDefaultBuilder method in the preceding code snippet can be seen here.

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.For more information, see Configuration in ASP.NET Core.

Verschieben des Initialisierungscodes der DatenbankMove database initialization code

In 1.x-Projekten, die EF Core 1.x verwenden, bewirkt ein Befehl wie dotnet ef migrations add Folgendes:In 1.x projects using EF Core 1.x, a command such as dotnet ef migrations add does the following:

  1. Instanziiert eine Startup-InstanzInstantiates a Startup instance
  2. Ruft die ConfigureServices-Methode auf, um alle Dienste mit Abhängigkeitsinjektion (einschließlich DbContext-Typen zu registrierenInvokes the ConfigureServices method to register all services with dependency injection (including DbContext types)
  3. Führt die erforderlichen Aufgaben ausPerforms its requisite tasks

In 2.0-Projekten, die EF Core 2.0 verwenden, wird Program.BuildWebHost aufgerufen, um die Anwendungsdienste abzurufen.In 2.0 projects using EF Core 2.0, Program.BuildWebHost is invoked to obtain the application services. Im Gegensatz zu 1.x hat dies den zusätzlichen Nebeneffekt, dass Startup.Configure aufgerufen wird.Unlike 1.x, this has the additional side effect of invoking Startup.Configure. Wenn Ihre 1.x-App den Datenbankinitialisierungscode in der Configure-Methode aufgerufen hat, können unerwartete Probleme auftreten.If your 1.x app invoked database initialization code in its Configure method, unexpected problems can occur. Wenn die Datenbank beispielsweise noch nicht existiert, wird der Seedingcode vor der Befehlsausführung der EF Core-Migration ausgeführt.For example, if the database doesn't yet exist, the seeding code runs before the EF Core Migrations command execution. Dieses Problem führt dazu, dass ein dotnet ef migrations list-Befehl fehlschlägt, da die Datenbank noch nicht vorhanden ist.This problem causes a dotnet ef migrations list command to fail if the database doesn't yet exist.

Erwägen Sie den folgenden 1.x-Startcode der Initialisierung in der Configure-Methode von Startup.cs:Consider the following 1.x seed initialization code in the Configure method of 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 Aufruf SeedData.Initialize zur Main-Methode von Program.cs:In 2.0 projects, move the SeedData.Initialize call to the Main method of 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 keine gute Idee, etwas in BuildWebHost zu tun, außer den Webhost zu erstellen und zu konfigurieren.As of 2.0, it's bad practice to do anything in BuildWebHost except build and configure the web host. Alles, was in der Anwendung ausgeführt werden soll, sollte außerhalb von BuildWebHost — behandelt werden, in der Regel in der Main-Methode von Program.cs.Anything that's about running the application should be handled outside of BuildWebHost — typically in the Main method of Program.cs.

Überprüfen der Einstellungen für die Kompilierung der Razor-AnsichtReview Razor view compilation setting

Eine schnellere Anwendungsstartzeit und kleinere veröffentlichte Pakete sind für Sie von höchster Wichtigkeit.Faster application startup time and smaller published bundles are of utmost importance to you. Aus diesen Gründen ist Razor-Ansichtskompilierung in ASP.NET Core 2.0 standardmäßig aktiviert.For these reasons, Razor view compilation is enabled by default in ASP.NET Core 2.0.

Das Festlegen der MvcRazorCompileOnPublish-Eigenschaft auf „true“ ist nicht mehr erforderlich.Setting the MvcRazorCompileOnPublish property to true is no longer required. Außer wenn Sie die Ansichtskompilierung deaktivieren, kann die Eigenschaft aus der CSPROJ-Datei entfernt werden.Unless you're disabling view compilation, the property may be removed from the .csproj file.

Bei Entwicklung für .NET Framework müssen Sie weiter explizit auf das NuGet-Paket Microsoft.AspNetCore.Mvc.Razor.ViewCompilation in Ihrer .csproj-Datei verweisen:When targeting .NET Framework, you still need to explicitly reference the Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet package in your .csproj file:

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

Arbeiten mit den Startfeatures von Application InsightsRely on Application Insights "light-up" features

Die mühelose Einrichtung der Instrumentierung der Anwendungsleistung ist wichtig.Effortless setup of application performance instrumentation is important. Hierfür können Sie nun mit den neuen Startfeatures von Application Insights in den Visual Studio 2017-Tools arbeiten.You can now rely on the new Application Insights "light-up" features available in the Visual Studio 2017 tooling.

Bei in Visual Studio 2017 erstellten ASP.NET Core 1.1-Projekten wurde Application Insights standardmäßig hinzugefügt.ASP.NET Core 1.1 projects created in Visual Studio 2017 added Application Insights by default. Wenn Sie das Application Insights SDK nicht direkt verwenden, gehen Sie außerhalb von Program.cs und Startup.cs folgendermaßen vor:If you're not using the Application Insights SDK directly, outside of Program.cs and Startup.cs, follow these steps:

  1. Wenn .NET Core Ihr Ziel ist, entfernen Sie den folgenden <PackageReference />-Knoten aus der CSPROJ-Datei:If targeting .NET Core, remove the following <PackageReference /> node from the .csproj file:

    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
    
  2. Wenn .NET Core Ihr Ziel ist, entfernen Sie den Aufruf der Erweiterungsmethode UseApplicationInsights aus Program.cs:If targeting .NET Core, remove the UseApplicationInsights extension method invocation from 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 aus _Layout.cshtml den clientseitigen API-Aufruf von Application Insights.Remove the Application Insights client-side API call from _Layout.cshtml. Dieser umfasst die beiden folgenden Codezeilen:It comprises the following two lines of code:

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

Sie können das Application Insights SDK weiterhin direkt verwenden.If you are using the Application Insights SDK directly, continue to do so. metapackage der Version 2.0 enthält die neueste Version von Application Insights, weshalb ein Fehler zum Downgrade eines Pakets angezeigt wird, wenn Sie auf eine ältere Version verweisen.The 2.0 metapackage includes the latest version of Application Insights, so a package downgrade error appears if you're referencing an older version.

Übernehmen der Authentifizierung bzw. Verbesserungen an IdentityAdopt authentication/Identity improvements

ASP.NET Core 2.0 verfügt über ein neues Authentifizierungsmodell und bietet verschiedene Änderungen an ASP.NET Core Identity.ASP.NET Core 2.0 has a new authentication model and a number of significant changes to ASP.NET Core Identity. Wenn Sie Ihr Projekt mit aktivierter Option „Einzelne Benutzerkonten“ erstellt oder Authentifizierungs- oder Identitätsfunktionen manuell hinzugefügt haben, finden Sie unter Migrieren von Authentifizierungs- und Identitätseinstellungen nach ASP.NET Core 2.0 weitere Informationen.If you created your project with Individual User Accounts enabled, or if you have manually added authentication or Identity, see Migrate Authentication and Identity to ASP.NET Core 2.0.

Zusätzliche RessourcenAdditional resources