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

Von Rick Anderson

Unter What es new in ASP.NET Core 2.1 (Neues in ASP.NET Core 2.1) finden Sie eine Übersicht über die neuen Features in ASP.NET Core 2.1.

Inhalt dieses Artikels

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

Eine schnelle Möglichkeit, einen Überblick über die Änderungen in 2.1 zu erhalten, ist:

  • Erstellen Sie ASP.NET Core 2.0-Web-App mit dem Namen WebApp1.
  • Commit für WebApp1 in einem Quellcodeverwaltungssystem.
  • Löschen Sie WebApp1, und erstellen ASP.NET Core 2.1-Web-App mit dem Namen WebApp1 an derselben Stelle.
  • Überprüfen Sie die Änderungen in Version 2.1.

Dieser Artikel bietet eine Übersicht über die Migration zu ASP.NET Core 2.1. Es enthält keine vollständige Liste aller Änderungen, die für die Migration zu Version 2.1 erforderlich sind. Einige Projekte erfordern möglicherweise weitere Schritte, je nachdem, welche Optionen beim Erstellen des Projekts ausgewählt wurden und änderungen am Projekt vorgenommen wurden.

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 entfernt Microsoft.AspNetCore.All wurden. Weitere Informationen finden Sie unter Das Metapaket „Microsoft.AspNetCore.All“ für ASP.NET Core 2.0 und Microsoft.AspNetCore.App-Metapaket für ASP.NET Core.
  • Entfernen Sie das Attribut "Version" für den Paketverweis auf Microsoft.AspNetCore.App . Projekte, die <Project Sdk="Microsoft.NET.Sdk.Web"> verwenden, müssen die Version nicht festlegen. Die Version wird vom Zielframework impliziert und so ausgewählt, dass sie der ASP.NET Core 2.1 am besten passt. Weitere Informationen finden Sie im Abschnitt Regeln für Projekte, die auf das freigegebene Framework abzielen.
  • Aktualisieren Sie für Apps, die .NET Framework zielen, jeden Paketverweis auf 2.1.
  • Entfernen Sie Verweise auf < DotNetCliToolReference-Elemente > für die folgenden Pakete. Diese Tools werden standardmäßig im Paket .NET Core-CLI 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 die empfohlene Lösung zum Verteilen von Razor Dateien. Wenn Ihre App eingebettete Ansichten verwendet oder anderweitig auf die Laufzeitkompilierung von Dateien angewiesen ist, fügen Sie in Ihrer Projektdatei zu Razor <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> <PropertyGroup> 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 abzielen

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 vom Paketverweis angegebene Version ist die mindestens erforderliche Version. Beispielsweise wird ein Projekt, das auf die 2.1.1-Versionen dieser Pakete verweisen, nicht auf einem Computer ausgeführt, auf dem nur die Runtime 2.1.0 installiert ist.

Bekannte Probleme bei Projekten, die auf ein freigegebenes Framework abzielen:

  • Das .NET Core 2.1.300 SDK (erstmals in Visual Studio 15.6 enthalten) hat die implizite Version von auf 2.1.0 festgelegt, wodurch Konflikte mit Microsoft.AspNetCore.App Entity Framework Core 2.1.1 verursacht wurden. Die empfohlene Lösung besteht im Upgrade des .NET Core SDK auf 2.1.301 oder höher. Weitere Informationen finden Sie unter Pakete, die Abhängigkeiten gemeinsam mit Microsoft.AspNetCore.App können nicht auf Patchversionen verweisen.

  • Alle Projekte, die verwenden müssen oder sollten einen Paketverweis für das Paket in der Projektdatei hinzufügen, auch wenn sie einen Projektverweis auf ein anderes Projekt mit oder Microsoft.AspNetCore.All Microsoft.AspNetCore.App Microsoft.AspNetCore.All 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 einen Paketverweis für Microsoft.AspNetCore.App zu MyApp.Tests hinzu. Weitere Informationen finden Sie unter Integration testing is hard to set up and may break on shared framework servicing (Integrationstests sind schwer zu einrichten und können bei der Wartung freigegebener Frameworks unter Umständen nicht mehr durchgeführt werden).

Aktualisieren auf die 2.1-Docker-Images

In ASP.NET Core 2.1 wurden die Docker-Images zum Repository dotnet/dotnet-docker GitHub migriert. Die folgende Tabelle zeigt die Docker-Image- und Tagänderungen:

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 Zeilen in Ihrer Dockerfile-Datei so, dass die neuen Imagenamen und -tags in der Spalte FROM 2.1 der vorherigen Tabelle verwendet werden. 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 generierten Program.cs-Datei mit Vorlagen vorgenommen wurden.

Alte Versionsunterschiede

Die obige Abbildung zeigt die Version 2.0 mit den rot markierten Löschungen.

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

Unterschiede bei neuen Versionen

Der folgende Code zeigt die Version 2.1 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>();
    }
}

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

Änderungen am Start

Der folgende Code zeigt die Änderungen am generierten Code der 2.1-Vorlage. 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 folgenden Details ausführlich:

Änderungen am Authentifizierungscode

ASP.NET Core 2.1 stellt ASP.NET Core Identity als Klassenbibliothek Razor (RCL) zur Verfügung.

Die Standardmäßige 2.1-Benutzeroberfläche bietet derzeit keine signifikanten neuen Features Identity gegenüber version 2.0. Das Identity Ersetzen durch das RCL-Paket ist optional. Die Vorteile beim Ersetzen des generierten Codes der Identity Vorlage durch die RCL-Version sind:

  • Viele Dateien werden aus der Quellstruktur verschoben.
  • Alle Fehlerbehebungen oder neuen Features für Identity sind im Microsoft.AspNetCore.App enthalten. Sie erhalten automatisch den aktualisierten Identity , wenn Microsoft.AspNetCore.App aktualisiert wird.

Wenn Sie nicht triviale Änderungen am generierten Vorlagencode vorgenommen Identity haben:

  • Die oben genannten Vorteile rechtfertigen wahrscheinlich nicht die Konvertierung in die RCL-Version.
  • Sie können Ihren ASP.NET Core 2.0-Code Identity behalten. Er wird vollständig unterstützt.

Identity 2.1 macht Endpunkte mit dem Bereich Identity verfügbar. Die folgende Tabelle zeigt beispielsweise Beispiele für Identity Endpunkte, die sich von 2.0 in 2.1 ändern:

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

Anwendungen mit Code, der Identity die 2.0-Benutzeroberfläche verwendet und Identity durch die 2.1-Bibliothek ersetzt, Identity müssen URLs berücksichtigen, Identity deren Segment den /Identity URIs voranstellt wurde. Eine Möglichkeit, die neuen Endpunkte zu Identity verarbeiten, besteht darin, Umleitungen einzurichten, z. B. von /Account/Login zu /Identity/Account/Login .

Update Identity auf Version 2.1

Die folgenden Optionen sind verfügbar, um Identity auf Version 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 Code vorgenommen Identity wurden.
  • Löschen Sie Ihren vorhandenen Identity 2.0-Code, und integrieren Sie das Gerüst Identity in Ihr Projekt. Ihr Projekt verwendet die ASP.NET Core Identity Razor Klassenbibliothek. Sie können Code und benutzeroberfläche für einen beliebigen Identity Benutzeroberflächencode generieren, den Sie geändert haben. Wenden Sie Ihre Codeänderungen auf den neu gerüstierten Benutzeroberflächencode an.
  • Löschen Sie Ihren vorhandenen Identity 2.0-Code, und stellen Identity Sie das Gerüst in Ihr Projekt mit der Option Außerkraftsetzen aller Dateien ein.

Ersetzen Sie Identity 2.0 UI durch die Identity 2.1-Klassenbibliothek. Razor

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

  • Vergewissern Sie sich, dass die Projektdatei für die Verwendung von 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üstbau Identity in Ihr Projekt:
    • Wählen Sie die Projekte aus, die die Datei _ Layout.cshtml beenden.
    • Wählen Sie das + Symbol auf der rechten Seite der Datenkontextklasse aus. Übernehmen Sie den Standardnamen.
    • Wählen Sie Hinzufügen aus, um eine neue Datenkontextklasse zu erstellen. Zum Erstellen eines Gerüsts ist ein neuer Datenkontext erforderlich. Sie entfernen den neuen Datenkontext im nächsten Abschnitt.

Aktualisieren nach dem Gerüstbau Identity

  • Löschen Sie die Identity generierte IdentityDbContext abgeleitete Gerüstbauklasse im Ordner Identity Areas//Data/.

  • Delete Identity / Identity Areas/HostingStartup.cs.

  • Aktualisieren Sie die Datei _ LoginPartial.cshtml:

    • Verschieben Sie _ Pages/LoginPartial.cshtml in Pages/Shared/ _ LoginPartial.cshtml.
    • Fügen Sie asp-area="Identity" dem Formular und den Ankerverknüpfungslinks hinzu.
    • Aktualisieren Sie das <form /> -Element in <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 Razor Pages-Projektdateien

Die Layoutdatei

  • Verschieben von _ Pages/Layout.cshtml in Pages/Shared/ _ Layout.cshtml

  • Ändern Sie in Identity Areas//Pages/ _ ViewStart.cshtml Layout = "/Pages/_Layout.cshtml" in Layout = "/Pages/Shared/_Layout.cshtml" .

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

_ValidationScriptsPartial.cshtml

  • Pages/ _ ValidationScriptsPartial.cshtml wird zu Pages/Shared/ _ ValidationScriptsPartial.cshtml verschoben.
  • jquery.validate/1.14.0 ändert sich in jquery.validate/1.17.0.

Neue Dateien

Die folgenden Dateien werden hinzugefügt:

  • Privacy.cshtml
  • Privacy.cshtml.cs

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

Änderungen an MVC-Projektdateien Razor

Die Layoutdatei

Die Datei Layout.cshtml weist die folgenden Änderungen auf:

  • <partial name="_CookieConsentPartial" /> wird hinzugefügt.
  • jQuery ändert sich von 2.2.0 in 3.3.1.

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 ändert sich in jquery.validate/1.17.0

Neue Dateien und Aktionsmethoden

Folgendes wird hinzugefügt:

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

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

Änderungen am launchSettings.jsin der Datei

Da ASP.NET Core Apps jetzt standardmäßig HTTPS verwenden, hat sich die Eigenschaft/launchSettings.jsin der Datei geändert.

Der folgende JSON-Code zeigt die zuvor generierte 2.0-Vorlage launchSettings.jsin der Datei:

{
  "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/"
    }
  }
}

Der folgende JSON-Code zeigt die neue 2.1-Vorlage, die in der DateilaunchSettings.jsgeneriert wurde:

{
  "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 Range-Header

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

ControllerBase.File- und PhysicalFile-Bereichsheader

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

Legen Sie den Accept-Ranges Parameter auf fest, um den Header EnableRangeProcessing zu true aktivieren.

Weitere Änderungen