Migrieren von ASP.NET Core 2.1 zu 2.2

Von Scott Addie

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

Voraussetzungen

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)

Projekte für .NET Core sollten das TFM einer Version verwenden, die größer oder gleich .NET Core 2.2 ist. Aktualisieren Sie in der Projektdatei den <TargetFramework> inneren Text des Knotens mit netcoreapp2.2 :

<TargetFramework>netcoreapp2.2</TargetFramework>

Projekte, die auf .NET Framework ausgerichtet sind, verwenden möglicherweise weiterhin das TFM einer Version, die größer oder gleich .NET Framework 4.6.1 ist:

<TargetFramework>net461</TargetFramework>

Übernehmen des IIS-In-Process-Hostingmodells

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

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

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

Weitere Informationen finden Sie unter ASP.NET Core-Modul.

Aktualisieren einer benutzerdefinierten web.config-Datei

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

  • Ändern Sie in dem <handlers> Eintrag, der das ASP.NET Core Module ( ) hinzufügt, name="aspNetCore" den modules Attributwert von AspNetCoreModule in AspNetCoreModuleV2 .
  • Fügen Sie im <aspNetCore> -Element das Hostingmodellattribut ( hostingModel="InProcess" ) hinzu.

Weitere Informationen und Beispieldateienweb.config finden Sie unter ASP.NET Core-Modul .

Aktualisieren von Paketverweisen

Wenn Sie .NET Core als Ziel haben, entfernen Sie das -Attribut des Metapaketverweises Version in der Projektdatei. Die Aufnahme 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>

Wenn sie .NET Framework als Ziel verwenden, aktualisieren Sie das Attribut jedes Paketverweises Version auf 2.2.0 oder höher. Hier sind die Paketverweise in einem typischen ASP.NET Core 2.2-Projekt für .NET Framework:

<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 Microsoft.AspNetCore verwiesen Razor wird. Aktualisieren Sie das -Attribut des Entwurfspakets Version auf 2.2.0 oder höher. Wenn Sie dies nicht tun, führt dies zu folgendem Fehler:

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 auf einem global.js auf einer Datei basiert, um eine bestimmte .NET Core SDK Version als Ziel zu verwenden, aktualisieren Sie die version -Eigenschaft auf die 2.2-Version, die auf Ihrem Computer installiert ist:

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

Aktualisieren der Starteinstellungen

Wenn Sie Visual Studio Code verwenden, aktualisieren Sie die Starteinstellungsdatei des Projekts (.vscode/launch.jsauf). Der program Pfad sollte auf das neue 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 Kestrel der Konfiguration

Wenn die App UseKestrel aufruft, indem CreateDefaultBuilder sie in der CreateWebHostBuilder-Methode der Program -Klasse aufruft, rufen Sie ConfigureKestrel auf, um Kestrel den Server anstelle von UseKestrel zu konfigurieren, um Konflikte mit dem IIS-In-Process-Hostingmodellzu 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 den Host nicht manuell in der -Klasse aufruft CreateDefaultBuilder und Program erstellt, rufen Sie UseKestrel vor dem Aufruf 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 Implementierung des Webservers Kestrel 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 und Anmeldeinformationen zulässt. Anmeldeinformationen werden nicht unterstützt, wenn ein Platzhalterursprung ( * ) angegeben wird, und Browser die CORS-Anforderung nicht dürfen. Weitere Informationen, einschließlich Optionen zum Beheben des Problems auf dem Client, finden Sie in der MDN-Webdokument.

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

  • Ändern Sie die CORS-Richtlinie, um keine Anmeldeinformationen mehr zuzulassen. Das heißt, entfernen Sie den Aufruf von AllowCredentials beim Konfigurieren der Richtlinie.
  • Wenn Anmeldeinformationen erforderlich sind, damit die CORS-Anforderung erfolgreich ausgeführt werden kann, ändern Sie die Richtlinie, um zulässige Hosts anzugeben. Verwenden Sie beispielsweise builder.WithOrigins("https://api.example1.com", "https://example2.com") anstelle von AllowAnyOrigin .

Aktualisieren von Docker-Images

Die folgende Tabelle zeigt die Änderungen am Docker-Imagetag:

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-Datei so, dass die neuen Imagetags in der Spalte 2.2 der vorherigen Tabelle verwendet werden.

Manuelles Erstellen in Visual Studio bei Verwendung von IIS-In-Process-Hosting

Visual Studio autobuild on browser request experience doesn't function with the IIS in-process hosting model (Automatisches Erstellen auf Browseranforderung funktioniert nicht mit dem IIS-In-Process-Hostingmodell). Sie müssen das Projekt manuell neu erstellen, wenn Sie In-Process-Hosting verwenden. Verbesserungen an dieser Benutzeroberfläche sind für eine zukünftige Version von Visual Studio geplant.

Aktualisieren des Protokollierungscodes

Empfohlener Protokollierungskonfigurationscode hat sich nicht von 2.1 auf 2.2 geändert, aber einige 1.x-Codierungsmuster, die in 2.1 noch funktioniert haben, funktionieren in 2.2 nicht mehr.

Wenn Ihre App die Initialisierung des Protokollierungsanbieters, das Filtern und das Laden der Konfiguration in der Startup -Klasse durchsetzt, verschieben Sie diesen Code in Program.Main :

  • Anbieterinitialisierung:

    1.x-Beispiel:

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

    Beispiel 2.2:

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

    Beispiel 2.2:

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

    Beispiel 2.2:

    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.

Zusätzliche Ressourcen