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 die TFM einer Version verwenden, die größer oder gleich .NET Core 2.2 ist. Aktualisieren Sie in der Projektdatei den inneren Text des <TargetFramework> Knotens mit netcoreapp2.2:

<TargetFramework>netcoreapp2.2</TargetFramework>

Projekte für .NET Framework können weiterhin die TFM einer Version verwenden, 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 IIS zu übernehmen, fügen Sie die <AspNetCoreHostingModel> Eigenschaft mit einem Wert InProcess von einem <PropertyGroup> in der Projektdatei hinzu:

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

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

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

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 im Eintrag, der <handlers> das ASP.NET Core Modul (name="aspNetCore") hinzufügt, den modules Attributwert von AspNetCoreModule zu AspNetCoreModuleV2.
  • Fügen Sie im <aspNetCore> Element das Hostingmodell-Attribut (hostingModel="InProcess") hinzu.

Weitere Informationen und beispiele für web.config Dateien finden Sie unter ASP.NET Core Modul (ANCM) für IIS.

Aktualisieren von Paketverweisen

Wenn sie auf .NET Core ausgerichtet sind, entfernen Sie das Attribut des Metapackage-Verweises Version 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 Metapackage für ASP.NET Core.

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

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

Wenn sie auf .NET Framework abzielen, aktualisieren Sie das Attribut jedes Paketverweis Version auf 2.2.0 oder höher. Nachfolgend sehen Sie die Paketbezüge in einem typischen ASP.NET Core 2.2-Projekt, das .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 Sie auf microsoft.AspNetCore verweisen.Razor Designpaket , aktualisieren Sie ihr Version Attribut auf 2.2.0 oder höher. Fehler bei der Vorgehensweise führt zu dem folgenden 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 eine globale.json-Datei basiert, um auf eine bestimmte .NET Core SDK-Version zu abzielen, aktualisieren Sie ihre version Eigenschaft auf die auf Ihrem Computer installierte 2.2-Version:

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

Aktualisieren der Starteinstellungen

Wenn Sie Visual Studio Code verwenden, aktualisieren Sie die Starteinstellungendatei des Projekts (.vscode/launch.json). Der program Pfad 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}"
        }
    ]
}

Konfiguration aktualisieren Kestrel

Wenn die App UseKestrel durch Aufrufen CreateDefaultBuilder in der CreateWebHostBuilder-Methode der Program Klasse aufruft, rufen Sie KestrelConfigureKestrel den Server UseKestrel anstelle von Konflikten mit dem IIS-In-Process-Hostingmodell auf:

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 erstellt, rufen Sie UseKestrelvor dem Program Aufrufen ConfigureKestrelauf:

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 in ASP.NET Core.

Kompatibilitätsversion aktualisieren

Aktualisieren der Kompatibilitätsversion in Startup.ConfigureServicesVersion_2_2:

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

Aktualisieren der CORS-Richtlinie

In ASP.NET Core 2.2 reagiert die CORS-Middleware mit einem Wildcard-Ursprung (*) wenn eine Richtlinie einen Ursprung ermöglicht und Anmeldeinformationen erlaubt. Anmeldeinformationen werden nicht unterstützt, wenn ein Wildcard-Ursprung (*) angegeben wird, und Browser können die CORS-Anforderung nicht zulassen. Weitere Informationen, einschließlich Optionen zum Korrigieren des Problems auf dem Client, finden Sie in den MDN-Webdokumenten.

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. Das heißt, entfernen Sie den Aufruf AllowCredentials beim Konfigurieren der Richtlinie.
  • Wenn Anmeldeinformationen für die CORS-Anforderung erforderlich sind, um erfolgreich zu sein, ändern Sie die Richtlinie, um zulässige Hosts anzugeben. Verwenden Sie builder.WithOrigins("https://api.example1.com", "https://example2.com") beispielsweise anstelle der Verwendung AllowAnyOrigin.

Aktualisieren von Docker-Bildern

Die folgende Tabelle zeigt die Änderungen des Docker-Bildtags:

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 Zeilen in Ihrer Dockerfile-Datei, um die FROM neuen Bildtags in der Spalte 2.2 der vorherigen Tabelle zu verwenden.

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

Die Automatische Erstellung von Visual Studio auf Browseranforderungserfahrung funktioniert nicht mit dem IIS-In-Process-Hostingmodell. Sie müssen das Projekt manuell neu erstellen, wenn Sie das In-Process-Hosting verwenden. Verbesserungen an dieser Erfahrung sind für eine zukünftige Version von Visual Studio geplant.

Aktualisieren des Protokollierungscodes

Der empfohlene Protokollierungskonfigurationscode wurde von 2.1 bis 2.2 nicht geändert, aber einige 1.x-Codierungsmuster, die noch in 2.1 funktionierten, funktionieren nicht mehr in 2.2.

Wenn Ihre App die Protokollierungsanbieter-Initialisierung, Filterung und Konfiguration in der Startup Klasse ausführt, verschieben Sie diesen Code zu Program.Main:

  • Anbieter-Initialisierung:

    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) keine ausgewählte Komponente war, wenn Visual Studio installiert wurde oder eine vorherige Version des ANCM-Systems installiert wurde, laden Sie das neueste .NET Core Hosting Bundle Installer (direktes Herunterladen) herunter, und führen Sie das Installationsprogramm aus. Weitere Informationen finden Sie unter Hosting Bundle.

Zusätzliche Ressourcen