Migrieren von ASP.NET Core 2.2 zu 3.0

Von Scott Addie und Rick Anderson

In diesem Artikel wird erläutert, wie Sie ein vorhandenes ASP.NET Core 2.2-Projekt auf ASP.NET Core 3.0 aktualisieren. Die Erstellung eines neuen ASP.NET Core 3.0-Projekts kann für Folgendes hilfreich sein:

• Vergleich mit dem ASP.NET Core 2.2-Code
• Kopieren relevanter Änderungen in Ihr ASP.NET Core 3.0-Projekt

Voraussetzungen

.NET Core SDK-Version in global.json aktualisieren

Wenn Ihre Lösung von einer Datei vom Typ 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 3.0:

{
  "sdk": {
    "version": "3.0.100"
  }
}

Aktualisieren der Projektdatei

Aktualisieren des Zielframeworks

ASP.NET Core 3.0 oder höher kann nur auf .NET Core ausgeführt werden. Legen Sie den Bezeichner des Zielframeworks (TFM) auf netcoreapp3.0 fest:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

Entfernen von Verweisen auf veraltete Pakete

Eine große Anzahl von NuGet-Paketen ist nicht für ASP.NET Core 3.0 konzipiert. Entsprechende Paketverweise müssen aus der Projektdatei entfernt werden. Sehen Sie sich die folgende Projektdatei für eine ASP.NET Core 2.2-Web-App an:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App"/>
    <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
  </ItemGroup>

</Project>

Aktualisierte Projektdatei für ASP.NET Core 3.0:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

Für die aktualisierte ASP.NET Core 3.0-Projektdatei gilt Folgendes:

• In <PropertyGroup>:

  • Aktualisiert das TFM auf netcoreapp3.0.
  • Das <AspNetCoreHostingModel>-Element wird entfernt. Weitere Informationen finden Sie unter In-Process-Hostingmodell in diesem Dokument.

• In <ItemGroup>:

  • Microsoft.AspNetCore.App wurde entfernt. Weitere Informationen finden Sie unter Framework-Referenz in diesem Dokument.
  • Microsoft.AspNetCore.Razor.Design wird entfernt und befindet sich in der folgenden Liste der Pakete, die nicht mehr produziert werden.

Um die vollständige Liste der Pakete anzuzeigen, die nicht mehr produziert werden, können Sie die folgende Erweiterungsliste auswählen:

Änderungen mit schwerwiegenden Auswirkungen überprüfen

Überprüfen von Breaking Changes

Framework-Referenz

Features von ASP.NET Core, die über eines der oben aufgeführten Pakete verfügbar waren, sind als Teil des freigegebenen Frameworks Microsoft.AspNetCore.App verfügbar. Das freigegebene Framework ist der Satz von Assemblys (DLL-Dateien), die auf dem Computer installiert werden und eine Laufzeitkomponente sowie ein Zielpaket enthalten. Weitere Informationen finden Sie unter The shared framework (Das freigegebene Framework).

• Projekte, die auf das Microsoft.NET.Sdk.Web SDK abzielen, verweisen implizit auf das Microsoft.AspNetCore.App-Framework.

  Für diese Projekte sind keine weiteren Verweise erforderlich:

  <Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
      <TargetFramework>netcoreapp3.0</TargetFramework>
    </PropertyGroup>
      ...
  </Project>
  

• Bei Projekten, die auf das Microsoft.NET.Sdk oder Microsoft.NET.Sdk.Razor SDK ausgerichtet sind, muss ein explizites FrameworkReference-Element zu Microsoft.AspNetCore.App hinzugefügt werden:

  <Project Sdk="Microsoft.NET.Sdk.Razor">
    <PropertyGroup>
      <TargetFramework>netcoreapp3.0</TargetFramework>
    </PropertyGroup>
  
    <ItemGroup>
      <FrameworkReference Include="Microsoft.AspNetCore.App" />
    </ItemGroup>
      ...
  </Project>
  

Frameworkabhängige Builds mit Docker

Frameworkabhängige Builds von Konsolen-Apps, die ein Paket verwenden, das vom freigegebenen ASP.NET Core-Framework abhängt, können den folgenden Laufzeitfehler verursachen:

It was not possible to find any compatible framework version
The specified framework 'Microsoft.AspNetCore.App', version '3.0.0' was not found.
  - No frameworks were found.

Microsoft.AspNetCore.App ist das freigegebene Framework, das die ASP.NET Core-Runtime enthält, und nur im Docker-Image „dotnet/core/aspnet“ vorhanden. Das 3.0 SDK reduziert die Größe frameworkabhängiger Builds mithilfe von ASP.NET Core, indem doppelte Kopien von Bibliotheken, die im freigegebenen Framework verfügbar sind, nicht eingeschlossen werden. Dies ist eine potenzielle Einsparung von bis zu 18 MB. Es erfordert aber, dass die ASP.NET Core Runtime vorhanden bzw. installiert ist, um die App auszuführen.

Um festzustellen, ob die App eine (direkte oder indirekte) Abhängigkeit vom freigegebenen ASP.NET Core-Framework aufweist, überprüfen Sie die Datei runtimeconfig.json, die während eines Build-/Veröffentlichungsvorgangs Ihrer App generiert wurde. Die folgende JSON-Datei enthält eine Abhängigkeit vom freigegebenen ASP.NET Core-Framework:

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.0",
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "3.0.0"
    },
    "configProperties": {
      "System.GC.Server": true
    }
  }
}

Wenn Ihre App Docker verwendet, verwenden Sie ein Basisimage, das ASP.NET Core 3.0 enthält. Beispiel: docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.

Hinzufügen von Paketverweisen für entfernte Assemblys

ASP.NET Core 3.0 entfernt einige Assemblys, die zuvor Teil des Microsoft.AspNetCore.App-Paketverweises waren. Vergleichen Sie die beiden Ordner des freigegebenen Frameworks, um zu sehen, welche Assemblys entfernt wurden. Hier sehen Sie beispielsweise einen Vergleich der Versionen 2.2.7 und 3.0.0:

Verweisen Sie auf die 3.0-Versionen der entsprechenden Pakete, um weiterhin Features zu verwenden, die von den entfernten Assemblys bereitgestellt werden:

• Für eine vorlagengenerierte Web-App mit individuellen Benutzerkonten müssen die folgenden Pakete hinzugefügt werden:

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
    <PropertyGroup>
      <TargetFramework>netcoreapp3.0</TargetFramework>
      <UserSecretsId>My-secret</UserSecretsId>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="3.0.0" />
      <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="3.0.0" />
      <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="3.0.0" />
      <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="3.0.0" />
      <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.0.0" />
    </ItemGroup>
  
  </Project>
  

• Microsoft.EntityFrameworkCore

  Weitere Informationen zu Verweisen auf das datenbankanbieterspezifische Paket finden Sie unter Datenbankanbieter.

• Identity Benutzeroberfläche

  Unterstützung der Identity-Benutzeroberfläche kann durch einen Verweis auf das Microsoft.AspNetCore.Identity.UI-Paket hinzugefügt werden.

• SPA-Dienste

  • Microsoft.AspNetCore.SpaServices
  • Microsoft.AspNetCore.SpaServices.Extensions

• Authentifizierung: Unterstützung von Drittanbieter-Authentifizierungsflows ist in Form von NuGet-Paketen verfügbar:

  • Facebook-OAuth (Microsoft.AspNetCore.Authentication.Facebook)
  • Google-OAuth (Microsoft.AspNetCore.Authentication.Google)
  • Microsoft-Kontoauthentifizierung (Microsoft.AspNetCore.Authentication.MicrosoftAccount)
  • OpenID Connect-Authentifizierung (Microsoft.AspNetCore.Authentication.OpenIdConnect)
  • OpenID Connect-Bearer-Token (Microsoft.AspNetCore.Authentication.JwtBearer)
  • Twitter-OAuth (Microsoft.AspNetCore.Authentication.Twitter)
  • WsFederation-Authentifizierung (Microsoft.AspNetCore.Authentication.WsFederation)

• Unterstützung von Formatierung und Inhaltsaushandlung für System.Net.HttpClient: Das NuGet-Paket Microsoft.AspNet.WebApi.Client bietet praktische Erweiterbarkeit für System.Net.HttpClient mit APIs wie ReadAsAsync und PostJsonAsync. Dieses Paket hängt jedoch von Newtonsoft.Json ab, nicht von System.Text.Json. Dies bedeutet z. B., dass die durch JsonPropertyNameAttribute (System.Text.Json) angegebenen Serialisierungseigenschaftsnamen ignoriert werden. Es gibt ein neueres NuGet-Paket, das ähnliche Erweiterungsmethoden enthält, aber System.Text.Json verwendet: System.Net.Http.Json.

• Razor-Laufzeitkompilierung: Unterstützung der Laufzeitkompilierung von Razor-Ansichten und -Seiten ist jetzt Teil von Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

• Unterstützung von MVC mit Newtonsoft.Json (Json.NET): Unterstützung für die Verwendung von MVC mit Newtonsoft.Json ist jetzt Teil von Microsoft.AspNetCore.Mvc.NewtonsoftJson.

Änderungen beim Start

Die folgende Abbildung zeigt die gelöschten und geänderten Zeilen in einer Razor Pages-Web-App für ASP.NET Core 2.2:

In der obigen Abbildung ist gelöschter Code rot dargestellt. Der gelöschte Code zeigt keinen cookie-Optionscode. Dieser wurde gelöscht, bevor die Dateien verglichen wurden.

Die folgende Abbildung zeigt die hinzugefügten und geänderten Zeilen in einer Razor Pages-Web-App für ASP.NET Core 3.0:

In der obigen Abbildung ist hinzugefügter Code grün dargestellt. Weitere Informationen zu den folgenden Änderungen:

• services.AddMvc bis services.AddRazorPages, siehe MVC-Dienstregistrierung in diesem Dokument.
• CompatibilityVersion: Weitere Informationen finden Sie unter Kompatibilitätsversion für ASP.NET Core MVC.
• IHostingEnvironment bis IWebHostEnvironment, siehe diese GitHub-Ankündigung.
• app.UseAuthorization wurde den Vorlagen hinzugefügt, um die Reihenfolge anzuzeigen, in der die Autorisierungs-Middleware hinzugefügt werden muss. Wenn die App keine Autorisierung verwendet, können Sie den Aufruf von app.UseAuthorization problemlos entfernen.
• app.UseEndpoints: Weitere Informationen finden Sie unter Razor Pages oder unter Migrate Startup.Configure in diesem Dokument.

Unterstützung des Analysetools

Projekte, die implizit auf Microsoft.NET.Sdk.Web ausgerichtet sind, verweisen implizit auf Analysetools, die zuvor als Teil des Pakets Microsoft.AspNetCore.Mvc.Analyzers bereitgestellt wurden. Es sind keine zusätzlichen Verweise erforderlich, um sie zu aktivieren.

Wenn Ihre App API-Analysetools verwendet, die zuvor mit dem Paket Microsoft.AspNetCore.Mvc.Api.Analyzers bereitgestellt wurden, bearbeiten Sie Ihre Projektdatei, um auf die Analysetools zu verweisen, die im .NET Core Web SDK enthalten sind:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
    </PropertyGroup>

    ...
</Project>

Razor Klassenbibliothek

Bei Razor-Klassenbibliotheksprojekten, die Benutzeroberflächenkomponenten für MVC bereitstellen, muss die AddRazorSupportForMvc-Eigenschaft in der Projektdatei festgelegt werden:

<PropertyGroup>
  <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
</PropertyGroup>

In-Process-Hostingmodell

Projekte werden ab ASP.NET Core 3.0 standardmäßig im In-Process-Hostingmodell ausgeführt. Sie können in der Projektdatei optional die <AspNetCoreHostingModel>-Eigenschaft entfernen, wenn sie den Wert InProcess hat.

Kestrel

Konfiguration

Migrieren Sie die Kestrel-Konfiguration zum Webhost-Generator, der von ConfigureWebHostDefaults (Program.cs) bereitgestellt wird:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Wenn die App den Host manuell mit ConfigureWebHost anstelle von ConfigureWebHostDefaultserstellt, rufen Sie UseKestrel im Webhost-Generator auf:

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

    host.Run();
}

Verbindungs-Middleware ersetzt Verbindungsadapter

Verbindungsadapter (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) wurden aus Kestrel entfernt. Ersetzen Sie Verbindungsadapter durch Verbindungs-Middleware. Die Verbindungs-Middleware ähnelt der HTTP-Middleware in der ASP.NET Core Pipeline, aber für Verbindungen auf niedrigerer Ebene. HTTPS- und Verbindungsprotokollierung:

• Wurden von Verbindungsadaptern zur Verbindungs-Middleware verschoben.
• Diese Erweiterungsmethoden funktionieren wie in früheren Versionen von ASP.NET Core.

Weitere Informationen finden Sie im TlsFilterConnectionHandler-Beispiel im Abschnitt „ListenOptions.Protocols“ des Kestrel-Artikels.

Datentransportabstraktionen wurden verschoben und öffentlich gemacht.

Die Kestrel-Transportschicht wurde in Connections.Abstractions als öffentliche Schnittstelle verfügbar gemacht. Im Zuge dieser Updates wurde Folgendes geändert:

• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions und zugehörige Typen wurden entfernt.
• NoDelay wurde von ListenOptions in die Transportoptionen verschoben.
• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode wurde aus KestrelServerOptions entfernt.

Weitere Informationen finden Sie in den folgenden GitHub-Ressourcen:

• Client-/Server-Netzwerkabstraktionen (dotnet/AspNetCore #10308)
• Implementiere neue Bedrock-Listener-Abstraktion und platziere neu darüber (dotnet/AspNetCore #10321)

Kestrel Anfrage-Trailer-Header

Für Apps, die auf frühere Versionen von ASP.NET Core ausgerichtet sind, gilt Folgendes:

• Kestrel fügt HTTP/1.1-Chunked-Trailer-Header in die Sammlung der Anforderungsheader ein.
• Trailer sind verfügbar, nachdem der Anforderungstext bis zum Ende gelesen wurde.

Aufgrund von Bedenken hinsichtlich Unklarheiten zwischen Headern und Trailern wurden Trailer in 3.0 in eine neue Sammlung (RequestTrailerExtensions) verschoben.

HTTP/2-Anforderungstrailer sind:

• in ASP.NET Core 2.2 nicht verfügbar.
• in 3.0 als RequestTrailerExtensions verfügbar.

Für den Zugriff auf diese Trailer sind neue Anforderungserweiterungsmethoden vorhanden. Genau wie bei HTTP/1.1 sind Trailer verfügbar, nachdem der Anforderungstext bis zum Ende gelesen wurde.

Für das Release 3.0 sind folgende RequestTrailerExtensions-Methoden verfügbar:

• GetDeclaredTrailers: Ruft den Anforderungsheader „Trailer“ ab, in dem aufgelistet wird, welche Trailer nach dem Text erwartet werden.
• SupportsTrailers: Gibt an, ob die Anfrage den Empfang von Trailerheadern unterstützt.
• CheckTrailersAvailable: Überprüft, ob die Anforderung Trailer unterstützt und ob diese zum Lesen verfügbar sind. Bei dieser Überprüfung wird nicht davon ausgegangen, dass Trailer zum Lesen vorhanden sind. Möglicherweise sind keine Trailer zum Lesen verfügbar, auch wenn diese Methode true zurückgibt.
• GetTrailer: Ruft den angeforderten Trailer-Header aus der Antwort ab. Überprüfen Sie SupportsTrailers, bevor Sie GetTrailer aufrufen, da andernfalls möglicherweise eine Ausnahme vom Typ NotSupportedException auftritt, wenn die Anfrage keine nachgestellten Header unterstützt.

Weitere Informationen finden Sie unter Anforderungs-Trailer in einer separaten Sammlung speichern (dotnet/AspNetCore #10410).

AllowSynchronousIO deaktiviert

AllowSynchronousIO aktiviert oder deaktiviert synchrone E/A-APIs wie HttpRequest.Body.Read, HttpResponse.Body.Write und Stream.Flush. Diese APIs sind eine Quelle für einen Ressourcenmangel im Thread, der zu App-Abstürzen führt. In 3.0 ist AllowSynchronousIO standardmäßig deaktiviert. Weitere Informationen finden Sie im Abschnitt zu synchroner E/A im Kestrel-Artikel.

Synchrone E/A kann bei Bedarf durch Konfigurieren der AllowSynchronousIO-Option auf dem verwendeten Server konfiguriert werden (beim Aufrufen von ConfigureKestrel – z. B. bei Verwendung von Kestrel). Beachten Sie, dass Server (Kestrel, HttpSys, TestServer usw.) alle über eine eigene AllowSynchronousIO-Option verfügen, die sich nicht auf andere Server auswirkt. Synchrone E/A-Vorgänge können für alle Server auf Anforderungsbasis mit der Option IHttpBodyControlFeature.AllowSynchronousIO aktiviert werden:

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();

if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Wenn Sie Probleme mit TextWriter-Implementierungen oder anderen Streams haben, die synchrone APIs in Dispose aufrufen, rufen Sie stattdessen die neue DisposeAsync-API auf.

Weitere Informationen finden Sie unter [Announcement] AllowSynchronousIO disabled in all servers (dotnet/AspNetCore #7644).

Pufferung des Ausgabeformatierers

Auf Newtonsoft.Json, XmlSerializer und DataContractSerializer basierende Ausgabeformatierer unterstützen nur synchrone Serialisierung. Damit diese Formatter mit den AllowSynchronousIO-Einschränkungen des Servers kompatibel sind, puffert MVC deren Ausgabe, bevor sie auf den Datenträger geschrieben wird. Aufgrund der Pufferung schließt MVC den Content-Length-Header bei Antworten mit diesen Formatierern ein.

System.Text.Json unterstützt asynchrone Serialisierung. Daher puffert der System.Text.Json-basierte Formatierer nicht. Erwägen Sie die Verwendung dieses Formatierers, um die Leistung zu verbessern.

Um die Pufferung zu deaktivieren, können Anwendungen SuppressOutputFormatterBuffering in der Startkonfiguration festlegen:

services.AddControllers(options => options.SuppressOutputFormatterBuffering = true)

Beachten Sie, dass dies dazu führen kann, dass die Anwendung eine Laufzeitausnahme auslöst, wenn AllowSynchronousIO nicht ebenfalls konfiguriert ist.

Die Assembly „Microsoft.AspNetCore.Server.Kestrel.Https“ wurde entfernt

In ASP.NET Core 2.1 wurde der Inhalt von Microsoft.AspNetCore.Server.Kestrel.Https.dll in Microsoft.AspNetCore.Server.Kestrel.Core.dll verschoben. Dies war ein Update ohne kompatibilitätsbrechende Änderungen unter Verwendung von TypeForwardedTo-Attributen. Für 3.0 wurden die leere Assembly Microsoft.AspNetCore.Server.Kestrel.Https.dll und das NuGet-Paket entfernt.

In Bibliotheken, die auf Microsoft.AspNetCore.Server.Kestrel.Https verweisen, müssen ASP.NET Core-Abhängigkeiten mindestens auf 2.1 aktualisiert werden.

In Apps und Bibliotheken, die auf ASP.NET Core 2.1 oder höher ausgerichtet sind, müssen alle direkten Verweise auf das Paket Microsoft.AspNetCore.Server.Kestrel.Https entfernt werden.

Unterstützung von Newtonsoft.Json (Json.NET)

Im Rahmen der Verbesserung des freigegebenen ASP.NET Core-Frameworks wurde Newtonsoft.Json (Json.NET) aus dem freigegebenen ASP.NET Core-Framework entfernt.

Das standardmäßige JSON-Serialisierungsmodul für ASP.NET Core ist jetzt System.Text.Json (neu in .NET Core 3.0). Verwenden Sie nach Möglichkeit System.Text.Json. Es ist äußerst leistungsfähig und erfordert keine zusätzliche Bibliotheksabhängigkeit. Da System.Text.Json jedoch neu ist, fehlen möglicherweise derzeit Features, die Ihre App benötigt. Weitere Informationen finden Sie unter Migrieren von Newtonsoft.Json zu System.Text.Json.

Verwenden von Newtonsoft.Json in einem SignalR-Projekt für ASP.NET Core 3.0

• Installieren Sie das NuGet-Paket Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson.

• Verketten Sie auf dem Client einen AddNewtonsoftJsonProtocol-Methodenaufruf mit der HubConnectionBuilder-Instanz:

  new HubConnectionBuilder()
      .WithUrl("/chathub")
      .AddNewtonsoftJsonProtocol(...)
      .Build();
  

• Verketten Sie auf dem Server einen AddNewtonsoftJsonProtocol-Methodenaufruf mit dem AddSignalR-Methodenaufruf in Startup.ConfigureServices:

  services.AddSignalR()
      .AddNewtonsoftJsonProtocol(...);
  

Verwenden von Newtonsoft.Json in einem MVC-Projekt für ASP.NET Core 3.0

• Installieren Sie das Microsoft.AspNetCore.Mvc.NewtonsoftJson-Paket.

• Aktualisieren Sie Startup.ConfigureServices, um AddNewtonsoftJson aufzurufen.

  services.AddMvc()
      .AddNewtonsoftJson();
  

  AddNewtonsoftJson ist mit den folgenden neuen MVC-Dienstregistrierungsmethoden kompatibel:

  • AddRazorPages
  • AddControllersWithViews
  • AddControllers

  services.AddControllers()
      .AddNewtonsoftJson();
  

  Newtonsoft.Json-Einstellungen können im Aufruf von AddNewtonsoftJson festgelegt werden:

  services.AddMvc()
      .AddNewtonsoftJson(options =>
             options.SerializerSettings.ContractResolver =
                new CamelCasePropertyNamesContractResolver());
  

  Hinweis: Falls die AddNewtonsoftJson-Methode nicht verfügbar ist, vergewissern Sie sich, dass Sie das Paket Microsoft.AspNetCore.Mvc.NewtonsoftJson installiert haben. Ein häufiger Fehler ist die Installation des Pakets Newtonsoft.Json anstelle des Pakets Microsoft.AspNetCore.Mvc.NewtonsoftJson.

Weitere Informationen finden Sie unter Hinzufügen der Unterstützung für das JSON-Format auf der Grundlage von Newtonsoft.Json.

MVC-Dienstregistrierung

In ASP.NET Core 3.0 werden neue Optionen zum Registrieren von MVC-Szenarien in Startup.ConfigureServices hinzugefügt.

Drei neue Erweiterungsmethoden auf oberster Ebene im Zusammenhang mit MVC-Szenarien für IServiceCollection sind verfügbar. Vorlagen verwenden diese neuen Methoden anstelle von AddMvc. AddMvc verhält sich jedoch weiterhin wie in früheren Releases.

Im folgenden Beispiel wird Unterstützung von Controllern und API-bezogenen Features hinzugefügt, aber keine Unterstützung von Ansichten oder Seiten. Die API-Vorlage verwendet den folgenden Code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
}

Im folgenden Beispiel wird Unterstützung von Controllern, API-bezogenen Features und Ansichten hinzugefügt, aber keine Unterstützung von Seiten. Die Vorlage „Webanwendung (MVC)“ verwendet den folgenden Code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
}

Das folgende Beispiel fügt Unterstützung für Razor Pages sowie eine minimale Unterstützung für Controller hinzu. Die Vorlage „Webanwendung“ verwendet den folgenden Code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();
}

Die neuen Methoden können auch kombiniert werden. Das folgende Beispiel entspricht dem Aufruf von AddMvc in ASP.NET Core 2.2:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddRazorPages();
}

Weiterleitung von Startcode

Wenn eine App UseMvc oder UseSignalR aufruft, migrieren Sie die App nach Möglichkeit zu Endpunktrouting. Um die Endpunktrouting-Kompatibilität mit früheren Versionen von MVC zu verbessern, haben wir einige der in ASP.NET Core 2.2 eingeführten Änderungen bei der URL-Generierung rückgängig gemacht. Sollten bei der Verwendung von Endpunktrouting in Version 2.2 Probleme aufgetreten sein, können Sie in ASP.NET Core 3.0 Verbesserungen erwarten. Es gibt jedoch ein paar Ausnahmen:

• Wenn die App IRouter implementiert oder von Route erbt, verwenden Sie DynamicRouteValuesTransformer als Ersatz.
• Wenn die App direkt auf RouteData.Routers in MVC zugreift, um URLs zu analysieren, können Sie dies durch die Verwendung von LinkParser.ParsePathByEndpointName ersetzen.
  • Definieren Sie die Route mit einem Routennamen.
  • Verwenden Sie LinkParser.ParsePathByEndpointName, und übergeben Sie den gewünschten Routennamen.

Endpunktrouting unterstützt die gleiche Routenmustersyntax und die gleichen Features für die Routenmustererstellung wie IRouter. Endpunktweiterleitung unterstützt IRouteConstraint. Endpunktrouting unterstützt [Route], [HttpGet] und die anderen MVC-Routingattribute.

Bei den meisten Anwendungen sind nur für Startup Änderungen erforderlich.

Migrieren von Startup.Configure

Allgemeine Tipps:

• Fügen Sie UseRoutinghinzu.

• Wenn die App UseStaticFiles aufruft, platzieren Sie UseStaticFilesvorUseRouting.

• Wenn die App Authentifizierungs-/Autorisierungsfunktionen wie AuthorizePage oder [Authorize] verwendet, platzieren Sie die Aufrufe von UseAuthentication und UseAuthorization: after, UseRouting und UseCors, aber vor UseEndpoints:

  public void Configure(IApplicationBuilder app)
  {
    ...
  
    app.UseStaticFiles();
  
    app.UseRouting();
    app.UseCors();
  
    app.UseAuthentication();
    app.UseAuthorization();
  
    app.UseEndpoints(endpoints => {
       endpoints.MapControllers();
    });
  

• Ersetzen Sie UseMvc oder UseSignalR durch UseEndpoints.

• Wenn die App CORS-Szenarien verwendet (z. B. [EnableCors]), platzieren Sie den Aufruf von UseCors vor jeder anderen Middleware, die CORS verwendet. Platzieren Sie also beispielsweise UseCors vor UseAuthentication, UseAuthorization und UseEndpoints.

• Ersetzen Sie IHostingEnvironment durch IWebHostEnvironment, und fügen Sie eine using-Anweisung für den Microsoft.AspNetCore.Hosting-Namespace hinzu.

• Ersetzen Sie IApplicationLifetime durch IHostApplicationLifetime (Microsoft.Extensions.Hosting-Namespace).

• Ersetzen Sie EnvironmentName durch Environments (Microsoft.Extensions.Hosting-Namespace).

Der folgende Code ist ein Beispiel für Startup.Configure in einer typischen ASP.NET Core 2.2-App:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseStaticFiles();

    app.UseAuthentication();

    app.UseSignalR(hubs =>
    {
        hubs.MapHub<ChatHub>("/chat");
    });

    app.UseMvc(routes =>
    {
        routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Nach der Aktualisierung des vorherigen Startup.Configure-Codes:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseStaticFiles();

    app.UseRouting();

    app.UseCors();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chat");
        endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Integritätsprüfungen

Health Checks verwenden Endpunktrouting mit dem Generic Host. Rufen Sie in Startup.ConfigureMapHealthChecks für den Endpunkt-Generator mit der Endpunkt-URL oder dem relativen Pfad auf:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Integritätsprüfungsendpunkte können Folgendes:

• Sie geben mindestens einen zugelassenen Host oder Port an.
• Sie erfordern Autorisierung.
• CORS erforderlich.

Weitere Informationen finden Sie unter Integritätsprüfungen in ASP.NET Core.

Leitfaden für Sicherheitsmiddleware

Die Unterstützung von Autorisierung und CORS ist auf Basis des Middlewareansatzes vereinheitlicht. Dies ermöglicht die Verwendung der gleichen Middleware und Funktionen in allen diesen Szenarien. In dieser Version wird eine aktualisierte Autorisierungs-Middleware bereitgestellt, und CORS-Middleware wird verbessert, sodass sie die von MVC-Controllern verwendeten Attribute verstehen kann.

CORS

Früher war CORS nicht immer einfach zu konfigurieren. Zwar wurde Middleware für die Verwendung in einigen Anwendungsfällen bereitgestellt, in anderen Anwendungsfällen waren MVC-Filter aber für die Verwendung ohne Middleware vorgesehen. Mit ASP.NET Core 3.0 empfehlen wir, dass alle Apps, die CORS erfordern, die CORS-Middleware zusammen mit Endpoint Routing verwenden. UseCors kann mit einer Standardrichtlinie bereitgestellt werden, und die Attribute [EnableCors] und [DisableCors] können verwendet werden, um die Standardrichtlinie bei Bedarf außer Kraft zu setzen.

Im folgenden Beispiel:

• CORS ist für alle Endpunkte mit der Richtlinie namens default aktiviert.
• Die MyController-Klasse deaktiviert CORS mit dem [DisableCors]-Attribut.

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseCors("default");

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

[DisableCors]
public class MyController : ControllerBase
{
    ...
}

Autorisierung

In früheren Versionen von ASP.NET Core wurde die Autorisierungsunterstützung über das [Authorize]-Attribut bereitgestellt. Autorisierungsmiddleware war nicht verfügbar. In ASP.NET Core 3.0 ist Autorisierungsmiddleware erforderlich. Es wird empfohlen, die ASP.NET Core Autorisierungs-Middleware (UseAuthorization) unmittelbar danach UseAuthenticationzu platzieren. Die Autorisierungs-Middleware kann auch mit einer Standardrichtlinie konfiguriert werden, die überschrieben werden kann.

In ASP.NET Core 3.0 oder höher wird UseAuthorization in Startup.Configure aufgerufen, und das folgende HomeController erfordert einen angemeldeten Benutzer:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

public class HomeController : Controller
{
    [Authorize]
    public IActionResult BuyWidgets()
    {
        ...
    }
}

Bei Verwendung von Endpunktrouting wird empfohlen, nicht AuthorizeFilter zu konfigurieren und stattdessen die Autorisierungsmiddleware zu verwenden. Wenn die App einen Autorisierungsfilter (AuthorizeFilter) als globalen Filter in MVC verwendet, wird empfohlen, den Code umzugestalten, um im Aufruf von AddAuthorization eine Richtlinie bereitzustellen.

DefaultPolicy ist anfangs so konfiguriert, dass eine Authentifizierung erforderlich ist, sodass keine zusätzliche Konfiguration erforderlich ist. Im folgenden Beispiel werden MVC-Endpunkte als RequireAuthorization gekennzeichnet, sodass alle Anfragen auf Grundlage von DefaultPolicy autorisiert werden müssen. Jedoch ermöglicht HomeController aufgrund von [AllowAnonymous] den Zugriff, ohne dass sich die Benutzer*innen in der App anmelden:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute().RequireAuthorization();
    });
}

[AllowAnonymous]
public class HomeController : Controller
{
    ...
}

Autorisierung für bestimmte Endpunkte

Die Autorisierung kann auch für bestimmte Endpunktklassen konfiguriert werden. Der folgende Code ist ein Beispiel für die Konvertierung einer MVC-App mit einem konfigurierten globalen Autorisierungsfilter (AuthorizeFilter) in eine App mit einer bestimmten Richtlinie, die eine Autorisierung erfordert:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    static readonly string _RequireAuthenticatedUserPolicy = 
                            "RequireAuthenticatedUserPolicy";
    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
                 options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        // Pre 3.0:
        // services.AddMvc(options => options.Filters.Add(new AuthorizeFilter(...));

        services.AddControllersWithViews();
        services.AddRazorPages();
        services.AddAuthorization(o => o.AddPolicy(_RequireAuthenticatedUserPolicy,
                        builder => builder.RequireAuthenticatedUser()));

    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseDatabaseErrorPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            app.UseHsts();
        }
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute()
                .RequireAuthorization(_RequireAuthenticatedUserPolicy);
            endpoints.MapRazorPages();
        });
    }
}

Richtlinien können auch angepasst werden. Das DefaultPolicy ist so konfiguriert, dass eine Authentifizierung erforderlich ist:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
                 options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        services.AddControllersWithViews();
        services.AddRazorPages();
        services.AddAuthorization(options =>
        {
            options.DefaultPolicy = new AuthorizationPolicyBuilder()
              .RequireAuthenticatedUser()
              .Build();
        });

    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseDatabaseErrorPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            app.UseHsts();
        }
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute().RequireAuthorization();
            endpoints.MapRazorPages();
        });
    }
}

[AllowAnonymous]
public class HomeController : Controller
{

Alternativ können alle Endpunkte so konfiguriert werden, dass eine Autorisierung erforderlich ist, ohne [Authorize] oder RequireAuthorization, indem eine FallbackPolicy konfiguriert wird. Das FallbackPolicy unterscheidet sich von dem DefaultPolicy. DefaultPolicy wird durch [Authorize] oder RequireAuthorization ausgelöst, während FallbackPolicy ausgelöst wird, wenn keine andere Richtlinie festgelegt wurde. FallbackPolicy ist zunächst so konfiguriert, dass Anfragen ohne Autorisierung erlaubt werden.

Das folgende Beispiel entspricht dem vorhergehenden DefaultPolicy-Beispiel, verwendet jedoch FallbackPolicy, um für alle Endpunkte stets eine Authentifizierung zu verlangen, es sei denn, [AllowAnonymous] wird angegeben:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddAuthorization(options =>
    {
        options.FallbackPolicy = new AuthorizationPolicyBuilder()
          .RequireAuthenticatedUser()
          .Build();
    });
}

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

[AllowAnonymous]
public class HomeController : Controller
{
    ...
}

Die Autorisierung durch Middleware funktioniert, ohne dass das Framework über spezifische Autorisierungsinformationen verfügt. Beispielsweise haben Health Checks keine spezifische Kenntnis von der Autorisierung, aber über die Middleware kann eine konfigurierbare Autorisierungsrichtlinie auf sie angewendet werden.

Darüber hinaus können die Autorisierungsanforderungen jedes Endpunkts angepasst werden. Im folgenden Beispiel verarbeitet UseAuthorization die Autorisierung mit DefaultPolicy, aber der Health-Check-Endpunkt /healthz erfordert einen Benutzer vom Typ admin:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints
            .MapHealthChecks("/healthz")
            .RequireAuthorization(new AuthorizeAttribute(){ Roles = "admin", });
    });
}

Für einige Szenarien wird Schutz implementiert. Endpoints Middleware löst eine Ausnahme aus, wenn eine Autorisierungs- oder CORS-Richtlinie aufgrund fehlender Middleware übersprungen wird. Die Unterstützung durch den Analysator zur Bereitstellung zusätzlichen Feedbacks zu Fehlkonfigurationen wird derzeit entwickelt.

Benutzerdefinierte Autorisierungshandler

Wenn die App benutzerdefinierte Autorisierungshandler verwendet, übergibt das Endpunktrouting einen anderen Ressourcentyp an Handler als MVC. Handler, die erwarten, dass die Autorisierungshandlerkontext-Ressource vom Typ AuthorizationFilterContext ist (der von MVC-Filtern bereitgestellte Ressourcentyp), müssen aktualisiert werden, um Ressourcen vom Typ RouteEndpoint zu behandeln (der Ressourcentyp, der vom Endpunktrouting an Autorisierungshandler übergeben wird).

MVC verwendet weiterhin AuthorizationFilterContext-Ressourcen. Wenn die App also MVC-Autorisierungsfilter zusammen mit der Endpunktroutingautorisierung verwendet, müssen möglicherweise beide Arten von Ressourcen behandelt werden.

SignalR

Die Zuordnung von SignalR-Hubs erfolgt jetzt in UseEndpoints.

Ordnen Sie jeden Hub mit MapHub zu. Wie in früheren Versionen wird jeder Hub explizit aufgeführt.

Im folgenden Beispiel wird Unterstützung für den ChatHubSignalR-Hub hinzugefügt:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>();
    });
}

Es gibt eine neue Option zum Steuern von Nachrichtengrößenbeschränkungen von Clients. Gehen Sie beispielsweise in Startup.ConfigureServices folgendermaßen vor:

services.AddSignalR(hubOptions =>
{
    hubOptions.MaximumReceiveMessageSize = 32768;
});

In ASP.NET Core 2.2 können Sie TransportMaxBufferSize festlegen, um die maximale Nachrichtengröße zu steuern. In ASP.NET Core 3.0 legt diese Option jetzt nur noch die maximale Größe fest, bevor Gegendruck einsetzt.

SignalR-Assemblys im freigegebenen Framework

Serverseitige SignalR-Assemblys von ASP.NET Core werden jetzt mit dem .NET Core SDK installiert. Weitere Informationen finden Sie unter Entfernen von Verweisen auf veraltete Pakete in diesem Dokument.

MVC-Controller

Die Zuordnung von Controllern erfolgt jetzt in UseEndpoints.

Fügen Sie MapControllers hinzu, wenn die App Attributrouting verwendet. Das Routing beinhaltet die Unterstützung vieler Frameworks ab ASP.NET Core 3.0. Daher ist das Hinzufügen von Controllern mit attributbasiertem Routing optional.

Ersetzen Sie Folgendes:

• MapRoute mit MapControllerRoute
• MapAreaRoute mit MapAreaControllerRoute

Da das Routing jetzt mehr als nur MVC unterstützt, hat sich die Terminologie geändert, damit klar ist, was die jeweilige Methode bewirkt. Konventionelle Routen wie MapControllerRoute/MapAreaControllerRoute/MapDefaultControllerRoute werden in der Reihenfolge angewendet, in der sie hinzugefügt werden. Platzieren Sie spezifischere Routen (z. B. Routen für einen Bereich) weiter vorn.

Im folgenden Beispiel:

• MapControllers fügt Unterstützung von Controllern mit attributbasiertem Routing hinzu.
• MapAreaControllerRoute fügt eine konventionelle Route für Controller in einem Bereich hinzu.
• MapControllerRoute fügt eine konventionelle Route für Controller hinzu.

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapAreaControllerRoute(
            "admin",
            "admin",
            "Admin/{controller=Home}/{action=Index}/{id?}");
        endpoints.MapControllerRoute(
            "default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Entfernung des Async-Suffix aus Controlleraktionsnamen

In ASP.NET Core 3.0 entfernt ASP.NET Core MVC das Suffix Async aus Controlleraktionsnamen. Dieser neue Standard wirkt sich sowohl auf das Routing als auch auf die Linkgenerierung aus. Beispiel:

public class ProductsController : Controller
{
    public async Task<IActionResult> ListAsync()
    {
        var model = await _dbContext.Products.ToListAsync();
        return View(model);
    }
}

Vor ASP.NET Core 3.0:

• Auf die vorherige Aktion konnte unter der Route Products/ListAsync zugegriffen werden.

• Für die Linkgenerierung musste das Suffix Async angegeben werden. Beispiel:

  <a asp-controller="Products" asp-action="ListAsync">List</a>
  

In ASP.NET Core 3.0:

• Auf die vorherige Aktion kann über die Route Products/List zugegriffen werden.

• Für die Linkgenerierung muss das Suffix Async nicht angegeben werden. Beispiel:

  <a asp-controller="Products" asp-action="List">List</a>
  

Diese Änderung hat keine Auswirkungen auf Namen, die mit dem [ActionName]-Attribut angegeben werden. Dieses Standardverhalten kann mit folgendem Code in Startup.ConfigureServices deaktiviert werden:

services.AddMvc(options =>
    options.SuppressAsyncSuffixInActionNames = false);

Änderungen an der Linkgenerierung

Es gibt einige Unterschiede bei der Linkgenerierung (z. B. mithilfe von Url.Link und ähnlichen APIs). Dazu gehören:

• Standardmäßig wird bei Verwendung von Endpoint Routing die Groß- und Kleinschreibung von Routenparametern in generierten URIs nicht zwangsläufig beibehalten. Dieses Verhalten kann mit der IOutboundParameterTransformer-Schnittstelle gesteuert werden.
• Die Generierung eines URI für eine ungültige Route (einen Controller/eine Aktion oder eine Seite, die nicht vorhanden ist) ergibt bei Verwendung von Endpunktrouting eine leere Zeichenfolge, anstatt einen ungültigen URI zu erzeugen.
• Umgebungswerte (Routenparameter aus dem aktuellen Kontext) werden bei der Linkgenerierung mit Endpunktrouting nicht automatisch verwendet. Bisher wurden beim Generieren eines Links zu einer anderen Aktion (oder Seite) nicht angegebene Routenwerte von den aktuellen Umgebungswerten von Routen abgeleitet. Bei Verwendung des Endpunktroutings müssen während der Linkgenerierung alle Routenparameter explizit angegeben werden.

Razor Seiten

Die Zuordnung von Razor Seiten erfolgt jetzt in UseEndpoints.

Fügen Sie MapRazorPages hinzu, wenn die App Razor Pages verwendet. Da Endpoint Routing viele Frameworks unterstützt, muss das Hinzufügen von Razor Pages jetzt explizit aktiviert werden.

In der folgenden Startup.Configure-Methode fügt MapRazorPages Unterstützung für Razor-Seiten hinzu:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

Verwenden von MVC ohne Endpunktrouting

Die Verwendung von MVC über UseMvc oder UseMvcWithDefaultRoute in ASP.NET Core 3.0 erfordert eine explizite Aktivierung innerhalb von Startup.ConfigureServices. Dies ist erforderlich, da MVC während der Initialisierung wissen muss, ob es sich auf die Autorisierungs- und CORS-Middleware verlassen kann. Es wird ein Analysetool bereitgestellt, das eine Warnung ausgibt, wenn die App versucht, eine nicht unterstützte Konfiguration zu verwenden.

Wenn die App Legacy-Unterstützung für IRouter erfordert, deaktivieren Sie EnableEndpointRouting mit einem der folgenden Ansätze in Startup.ConfigureServices:

services.AddMvc(options => options.EnableEndpointRouting = false);

services.AddControllers(options => options.EnableEndpointRouting = false);

services.AddControllersWithViews(options => options.EnableEndpointRouting = false);

services.AddRazorPages().AddMvcOptions(options => options.EnableEndpointRouting = false);

Integritätsprüfungen

Integritätsprüfungen können als Routinglösung mit Endpunktrouting verwendet werden.

Fügen Sie MapHealthChecks hinzu, um Integritätsprüfungen mit Endpunktrouting zu verwenden. Die MapHealthChecks-Methode akzeptiert Argumente wie UseHealthChecks. Der Vorteil der Verwendung von MapHealthChecks gegenüber UseHealthChecks ist die Möglichkeit, Autorisierung zu verwenden und eine präzisere Kontrolle über die Abgleichsrichtlinie zu haben.

Im folgenden Beispiel wird MapHealthChecks für einen Integritätsprüfungsendpunkt unter /healthz aufgerufen:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz", new HealthCheckOptions() { });
    });
}

HostBuilder ersetzt WebHostBuilder

Die ASP.NET Core 3.0-Vorlagen verwenden den allgemeinen Host. In vorherigen Versionen wurde der Webhost verwendet. Der folgende Code zeigt die per ASP.NET Core 3.0-Vorlage generierte Program-Klasse:

// requires using Microsoft.AspNetCore.Hosting;
// requires using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Der folgende Code zeigt die per ASP.NET Core 2.2-Vorlage generierte Program-Klasse:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

IWebHostBuilder bleibt in 3.0 und ist der Typ von webBuilder aus dem vorherigen Codebeispiel. WebHostBuilder wird in einem zukünftigen Release als veraltet markiert und durch HostBuilder ersetzt.

Die wichtigste Änderung zwischen WebHostBuilder und HostBuilder betrifft die Abhängigkeitsinjektion (Dependency Injection, DI). Bei Verwendung von HostBuilder kann nur Folgendes in den Konstruktor von Startup eingefügt werden:

• IConfiguration
• IHostEnvironment
• IWebHostEnvironment

Die HostBuilder DI-Einschränkungen:

• Aktivieren, dass der DI-Container nur einmal erstellt wird.
• Vermeidet die daraus resultierenden Probleme mit der Objektlebensdauer, wie das Auflösen mehrerer Instanzen von Singletons.

Weitere Informationen finden Sie unter Avoiding Startup service injection in ASP.NET Core 3.

AddAuthorization wurde in eine andere Assembly verschoben

Für die AddAuthorization-Methoden von ASP.NET Core 2.2 und niedrigeren Versionen in Microsoft.AspNetCore.Authorization.dll gilt:

• Sie wurden in AddAuthorizationCore umbenannt.
• Sie wurden in Microsoft.AspNetCore.Authorization.Policy.dll verschoben.

Apps, die sowohl Microsoft.AspNetCore.Authorization.dll als auch Microsoft.AspNetCore.Authorization.Policy.dll verwenden, sind davon nicht betroffen.

Für Apps, die nicht Microsoft.AspNetCore.Authorization.Policy.dll verwenden, muss eine der folgenden Aktionen ausgeführt werden:

• Fügen Sie einen Verweis auf Microsoft.AspNetCore.Authorization.Policy.dll hinzu. Dieser Ansatz funktioniert für die meisten Apps, und mehr ist nicht nötig.
• Wechseln Sie zur Verwendung von AddAuthorizationCore.

Weitere Informationen finden Sie unter Breaking Change: Die AddAuthorization(o =>-Überladung befindet sich in einer anderen Assembly #386.

Identity Benutzeroberfläche

Aktualisierungen für die Identity-Benutzeroberfläche für ASP.NET Core 3.0:

• Fügen Sie einen Paketverweis auf Microsoft.AspNetCore.Identity.UI hinzu.
• Apps, die nicht Razor Pages verwenden, müssen MapRazorPages aufrufen. Siehe Razor Seiten in diesem Dokument.
• Bootstrap 4 ist das Standardframework für die Benutzeroberfläche. Legen Sie eine IdentityUIFrameworkVersion-Projekteigenschaft fest, um die Standardeinstellung zu ändern. Weitere Informationen finden Sie in dieser GitHub-Ankündigung.

SignalR

Der SignalR-JavaScript-Client wurde von @aspnet/signalr in @microsoft/signalr geändert. Um auf diese Änderung zu reagieren, ändern Sie die Verweise in Dateien vom Typ package.json, in require-Anweisungen und in ECMAScript-import-Anweisungen.

System.Text.Json ist das Standardprotokoll.

System.Text.Json ist jetzt das Standardhubprotokoll und wird sowohl vom Client als auch vom Server verwendet.

Rufen Sie in Startup.ConfigureServicesAddJsonProtocol auf, um Serializeroptionen festzulegen.

Server:

services.AddSignalR(...)
        .AddJsonProtocol(options =>
        {
            options.PayloadSerializerOptions.WriteIndented = false;
        })

Kunde:

new HubConnectionBuilder()
    .WithUrl("/chathub")
    .AddJsonProtocol(options =>
    {
        options.PayloadSerializerOptions.WriteIndented = false;
    })
    .Build();

Wechseln zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json verwenden, die in System.Text.Json nicht unterstützt werden, können Sie zu Newtonsoft.Json zurückwechseln. Weitere Informationen finden Sie weiter oben in diesem Artikel unter Verwenden von Newtonsoft.Json in einem SignalR-Projekt für ASP.NET Core 3.0.

Verteilte Redis-Caches

Das Paket Microsoft.Extensions.Caching.Redis ist nicht für Apps ab ASP.NET Core 3.0 verfügbar. Ersetzen Sie den Paketverweis durch Microsoft.Extensions.Caching.StackExchangeRedis. Weitere Informationen finden Sie unter Verteiltes Zwischenspeichern in ASP.NET Core.

Aktivieren der Laufzeitkompilierung

Vor ASP.NET Core 3.0 war die Laufzeitkompilierung von Ansichten ein implizites Feature des Frameworks. Die Laufzeitkompilierung ergänzt die Buildzeitkompilierung von Ansichten. Es ermöglicht dem Framework, Razor-Ansichten und -Seiten (.cshtml-Dateien) zu kompilieren, wenn die Dateien geändert werden, ohne die gesamte App neu erstellen zu müssen. Dieses Feature unterstützt das Szenario einer schnellen Bearbeitung in der IDE mit anschließender Aktualisierung des Browsers, um die Änderungen anzuzeigen.

In ASP.NET Core 3.0 ist die Laufzeitkompilierung ein optionales Szenario. Die Buildzeitkompilierung ist der einzige Mechanismus für die Ansichtskompilierung, der standardmäßig aktiviert ist. Die Runtime basiert auf Visual Studio oder dotnet-watch in Visual Studio Code, um das Projekt neu zu erstellen, wenn Änderungen an Dateien vom Typ .cshtml erkannt werden. In Visual Studio lösen Änderungen an Dateien vom Typ .cs, .cshtml oder .razor eine Neukompilierung des Projekts aus. Das gilt allerdings nur für Projekte, die mithilfe von STRG+F5 ausgeführt werden, aber nicht für Projekte, die mithilfe von F5 gedebuggt werden.

So aktivieren Sie die Laufzeitkompilierung in Ihrem ASP.NET Core 3.0-Projekt

1. Installieren Sie das NuGet-Paket Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

2. Aktualisieren Sie Startup.ConfigureServices, um AddRazorRuntimeCompilation aufzurufen:

   Verwenden Sie für ASP.NET Core MVC den folgenden Code:

   services.AddControllersWithViews()
       .AddRazorRuntimeCompilation(...);
   

   Verwenden Sie für ASP.NET Core Razor Pages den folgenden Code:

   services.AddRazorPages()
       .AddRazorRuntimeCompilation(...);
   

Das Beispiel bei https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation zeigt, wie die Laufzeitkompilierung in Development Umgebungen bedingt aktiviert werden kann.

Weitere Informationen zur Kompilierung von Razor-Dateien finden Sie unter Kompilieren einer Razor-Datei in ASP.NET Core.

Bibliotheken per Multi-Targeting migrieren

Bibliotheken müssen häufig mehrere Versionen von ASP.NET Core unterstützen. Die meisten Bibliotheken, die für frühere Versionen von ASP.NET Core kompiliert wurden, sollten ohne Probleme weiter funktionieren. In folgenden Fällen muss die App kreuzkompiliert werden:

• Die Bibliothek ist auf ein Feature angewiesen, das eine binär inkompatible Änderung enthält.
• Die Bibliothek möchte neue Funktionen in ASP.NET Core 3.0 nutzen.

Beispiel:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>netcoreapp3.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.0'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
    <PackageReference Include="Microsoft.AspNetCore" Version="2.1.0" />
  </ItemGroup>
</Project>

Verwenden Sie #ifdefs, um spezifische APIs für ASP.NET Core 3.0 zu aktivieren:

var webRootFileProvider =
#if NETCOREAPP3_0
    GetRequiredService<IWebHostEnvironment>().WebRootFileProvider;
#elif NETSTANDARD2_0
    GetRequiredService<IHostingEnvironment>().WebRootFileProvider;
#else
#error unknown target framework
#endif

Weitere Informationen zur Verwendung von ASP.NET Core-APIs in einer Klassenbibliothek finden Sie unter Verwenden von ASP.NET Core-APIs in einer Klassenbibliothek.

Verschiedene Änderungen

Das Überprüfungssystem in .NET Core 3.0 oder höher behandelt nicht nullable Parameter oder gebundene Eigenschaften so, als hätten sie ein [Required] Attribut. Weitere Informationen finden Sie unter [Required]-Attribut.

Veröffentlichen

Löschen Sie die Ordner bin und obj im Projektverzeichnis.

TestServer

Bei Apps, die TestServer direkt mit dem Generic Host verwenden, erstellen Sie das TestServer auf einem IWebHostBuilder in ConfigureWebHost:

[Fact]
public async Task GenericCreateAndStartHost_GetTestServer()
{
    using var host = await new HostBuilder()
        .ConfigureWebHost(webBuilder =>
        {
            webBuilder
                .UseTestServer()
                .Configure(app => { });
        })
    .StartAsync();

    var response = await host.GetTestServer().CreateClient().GetAsync("/");

    Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
}

Bahnbrechende Änderungen

Verwenden Sie die Artikel in "Breaking changes in .NET ", um nach wichtigen Änderungen zu suchen, die beim Aktualisieren einer App auf eine neuere Version von .NET gelten können.

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Vollständige Liste der Breaking Changes im ASP.NET Core 3.0-Release
• Kompatibilitätsverletzende API-Änderungen in Antiforgery, CORS, Diagnostics, MVC und Routing. Diese Liste enthält Breaking Changes für Kompatibilitätsoptionen.

Routing für Endpunkte mit einem Catch-All-Parameter

public static void Main(string[] args)
{
   AppContext.SetSwitch("Microsoft.AspNetCore.Routing.UseCorrectCatchAllBehavior", 
                         true);
   CreateHostBuilder(args).Build().Run();
}
// Remaining code removed for brevity.

.NET Core 3.0 in Azure App Service

Der Rollout von .NET Core in Azure App Service ist abgeschlossen. .NET Core 3.0 ist in allen Azure App Service-Rechenzentren verfügbar.

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 Hosting Bundle.