Migrieren von ASP.NET Core 2.1 zu 2.2

Artikel
11/06/2024

In diesem Artikel wird erläutert, wie Sie ein vorhandenes ASP.NET Core 2.1-Projekt auf ASP.NET Core 2.2 aktualisieren.

Voraussetzungen

Visual Studio 2019 mit der Workload ASP.NET- und Webentwicklung
.NET Core SDK 2.2 oder höher

Warnung

Wenn Sie Visual Studio 2017 verwenden, finden Sie unter dotnet/sdk issue #3124 Informationen zu .NET Core SDK-Versionen, die nicht mit Visual Studio verwendet werden können.

Aktualisieren des Zielframeworkmonikers (Target Framework Moniker, TFM)

Auf .NET Core ausgerichtete Projekte müssen den Zielframeworkmoniker (Target Frame Moniker, TFM) einer Version größer gleich .NET Core 2.2 verwenden. Aktualisieren Sie in der Projektdatei den inneren Text des Knotens <TargetFramework> mit netcoreapp2.2:

<TargetFramework>netcoreapp2.2</TargetFramework>

Auf .NET Framework ausgelegte Projekte können weiterhin den TFM einer Version größer gleich .NET Framework 4.6.1 verwenden.

<TargetFramework>net461</TargetFramework>

Übernehmen des IIS-In-Process-Hostingmodells

Um das In-Process-Hostingmodell für IIS zu übernehmen, fügen Sie einer <PropertyGroup> in der Projektdatei die <AspNetCoreHostingModel>-Eigenschaft mit dem Wert von InProcess hinzu:

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

Das In-Process-Hostingmodell wird nicht für ASP.NET Core-Apps unterstützt, die auf .NET Framework ausgerichtet sind.

Weitere Informationen finden Sie im Artikel ASP.NET Core-Modul (ANCM) für IIS:

Aktualisieren einer benutzerdefinierten Datei „web.config“

Für Projekte, die eine benutzerdefinierte Datei web.config im Projektstamm verwenden, um die veröffentlichte Datei web.config zu generieren:

Ändern Sie im Eintrag <handlers>, der das ASP.NET Core-Modul (name="aspNetCore") hinzufügt, den Wert des modules-Attributs von AspNetCoreModule in AspNetCoreModuleV2.
Fügen Sie im <aspNetCore>-Element das Hostingmodell-Attribut (hostingModel="InProcess") hinzu.

Weitere Informationen und Beispiele zur Datei web.config finden Sie unter ASP.NET Core-Modul (ANCM) für IIS.

Aktualisieren von Paketverweisen

Wenn .NET Core das Ziel für Ihre Apps usw. ist, entfernen Sie das Version-Attribut des Metapaketverweis in der Projektdatei. Die Einbeziehung eines Version-Attributs führt zu der folgenden Warnung:

A PackageReference to 'Microsoft.AspNetCore.App' specified a Version of `2.2.0`. Specifying the version of this package is not recommended. For more information, see https://aka.ms/sdkimplicitrefs

Weitere Informationen finden Sie unter Microsoft.AspNetCore.App-Metapaket für ASP.NET Core.

Der Metapaketverweis sollte dem folgenden <PackageReference />-Knoten ähneln:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

Aktualisieren Sie bei Apps, die auf .NET Framework ausgerichtet sind, das Version-Attribut jedes Paketverweis auf 2.2.0 oder höher. Im Folgenden finden Sie die Paketverweise in einem typischen ASP.NET Core 2.2-Projekt, das auf .NET Framework ausgerichtet ist:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.HttpsPolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.2.0" />
</ItemGroup>

Wenn auf das Microsoft.AspNetCore.Razor.Design-Paket verwiesen wird, aktualisieren Sie das zugehörige Version-Attribut auf 2.2.0 oder höher. Andernfalls wird folgender Fehler ausgelöst:

Detected package downgrade: Microsoft.AspNetCore.Razor.Design from 2.2.0 to 2.1.2. Reference the package directly from the project to select a different version.

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

Wenn Ihre Lösung von einer Datei global.json abhängig ist, um eine bestimmte .NET Core SDK-Version als Ziel zu verwenden, aktualisieren Sie ihre version-Eigenschaft auf die auf Ihrem Computer installierte Version 2.2:

{
  "sdk": {
    "version": "2.2.100"
  }
}

Verwalten von Starteinstellungen

Wenn Sie Visual Studio Code verwenden, aktualisieren Sie die Starteinstellungsdatei des Projekts (.vscode/launch.json). Der Pfad program sollte auf den neuen TFM verweisen:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchBrowser": {
                "enabled": true,
                "args": "${auto-detect-url}",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start ${auto-detect-url}"
                },
                "osx": {
                    "command": "open"
                },
                "linux": {
                    "command": "xdg-open"
                }
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

Aktualisieren der Kestrel-Konfiguration

Wenn die App UseKestrel aufruft, indem sie CreateDefaultBuilder in der CreateWebHostBuilder-Methode der Program-Klasse aufruft, rufen Sie ConfigureKestrel auf, um Kestrel-Server anstelle von UseKestrel zu konfigurieren, um Konflikte mit dem IIS-Process-Hostingmodell von IIS zu vermeiden:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

Wenn die App nicht CreateDefaultBuilder aufruft und den Host manuell in der Program-Klasse erstellt, rufen Sie UseKestrel vor dem Aufrufen von ConfigureKestrel auf:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        })
        .Build();

    host.Run();
}

Weitere Informationen finden Sie unter Kestrel-Webserver in ASP.NET Core.

Aktualisieren der Kompatibilitätsversion

Aktualisieren Sie die Kompatibilitätsversion in Startup.ConfigureServices auf Version_2_2:

services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Aktualisieren der CORS-Richtlinie

In ASP.NET Core 2.2 antwortet die CORS-Middleware mit einem Platzhalterursprung (*), wenn eine Richtlinie einen beliebigen Ursprung zulässt und Anmeldeinformationen zulässt. Anmeldeinformationen werden nicht unterstützt, wenn ein Platzhalterursprung (*) angegeben wird, und Browser lassen die CORS-Anforderung nicht zu. Weitere Informationen, einschließlich Optionen zum Beheben des Problems auf dem Client, finden Sie in der MDN-Webdokumentation.

Führen Sie eine der folgenden Aktionen aus, um dieses Problem auf dem Server zu beheben:

Ändern Sie die CORS-Richtlinie, um Anmeldeinformationen nicht mehr zuzulassen. Dazu müssen Sie beim Konfigurieren der Richtlinie den Aufruf an AllowCredentials entfernen.
Wenn Anmeldeinformationen erforderlich sind, damit die CORS-Anforderung erfolgreich ausgeführt werden kann, ändern Sie die Richtlinie, um zulässige Hosts anzugeben. Verwenden Sie z. B. builder.WithOrigins("https://api.example1.com", "https://example2.com") anstelle von AllowAnyOrigin.

Aktualisieren von Docker-Images

In der folgenden Tabelle sind die Änderungen der Docker-Images und -Tags aufgeführt:

2.1	2.2
`microsoft/dotnet:2.1-aspnetcore-runtime`	`mcr.microsoft.com/dotnet/core/aspnet:2.2`
`microsoft/dotnet:2.1-sdk`	`mcr.microsoft.com/dotnet/core/sdk:2.2`

Ändern Sie die FROM-Zeilen in Ihrer Dockerfile, um die neuen Imagetags in der Spalte „2.2“ der obigen Tabelle zu verwenden.

Manuelles Erstellen in Visual Studio bei Verwendung des IIS-prozessinternen Hostings

Die Benutzeroberfläche von Visual Studio für die automatische Erstellung bei Browseranforderungen funktioniert nicht mit dem IIS-internen Prozesshostingmodell. Sie müssen das Projekt manuell neu erstellen, wenn Sie das prozessinterne Hosting verwenden. Verbesserungen an dieser Oberfläche sind für eine zukünftige Version von Visual Studio geplant.

Aktualisieren des Protokollierungscodes

Der empfohlene Code für die Protokollierungskonfiguration wurde nicht von 2.1 zu 2.2 geändert, aber einige 1.x-Codierungsmuster, die in Version 2.1 noch funktionierten, funktionieren in Version 2.2 nicht mehr.

Wenn Ihre App die Initialisierung, Filterung und das Laden von Konfigurationen des Protokollierungsanbieters in der Startup -Klasse durchführt, verschieben Sie diesen Code in Program.Main:

Anbieterinitialisierung:

1.x-Beispiel:

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole();
}

2.2-Beispiel:


public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole();
        })
        // ...
}

Filtern:

1.x-Beispiel:

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(LogLevel.Information);
    // or
    loggerFactory.AddConsole((category, level) => 
        category == "A" || level == LogLevel.Critical);
}

2.2-Beispiel:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole()
                   .AddFilter<ConsoleLoggerProvider>
                       (category: null, level: LogLevel.Information)
                   // or
                   .AddFilter<ConsoleLoggerProvider>
                       ((category, level) => category == "A" ||
                           level == LogLevel.Critical)
            );
        })
        // ...
}

Laden der Konfiguration:

1.x-Beispiel:

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration);
}

2.2-Beispiel:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
        })
        // ...
}

Weitere Informationen finden Sie unter Protokollieren in .NET Core und ASP.NET Core.

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.

Teilen über

Migrieren von ASP.NET Core 2.1 zu 2.2

Voraussetzungen

Aktualisieren des Zielframeworkmonikers (Target Framework Moniker, TFM)

Übernehmen des IIS-In-Process-Hostingmodells

Aktualisieren einer benutzerdefinierten Datei „web.config“

Aktualisieren von Paketverweisen

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

Verwalten von Starteinstellungen

Aktualisieren der Kestrel-Konfiguration

Aktualisieren der Kompatibilitätsversion

Aktualisieren der CORS-Richtlinie

Aktualisieren von Docker-Images

Manuelles Erstellen in Visual Studio bei Verwendung des IIS-prozessinternen Hostings

Aktualisieren des Protokollierungscodes

ASP.NET Core-Modul (ANCM)

Zusätzliche Ressourcen

Zusätzliche Ressourcen