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 inneren Text des <TargetFramework> 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 IIS zu übernehmen, fügen Sie die <AspNetCoreHostingModel> -Eigenschaft mit dem Wert InProcess zu einer <PropertyGroup> in der 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 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 <handlers> Eintrag, der das ASP.NET Core Module (name="aspNetCore") hinzufügt, den modules Attributwert von in AspNetCoreModuleV2AspNetCoreModule .
  • Fügen Sie im <aspNetCore> -Element das Hostingmodellattribut (hostingModel="InProcess") hinzu.

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

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 wirdRazor. Aktualisieren Sie das Version -Attribut des Entwurfspakets 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 eine global.json-Datei als Ziel für eine bestimmte .NET Core SDK Version verwendet, aktualisieren Sie die version -Eigenschaft auf die auf Ihrem Computer installierte Version 2.2:

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

Aktualisieren der Starteinstellungen

Wenn Sie Visual Studio Code verwenden, aktualisieren Sie die Starteinstellungsdatei des Projekts (.vscode/launch.json). 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 aufruft, indem CreateDefaultBuilder sie in der CreateWebHostBuilder-Methode der Program -Klasse aufruftUseKestrel, rufen Sie ConfigureKestrel auf, um den Server anstelle von UseKestrel zu konfigurierenKestrel, um Konflikte mit dem IIS-In-Process-Hostingmodell 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 den Host nicht manuell in der Program -Klasse aufruft CreateDefaultBuilder und erstellt, rufen Sie vor dem Aufruf von aufConfigureKestrelUseKestrel:

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 auf Startup.ConfigureServicesVersion_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 lassen die CORS-Anforderung nicht zu. 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 builder.WithOrigins("https://api.example1.com", "https://example2.com") beispielsweise 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.

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 war, laden Sie den neuesten .NET Core Hosting Bundle Installer (direkter Download) herunter, und führen Sie das Installationsprogramm aus. Weitere Informationen finden Sie unter Hosting Bundle.

Zusätzliche Ressourcen