Migrate from ASP.NET Core 2.0 to 2.1 (Migrieren von ASP.NET Core 2.0 zu 2.1)

  • Artikel

Von Rick Anderson

Eine Übersicht über die neuen Features in .NET Core 2.1 finden Sie unter Neuerungen in ASP.NET Core 2.1.

Dieser Artikel:

  • Behandelt die Grundlagen der Migration einer ASP.NET Core 2.0-App zu 2.1.
  • Bietet eine Übersicht über die Änderungen an den ASP.NET Core-Webanwendungsvorlagen.

Sie können sich schnell einen Überblick über die Änderungen in Version 2.1 verschaffen, indem Sie die folgenden Schritte ausführen:

  • Erstellen Sie eine ASP.NET Core 2.0-Web-App namens WebApp1.
  • Committen Sie webApp1 in einem Quellcodeverwaltungssystem.
  • Löschen Sie WebApp1, und erstellen Sie am selben Ort eine ASP.NET Core 2.1-Web-App namens WebApp1.
  • Überprüfen Sie die Änderungen in der Version 2.1.

Dieser Artikel bietet eine Übersicht über die Migration zu ASP.NET Core 2.1. Er enthält keine vollständige Liste aller Änderungen, die für die Migration zu Version 2.1 erforderlich sind. Einige Projekte erfordern abhängig von den Optionen, die bei der Erstellung des Projekts ausgewählt wurden, möglicherweise weitere Schritte und Änderungen am Projekt.

Aktualisieren der Projektdatei, damit sie die 2.1-Versionen verwendet

Aktualisieren Sie die Projektdatei:

  • Ändern Sie das Zielframework in .NET Core 2.1, indem Sie die Projektdatei auf <TargetFramework>netcoreapp2.1</TargetFramework> aktualisieren.
  • Ersetzen Sie den Paketverweis für Microsoft.AspNetCore.All durch einen Paketverweis für Microsoft.AspNetCore.App. Möglicherweise müssen Sie Abhängigkeiten hinzufügen, die aus Microsoft.AspNetCore.All entfernt wurden. Weitere Informationen finden Sie unter Metapaket „Microsoft.AspNetCore.All“ für ASP.NET Core 2.0 und Metapaket „Microsoft.AspNetCore.App“ für ASP.NET Core.
  • Entfernen Sie das Attribut „Version“ im Paketverweis auf Microsoft.AspNetCore.App. Projekte, die <Project Sdk="Microsoft.NET.Sdk.Web"> verwenden, müssen die Version nicht festlegen. Das Zielframework impliziert und wählt die am besten passende Version entsprechend der Funktionsweise von ASP.NET Core 2.1. Weitere Informationen finden Sie im Abschnitt Regeln für Projekte, die auf das freigegebene Framework ausgerichtet sind.
  • Aktualisieren Sie für Apps, die auf .NET Framework ausgerichtet sind, jeden Paketverweis auf Version 2.1.
  • Entfernen Sie Verweise auf <DotNetCliToolReference>-Elemente für die folgenden Pakete. Diese Tools sind standardmäßig in der .NET Core-CLI gebündelt und müssen nicht separat installiert werden.
    • Microsoft.DotNet.Watcher.Tools (dotnet watch)
    • Microsoft.EntityFrameworkCore.Tools.DotNet (dotnet ef)
    • Microsoft.Extensions.Caching.SqlConfig.Tools (dotnet sql-cache)
    • Microsoft.Extensions.SecretManager.Tools (dotnet user-secrets)
  • Optional: Sie können das <DotNetCliToolReference>-Element für Microsoft.VisualStudio.Web.CodeGeneration.Tools entfernen. Sie können dieses Tool durch eine global installierte Version ersetzen, indem Sie dotnet tool install -g dotnet-aspnet-codegenerator ausführen.
  • Für 2.1 ist eine Razor-Klassenbibliothek (Razor Class Library, RCL) die empfohlene Lösung zum Verteilen von Razor-Dateien. Wenn Ihre App eingebettete Ansichten verwendet oder anderweitig auf der Laufzeitkompilierung von Razor-Dateien basiert, fügen Sie <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> zu einer <PropertyGroup> in Ihrer Projektdatei hinzu.

Das folgende Markup zeigt die von der Vorlage generierte 2.0-Projektdatei:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4" PrivateAssets="All" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.3" />
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.4" />
  </ItemGroup>
</Project>

Das folgende Markup zeigt die von der Vorlage generierte 2.1-Projektdatei:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.1" PrivateAssets="All" />
  </ItemGroup>

</Project>

Regeln für Projekte, die auf das freigegebene Framework ausgerichtet sind

Ein freigegebenes Framework besteht aus einer Reihe von Assemblys (DLL-Dateien), die sich nicht in den Ordnern der App befinden. Das freigegebene Framework muss zum Ausführen der App auf dem Computer installiert sein. Weitere Informationen finden Sie unter The shared framework (Das freigegebene Framework).

ASP.NET Core 2.1 enthält die folgenden freigegebenen Frameworks:

Die durch den Paketverweis angegebene Version ist die erforderliche Mindestversion. Beispielsweise kann ein Projekt, das auf die 2.1.1-Versionen dieser Pakete verweist, nicht auf einem Computer ausgeführt werden, auf dem nur die 2.1.0-Runtime installiert ist.

Bekannte Probleme bei Projekten, die auf ein freigegebenes Framework ausgerichtet sind:

  • Das .NET Core 2.1.300 SDK (erstmals in Visual Studio 15.6 enthalten) legte die implizite Version von Microsoft.AspNetCore.App auf 2.1.0 fest, wodurch Konflikte mit Entity Framework Core 2.1.1 verursacht wurden. Die empfohlene Lösung besteht darin, das .NET Core SDK auf 2.1.301 oder höher zu aktualisieren. Weitere Informationen finden Sie unter Packages that share dependencies with Microsoft.AspNetCore.App cannot reference patch versions (Pakete, die gemeinsame Abhängigkeiten mit Microsoft.AspNetCore.App aufweisen, können nicht auf Patchversionen verweisen).

  • Alle Projekte, die Microsoft.AspNetCore.All oder Microsoft.AspNetCore.App verwenden müssen, sollten einen Paketverweis für das Paket in der Projektdatei hinzufügen, auch wenn sie einen Projektverweis auf ein anderes Projekt mit Microsoft.AspNetCore.All oder Microsoft.AspNetCore.App enthalten.

    Beispiel:

    • MyApp verfügt über einen Paketverweis auf Microsoft.AspNetCore.App.
    • MyApp.Tests verfügt über einen Projektverweis auf MyApp.csproj.

    Fügen Sie MyApp.Tests einen Paketverweis für Microsoft.AspNetCore.App hinzu. Weitere Informationen finden Sie unter Integration testing is hard to set up and may break on shared framework servicing (Integrationstests sind schwer einzurichten und können bei der Wartung von freigegebenen Frameworks unterbrochen werden).

Update für die 2.1-Docker-Images

In ASP.NET Core 2.1 wurden die Docker-Images zum GitHub-Repository „dotnet/dotnet-docker“ migriert. In der folgenden Tabelle sind die Änderungen der Docker-Images und -Tags aufgeführt:

2.0 2.1
microsoft/aspnetcore:2.0 microsoft/dotnet:2.1-aspnetcore-runtime
microsoft/aspnetcore-build:2.0 microsoft/dotnet:2.1-sdk

Ändern Sie die FROM-Zeilen in Ihrer Dockerfile, um die neuen Imagenamen und -tags in der Spalte „2.1“ der obigen Tabelle zu verwenden. Weitere Informationen finden Sie unter Migrating from aspnetcore docker repos to dotnet (Migrieren von aspnetcore-Docker-Repositorys zu dotnet).

Änderungen an „Main“

Die folgenden Abbildungen zeigen die Änderungen, die an der mit Vorlagen generierten Datei Program.cs vorgenommen wurden.

old version differences

Die obige Abbildung zeigt die Version 2.0 mit den Löschungen in Rot.

Die folgende Abbildung zeigt den 2.1-Code. Der Code in Grün ersetzt den Code der Version 2.0:

new version differences

Der folgende Code zeigt die 2.1-Version von Program.cs:

namespace WebApp1
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>();
    }
}

Der neue Main-Code ersetzt den Aufruf von BuildWebHost durch CreateWebHostBuilder. IWebHostBuilder wurde hinzugefügt, um eine neue Integrationstestinfrastruktur zu unterstützen.

Änderungen an „Startup“

Der folgende Code zeigt die Änderungen am Code, der von der 2.1-Vorlage generiert wird. Alle Änderungen sind neu hinzugefügter Code, außer dass UseBrowserLink entfernt wurde:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace WebApp1
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });


            services.AddMvc()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();
            // If the app uses Session or TempData based on Session:
            // app.UseSession();

            app.UseMvc();
        }
    }
}

Die vorangehenden Codeänderungen werden in den folgenden Artikeln ausführlich beschrieben:

Änderungen am Authentifizierungscode

ASP.NET Core 2.1 stellt ASP.NET Core Identity als Razor-Klassenbibliothek bereit.

Die standardmäßige 2.1 Identity-Benutzeroberfläche bietet derzeit keine signifikanten neuen Features im Vergleich zu Version 2.0. Das Ersetzen von Identity durch das RCL-Paket ist optional. Das Ersetzen des vorlagengenerierten Identity-Codes durch die RCL-Version hat folgende Vorteile:

  • Viele Dateien werden aus der Quellstruktur verschoben.
  • Alle Fehlerkorrekturen oder neuen Features für Identity sind im Microsoft.AspNetCore.App-Metapaket enthalten. Sie erhalten automatisch die aktualisierte Identity-Version, wenn Microsoft.AspNetCore.App aktualisiert wird.

Wenn Sie nicht triviale Änderungen am vorlagengenerierten Identity-Code vorgenommen haben:

  • Die vorstehenden Vorteile rechtfertigen wahrscheinlich nicht die Konvertierung in die RCL-Version.
  • Sie können Ihren ASP.NET Core 2.0-Identity-Code beibehalten, er wird vollständig unterstützt.

Identity 2.1 macht Endpunkte mit dem Bereich Identity verfügbar. Die folgende Tabelle enthält Beispiele für Identity-Endpunkte, die von 2.0 in 2.1 geändert werden:

2.0-URL 2.1-URL
/Account/Login /Identity/Account/Login
/Account/Logout /Identity/Account/Logout
/Account/Manage /Identity/Account/Manage

Bei Anwendungen, die Code mit Identity enthalten und die 2.0-Identity-Benutzeroberfläche durch die 2.1-Identity-Bibliothek ersetzen, muss berücksichtigt werden, dass den URIs bei Identity-URLs das /Identity-Segment vorangestellt ist. Eine Möglichkeit, die neuen Identity-Endpunkte zu behandeln, besteht darin, Umleitungen einzurichten, z. B. von /Account/Login zu /Identity/Account/Login.

Update von Identity auf Version 2.1

Die folgenden Optionen sind verfügbar, um Identity auf 2.1 zu aktualisieren.

  • Verwenden Sie den Identity-UI-2.0-Code ohne Änderungen. Die Verwendung von Identity-UI 2.0-Code wird vollständig unterstützt. Dies ist ein guter Ansatz, wenn erhebliche Änderungen am generierten Identity-Code vorgenommen wurden.
  • Löschen Sie den vorhandenen Identity 2.0-Code und das Gerüst Identity für Ihr Projekt. Ihr Projekt verwendet die ASP.NET CoreIdentityRazor-Klassenbibliothek. Sie können den Code und die Benutzeroberfläche für jeden mit Identity generierten Benutzeroberflächencode, den Sie geändert haben, generieren. Wenden Sie Ihre Codeänderungen auf den neu gestalteten Benutzeroberflächencode an.
  • Löschen Sie den vorhandenen Identity-2.0-Code und Scaffold Identity in Ihrem Projekt mit der Option Alle Dateien überschreiben.

Ersetzen der Identity-2.0-Benutzeroberfläche durch die Identity 2.1-Razor-Klassenbibliothek

In diesem Abschnitt werden die Schritte zum Ersetzen des von ASP.NET Core 2.0-Vorlagen generierten Identity-Codes durch die ASP.NET Core-IdentityRazor-Klassenbibliothek beschrieben. Die folgenden Schritte gelten für ein Razor Pages-Projekt, aber der Ansatz für ein MVC-Projekt ist ähnlich.

  • Überprüfen, ob die Projektdatei für die Verwendung der Version 2.1 aktualisiert wurde
  • Löschen Sie die folgenden Ordner und alle darin enthaltenen Dateien:
    • Controller
    • Pages/Account/
    • Erweiterungen
  • Erstellen Sie das Projekt.
  • Gerüst für Identity in Ihrem Projekt:
    • Wählen Sie die Projekte mit einer vorhandenen Datei _Layout.cshtml aus.
    • Wählen Sie das Symbol + rechts neben Datenkontextklasse: aus. Übernehmen Sie den Standardnamen.
    • Wählen Sie Hinzufügen aus, um eine neue Datenkontextklasse zu erstellen. Das Erstellen eines neuen Datenkontexts ist für den Gerüstbau erforderlich. Im nächsten Abschnitt entfernen Sie den neuen Datenkontext.

Aktualisieren nach dem Gerüstbau für Identity

  • Löschen Sie die von der Identity-Gerüsterstellung generierte abgeleitete IdentityDbContext-Klasse im Ordner Areas/Identity/Data/.

  • Löschen Sie Areas/Identity/IdentityHostingStartup.cs.

  • Aktualisieren Sie die Datei _LoginPartial.cshtml:

    • Verschieben Sie Pages/_LoginPartial.cshtml nach Pages/Shared/_LoginPartial.cshtml.
    • Fügen Sie asp-area="Identity" dem Formular und Ankerlinks hinzu.
    • Aktualisieren Sie das <form />-Element auf <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">.

    Der folgende Code zeigt die aktualisierte Datei _LoginPartial.cshtml:

    @using Microsoft.AspNetCore.Identity

@inject SignInManager<ApplicationUser> SignInManager
@inject UserManager<ApplicationUser> UserManager

@if (SignInManager.IsSignedIn(User))
{
    <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">
        <ul class="nav navbar-nav navbar-right">
            <li>
                <a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">Hello @UserManager.GetUserName(User)!</a>
            </li>
            <li>
                <button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
            </li>
        </ul>
    </form>
}
else
{
    <ul class="nav navbar-nav navbar-right">
        <li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
        <li><a asp-area="Identity" asp-page="/Account/Login">Log in</a></li>
    </ul>
}

Aktualisieren Sie ConfigureServices mit folgendem Code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    services.AddDefaultIdentity<ApplicationUser>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();

    services.AddMvc();

    // Register no-op EmailSender used by account confirmation and password reset 
    // during development
    services.AddSingleton<IEmailSender, EmailSender>();
}

Änderungen an Razor-Dateien von Razor Pages-Projekten

Layoutdatei

  • Verschiebung von Pages/_Layout.cshtml in Pages/Shared/_Layout.cshtml

  • Änderung von Layout = "/Pages/_Layout.cshtml" in Areas/Identity/Pages/_ViewStart.cshtml in Layout = "/Pages/Shared/_Layout.cshtml".

  • Die Datei _Layout.cshtml weist die folgenden Änderungen auf:

_ValidationScriptsPartial.cshtml

  • Pages/_ValidationScriptsPartial.cshtml wechselt zu Pages/Shared/_ValidationScriptsPartial.cshtml.
  • jquery.validate/1.14.0 wechselt zu jquery.validate/1.17.0.

Neue Dateien

Die folgenden Dateien wurden hinzugefügt:

  • Privacy.cshtml
  • Privacy.cshtml.cs

Informationen zu den vorherigen Dateien finden Sie unter DSGVO-Unterstützung in ASP.NET Core.

Änderungen an Razor-Dateien in MVC-Projekten

Layoutdatei

Für die Datei Layout.cshtml wurden folgende Änderungen vorgenommen:

  • <partial name="_CookieConsentPartial" /> wird hinzugefügt.
  • jQuery wechselt von 2.2.0 zu 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 wechselt zu jquery.validate/1.17.0

Neue Dateien und Aktionsmethoden

Folgendes wurde hinzugefügt:

  • Views/Home/Privacy.cshtml
  • Die Privacy-Aktionsmethode wurde dem Home-Controller hinzugefügt.

Informationen zu den vorherigen Dateien finden Sie unter DSGVO-Unterstützung in ASP.NET Core.

Änderungen an der Datei „!aunchSettings.json“

Da ASP.NET Core-Apps jetzt standardmäßig HTTPS verwenden, wurde die Datei Properties/launchSettings.json geändert.

Die folgende JSON-Datei zeigt die von der früheren 2.0-Vorlage generierte Datei launchSettings.json:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:1799/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:1798/"
    }
  }
}

Die folgende JSON-Datei zeigt die von der neuen 2.1-Vorlage generierte Datei launchSettings.json:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:39191",
      "sslPort": 44390
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Weitere Informationen finden Sie unter Erzwingen von HTTPS in ASP.NET Core.

Aktuelle Änderungen

FileResult-Bereichsheader

FileResult verarbeitet den Accept-Ranges-Header nicht mehr standardmäßig. Legen Sie zum Aktivieren des Accept-Ranges-Headers EnableRangeProcessing auf true fest.

ControllerBase.File- und PhysicalFile-Bereichsheader

Die folgenden ControllerBase-Methoden verarbeiten den Accept-Ranges-Header standardmäßig nicht mehr:

Um den Accept-Ranges-Header zu aktivieren, legen Sie den Parameter EnableRangeProcessing auf fest true.

ASP.NET Core-Modul (ANCM)

Wenn das ASP.NET Core-Modul (ANCM) bei der Installation von Visual Studio keine ausgewählte Komponente war oder wenn eine frühere Version des ANCM auf dem System installiert wurde, laden Sie den neuesten Installer für das .NET Core Hosting-Paket (direkter Download) herunter, und führen Sie das Installationsprogramm aus. Weitere Informationen finden Sie unter Das .NET Core-Hostingbundle.

Weitere Änderungen