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. Es kann hilfreich sein, ein neues ASP.NET Core 3.0-Projekt zu erstellen, um:

• Vergleichen Sie den ASP.NET Core 2.2-Code.
• Kopieren Sie die relevanten Änderungen in ASP.NET Core 3.0-Projekt.

Voraussetzungen

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

Wenn Ihre Lösung auf einer dateispezifischenglobal.jsbasiert, um eine bestimmte .NET Core SDK-Version als Ziel zu verwenden, aktualisieren Sie die -Eigenschaft auf die version 3.0, die auf Ihrem Computer version installiert ist:

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

Aktualisieren der Projektdatei

Aktualisieren des Zielframework

ASP.NET Core 3.0 und höher werden nur unter .NET Core ausgeführt. Legen Sie den Zielframeworkmoniker (Target Framework Moniker, TFM) auf netcoreapp3.0 fest:

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

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

</Project>

Entfernen veralteter Paketverweise

Für NuGet 3.0 werden keine ASP.NET Core erstellt. Solche Paketverweise sollten aus der Projektdatei entfernt werden. Betrachten Sie die folgende Projektdatei für eine ASP.NET Core 2.2-Web-App:

<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>

Die aktualisierte Projektdatei für ASP.NET Core 3.0:

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

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

</Project>

Die aktualisierte ASP.NET Core 3.0-Projektdatei:

• In <PropertyGroup>:

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

• In <ItemGroup>:

  • Microsoft.AspNetCore.App wird entfernt. Weitere Informationen finden Sie in der Frameworkreferenz in diesem Dokument.
  • Microsoft.AspNetCore.Razor.Design wird entfernt und in der folgenden Liste der Pakete, die nicht mehr erstellt werden.

Um die vollständige Liste der Pakete zu sehen, die nicht mehr erstellt werden, wählen Sie die folgende Erweiterungsliste aus:

Überprüfen von Breaking Changes

Überprüfen von Breaking Changes

Frameworkreferenz

Features von ASP.NET Core, die über eines der oben aufgeführten Pakete verfügbar waren, sind als Teil des freigegebenen Microsoft.AspNetCore.App Frameworks 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>
  

• Projekte, die auf Microsoft.NET.Sdk oder Microsoft.NET.Sdk.Razor das SDK zielen, sollten explizit zu FrameworkReference Microsoft.AspNetCore.App hinzufügen:

  <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 geben:

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.Appist das freigegebene Framework, das ASP.NET Core Runtime enthält und nur im Docker-Image dotnet/core/aspnet vorhanden ist. Das SDK 3.0 reduziert die Größe frameworkabhängiger Builds mithilfe von ASP.NET Core, indem keine doppelten Kopien von Bibliotheken enthalten sind, die im freigegebenen Framework verfügbar sind. Dies ist eine potenzielle Einsparung von bis zu 18 MB, erfordert jedoch, dass die ASP.NET Core-Runtime vorhanden/installiert ist, um die App ausführen zu können.

Um zu ermitteln, ob die App über eine Abhängigkeit (direkt oder indirekt) vom freigegebenen ASP.NET Core-Framework verfügt, überprüfen Sie dieruntimeconfig.jsin der Datei, die während eines Build-/Veröffentlichungs-Veröffentlichungs-App generiert wurde. Die folgende JSON-Datei zeigt 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 freigegebenen Frameworkordner, um zu visualisieren, welche Assemblys entfernt wurden. Ein Vergleich der Versionen 2.2.7 und 3.0.0:

Um die von den entfernten Assemblys bereitgestellten Funktionen weiterhin zu verwenden, verweisen Sie auf die 3.0-Versionen der entsprechenden Pakete:

• Eine von einer Vorlage generierte Web-App mit einzelnen Benutzerkonten erfordert das Hinzufügen der folgenden Pakete:

  <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 zum Verweisen auf das datenbankanbieterspezifische Paket finden Sie unter Datenbankanbieter.

• Benutzeroberfläche von Identity

  Unterstützung für Identity die Benutzeroberfläche kann durch Verweisen auf Microsoft.AspNetCore hinzugefügt werden. Identity Benutzeroberflächenpaket.

• SPA-Dienste

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

• Authentifizierung: Unterstützung für Authentifizierungsflüsse von Drittanbietern ist als NuGet verfügbar:

  • Facebook OAuth (Microsoft.AspNetCore.Authentication.Facebook)
  • Google OAuth (Microsoft.AspNetCore.Authentication.Google)
  • Microsoft-Kontoauthentifizierung (Microsoft.AspNetCore.Authentication.MicrosoftAccount)
  • OpenID Verbinden-Authentifizierung (Microsoft.AspNetCore.Authentication.OpenIdConnect)
  • OpenID Verbinden Bearertoken (Microsoft.AspNetCore.Authentication.JwtBearer)
  • Twitter OAuth (Microsoft.AspNetCore.Authentication.Twitter)
  • WsFederation-Authentifizierung (Microsoft.AspNetCore.Authentication.WsFederation)

• Formatierungs- und Inhaltsaushandlungsunterstützung für System.Net.HttpClient : Das Microsoft.AspNet.WebApi.Client NuGet-Paket bietet nützliche Erweiterbarkeit für mit APIs wie System.Net.HttpClient und ReadAsAsync PostJsonAsync .

• Razor Laufzeitkompilierung: Die Unterstützung für die Laufzeitkompilierung von Ansichten und Seiten Razor ist jetzt Teil von Microsoft.AspNetCore.Mvc. Razor RuntimeCompilation.

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

Startänderungen

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

In der obigen Abbildung wird gelöschter Code rot dargestellt. Der gelöschte Code zeigt keinen Optionscode an, der vor dem cookie Vergleichen der Dateien gelöscht wurde.

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

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

• services.AddMvc zu services.AddRazorPages , siehe MVC-Dienstregistrierung in diesem Dokument.
• CompatibilityVersion, siehe Kompatibilitätsversion für ASP.NET Core MVC .
• IHostingEnvironmentzu IWebHostEnvironment , siehe GitHub Ankündigungvon .
• app.UseAuthorization wurde den Vorlagen hinzugefügt, um die Reihenfolge der Autorisierungs-Middleware zu zeigen, die hinzugefügt werden muss. Wenn die App keine Autorisierung verwendet, können Sie den Aufruf von sicher app.UseAuthorization entfernen.
• app.UseEndpointsfinden Sie Razor unter Seiten oder Startup.Configin diesem Dokument.

Analyzer-Unterstützung

Projekte, die auf Analysegeräte verweisen, die zuvor als Teil des Microsoft.NET.Sdk.Web Pakets Microsoft.AspNetCore.Mvc.Analyzers ausgeliefert wurden. Es sind keine zusätzlichen Verweise erforderlich, um diese zu aktivieren.

Wenn Ihre App API-Analysefunktionen verwendet, die zuvor mit dem Paket Microsoft.AspNetCore.Mvc.Api.Analyzers ausgeliefert wurden, bearbeiten Sie Ihre Projektdatei, um auf die Analysefunktionen zu verweisen, die als Teil des .NET Core Web SDK bereitgestellt wurden:

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

    ...
</Project>

Razor Klassenbibliothek

Razor Klassenbibliotheksprojekte, die Benutzeroberflächenkomponenten für MVC bereitstellen, müssen die AddRazorSupportForMvc -Eigenschaft in der Projektdatei festlegen:

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

In-Process-Hostingmodell

Projekte verwenden standardmäßig das In-Process-Hostingmodell in ASP.NET Core 3.0 oder höher. Sie können optional die -Eigenschaft <AspNetCoreHostingModel> in der Projektdatei entfernen, wenn ihr Wert InProcess ist.

Kestrel

Konfiguration

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

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 anstelle ConfigureWebHost von ConfigureWebHostDefaults erstellt, rufen Sie im UseKestrel 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. Verbindungs-Middleware ähnelt HTTP-Middleware in ASP.NET Core Pipeline, aber für Verbindungen auf niedrigerer Ebene. HTTPS und Verbindungsprotokollierung:

• Wurden von Verbindungsadaptern in 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.

Transportabstraktion verschoben und öffentlich gemacht

Die Kestrel-Transportschicht wurde in Connections.Abstractions als öffentliche Schnittstelle verfügbar gemacht. Im Rahmen dieser Updates:

• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions und die zugeordneten 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-Netzwerkabstraktion (dotnet/AspNetCore #10308)
• Implementieren Sie die neue Bedrock-Listenerabstraktion, und führen Sie eine neue Plattform oben Kestrel durch (dotnet/AspNetCore #10321)

Kestrel Anforderungstrailerheader

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

• Kestrel fügt der Auflistung der Anforderungsheader in blockierten Http/1.1-Trailerheadern hinzu.
• Nachspanner sind verfügbar, nachdem der Anforderungskörper bis zum Ende gelesen wurde.

Dies verursacht einige Bedenken hinsichtlich der Mehrdeutigkeit zwischen Headern und Nachspannen, sodass die Trailer in 3.0 in eine neue Sammlung ( RequestTrailerExtensions ) verschoben wurden.

HTTP/2-Anforderungstrailer sind:

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

Neue Anforderungserweiterungsmethoden sind vorhanden, um auf diese Trailer zu zugreifen. Wie bei HTTP/1.1 sind Trailer verfügbar, nachdem der Anforderungskörper bis zum Ende gelesen wurde.

Für das Release 3.0 sind die folgenden RequestTrailerExtensions Methoden verfügbar:

• GetDeclaredTrailers: Ruft den Anforderungsheader Trailer ab, der auflistet, welche Nachspanner nach dem Text erwartet werden.
• SupportsTrailers: Gibt an, ob die Anforderung den Empfang von Trailerheadern unterstützt.
• CheckTrailersAvailable: Überprüft, ob die Anforderung Trailer unterstützt und ob sie gelesen werden können. Bei dieser Überprüfung wird nicht davon ausgegangen, dass Nachspann gelesen werden müssen. Es gibt möglicherweise keine zu lesenden Trailer, auch wenn true von dieser Methode zurückgegeben wird.
• GetTrailer: Ruft den angeforderten nachgestellten Header aus der Antwort ab. Überprüfen Sie SupportsTrailers vor dem Aufrufen von , oder es kann ein GetTrailer NotSupportedException auftreten, wenn die Anforderung nachfolgende Header nicht unterstützt.

Weitere Informationen finden Sie unter Put request trailers in a separate collection (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 Threadverhungen, die zu App-Abstürzen führen. In 3.0 ist AllowSynchronousIO standardmäßig deaktiviert. Weitere Informationen finden Sie im Abschnitt Synchrone E/A im Kestrel Artikel.

Wenn synchrone E/A erforderlich ist, kann sie aktiviert werden, indem die Option auf dem verwendeten Server konfiguriert AllowSynchronousIO wird (z. B. bei Verwendung von ), wenn aufgerufen ConfigureKestrel Kestrel wird. Beachten Sie, dass Server ( Kestrel , HttpSys, TestServer usw.) alle über eine eigene Option verfügen, die sich AllowSynchronousIO nicht auf andere Server auswirkt. Synchrone E/A kann für alle Server auf Anforderungsbasis mithilfe der Option aktiviert IHttpBodyControlFeature.AllowSynchronousIO 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 Disposeaufrufen, rufen Sie stattdessen die neue DisposeAsync API auf.

Weitere Informationen finden Sie unter [Ankündigung] AllowSynchronousIO auf allen Servern deaktiviert (dotnet/AspNetCore #7644).

Pufferung des Ausgabeformatierers

Newtonsoft.Jsauf, XmlSerializer und DataContractSerializer basierenden Ausgabeformatierern unterstützen nur die synchrone Serialisierung. Damit diese Formatierer mit den AllowSynchronousIO-Einschränkungen des Servers arbeiten können, puffert MVC die Ausgabe dieser Formatierer, bevor auf den Datenträger geschrieben wird. Aufgrund der Pufferung schließt MVC den Content-Length-Header ein, wenn mit diesen Formatierern reagiert wird.

System.Text.Json unterstützt die asynchrone Serialisierung, und folglich puffert der System.Text.Json basierte Formatierungsprogramm nicht. Erwägen Sie die Verwendung dieses Formatierungsformatierers, um die Leistung zu verbessern.

Um die Pufferung zu deaktivieren, können Anwendungen beim Start Folgendes SuppressOutputFormatterBuffering konfigurieren:

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.

Microsoft.AspNetCore.Server. Kestrel . HTTPS-Assembly entfernt

In ASP.NET Core 2.1 wurden die Inhalte von Microsoft.AspNetCore.Server. Kestrel.Https.dll nach Microsoft.AspNetCore.Server Kestrel verschoben..Core.dll. Dies war ein nicht breaking update mit TypeForwardedTo Attributen. Für 3.0 wurden die leere Microsoft.AspNetCore.Server. Kestrel.Https.dll Assembly und das NuGet Paket entfernt.

Bibliotheken, die auf Microsoft.AspNetCore.Server Kestrel verweisen. Https sollte ASP.NET Core Abhängigkeiten auf 2.1 oder höher aktualisieren.

Apps und Bibliotheken für ASP.NET Core 2.1 oder höher sollten alle direkten Verweise auf Microsoft.AspNetCore.Server Kestrel entfernen. HTTPS-Paket.

Newtonsoft.Js-Unterstützung (Json.NET)

Im Rahmen der Arbeit zur Verbesserung des ASP.NET Core freigegebenen Frameworkswurde Newtonsoft.Json (Json.NET) aus dem ASP.NET Core freigegebenen Framework entfernt.

Das STANDARDMÄßIGE JSON-Serialisierungsprogramm für ASP.NET Core ist jetzt System.Text.Json , das in .NET Core 3.0 neu ist. Erwägen Sie nach Möglichkeit die Verwendung System.Text.Json von . Dies ist eine hohe Leistung und erfordert keine zusätzliche Bibliotheksabhängigkeit. Da jedoch System.Text.Json neu ist, fehlen möglicherweise derzeit Funktionen, die Ihre App benötigt. Weitere Informationen finden Sie unter Migrieren von Newtonsoft.Jszu System.Text.Jsunter.

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

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

• Verketten Sie auf dem Client einen AddNewtonsoftJsonProtocol Methodenaufruf an die 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 ASP.NET Core 3.0 MVC-Projekt

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

• Aktualisieren Sie Startup.ConfigureServices , um AddNewtonsoftJson aufzurufen.

  services.AddMvc()
      .AddNewtonsoftJson();
  

  AddNewtonsoftJson ist mit den neuen MVC-Dienstregistrierungsmethoden kompatibel:

  • AddRazorPages
  • AddControllersWithViews
  • AddControllers

  services.AddControllers()
      .AddNewtonsoftJson();
  

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

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

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

Weitere Informationen finden Sie unter Hinzufügen Newtonsoft.Jsunterstützung für das on-based JSON-Format.

MVC-Dienstregistrierung

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

Es sind drei neue Erweiterungsmethoden der obersten Ebene verfügbar, die sich auf MVC-Szenarien IServiceCollection beziehen. Vorlagen verwenden diese neuen Methoden anstelle von AddMvc . Verhält sich jedoch AddMvc weiterhin wie in früheren Versionen.

Im folgenden Beispiel wird Unterstützung für Controller und API-bezogene Features hinzugefügt, jedoch nicht für Ansichten oder Seiten. Die API-Vorlage verwendet diesen Code:

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

Im folgenden Beispiel wird Unterstützung für Controller, API-bezogene Features und Ansichten hinzugefügt, jedoch nicht für Seiten. Die Vorlage Webanwendung (MVC) verwendet diesen Code:

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

Im folgenden Beispiel wird Unterstützung für Razor Pages und minimale Controllerunterstützung hinzugefügt. Die Webanwendungsvorlage verwendet diesen Code:

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

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

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

Routingstartcode

Wenn eine App UseMvc oder aufruft, migrieren Sie die App nach Möglichkeit zum UseSignalR Endpunktrouting. Um die Kompatibilität des Endpunktroutings mit früheren Versionen von MVC zu verbessern, haben wir einige der Änderungen bei der URL-Generierung zurückgesetzt, die in ASP.NET Core 2.2 eingeführt wurden. Wenn bei der Verwendung des Endpunktroutings in 2.2 Probleme aufgetreten sind, erwarten Sie Verbesserungen in ASP.NET Core 3.0 mit den folgenden Ausnahmen:

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

Endpunktrouting unterstützt die gleiche Routenmustersyntax und routenmustererstellungsfeatures wie IRouter . Endpunktrouting unterstützt IRouteConstraint . Endpunktrouting unterstützt [Route] , und die anderen [HttpGet] MVC-Routingattribute.

Für die meisten Anwendungen sind nur Startup Änderungen erforderlich.

Migrieren Startup.Configure

Allgemeine Hinweise:

• Fügen Sie UseRoutinghinzu.

• Wenn die App UseStaticFiles aufruft, platzieren Sie UseStaticFiles vor UseRouting .

• Wenn die App Authentifizierungs-/Autorisierungsfunktionen wie AuthorizePage oder [Authorize] verwendet, platzieren Sie den Aufruf von UseAuthentication und : UseAuthorization nach und , aber UseRouting vor UseCors 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 wie verwendet, [EnableCors] platzieren Sie den Aufruf von vor jeder anderen UseCors Middleware, die CORS verwendet (z. B. UseCors vor , und UseAuthentication UseAuthorization UseEndpoints ).

• Ersetzen Sie durch , IHostingEnvironment und fügen Sie eine IWebHostEnvironment using -Anweisung für den Namespace Microsoft.Extensions.Hosting 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 dem Aktualisieren 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

Integritätsprüfungen verwenden das Endpunktrouting mit dem generischen Host. Rufen Sie in Startup.Configure auf der Endpunkterstellung mit der Endpunkt-URL oder dem relativen Pfad MapHealthChecks auf:

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

Für Endpunkte für Integritätsprüfungen gilt Folgendes:

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

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

Leitfaden zur Sicherheits-Middleware

Die Unterstützung für Autorisierung und CORS ist rund um den Middlewareansatz vereinheitlicht. Dies ermöglicht die Verwendung derselben Middleware und Funktionalität in diesen Szenarien. In dieser Version wird eine aktualisierte Autorisierungs-Middleware bereitgestellt, und die CORS-Middleware wird erweitert, damit sie die von MVC-Controllern verwendeten Attribute verstehen kann.

CORS

Zuvor konnte CORS schwierig zu konfigurieren sein. Middleware wurde für die Verwendung in einigen Anwendungsfällen bereitgestellt, aber MVC-Filter sollten in anderen Anwendungsfällen ohne Middleware verwendet werden. Mit ASP.NET Core 3.0 wird empfohlen, dass alle Apps, die CORS benötigen, die CORS-Middleware zusammen mit Endpunktrouting verwenden. UseCors kann mit einer Standardrichtlinie bereitgestellt [EnableCors] werden, und [DisableCors] Attribute können verwendet werden, um die Standardrichtlinie bei Bedarf zu überschreiben.

Siehe folgendes Beispiel:

• CORS ist für alle Endpunkte mit der default benannten Richtlinie 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 Autorisierungsunterstützung über das [Authorize] -Attribut bereitgestellt. Autorisierungs-Middleware war nicht verfügbar. In ASP.NET Core 3.0 ist Autorisierungs-Middleware erforderlich. Es wird empfohlen, die ASP.NET Core Authorization Middleware ( ) unmittelbar nach zu UseAuthorization UseAuthentication platzieren. Die Autorisierungs-Middleware kann auch mit einer Standardrichtlinie konfiguriert werden, die überschrieben werden kann.

In ASP.NET Core 3.0 oder höher UseAuthorization wird in aufgerufen, Startup.Configure und Folgendes erfordert einen HomeController 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 des Endpunktroutings wird empfohlen, die AuthorizeFilter Autorisierungs-Middleware nicht zu konfigurieren und stattdessen zu verwenden. Wenn die App AuthorizeFilter als globalen Filter in MVC verwendet, empfiehlt es sich, den Code umzugestalten, um eine Richtlinie im Aufruf von AddAuthorization bereitzustellen.

Der DefaultPolicy ist anfänglich so konfiguriert, dass eine Authentifizierung erforderlich ist, sodass keine zusätzliche Konfiguration erforderlich ist. Im folgenden Beispiel werden MVC-Endpunkte als RequireAuthorization markiert, sodass alle Anforderungen basierend auf autorisiert werden DefaultPolicy müssen. Der ermöglicht jedoch den Zugriff, ohne dass HomeController sich der Benutzer aufgrund von bei der App anmeldet: [AllowAnonymous]

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 Klassen von Endpunkten konfiguriert werden. Der folgende Code ist ein Beispiel für die Konvertierung einer MVC-App, die eine globale in eine App mit einer bestimmten Richtlinie konfiguriert hat, AuthorizeFilter 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. DefaultPolicyIst 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 ohne [Authorize] oder RequireAuthorization erforderlich ist, indem ein konfiguriert FallbackPolicy wird. Die FallbackPolicy unterscheidet sich von der DefaultPolicy . Wird DefaultPolicy durch [Authorize] oder RequireAuthorization ausgelöst, während ausgelöst FallbackPolicy wird, wenn keine andere Richtlinie festgelegt ist. FallbackPolicy ist anfänglich so konfiguriert, dass Anforderungen ohne Autorisierung zugelassen werden.

Das folgende Beispiel entspricht dem vorherigen DefaultPolicy Beispiel, verwendet jedoch , FallbackPolicy um immer eine Authentifizierung auf allen Endpunkten anzufordern, außer wenn [AllowAnonymous] angegeben ist:

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 Kenntnisse der Autorisierung verfügt. Integritätsprüfungen verfügen beispielsweise nicht über spezifische Kenntnisse der Autorisierung, aber für Integritätsprüfungen kann eine konfigurierbare Autorisierungsrichtlinie von der Middleware angewendet werden.

Darüber hinaus kann jeder Endpunkt seine Autorisierungsanforderungen anpassen. Im folgenden Beispiel verarbeitet die UseAuthorization Autorisierung mit , aber für den Endpunkt der DefaultPolicy /healthz Integritätsprüfung ist ein Benutzer admin erforderlich:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

Der Schutz wird für einige Szenarien implementiert. Die Endpunkt-Middleware löst eine Ausnahme aus, wenn eine Autorisierungs- oder CORS-Richtlinie aufgrund fehlender Middleware übersprungen wird. Unterstützung des Analysetools, um zusätzliches Feedback zu Fehlkonfigurationen bereitzustellen, wird ausgeführt.

Benutzerdefinierte Autorisierungshandler

Wenn die App benutzerdefinierte Autorisierungshandlerverwendet, übergibt das Endpunktrouting einen anderen Ressourcentyp an Handler als MVC. Handler, die erwarten, dass die Kontextressource des Autorisierungshandlers vom Typ AuthorizationFilterContext ist (der von MVC-Filtern bereitgestellteRessourcentyp), müssen aktualisiert werden, um Ressourcen vom Typ RouteEndpoint (den Ressourcentyp, der Autorisierungshandlern durch Endpunktrouting zur Verfügung gestellt wird) zu verarbeiten.

MVC verwendet weiterhin AuthorizationFilterContext Ressourcen. Wenn die App MVC-Autorisierungsfilter zusammen mit der Endpunktroutingautorisierung verwendet, ist es möglicherweise erforderlich, beide Arten von Ressourcen zu behandeln.

SignalR

Die Zuordnung von SignalR Hubs erfolgt jetzt innerhalb von UseEndpoints .

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

Im folgenden Beispiel wird Unterstützung für den ChatHub SignalR Hub hinzugefügt:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

Es gibt eine neue Option zum Steuern der Grenzwerte für die Nachrichtengröße von Clients. Gehen Sie beispielsweise in Startup.ConfigureServices folgendermaßen vor:

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

In ASP.NET Core 2.2 könnten Sie festlegen, TransportMaxBufferSize und dies würde die maximale Nachrichtengröße effektiv steuern. In ASP.NET Core 3.0 steuert diese Option jetzt nur die maximale Größe, bevor ein Rückdrückdruck beobachtet wird.

MVC-Controller

Die Zuordnung von Controllern erfolgt jetzt innerhalb von UseEndpoints .

Fügen Sie MapControllers hinzu, wenn die App Attributrouting verwendet. Da das Routing Unterstützung für viele Frameworks in ASP.NET Core 3.0 oder höher umfasst, ist das Hinzufügen von Controllern mit Attributrouten aktiviert.

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, um diese Methoden eindeutig anzugeben, was sie tun. Herkömmliche Routen wie MapControllerRoute / MapAreaControllerRoute / MapDefaultControllerRoute werden in der Reihenfolge angewendet, in der sie hinzugefügt werden. Platzieren Sie zuerst spezifischere Routen (z. B. Routen für einen Bereich).

Siehe folgendes Beispiel:

• MapControllers fügt Unterstützung für Controller mit Attributroute hinzu.
• MapAreaControllerRoute fügt eine herkömmliche Route für Controller in einem Bereich hinzu.
• MapControllerRoute fügt eine herkömmliche 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?}");
    });
}

Entfernen von asynchronen Suffixen aus Controlleraktionsnamen

In ASP.NET Core 3.0 entfernt ASP.NET Core MVC das Async Suffix aus Controlleraktionsnamen. Diese neue Standardeinstellung 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 kann über die Route Products/ListAsync zugegriffen werden.

• Linkgenerierung erforderlich, um das Async Suffix anzugeben. 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 ist es nicht erforderlich, das Async Suffix anzugeben. Beispiel:

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

Diese Änderung wirkt sich nicht auf Namen aus, die mit dem -Attribut angegeben [ActionName] werden. Das Standardverhalten kann mit dem folgenden Code in deaktiviert Startup.ConfigureServices werden:

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

Änderungen an der Linkgenerierung

Wie in der Dokumentation zu unterschieden von früheren Versionen des Routingserläutert, gibt es einige Unterschiede bei der Linkgenerierung Url.Link (z. B. mit und ähnlichen APIs). Dazu zählen unter anderem folgende Einstellungen:

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

Razor Pages

RazorZuordnungsseiten finden jetzt in UseEndpoints statt.

Fügen Sie MapRazorPages hinzu, wenn die App Razor Pages verwendet. Da das Endpunktrouting Unterstützung für viele Frameworks umfasst, ist das Hinzufügen von Razor Pages jetzt optional.

In der folgenden Startup.Configure Methode fügt Unterstützung für Pages MapRazorPages Razor 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 Zustimmung in Startup.ConfigureServices . Dies ist erforderlich, da MVC wissen muss, ob es sich während der Initialisierung auf die Autorisierung und CORS-Middleware verlassen kann. Ein Analyseprogramm wird bereitgestellt, das warnt, wenn die App versucht, eine nicht unterstützte Konfiguration zu verwenden.

Wenn die App IRouter Legacyunterstützung erfordert, deaktivieren Sie EnableEndpointRouting die Verwendung eines 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 Router-/Routenplanung mit Endpunktrouting verwendet werden.

Fügen Sie MapHealthChecks hinzu, um Integritätsprüfungen mit Endpunktrouting zu verwenden. Die MapHealthChecks -Methode akzeptiert Argumente ähnlich UseHealthChecks wie . Der Vorteil der Verwendung von over ist die Möglichkeit, autorisierung anzuwenden und eine bessere fein abgleichende MapHealthChecks UseHealthChecks Kontrolle über die Abgleichsrichtlinie zu erhalten.

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 generischen Host. In früheren Versionen wurde Webhost verwendet. Der folgende Code zeigt die 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 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 verbleibt in 3.0 und ist der Typ des im vorherigen webBuilder Codebeispiel. WebHostBuilder wird in einer zukünftigen Version veraltet sein und durch HostBuilder ersetzt.

Die wichtigste Änderung von in WebHostBuilder ist HostBuilder die Abhängigkeitsinjektion (Dependency Injection, DI). Wenn Sie HostBuilder verwenden, können Sie nur Folgendes in den Startup Konstruktor von einjizieren:

• IConfiguration
• IHostEnvironment
• IWebHostEnvironment

HostBuilderDi-Einschränkungen:

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

Weitere Informationen finden Sie unter Vermeiden der Einjektion des Startdiensts in ASP.NET Core 3.

AddAuthorization in eine andere Assembly verschoben

Die ASP.NET Core 2.2 und AddAuthorization niedrigeren Methoden in Microsoft.AspNetCore.Authorization.dll:

• Wurde AddAuthorizationCore umbenannt.
• Wurden in die Microsoft.AspNetCore.Authorization.Policy.dll.

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

Apps, die keine Microsoft.AspNetCore.Authorization.Policy.dll, sollten eine der folgenden Aufgaben haben:

• Fügen Sie einen Verweis auf Microsoft.AspNetCore.Authorization.Policy.dll. Dieser Ansatz funktioniert für die meisten Apps und ist alles, was erforderlich ist.
• Umschalten zur Verwendung von AddAuthorizationCore

Weitere Informationen finden Sie unter Breaking Change in ) overload lives in a different assembly AddAuthorization(o => #386.

Benutzeroberfläche von Identity

IdentityBenutzeroberflächenupdates ASP.NET Core 3.0:

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

SignalR

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

System.Text.Json ist das Standardprotokoll.

System.Text.Json ist jetzt das Standard-Hubprotokoll, das sowohl vom Client als auch vom Server verwendet wird.

Rufen Startup.ConfigureServices Sie in AddJsonProtocol auf, um Serialisierungsoptionen zu festlegen.

Server:

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

Client:

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

Wechseln Sie zu Newtonsoft.JsEin.

Wenn Sie Features von Newtonsoft.Jsverwenden, die inSystem.Text.Jsunter nicht unterstützt werden, können Sie zurück zu Newtonsoft.Json wechseln. Siehe Use Newtonsoft.Json in an ASP.NET Core 3.0 SignalR project weiter oben in diesem Artikel.

Redis Distributed Caches

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

Zur Laufzeitkompilierung verwenden

Vor ASP.NET Core 3.0 war die Laufzeitkompilierung von Sichten ein implizites Feature des Frameworks. Die Laufzeitkompilierung ergänzt die Kompilierung von Ansichten zur Buildzeit. Dadurch kann das Framework Ansichten und Seiten Razor (CSHTML-Dateien) kompilieren, wenn die Dateien geändert werden, ohne die gesamte App neu erstellen zu müssen. Dieses Feature unterstützt das Szenario, in dem eine schnelle Bearbeitung in der IDE und das Aktualisieren des Browsers zum Anzeigen der Änderungen vorgenommen wird.

In ASP.NET Core 3.0 ist die Laufzeitkompilierung ein optionales Szenario. Die Kompilierung zur Buildzeit 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 CSHTML-Dateien erkannt werden. In Visual Studio änderungen an CS-, CSHTML- oder RAZOR-Dateien im Projekt, das ausgeführt wird (STRG+F5), aber nicht debuggt (F5), lösen eine Neukompilierung des Projekts aus.

So aktivieren Sie die Laufzeitkompilierung im ASP.NET Core 3.0-Projekt:

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

2. Aktualisieren Sie Startup.ConfigureServices , um auf zu AddRazorRuntimeCompilation rufen:

   Verwenden ASP.NET Core MVC den folgenden Code:

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

   Für ASP.NET Core Razor Pages verwenden Sie den folgenden Code:

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

Das Beispiel unter zeigt ein Beispiel für die bedingte https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation Aktivierung der Laufzeitkompilierung in Entwicklungsumgebungen.

Weitere Informationen zur Razor Dateikompilierung finden Sie unter RazorDateikompilierung in ASP.NET Core .

Migrieren von Bibliotheken über zielübergreifendes Ziel

Bibliotheken müssen häufig mehrere Versionen von ASP.NET Core. Die meisten Bibliotheken, die für frühere Versionen von ASP.NET Core wurden, sollten weiterhin ohne Probleme funktionieren. Die folgenden Bedingungen erfordern, dass die App kreuz kompiliert wird:

• Die Bibliothek basiert auf einem Feature, das über eine binäre Breaking Change verfügt.
• Die Bibliothek möchte die neuen Features 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 #ifdefs Sie , ASP.NET Core 3.0-spezifische APIs 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 Validierungssystem in .NET Core 3.0 und höher behandelt Non-Nullable-Parameter oder gebundene Eigenschaften so, als würden sie ein [Required]-Attribut aufweisen. Weitere Informationen finden Sie unter [Erforderlich] Attribut.

Veröffentlichen

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

TestServer

Erstellen Sie für Apps, TestServer die direkt mit dem generischen Host verwenden, TestServer die auf einem in IWebHostBuilder 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);
}

Breaking API-Änderungen

Überprüfen von Breaking Changes:

• Vollständige Liste der Breaking Changes im release ASP.NET Core 3.0
• Breaking API-Änderungen in Antiforgery, CORS, Diagnostics, MVC und Routing. Diese Liste enthält Breaking Changes für Kompatibilitätsoptionen.
• Eine Zusammenfassung der Breaking Changes von 2.2 zu 3.0 in .NET Core, ASP.NET Core und Entity Framework Core finden Sie unter Breaking Changes für die Migration von Version 2.2 zu 3.0.

Endpunktrouting mit 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 auf Azure App Service

Das Rollout von .NET Core für Azure App Service ist abgeschlossen. .NET Core 3.0 ist in allen Azure App Service verfügbar.