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:

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

Voraussetzungen

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

Wenn Ihre Lösung auf eine globale.json-Datei basiert, um auf eine bestimmte .NET Core SDK-Version zu abzielen, aktualisieren Sie ihre version Eigenschaft auf die auf Ihrem Computer installierte 3.0-Version:

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

Aktualisieren der Projektdatei

Aktualisieren des Zielframeworks

ASP.NET Core 3.0 und höher nur auf .NET Core ausgeführt. Legen Sie den Zielframework Moniker (TFM) auf netcoreapp3.0:

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

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

</Project>

Entfernen veralteter Paketbezüge

Eine große Anzahl von NuGet Paketen wird für ASP.NET Core 3.0 nicht produziert. Solche Paketbezüge sollten aus Ihrer Projektdatei entfernt werden. Berücksichtigen 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 die TFM auf netcoreapp3.0
    • Entfernt das <AspNetCoreHostingModel> Element. Weitere Informationen finden Sie im In-Process-Hostingmodell in diesem Dokument.
  • In <ItemGroup>:

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

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

Klicken Sie, um die Liste der Pakete zu erweitern, die nicht mehr erstellt werden
  • Microsoft.AspNetCore
  • Microsoft.AspNetCore.All
  • Microsoft.AspNetCore.App
  • Microsoft.AspNetCore.Antiforgery
  • Microsoft.AspNetCore.Authentication
  • Microsoft.AspNetCore.Authentication.Abstractions
  • Microsoft.AspNetCore.Authentication.Cookie s
  • Microsoft.AspNetCore.Authentication.Core
  • Microsoft.AspNetCore.Authentication.OAuth
  • Microsoft.AspNetCore.Authorization.Policy
  • Microsoft.AspNetCore.Cookie Politik
  • Microsoft.AspNetCore.Cors
  • Microsoft.AspNetCore.Diagnostics
  • Microsoft.AspNetCore.Diagnostics.HealthChecks
  • Microsoft.AspNetCore.HostFiltering
  • Microsoft.AspNetCore.Hosting
  • Microsoft.AspNetCore.Hosting.Abstractions
  • Microsoft.AspNetCore.Hosting.Server.Abstractions
  • Microsoft.AspNetCore.Http
  • Microsoft.AspNetCore.Http.Abstractions
  • Microsoft.AspNetCore.Http.Connections
  • Microsoft.AspNetCore.Http.Extensions
  • Microsoft.AspNetCore.HttpOverrides
  • Microsoft.AspNetCore.HttpsPolicy
  • Microsoft.AspNetCore.Identity
  • Microsoft.AspNetCore.Localization
  • Microsoft.AspNetCore.Localization.Routing
  • Microsoft.AspNetCore.Mvc
  • Microsoft.AspNetCore.Mvc.Abstractions
  • Microsoft.AspNetCore.Mvc.Analyzers
  • Microsoft.AspNetCore.Mvc.ApiExplorer
  • Microsoft.AspNetCore.Mvc.Api.Analyzers
  • Microsoft.AspNetCore.Mvc.Core
  • Microsoft.AspNetCore.Mvc.Cors
  • Microsoft.AspNetCore.Mvc.DataAnnotations
  • Microsoft.AspNetCore.Mvc.Formatters.Json
  • Microsoft.AspNetCore.Mvc.Formatters.Xml
  • Microsoft.AspNetCore.Mvc.Localization
  • Microsoft.AspNetCore.Mvc.Razor
  • Microsoft.AspNetCore.Mvc.Razor. ViewCompilation
  • Microsoft.AspNetCore.Mvc.Razor Seiten
  • Microsoft.AspNetCore.Mvc.TagHelpers
  • Microsoft.AspNetCore.Mvc.ViewFeatures
  • Microsoft.AspNetCore.Razor
  • Microsoft.AspNetCore.Razor. Laufzeit
  • Microsoft.AspNetCore.Razor. Design
  • Microsoft.AspNetCore.ResponseCaching
  • Microsoft.AspNetCore.ResponseCaching.Abstractions
  • Microsoft.AspNetCore.ResponseCompression
  • Microsoft.AspNetCore.Rewrite
  • Microsoft.AspNetCore.Routing
  • Microsoft.AspNetCore.Routing.Abstractions
  • Microsoft.AspNetCore.Server.HttpSys
  • Microsoft.AspNetCore.Server.IIS
  • Microsoft.AspNetCore.Server.IISIntegration
  • Microsoft.AspNetCore.Server.Kestrel
  • Microsoft.AspNetCore.Server.Kestrel. Kern
  • Microsoft.AspNetCore.Server.Kestrel. Https
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Abstraktionen
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Sockets
  • Microsoft.AspNetCore.Session
  • Microsoft.AspNetCore.SignalR
  • Microsoft.AspNetCore.SignalR. Kern
  • Microsoft.AspNetCore.StaticFiles
  • Microsoft.AspNetCore.WebSockets
  • Microsoft.AspNetCore.WebUtilities
  • Microsoft.Net.Http.Headers

Überprüfen von Änderungsänderungen

Überprüfen von Änderungsänderungen

Frameworkreferenz

Features von ASP.NET Core, die über eine der oben aufgeführten Pakete verfügbar waren, sind im Rahmen des Microsoft.AspNetCore.App freigegebenen 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 ziel oder SDK zielenMicrosoft.NET.Sdk, sollten einem FrameworkReference expliziten Hinzufügen von Microsoft.AspNetCore.App:Microsoft.NET.Sdk.Razor

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

Framework-abhängige Builds mithilfe von Docker

Framework-abhängige Builds von Konsolen-Apps, die ein Paket verwenden, das vom ASP.NET Core freigegebenen Framework abhängt, kann 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 die ASP.NET Core-Laufzeit enthält und nur im dotnet/core/aspnet Docker-Image vorhanden ist. Das 3.0 SDK reduziert die Größe von Framework-abhängigen 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, aber es erfordert, dass die ASP.NET Core-Laufzeit vorhanden / installiert ist, um die App auszuführen.

Um festzustellen, ob die App eine Abhängigkeit (entweder direkt oder indirekt) auf dem ASP.NET Core freigegebenen Framework aufweist, überprüfen Sie die datei, die runtimeconfig.json während eines Build-/Veröffentlichungsvorgangs Ihrer App generiert wurde. Die folgende JSON-Datei zeigt eine Abhängigkeit vom ASP.NET Core freigegebenen 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 Paketbezügen für entfernte Assemblys

ASP.NET Core 3.0 entfernt einige Assemblys, die zuvor Teil des Microsoft.AspNetCore.App Paketverweis waren. Um zu visualisieren, welche Assemblys entfernt wurden, vergleichen Sie die beiden freigegebenen Frameworkordner. Beispiel: Vergleich von Versionen 2.2.7 und 3.0.0:

shared framework assemblies comparison

Um die verwendung von den entfernten Assemblys bereitgestellten Features fortzusetzen, verweisen Sie auf die 3.0-Versionen der entsprechenden Pakete:

Startänderungen

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

the deleted and changed lines in an ASP.NET Core 2.2 Razor Web app

Im vorherigen Bild wird gelöschter Code in Rot angezeigt. Der gelöschte Code zeigt cookie keinen Optionscode an, der vor dem Vergleichen der Dateien gelöscht wurde.

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

the added and changed lines in an ASP.NET Core 3.0 Razor Web app

Im vorherigen Bild wird der hinzugefügte Code in Grün angezeigt. Informationen zu den folgenden Änderungen:

Analyseunterstützung

Projekte, die Microsoft.NET.Sdk.Web implizit auf Referenzanalyses abzielen, die zuvor im Rahmen des Microsoft.AspNetCore.Mvc.Analyzers-Pakets bereitgestellt wurden. Es sind keine zusätzlichen Verweise erforderlich, um diese zu aktivieren.

Wenn Ihre App API-Analysegeräte verwendet, die zuvor über das Microsoft.AspNetCore.Mvc.Api.Analyzers-Paket gesendet wurden, bearbeiten Sie Ihre Projektdatei, um auf die im .NET Core Web SDK bereitgestellten Analysegeräte zu verweisen:

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

    ...
</Project>

Razor Klassenbibliothek

Razor Klassenbibliotheksprojekte, die UI-Komponenten für MVC bereitstellen, müssen die AddRazorSupportForMvc Eigenschaft in der Projektdatei festlegen:

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

In-Process-Hostingmodell

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

Kestrel

Konfiguration

Migrieren der Kestrel Konfiguration im Webhost-Generator (ConfigureWebHostDefaultsProgram.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 ConfigureWebHostConfigureWebHostDefaultsanstelle erstellt, rufen Sie UseKestrel den 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 Kestrelentfernt. Ersetzen Sie Verbindungsadapter durch Verbindungs-Middleware. Connection Middleware ähnelt HTTP Middleware in der ASP.NET Core Pipeline, aber für Verbindungen mit niedrigerer Ebene. HTTPS- und Verbindungsprotokollierung:

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

Weitere Informationen finden Sie im Beispiel "TlsFilterConnectionHandler" im Abschnitt "ListenOptions.Protocol" des Kestrel Artikels.

Transportabstraktionen verschoben und öffentlich gemacht

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

  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions und zugeordnete Typen wurden entfernt.
  • NoDelay wurde von ListenOptions den Transportoptionen verschoben.
  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode wurde aus KestrelServerOptionsentfernt.

Weitere Informationen finden Sie in den folgenden GitHub Ressourcen:

Kestrel Anfordern von Trailerheadern

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

  • Kestrel fügt HTTP/1.1-Block-Trailerheader in die Anforderungsheadersammlung ein.
  • Trailer sind verfügbar, nachdem der Anforderungstext am Ende gelesen wurde.

Dies verursacht einige Bedenken hinsichtlich der Unklarheit zwischen Kopfzeilen und Trailern, sodass die Trailer in eine neue Sammlung (RequestTrailerExtensions) in 3.0 verschoben wurden.

HTTP/2-Anforderungs-Trailer sind:

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

Neue Anforderungserweiterungsmethoden sind vorhanden, um auf diese Trailer zuzugreifen. Wie bei HTTP/1.1 sind Trailer verfügbar, nachdem der Anforderungstext am Ende gelesen wurde.

Für die 3.0-Version sind die folgenden RequestTrailerExtensions Methoden verfügbar:

  • GetDeclaredTrailers: Ruft den Anforderungsheader Trailer ab, der listet, welche Trailer nach dem Textkörper erwartet werden sollen.
  • 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 Trailer gelesen werden können. Möglicherweise gibt es keine Trailer, die gelesen werden sollen, auch wenn true diese Methode zurückgegeben wird.
  • GetTrailer: Ruft den angeforderten nachgestellten Header aus der Antwort ab. Überprüfen Sie SupportsTrailers vor dem Aufrufen GetTraileroder kann NotSupportedException auftreten, wenn die Anforderung keine nachgestellten Header unterstützt.

Weitere Informationen finden Sie unter Put request trailers in a separate collection (dotnet/AspNetCore #10410).

AllowSynchronousIO deaktiviert

AllowSynchronousIO aktiviert oder deaktiviert synchrone I/O-APIs, z HttpRequest.Body.Read. B. , HttpResponse.Body.Writeund Stream.Flush. Diese APIs sind eine Quelle von Thread-Starvation, die zu App-Absturzen führt. 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 AllowSynchronousIO Option auf dem verwendeten Server konfiguriert wird (zKestrel. B. beim AufrufenConfigureKestrel). Beachten Sie, dass Server (KestrelhttpSys, TestServer usw.) ihre eigene AllowSynchronousIO Option haben, die sich nicht auf andere Server auswirkt. Synchrone E/A kann für alle Server pro Anforderung mithilfe der IHttpBodyControlFeature.AllowSynchronousIO Option 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 [Ankündigung] AllowSynchronousIO deaktiviert auf allen Servern (dotnet/AspNetCore #7644).

Ausgabeformatierpufferung

Newtonsoft.Json, XmlSerializerund DataContractSerializer basierende Ausgabeformatierer unterstützen nur synchrone Serialisierung. Damit diese Formatierer mit den AllowSynchronousIO-Einschränkungen des Servers arbeiten können, puffert MVC die Ausgabe dieser Formatierer vor dem Schreiben auf den Datenträger. Als Ergebnis der Pufferung enthält MVC den Header "Inhaltslänge" bei der Reaktion auf diese Formatierer.

System.Text.Json Unterstützt asynchrone Serialisierung und folglich wird der System.Text.Json basierte Formatierer nicht puffert. Erwägen Sie, diesen Formatierer für eine verbesserte Leistung zu verwenden.

Zum Deaktivieren der Pufferung können Anwendungen in ihrem Start konfigurieren SuppressOutputFormatterBuffering :

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

Beachten Sie, dass dies dazu führen kann, dass die Anwendung eine Laufzeit ausnahme auslöst, wenn AllowSynchronousIO sie nicht auch konfiguriert ist.

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

In ASP.NET Core 2.1 ist der Inhalt von Microsoft.AspNetCore.Server.Kestrel. Https.dll wurden in Microsoft.AspNetCore.ServerKestrel verschoben. Core.dll. Dies war ein nicht unterbrechungsfreies Update mit TypeForwardedTo Attributen. Für 3.0 ist der leere Microsoft.AspNetCore.Server.Server.Kestrel Https.dll Assembly und das NuGet Paket wurden entfernt.

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

Apps und Bibliotheken, die auf ASP.NET Core 2.1 oder höher ausgerichtet sind, sollten direkte Verweise auf microsoft.AspNetCore.Server entfernenKestrel. Https-Paket.

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

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

Der standardmäßige JSON-Serializer für ASP.NET Core ist jetzt System.Text.Jsonneu in .NET Core 3.0. Erwägen Sie die Verwendung System.Text.Json , wenn möglich. Es ist eine hohe Leistung und erfordert keine zusätzliche Bibliotheksabhängigkeit. Da System.Text.Json es jedoch neu ist, fehlen 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 ASP.NET Core 3.0-Projekt SignalR

  • Installieren Sie microsoft.AspNetCore.SignalR. Protocol.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 an den 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.

  • Auf Anruf AddNewtonsoftJsonaktualisieren Startup.ConfigureServices .

    services.AddMvc()
        .AddNewtonsoftJson();
    

    AddNewtonsoftJson ist kompatibel mit den neuen MVC-Dienstregistrierungsmethoden:

    • AddRazorPages
    • AddControllersWithViews
    • AddControllers
    services.AddControllers()
        .AddNewtonsoftJson();
    

    Newtonsoft.Json Einstellungen können im Anruf AddNewtonsoftJsonauf :

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

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

Weitere Informationen finden Sie unter Add Newtonsoft.Json-basierte JSON-Formatunterstützung.

MVC-Dienstregistrierung

ASP.NET Core 3.0 fügt neue Optionen für die Registrierung von MVC-Szenarien innerhalb Startup.ConfigureServiceshinzu.

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

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

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

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

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

Im folgenden Beispiel werden Unterstützung für Razor Seiten 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 Aufrufen AddMvc in ASP.NET Core 2.2:

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

Routingstartcode

Wenn eine App aufruft UseMvc oder UseSignalR, migrieren Sie die App ggf. zu Endpunkt-Routing . Um die Endpunktweiterleitungskompatibilität mit früheren Versionen von MVC zu verbessern, haben wir einige der Änderungen an der IN ASP.NET Core 2.2 eingeführten URL-Generation zurückgesetzt. Wenn Sie Probleme mit der Verwendung von Endpoint Routing in 2.2 haben, erwarten Sie Verbesserungen in ASP.NET Core 3.0 mit den folgenden Ausnahmen:

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

Endpoint Routing unterstützt dieselbe Routingmustersyntax und Routingmustererstellungsfeatures wie IRouter. Endpunktrouting unterstützt IRouteConstraint. Endpunktrouting unterstützt [Route], [HttpGet]und die anderen MVC-Routingattribute.

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

Migrieren von Startup.Configure

Allgemeine Beratung:

  • Fügen Sie UseRoutinghinzu.

  • Wenn die App aufruft UseStaticFiles, platzieren Sie UseStaticFilesvorUseRouting.

  • Wenn die App Authentifizierungs-/Autorisierungsfeatures wie z AuthorizePage[Authorize]. B. oder , den Aufruf UseAuthentication an und UseAuthorization: nachUseRouting und , UseCorsaber vor UseEndpoints:

    public void Configure(IApplicationBuilder app)
    {
      ...
    
      app.UseStaticFiles();
    
      app.UseRouting();
      app.UseCors();
    
      app.UseAuthentication();
      app.UseAuthorization();
    
      app.UseEndpoints(endpoints => {
         endpoints.MapControllers();
      });
    
  • Ersetzen UseMvc oder UseSignalR durch UseEndpoints.

  • Wenn die App CORS-Szenarien verwendet, z[EnableCors]. B. den Aufruf UseCors vor einer anderen Middleware, die CORS verwenden (z. B. vor UseAuthorizationUseCorsUseAuthentication, und UseEndpoints).

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

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

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

Der folgende Code ist ein Beispiel Startup.Configure für eine typische 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?}");
    });
}

Warnung

Für die meisten Apps müssen Anrufe an UseAuthenticationUseAuthorization, und UseCors sie müssen zwischen den Anrufen UseRouting angezeigt und UseEndpoints wirksam sein.

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.

Anleitungen zur Sicherheits-Middleware

Unterstützung für Autorisierung und CORS ist um den Middleware-Ansatz vereinheitlicht. Dies ermöglicht die Verwendung derselben Middleware und Funktionalität in diesen Szenarien. Eine aktualisierte Autorisierungs-Middleware wird in dieser Version bereitgestellt, und CORS Middleware wird erweitert, damit sie die attribute verstehen kann, die von MVC-Controllern verwendet werden.

CORS

Zuvor konnte CORS schwierig konfiguriert werden. Middleware wurde für die Verwendung in einigen Anwendungsfällen bereitgestellt, aber MVC-Filter sollten ohne die Middleware in anderen Anwendungsfällen verwendet werden. 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 [EnableCors][DisableCors] Attribute können verwendet werden, um die Standardrichtlinie bei Bedarf außer Kraft zu setzen.

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 die Autorisierungsunterstützung über das [Authorize] Attribut bereitgestellt. Die Autorisierungs-Middleware ist nicht verfügbar. In ASP.NET Core 3.0 ist die Autorisierungs-Middleware erforderlich. Es wird empfohlen, die ASP.NET Core Autorisierungs-Middleware (UseAuthorization) unmittelbar nach der Ausführung 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 UseAuthorization wird er aufgerufenStartup.Configure, und folgendes 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 des Endpunktroutings empfehlen wir, stattdessen die Autorisierungs-Middleware zu konfigurieren AuthorizeFilter und stattdessen auf die Autorisierungs-Middleware zu vertrauen. Wenn die App einen AuthorizeFilter globalen Filter in MVC verwendet, empfehlen wir, den Code neu zu erstellen, um eine Richtlinie im Aufruf AddAuthorizationbereitzustellen.

Dies DefaultPolicy ist zunächst so konfiguriert, dass die Authentifizierung erforderlich ist, sodass keine zusätzliche Konfiguration erforderlich ist. Im folgenden Beispiel werden MVC-Endpunkte markiert, damit RequireAuthorization alle Anforderungen basierend auf dem DefaultPolicy. Der Zugriff ermöglicht jedoch, ohne dass sich der HomeController Benutzer aufgrund [AllowAnonymous]von :

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, die eine globale AuthorizeFilter App in eine App mit einer bestimmten Richtlinie konfiguriert hat, 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. Dies DefaultPolicy ist so konfiguriert, dass die 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]RequireAuthorization oder durch Konfigurieren einer FallbackPolicyAutorisierung erforderlich ist. Dies FallbackPolicy unterscheidet sich von dem DefaultPolicy. Dies DefaultPolicy wird ausgelöst durch [Authorize] oder RequireAuthorization, während dies FallbackPolicy ausgelöst wird, wenn keine andere Richtlinie festgelegt ist. FallbackPolicy wird zunächst so konfiguriert, dass Anforderungen ohne Autorisierung zulässig sind.

Das folgende Beispiel entspricht dem vorherigen DefaultPolicy Beispiel, verwendet jedoch die FallbackPolicy immer Authentifizierung für alle Endpunkte, außer wenn [AllowAnonymous] 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 bestimmte Kenntnisse über Autorisierung hat. Die Integritätsüberprüfungen verfügen beispielsweise über keine spezifische Autorisierungskenntnisse, aber Integritätsüberprüfungen können über eine konfigurierbare Autorisierungsrichtlinie verfügen, die von der Middleware angewendet wird.

Darüber hinaus kann jeder Endpunkt seine Autorisierungsanforderungen anpassen. Im folgenden Beispiel UseAuthorization verarbeitet die Autorisierung mit dem DefaultPolicy, aber der /healthz Integritätsprüfungsendpunkt erfordert einen admin Benutzer:

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. Endpunkte Middleware löst eine Ausnahme aus, wenn eine Autorisierungs- oder CORS-Richtlinie aufgrund fehlender Middleware übersprungen wird. Die Analyseunterstützung, um zusätzliches Feedback zur Falschkonfiguration bereitzustellen, ist in Bearbeitung.

Benutzerdefinierte Autorisierungshandler

Wenn die App benutzerdefinierte Autorisierungshandler verwendet, übergibt Endpunktrouting einen anderen Ressourcentyp an Handler als MVC. Handler, die erwarten, dass die Autorisierungshandlerkontextressource vom Typ AuthorizationFilterContext (der ressourcentyp, der von MVC-Filtern bereitgestellt wird) zur Behandlung von Ressourcen RouteEndpoint des Typs aktualisiert werden muss (der Ressourcentyp, der den Autorisierungshandlern durch Endpunktrouting zugewiesen wurde).

MVC verwendet weiterhin Ressourcen, sodass die App MVC-Autorisierungsfilter zusammen mit der Endpunktweiterleitungsberechtigung verwendet AuthorizationFilterContext , kann es erforderlich sein, beide Arten von Ressourcen zu behandeln.

SignalR

Die Zuordnung von SignalR Hubs erfolgt jetzt innerhalb UseEndpoints.

Zuordnen jedes Hubs mit MapHub. Wie in früheren Versionen wird jeder Hub explizit aufgeführt.

Im folgenden Beispiel wird die 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önnten Sie die TransportMaxBufferSize maximale Nachrichtengröße effektiv steuern. In ASP.NET Core 3.0 steuert diese Option jetzt nur die maximale Größe, bevor die Rückpressung beobachtet wird.

MVC-Controller

Die Zuordnung von Controllern erfolgt jetzt innerhalb UseEndpoints.

Fügen Sie hinzu MapControllers , wenn die App Attributrouting verwendet. Da Routing unterstützung für viele Frameworks in ASP.NET Core 3.0 oder höher enthält, ist das Hinzufügen von Attributroutencontrollern opt-in.

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 klar anzugeben, was sie tun. Herkömmliche Routen wie zMapControllerRoute//MapAreaControllerRouteMapDefaultControllerRoute. B. 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 Attributroutencontroller 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 Async-Suffixen aus Controlleraktionsnamen

In ASP.NET Core 3.0 entfernt ASP.NET Core MVC das Async Suffix aus Controlleraktionsnamen. Sowohl Routing als auch Linkgenerierung sind von dieser neuen Standardeinstellung betroffen. 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 könnte auf die Route "Products/ListAsync " zugegriffen werden.

  • Die Verknüpfungsgenerierung ist 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 auf die Route "Produkte/Listen " zugegriffen werden.

  • Die Linkgenerierung erfordert keine Angabe des Async Suffixs. Beispiel:

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

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

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

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

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

Razor Pages

Die Zuordnungsseiten Razor werden jetzt innerhalb von UseEndpoints.

Fügen Sie hinzu MapRazorPages , wenn die App Seiten verwendet Razor . Da Endpoint Routing Unterstützung für viele Frameworks enthält, ist das Hinzufügen von Razor Seiten jetzt opt-in.

Fügt in der folgenden Startup.Configure Methode MapRazorPages Unterstützung für Razor Pages 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 Anmeldung innerhalb Startup.ConfigureServicesvon . Dies ist erforderlich, da MVC wissen muss, ob sie sich bei der Initialisierung auf die Autorisierung und CORS Middleware verlassen kann. Eine Analyse wird bereitgestellt, die warnt, wenn die App versucht, eine nicht unterstützte Konfiguration zu verwenden.

Wenn die App Legacyunterstützung IRouter erfordert, deaktivieren Sie EnableEndpointRouting die Verwendung einer 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 Routerware mit Endpunkt-Routing verwendet werden.

Fügen Sie MapHealthChecks hinzu, um Integritätsprüfungen mit Endpunkt-Routing zu verwenden. Die MapHealthChecks Methode akzeptiert Argumente ähnlich wie UseHealthChecks. Der Vorteil der Verwendung MapHealthChecks von Over UseHealthChecks ist die Möglichkeit, die Autorisierung anzuwenden und eine bessere feinkörnige Kontrolle über die übereinstimmende Richtlinie zu haben.

Im folgenden Beispiel MapHealthChecks wird für einen Integritätsprüfungsendpunkt /healthzunter :

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 generischen Host. Frühere Versionen haben den Webhost verwendet. Der folgende Code zeigt die generierte Program ASP.NET Core 3.0-Vorlage:

// 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 bleibt in 3.0 und ist der Typ des webBuilder im vorherigen Codebeispiel angezeigten Codes. WebHostBuilder wird in einer zukünftigen Version veraltet sein und durch HostBuilder.

Die wichtigste Änderung von WebHostBuilder zu einer HostBuilderAbhängigkeitsinjektion (DI) ist. Bei Verwendung können Sie folgendes nur in Startupden Konstruktor einfügenHostBuilder:

Die HostBuilder DI-Einschränkungen:

  • Aktivieren Sie den DI-Container nur einmal.
  • Vermeiden Sie die resultierenden Objektlebensdauerprobleme, z. B. das Beheben mehrerer Instanzen von Singletons.

Weitere Informationen finden Sie unter Vermeiden der Einfügung des Startdiensts in ASP.NET Core 3.

Hinzufügen von Authentifizierung in eine andere Assembly

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

  • Wurde umbenannt AddAuthorizationCore.
  • Wurden in Microsoft.AspNetCore.Authorization.Policy.dllverschoben.

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

Apps, die Microsoft.AspNetCore.Authorization.Policy.dll nicht verwenden, sollten eine der folgenden Aktionen ausführen:

  • Hinzufügen eines Verweises auf Microsoft.AspNetCore.Authorization.Policy.dll. Dieser Ansatz funktioniert für die meisten Apps und ist alles, was erforderlich ist.
  • Wechseln zur Verwendung AddAuthorizationCore

Weitere Informationen finden Sie unter "Unterbrechung der Änderung der AddAuthorization(o =>Überladung" in einer anderen Assembly #386.

Benutzeroberfläche von Identity

IdentityUi-Updates für ASP.NET Core 3.0:

  • Fügen Sie einen Paketverweis zu Microsoft.AspNetCore hinzuIdentity. UI.
  • Apps, die keine Seiten verwenden Razor , müssen aufrufen MapRazorPages. Siehe Razor Seiten in diesem Dokument.
  • Bootstrap 4 ist das Standard-UI-Framework. 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 hat sich von "in @aspnet/signalr@microsoft/signalr" geändert. Um auf diese Änderung zu reagieren, ändern Sie die Verweise in package.json Dateien, require Anweisungen und ECMAScript-Anweisungen import .

System.Text.Json ist das Standardprotokoll

System.Text.Json ist jetzt das Standardmäßige Hub-Protokoll, das sowohl vom Client als auch vom Server verwendet wird.

Rufen Sie in Startup.ConfigureServices, um AddJsonProtocol Serialisierungsoptionen festzulegen.

Server:

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

Client:

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 zurück zu Newtonsoft.Json. Siehe "Newtonsoft.Json" in einem ASP.NET Core 3.0-Projekt SignalR weiter oben in diesem Artikel.

Redis verteilte Caches

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

Zur Laufzeitkompilierung anmelden

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, Ansichten und Seiten (.cshtml Dateien) zu kompilierenRazor, wenn die Dateien geändert werden, ohne die gesamte App neu erstellen zu müssen. Dieses Feature unterstützt das Szenario, eine schnelle Bearbeitung in der IDE vorzunehmen und den Browser zu aktualisieren, um die Änderungen anzuzeigen.

In ASP.NET Core 3.0 ist die Laufzeitkompilierung ein Opt-In-Szenario. Die Buildzeitkompilierung ist der einzige Mechanismus für die Ansichtskompilierung, die standardmäßig aktiviert ist. Die Laufzeit 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 lösen Änderungen an .cs, .cshtmloder .razor Dateien im ausgeführten Projekt (STRG+F5), aber nicht debuggen (F5) die Neukompilierung des Projekts aus.

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

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

  2. Auf Anruf AddRazorRuntimeCompilationaktualisierenStartup.ConfigureServices:

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

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

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

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

Das Beispiel zeigt https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation ein Beispiel zum bedingten Aktivieren der Laufzeitkompilierung in Entwicklungsumgebungen.

Weitere Informationen zur RazorDateikompilierung finden Sie unterRazor dateikompilierung in ASP.NET Core.

Migrieren von Bibliotheken über Multi-Targeting

Bibliotheken müssen häufig mehrere Versionen von ASP.NET Core unterstützen. Die meisten Bibliotheken, die mit früheren Versionen von ASP.NET Core kompiliert wurden, sollten ohne Probleme weiterhin funktionieren. Die folgenden Bedingungen erfordern, dass die App kompiliert werden muss:

  • Die Bibliothek basiert auf einem Feature, das eine binäre Änderung aufweist.
  • Die Bibliothek möchte neue 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>

Wird verwendet#ifdefs, um ASP.NET Core 3.0-spezifischen 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 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 [Required]-Attribut.

Veröffentlichen

Löschen Sie die Ordner "Bin " und "obj " im Projektverzeichnis.

TestServer

Erstellen Sie für Apps, die direkt mit dem generischen Host verwendet werdenTestServer, die TestServer in :IWebHostBuilderConfigureWebHost

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

Unterbrechung von API-Änderungen

Überprüfen Sie unterbrechungsgebrochene Änderungen:

Endpunktrouting mit catch-all-Parameter

Warnung

Ein catch-all-Parameter kann aufgrund eines Fehlers beim Routing nicht ordnungsgemäß mit Routen übereinstimmen. Apps, die von diesem Fehler betroffen sind, weisen die folgenden Merkmale auf:

  • Eine catch-all-Route, zum Beispiel {**slug}"
  • Die catch-all-Route kann nicht mit Anforderungen abgeglichen werden, die abgeglichen werden sollen.
  • Durch das Entfernen anderer Routen funktioniert die catch-all-Route.

Weitere Beispiele zu diesem Fehler finden Sie in den GitHub-Issues 18677 und 16579.

Eine Opt-in-Behebung für diesen Fehler ist im .NET Core 3.1.301 SDK und höher enthalten. Der folgende Code legt einen internen Switch fest, mit dem dieser Fehler behoben wird:

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

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