Migruj z ASP.NET Core 2,2 do 3,0Migrate from ASP.NET Core 2.2 to 3.0

Przez Scott Addie i Rick AndersonBy Scott Addie and Rick Anderson

W tym artykule wyjaśniono, jak zaktualizować istniejący projekt ASP.NET Core 2,2 do ASP.NET Core 3,0.This article explains how to update an existing ASP.NET Core 2.2 project to ASP.NET Core 3.0. Warto utworzyć nowy projekt ASP.NET Core 3,0, aby:It might be helpful to create a new ASP.NET Core 3.0 project to:

  • Porównaj z kodem ASP.NET Core 2,2.Compare with the ASP.NET Core 2.2 code.
  • Skopiuj odpowiednie zmiany do projektu ASP.NET Core 3,0.Copy the relevant changes to your ASP.NET Core 3.0 project.

Wymagania wstępnePrerequisites

Aktualizacja zestaw .NET Core SDK wersji w global.jsnaUpdate .NET Core SDK version in global.json

Jeśli rozwiązanie jest oparte na global.jsw pliku przeznaczonym dla konkretnej wersji zestaw .NET Core SDK, zaktualizuj jej version właściwość do wersji 3,0 zainstalowanej na maszynie:If your solution relies upon a global.json file to target a specific .NET Core SDK version, update its version property to the 3.0 version installed on your machine:

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

Zaktualizuj plik projektuUpdate the project file

Aktualizowanie platformy docelowejUpdate the Target Framework

ASP.NET Core 3,0 i nowsze są uruchamiane tylko na platformie .NET Core.ASP.NET Core 3.0 and later only run on .NET Core. Ustaw moniker platformy docelowej (TFM) na netcoreapp3.0 :Set the Target Framework Moniker (TFM) to netcoreapp3.0:

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

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

</Project>

Usuń przestarzałe odwołania do pakietuRemove obsolete package references

Wiele pakietów NuGet nie jest produkowanych dla ASP.NET Core 3,0.A large number of NuGet packages aren't produced for ASP.NET Core 3.0. Takie odwołania do pakietów powinny zostać usunięte z pliku projektu.Such package references should be removed from your project file. Rozważmy następujący plik projektu dla aplikacji internetowej ASP.NET Core 2,2:Consider the following project file for an 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>

Zaktualizowany plik projektu dla ASP.NET Core 3,0:The updated project file for ASP.NET Core 3.0:

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

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

</Project>

Zaktualizowany plik projektu ASP.NET Core 3,0:The updated ASP.NET Core 3.0 project file:

  • W <PropertyGroup> :In the <PropertyGroup>:

    • Aktualizuje TFM do netcoreapp3.0Updates the TFM to netcoreapp3.0
    • Usuwa <AspNetCoreHostingModel> element.Removes the <AspNetCoreHostingModel> element. Aby uzyskać więcej informacji, zobacz model hostingu w procesie w tym dokumencie.For more information, see In-process hosting model in this document.
  • W <ItemGroup> :In the <ItemGroup>:

    • Microsoft.AspNetCore.App jest usuwany.Microsoft.AspNetCore.App is removed. Aby uzyskać więcej informacji, zobacz temat Informacje o strukturze w tym dokumencie.For more information, see Framework reference in this document.
    • Microsoft.AspNetCore.Razor.Design zostaje usunięty i na poniższej liście pakietów nie jest już generowany.Microsoft.AspNetCore.Razor.Design is removed and in the following list of packages no longer being produced.

Aby wyświetlić pełną listę pakietów, które nie są już generowane, wybierz następującą listę rozwijaną:To see the full list of packages that are no longer produced, select the following expand list:

Kliknij, aby rozwinąć listę pakietów, które nie są już generowaneClick to expand the list of packages no longer being produced
  • Microsoft. AspNetCoreMicrosoft.AspNetCore
  • Microsoft. AspNetCore. AllMicrosoft.AspNetCore.All
  • Microsoft. AspNetCore. AppMicrosoft.AspNetCore.App
  • Microsoft.AspNetCore.AntiforgeryMicrosoft.AspNetCore.Antiforgery
  • Microsoft.AspNetCore.AuthenticationMicrosoft.AspNetCore.Authentication
  • Microsoft.AspNetCore.Authentication.AbstractionsMicrosoft.AspNetCore.Authentication.Abstractions
  • Microsoft. AspNetCore. Authentication. Cookie woluminMicrosoft.AspNetCore.Authentication.Cookies
  • Microsoft.AspNetCore.Authentication.CoreMicrosoft.AspNetCore.Authentication.Core
  • Microsoft.AspNetCore.Authentication.OAuthMicrosoft.AspNetCore.Authentication.OAuth
  • Microsoft.AspNetCore.Authorization.PolicyMicrosoft.AspNetCore.Authorization.Policy
  • Microsoft. AspNetCore. Cookie ZasadMicrosoft.AspNetCore.CookiePolicy
  • Microsoft.AspNetCore.CorsMicrosoft.AspNetCore.Cors
  • Microsoft.AspNetCore.DiagnosticsMicrosoft.AspNetCore.Diagnostics
  • Microsoft.AspNetCore.Diagnostics.HealthChecksMicrosoft.AspNetCore.Diagnostics.HealthChecks
  • Microsoft. AspNetCore. HostFilteringMicrosoft.AspNetCore.HostFiltering
  • Microsoft. AspNetCore. hostingMicrosoft.AspNetCore.Hosting
  • Microsoft.AspNetCore.Hosting.AbstractionsMicrosoft.AspNetCore.Hosting.Abstractions
  • Microsoft.AspNetCore.Hosting.Server.AbstractionsMicrosoft.AspNetCore.Hosting.Server.Abstractions
  • Microsoft.AspNetCore.HttpMicrosoft.AspNetCore.Http
  • Microsoft.AspNetCore.Http.AbstractionsMicrosoft.AspNetCore.Http.Abstractions
  • Microsoft.AspNetCore.Http.ConnectionsMicrosoft.AspNetCore.Http.Connections
  • Microsoft.AspNetCore.Http.ExtensionsMicrosoft.AspNetCore.Http.Extensions
  • Microsoft.AspNetCore.HttpOverridesMicrosoft.AspNetCore.HttpOverrides
  • Microsoft.AspNetCore.HttpsPolicyMicrosoft.AspNetCore.HttpsPolicy
  • Microsoft. AspNetCore.IdentityMicrosoft.AspNetCore.Identity
  • Microsoft.AspNetCore.LocalizationMicrosoft.AspNetCore.Localization
  • Microsoft.AspNetCore.Localization.RoutingMicrosoft.AspNetCore.Localization.Routing
  • Microsoft. AspNetCore. MVCMicrosoft.AspNetCore.Mvc
  • Microsoft.AspNetCore.Mvc.AbstractionsMicrosoft.AspNetCore.Mvc.Abstractions
  • Microsoft.AspNetCore.Mvc.AnalyzersMicrosoft.AspNetCore.Mvc.Analyzers
  • Microsoft.AspNetCore.Mvc.ApiExplorerMicrosoft.AspNetCore.Mvc.ApiExplorer
  • Microsoft.AspNetCore.Mvc.Api.AnalyzersMicrosoft.AspNetCore.Mvc.Api.Analyzers
  • Microsoft.AspNetCore.Mvc.CoreMicrosoft.AspNetCore.Mvc.Core
  • Microsoft.AspNetCore.Mvc.CorsMicrosoft.AspNetCore.Mvc.Cors
  • Microsoft.AspNetCore.Mvc.DataAnnotationsMicrosoft.AspNetCore.Mvc.DataAnnotations
  • Microsoft.AspNetCore.Mvc.Formatters.JsonMicrosoft.AspNetCore.Mvc.Formatters.Json
  • Microsoft.AspNetCore.Mvc.Formatters.XmlMicrosoft.AspNetCore.Mvc.Formatters.Xml
  • Microsoft.AspNetCore.Mvc.LocalizationMicrosoft.AspNetCore.Mvc.Localization
  • Microsoft. AspNetCore. MVC.RazorMicrosoft.AspNetCore.Mvc.Razor
  • Microsoft. AspNetCore. MVC. Razor .. ViewCompilationMicrosoft.AspNetCore.Mvc.Razor.ViewCompilation
  • Microsoft. AspNetCore. MVC. Razor PageMicrosoft.AspNetCore.Mvc.RazorPages
  • Microsoft.AspNetCore.Mvc.TagHelpersMicrosoft.AspNetCore.Mvc.TagHelpers
  • Microsoft.AspNetCore.Mvc.ViewFeaturesMicrosoft.AspNetCore.Mvc.ViewFeatures
  • Microsoft. AspNetCore.RazorMicrosoft.AspNetCore.Razor
  • Microsoft. AspNetCore. Razor . Środowiska uruchomieniowegoMicrosoft.AspNetCore.Razor.Runtime
  • Microsoft. AspNetCore. Razor . ZdefiniowanychMicrosoft.AspNetCore.Razor.Design
  • Microsoft.AspNetCore.ResponseCachingMicrosoft.AspNetCore.ResponseCaching
  • Microsoft.AspNetCore.ResponseCaching.AbstractionsMicrosoft.AspNetCore.ResponseCaching.Abstractions
  • Microsoft.AspNetCore.ResponseCompressionMicrosoft.AspNetCore.ResponseCompression
  • Microsoft.AspNetCore.RewriteMicrosoft.AspNetCore.Rewrite
  • Microsoft. AspNetCore. RoutingMicrosoft.AspNetCore.Routing
  • Microsoft.AspNetCore.Routing.AbstractionsMicrosoft.AspNetCore.Routing.Abstractions
  • Microsoft.AspNetCore.Server.HttpSysMicrosoft.AspNetCore.Server.HttpSys
  • Microsoft.AspNetCore.Server.IISMicrosoft.AspNetCore.Server.IIS
  • Microsoft.AspNetCore.Server.IISIntegrationMicrosoft.AspNetCore.Server.IISIntegration
  • Microsoft.AspNetCore.Server.KestrelMicrosoft.AspNetCore.Server.Kestrel
  • Microsoft.AspNetCore.Server.Kestrel.CoreMicrosoft.AspNetCore.Server.Kestrel.Core
  • Microsoft.AspNetCore.Server.Kestrel.HttpsMicrosoft.AspNetCore.Server.Kestrel.Https
  • Microsoft.AspNetCore.Server.Kestrel.Transport.AbstractionsMicrosoft.AspNetCore.Server.Kestrel.Transport.Abstractions
  • Microsoft.AspNetCore.Server.Kestrel.Transport.SocketsMicrosoft.AspNetCore.Server.Kestrel.Transport.Sockets
  • Microsoft.AspNetCore.SessionMicrosoft.AspNetCore.Session
  • Microsoft. AspNetCore.SignalRMicrosoft.AspNetCore.SignalR
  • Microsoft. AspNetCore. SignalR . ProcesorMicrosoft.AspNetCore.SignalR.Core
  • Microsoft. AspNetCore. StaticFilesMicrosoft.AspNetCore.StaticFiles
  • Microsoft.AspNetCore.WebSocketsMicrosoft.AspNetCore.WebSockets
  • Microsoft.AspNetCore.WebUtilitiesMicrosoft.AspNetCore.WebUtilities
  • Microsoft.Net.Http.Headers Microsoft.Net.Http.Headers

Przejrzyj istotne zmianyReview breaking changes

Przejrzyj istotne zmianyReview breaking changes

Dokumentacja strukturyFramework reference

Funkcje ASP.NET Core, które były dostępne za pomocą jednego z wymienionych powyżej pakietów, są dostępne w Microsoft.AspNetCore.App ramach udostępnionej struktury.Features of ASP.NET Core that were available through one of the packages listed above are available as part of the Microsoft.AspNetCore.App shared framework. Platforma udostępniona to zestaw zestawów (plików dll ), które są zainstalowane na komputerze i zawiera składnik środowiska uruchomieniowego oraz pakiet docelowy.The shared framework is the set of assemblies ( .dll files) that are installed on the machine and includes a runtime component and a targeting pack. Aby uzyskać więcej informacji, zobacz udostępnioną strukturę.For more information, see The shared framework.

  • Projekty przeznaczone dla Microsoft.NET.Sdk.Web zestawu SDK niejawnie odwołują się do Microsoft.AspNetCore.App struktury.Projects that target the Microsoft.NET.Sdk.Web SDK implicitly reference the Microsoft.AspNetCore.App framework.

    Dla tych projektów nie są wymagane żadne dodatkowe odwołania:No additional references are required for these projects:

    <Project Sdk="Microsoft.NET.Sdk.Web">
      <PropertyGroup>
        <TargetFramework>netcoreapp3.0</TargetFramework>
      </PropertyGroup>
        ...
    </Project>
    
  • Projekty przeznaczone dla obiektów docelowych Microsoft.NET.Sdk lub Microsoft.NET.Sdk.Razor SDK powinny dodawać jawne FrameworkReference do Microsoft.AspNetCore.App :Projects that target Microsoft.NET.Sdk or Microsoft.NET.Sdk.Razor SDK, should add an explicit FrameworkReference to Microsoft.AspNetCore.App:

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

Kompilacje zależne od platformy przy użyciu platformy DockerFramework-dependent builds using Docker

Kompilacje zależne od platformy, które korzystają z pakietu, który jest zależny od ASP.NET Core udostępnionej platformy mogą spowodować następujący błąd w czasie wykonywania:Framework-dependent builds of console apps that use a package that depends on the ASP.NET Core shared framework may give the following runtime error:

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

Microsoft.AspNetCore.App jest strukturą udostępnioną zawierającą środowisko uruchomieniowe ASP.NET Core i jest obecna tylko w obrazie platformy Docker/ rdzeń/ASPNET .Microsoft.AspNetCore.App is the shared framework containing the ASP.NET Core runtime and is only present on the dotnet/core/aspnet Docker image. Zestaw 3,0 SDK zmniejsza rozmiar kompilacji zależnych od platformy przy użyciu ASP.NET Core, bez uwzględniania zduplikowanych kopii bibliotek, które są dostępne w środowisku współdzielonym.The 3.0 SDK reduces the size of framework-dependent builds using ASP.NET Core by not including duplicate copies of libraries that are available in the shared framework. Jest to potencjalne oszczędności do 18 MB, ale wymaga, aby środowisko uruchomieniowe ASP.NET Core było obecne/zainstalowane w celu uruchomienia aplikacji.This is a potential savings of up to 18 MB, but it requires that the ASP.NET Core runtime be present / installed to run the app.

Aby określić, czy aplikacja ma zależność (bezpośredni lub pośredni) w ASP.NET Core udostępnionej platformie, sprawdź runtimeconfig.js pliku wygenerowanego podczas kompilowania/publikowania aplikacji.To determine if the app has a dependency (either direct or indirect) on the ASP.NET Core shared framework, examine the runtimeconfig.json file generated during a build/publish of your app. Poniższy plik JSON przedstawia zależność od ASP.NET Core udostępnionej platformy:The following JSON file shows a dependency on the ASP.NET Core shared framework:

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

Jeśli aplikacja korzysta z platformy Docker, Użyj obrazu podstawowego zawierającego ASP.NET Core 3,0.If your app is using Docker, use a base image that includes ASP.NET Core 3.0. Na przykład docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.For example, docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.

Dodaj odwołania do pakietu dla usuniętych zestawówAdd package references for removed assemblies

ASP.NET Core 3,0 usuwa niektóre zestawy, które były wcześniej częścią Microsoft.AspNetCore.App odwołania do pakietu.ASP.NET Core 3.0 removes some assemblies that were previously part of the Microsoft.AspNetCore.App package reference. Aby wizualizować, które zestawy zostały usunięte, Porównaj te dwa udostępnione foldery struktury.To visualize which assemblies were removed, compare the two shared framework folders. Na przykład porównanie wersji 2.2.7 i 3.0.0:For example, a comparison of versions 2.2.7 and 3.0.0:

Porównanie zestawów wspólnych struktur

Aby nadal korzystać z funkcji dostarczonych przez usunięte zestawy, należy odwołać się do 3,0 wersji odpowiednich pakietów:To continue using features provided by the removed assemblies, reference the 3.0 versions of the corresponding packages:

Zmiany uruchamianiaStartup changes

Na poniższej ilustracji przedstawiono usunięte i zmienione wiersze w Razor aplikacji sieci Web ASP.NET Core 2,2:The following image shows the deleted and changed lines in an ASP.NET Core 2.2 Razor Pages Web app:

usunięte i zmienione wiersze w ASP.NET Core 2,2::: No-Loc (Razor)::: Web App

Na powyższym obrazie usunięty kod jest wyświetlany na czerwono.In the preceding image, deleted code is shown in red. Usunięty kod nie pokazuje cookie kodu opcji, który został usunięty przed porównaniem plików.The deleted code doesn't show cookie options code, which was deleted prior to comparing the files.

Na poniższej ilustracji przedstawiono dodane i zmienione wiersze w Razor aplikacji sieci Web ASP.NET Core 3,0:The following image shows the added and changed lines in an ASP.NET Core 3.0 Razor Pages Web app:

dodane i zmienione wiersze w ASP.NET Core 3,0::: No-Loc (Razor)::: Web App

Na powyższym obrazie dodany kod jest wyświetlany w kolorze zielonym.In the preceding image, added code is shown in green. Aby uzyskać informacje na temat następujących zmian:For information on the following changes:

Obsługa analizatoraAnalyzer support

Projekty, które są przeznaczone dla niejawnie przywoływanych Microsoft.NET.Sdk.Web analizatorów odwołań, które zostały wcześniej wysłane jako część pakietu Microsoft. AspNetCore. MVC. analizatory .Projects that target Microsoft.NET.Sdk.Web implicitly reference analyzers previously shipped as part of the Microsoft.AspNetCore.Mvc.Analyzers package. Nie są wymagane żadne dodatkowe odwołania, aby je włączyć.No additional references are required to enable these.

Jeśli Twoja aplikacja używa analizatorów interfejsów API , które zostały wcześniej dostarczone przy użyciu pakietu Microsoft. AspNetCore. MVC. API. analizatory , edytuj plik projektu, aby odwoływać się do analizatorów dostarczonych w ramach zestawu SDK sieci Web platformy .NET Core:If your app uses API analyzers previously shipped using the Microsoft.AspNetCore.Mvc.Api.Analyzers package, edit your project file to reference the analyzers shipped as part of the .NET Core Web SDK:

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

    ...
</Project>

Razor Biblioteka klasRazor Class Library

Razor Projekty biblioteki klas, które zapewniają składniki interfejsu użytkownika dla MVC, muszą ustawić AddRazorSupportForMvc Właściwość w pliku projektu:Razor Class Library projects that provide UI components for MVC must set the AddRazorSupportForMvc property in the project file:

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

Model hostingu w procesieIn-process hosting model

Projekty są domyślne dla modelu hostingu w procesie w ASP.NET Core 3,0 lub nowszym.Projects default to the in-process hosting model in ASP.NET Core 3.0 or later. Opcjonalnie można usunąć <AspNetCoreHostingModel> Właściwość w pliku projektu, jeśli jej wartość jest InProcess .You may optionally remove the <AspNetCoreHostingModel> property in the project file if its value is InProcess.

KestrelKestrel

KonfiguracjaConfiguration

Migruj konfigurację Kestrel do konstruktora hosta sieci Web dostarczonego przez program ConfigureWebHostDefaults ( program.cs ):Migrate Kestrel configuration to the web host builder provided by ConfigureWebHostDefaults ( 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>();
        });

Jeśli aplikacja tworzy hosta ręcznie przy użyciu programu HostBuilder , należy wywołać UseKestrel konstruktora hosta sieci Web w ConfigureWebHostDefaults :If the app creates the host manually with HostBuilder, call UseKestrel on the web host builder in ConfigureWebHostDefaults:

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

    host.Run();
}

Oprogramowanie pośredniczące połączenia zastępuje karty połączeńConnection Middleware replaces Connection Adapters

Adaptery połączeń ( Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter ) zostały usunięte z Kestrel.Connection Adapters (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) have been removed from Kestrel. Zamień karty połączeń na oprogramowanie pośredniczące połączenia.Replace Connection Adapters with Connection Middleware. Oprogramowanie pośredniczące połączenia jest podobne do oprogramowania pośredniczącego HTTP w potoku ASP.NET Core, ale dla połączeń niższego poziomu.Connection Middleware is similar to HTTP Middleware in the ASP.NET Core pipeline but for lower-level connections. Rejestrowanie protokołu HTTPS i połączeń:HTTPS and connection logging:

  • Zostały przeniesione z kart połączeń do oprogramowania pośredniczącego połączenia.Have been moved from Connection Adapters to Connection Middleware.
  • Te metody rozszerzające działają tak jak w poprzednich wersjach ASP.NET Core.These extension methods work as in previous versions of ASP.NET Core.

Aby uzyskać więcej informacji, zobacz przykład TlsFilterConnectionHandler w sekcji ListenOptions. Protocols artykułu Kestrel.For more information, see the TlsFilterConnectionHandler example in the ListenOptions.Protocols section of the Kestrel article.

Abstrakcje transportu przenoszone i udostępniane publicznieTransport abstractions moved and made public

Warstwa transportu Kestrel została udostępniona jako interfejs publiczny w programie Connections.Abstractions .The Kestrel transport layer has been exposed as a public interface in Connections.Abstractions. W ramach tych aktualizacji:As part of these updates:

  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions i skojarzone typy zostały usunięte.Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions and associated types have been removed.
  • NoDelay został przeniesiony z ListenOptions do opcji transportu.NoDelay was moved from ListenOptions to the transport options.
  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode został usunięty z KestrelServerOptions .Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode was removed from KestrelServerOptions.

Aby uzyskać więcej informacji, zobacz następujące zasoby w witrynie GitHub:For more information, see the following GitHub resources:

Nagłówki naczepy żądania KestrelKestrel Request trailer headers

Dla aplikacji przeznaczonych dla wcześniejszych wersji ASP.NET Core:For apps that target earlier versions of ASP.NET Core:

  • Kestrel dodaje nagłówki przegałęzień protokołu HTTP/1.1 do kolekcji nagłówków żądań.Kestrel adds HTTP/1.1 chunked trailer headers into the request headers collection.
  • Przyczepy są dostępne po odczytaniu treści żądania na końcu.Trailers are available after the request body is read to the end.

Powoduje to pewne wątpliwości dotyczące niejednoznaczności między nagłówkami i przyczepami, dlatego przyczepy zostały przeniesione do nowej kolekcji ( RequestTrailerExtensions ) w 3,0.This causes some concerns about ambiguity between headers and trailers, so the trailers have been moved to a new collection (RequestTrailerExtensions) in 3.0.

Żądania protokołu HTTP/2 są następujące:HTTP/2 request trailers are:

  • Niedostępne w ASP.NET Core 2,2.Not available in ASP.NET Core 2.2.
  • Dostępne w 3,0 jako RequestTrailerExtensions .Available in 3.0 as RequestTrailerExtensions.

Nowe metody rozszerzenia żądania są obecne w celu uzyskania dostępu do tych przyczep.New request extension methods are present to access these trailers. Podobnie jak w przypadku protokołu HTTP/1.1, przyczepy są dostępne po odczytaniu treści żądania na końcu.As with HTTP/1.1, trailers are available after the request body is read to the end.

W przypadku wersji 3,0 RequestTrailerExtensions dostępne są następujące metody:For the 3.0 release, the following RequestTrailerExtensions methods are available:

  • GetDeclaredTrailers: Pobiera nagłówek żądania Trailer , który zawiera listę przyczep, które mają być oczekiwane po treści.GetDeclaredTrailers: Gets the request Trailer header that lists which trailers to expect after the body.
  • SupportsTrailers: Wskazuje, czy żądanie obsługuje nagłówki przyczepy.SupportsTrailers: Indicates if the request supports receiving trailer headers.
  • CheckTrailersAvailable: Sprawdza, czy żądanie obsługuje przyczepy i czy są dostępne do odczytu.CheckTrailersAvailable: Checks if the request supports trailers and if they're available to be read. To sprawdzenie nie zakłada, że istnieją przyczepy do odczytu.This check doesn't assume that there are trailers to read. Być może nie ma żadnych przyczep do odczytania true , nawet jeśli jest zwracany przez tę metodę.There might be no trailers to read even if true is returned by this method.
  • GetTrailer: Pobiera żądany końcowy nagłówek z odpowiedzi.GetTrailer: Gets the requested trailing header from the response. Sprawdź SupportsTrailers przed wywołaniem GetTrailer lub NotSupportedException może wystąpić, jeśli żądanie nie obsługuje końcowych nagłówków.Check SupportsTrailers before calling GetTrailer, or a NotSupportedException may occur if the request doesn't support trailing headers.

Aby uzyskać więcej informacji, zobacz Put Zażądaj przyczep w osobnej kolekcji (#10410 dotnet/AspNetCore).For more information, see Put request trailers in a separate collection (dotnet/AspNetCore #10410).

AllowSynchronousIO wyłączoneAllowSynchronousIO disabled

AllowSynchronousIO Włącza lub wyłącza synchroniczne interfejsy operacji we/wy, takie jak HttpRequest.Body.Read , HttpResponse.Body.Write i Stream.Flush .AllowSynchronousIO enables or disables synchronous I/O APIs, such as HttpRequest.Body.Read, HttpResponse.Body.Write, and Stream.Flush. Te interfejsy API są źródłem zablokowania wątków prowadzącego do awarii aplikacji.These APIs are a source of thread starvation leading to app crashes. W 3,0, AllowSynchronousIO jest domyślnie wyłączona.In 3.0, AllowSynchronousIO is disabled by default. Aby uzyskać więcej informacji, zobacz sekcję synchronicznych operacji we/wy w artykule Kestrel.For more information, see the Synchronous I/O section in the Kestrel article.

Jeśli jest wymagana synchroniczna operacja we/wy, można ją włączyć, konfigurując AllowSynchronousIO opcję na używanym serwerze (podczas wywoływania ConfigureKestrel , na przykład, jeśli jest używany Kestrel).If synchronous I/O is needed, it can be enabled by configuring the AllowSynchronousIO option on the server being used (when calling ConfigureKestrel, for example, if using Kestrel). Należy pamiętać, że wszystkie serwery (Kestrel, HttpSys, TestServer itp.) mają własne AllowSynchronousIO Opcje, które nie wpłyną na inne serwery.Note that servers (Kestrel, HttpSys, TestServer, etc.) all have their own AllowSynchronousIO option that won't affect other servers. Synchroniczne we/wy można włączyć dla wszystkich serwerów w poszczególnych żądaniach, korzystając z IHttpBodyControlFeature.AllowSynchronousIO opcji:Synchronous I/O can be enabled for all servers on a per-request basis using the IHttpBodyControlFeature.AllowSynchronousIO option:

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

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

Jeśli masz problemy z TextWriter implementacjami lub innymi strumieniami wywołującymi synchroniczne interfejsy API w operacji Dispose, DisposeAsync zamiast tego wywołaj nowy interfejs API.If you have trouble with TextWriter implementations or other streams that call synchronous APIs in Dispose, call the new DisposeAsync API instead.

Aby uzyskać więcej informacji, zobacz [anons] AllowSynchronousIO wyłączone na wszystkich serwerach (dotnet/AspNetCore #7644).For more information, see [Announcement] AllowSynchronousIO disabled in all servers (dotnet/AspNetCore #7644).

Buforowanie wyjściowego programu formatującegoOutput formatter buffering

Newtonsoft.Jsw, XmlSerializer i DataContractSerializer oparte na danych wyjściowych elementy formatujące obsługują tylko serializacji synchroniczne.Newtonsoft.Json, XmlSerializer, and DataContractSerializer based output formatters only support synchronous serialization. Aby zezwolić tym programom do pracy z ograniczeniami AllowSynchronousIO serwera, MVC buforuje dane wyjściowe tych elementów formatujących przed zapisaniem na dysku.To allow these formatters to work with the AllowSynchronousIO restrictions of the server, MVC buffers the output of these formatters before writing to disk. W wyniku buforowania, MVC będzie zawierać nagłówek Content-Length, gdy odpowiada za pomocą tych elementów formatujących.As a result of buffering, MVC will include the Content-Length header when responding using these formatters.

System.Text.Json obsługuje Serializacja asynchroniczną, a w związku z tym, że System.Text.Json oparty na programie formatującego nie jest buforem.System.Text.Json supports asynchronous serialization and consequently the System.Text.Json based formatter does not buffer. Rozważ użycie tego programu formatującego w celu zwiększenia wydajności.Consider using this formatter for improved performance.

Aby wyłączyć buforowanie, aplikacje można skonfigurować SuppressOutputFormatterBuffering w trakcie ich uruchamiania:To disable buffering, applications can configure SuppressOutputFormatterBuffering in their startup:

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

Należy zauważyć, że może to spowodować, że aplikacja zgłasza wyjątek czasu wykonywania, jeśli AllowSynchronousIO nie jest również skonfigurowana.Note that this may result in the application throwing a runtime exception if AllowSynchronousIO isn't also configured.

Zestaw Microsoft. AspNetCore. Server. Kestrel. https został usuniętyMicrosoft.AspNetCore.Server.Kestrel.Https assembly removed

W ASP.NET Core 2,1 zawartość Microsoft.AspNetCore.Server.Kestrel.Https.dll została przeniesiona do Microsoft.AspNetCore.Server.Kestrel.Core.dll .In ASP.NET Core 2.1, the contents of Microsoft.AspNetCore.Server.Kestrel.Https.dll were moved to Microsoft.AspNetCore.Server.Kestrel.Core.dll . To była nieprzerwana Aktualizacja przy użyciu TypeForwardedTo atrybutów.This was a non-breaking update using TypeForwardedTo attributes. W przypadku 3,0 został usunięty pusty zestaw Microsoft.AspNetCore.Server.Kestrel.Https.dll i pakiet NuGet.For 3.0, the empty Microsoft.AspNetCore.Server.Kestrel.Https.dll assembly and the NuGet package have been removed.

Biblioteki odwołujące się do Microsoft. AspNetCore. Server. Kestrel. https powinny aktualizować ASP.NET Core zależności do 2,1 lub nowszych.Libraries referencing Microsoft.AspNetCore.Server.Kestrel.Https should update ASP.NET Core dependencies to 2.1 or later.

Aplikacje i biblioteki ukierunkowane na ASP.NET Core 2,1 lub nowsze powinny usunąć wszystkie bezpośrednie odwołania do pakietu Microsoft. AspNetCore. Server. Kestrel. https .Apps and libraries targeting ASP.NET Core 2.1 or later should remove any direct references to the Microsoft.AspNetCore.Server.Kestrel.Https package.

Obsługa Newtonsoft.Js(Json.NET)Newtonsoft.Json (Json.NET) support

W ramach pracy w celu usprawnienia ASP.NET Core udostępnionej struktury Newtonsoft.Json (JSON.NET) został usunięty z ASP.NET Core udostępnionej platformy.As part of the work to improve the ASP.NET Core shared framework, Newtonsoft.Json (Json.NET) has been removed from the ASP.NET Core shared framework.

Domyślny serializator JSON dla ASP.NET Core jest teraz System.Text.Json Nowy w programie .NET Core 3,0.The default JSON serializer for ASP.NET Core is now System.Text.Json, which is new in .NET Core 3.0. Rozważ użycie, System.Text.Json gdy jest to możliwe.Consider using System.Text.Json when possible. Jest wysoka wydajność i nie wymaga dodatkowej zależności biblioteki.It's high-performance and doesn't require an additional library dependency. Jednak od momentu, System.Text.Json gdy jest to nowe, może to oznaczać brak funkcji wymaganych przez aplikację.However, since System.Text.Json is new, it might currently be missing features that your app needs. Aby uzyskać więcej informacji, zobacz Jak przeprowadzić migrację z Newtonsoft.Js, aby System.Text.Js.For more information, see How to migrate from Newtonsoft.Json to System.Text.Json.

Używanie Newtonsoft.Jsw projekcie ASP.NET Core 3,0 SignalRUse Newtonsoft.Json in an ASP.NET Core 3.0 SignalR project

  • Zainstaluj pakiet Microsoft. AspNetCore. SignalR . Protocols. NewtonsoftJson pakiet NuGet.Install the Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson NuGet package.

  • Na kliencie należy utworzyć łańcuch AddNewtonsoftJsonProtocol wywołań metody do HubConnectionBuilder wystąpienia:On the client, chain an AddNewtonsoftJsonProtocol method call to the HubConnectionBuilder instance:

    new HubConnectionBuilder()
        .WithUrl("/chathub")
        .AddNewtonsoftJsonProtocol(...)
        .Build();
    
  • Na serwerze należy utworzyć łańcuch AddNewtonsoftJsonProtocol wywołania metody AddSignalR wywołania metody w Startup.ConfigureServices :On the server, chain an AddNewtonsoftJsonProtocol method call to the AddSignalR method call in Startup.ConfigureServices:

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

Używanie Newtonsoft.Jsw projekcie ASP.NET Core 3,0 MVCUse Newtonsoft.Json in an ASP.NET Core 3.0 MVC project

  • Zainstaluj Microsoft.AspNetCore.Mvc.NewtonsoftJson pakiet.Install the Microsoft.AspNetCore.Mvc.NewtonsoftJson package.

  • Aktualizacja Startup.ConfigureServices do wywołania AddNewtonsoftJson .Update Startup.ConfigureServices to call AddNewtonsoftJson.

    services.AddMvc()
        .AddNewtonsoftJson();
    

    AddNewtonsoftJson jest zgodny z nowymi metodami rejestracji usługi MVC:AddNewtonsoftJson is compatible with the new MVC service registration methods:

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

    Newtonsoft.Json Ustawienia można ustawić w wywołaniu AddNewtonsoftJson :Newtonsoft.Json settings can be set in the call to AddNewtonsoftJson:

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

    Uwaga: Jeśli AddNewtonsoftJson Metoda jest niedostępna, upewnij się, że zainstalowano Microsoft.AspNetCore.Mvc.NewtonsoftJson pakiet.Note: If the AddNewtonsoftJson method isn't available, make sure that you installed the Microsoft.AspNetCore.Mvc.NewtonsoftJson package. Typowym błędem jest zainstalowanie Newtonsoft.Jsw pakiecie zamiast Microsoft.AspNetCore.Mvc.NewtonsoftJson pakietu.A common error is to install the Newtonsoft.Json package instead of the Microsoft.AspNetCore.Mvc.NewtonsoftJson package.

Aby uzyskać więcej informacji, zobacz dodawanie Newtonsoft.Jsna podstawie obsługi formatu JSON.For more information, see Add Newtonsoft.Json-based JSON format support.

Rejestracja usługi MVCMVC service registration

ASP.NET Core 3,0 dodaje nowe opcje rejestrowania scenariuszy MVC wewnątrz Startup.ConfigureServices .ASP.NET Core 3.0 adds new options for registering MVC scenarios inside Startup.ConfigureServices.

Dostępne są trzy nowe metody rozszerzenia najwyższego poziomu związane z scenariuszami MVC IServiceCollection .Three new top-level extension methods related to MVC scenarios on IServiceCollection are available. Szablony wykorzystują te nowe metody zamiast AddMvc .Templates use these new methods instead of AddMvc. Jednak AddMvc nadal zachowuje się tak, jak w poprzednich wersjach.However, AddMvc continues to behave as it has in previous releases.

Poniższy przykład dodaje obsługę kontrolerów i funkcji związanych z interfejsem API, ale nie widoków ani stron.The following example adds support for controllers and API-related features, but not views or pages. Szablon interfejsu API używa tego kodu:The API template uses this code:

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

Poniższy przykład dodaje obsługę kontrolerów, funkcji związanych z interfejsem API i widoków, ale nie stron.The following example adds support for controllers, API-related features, and views, but not pages. Szablon aplikacji sieci Web (MVC) używa tego kodu:The Web Application (MVC) template uses this code:

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

Poniższy przykład dodaje obsługę Razor stron i minimalną obsługę kontrolera.The following example adds support for Razor Pages and minimal controller support. Szablon aplikacji sieci Web używa tego kodu:The Web Application template uses this code:

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

Nowe metody można również łączyć.The new methods can also be combined. Poniższy przykład jest odpowiednikiem wywołania AddMvc w ASP.NET Core 2,2:The following example is equivalent to calling AddMvc in ASP.NET Core 2.2:

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

Kod uruchomienia routinguRouting startup code

Jeśli aplikacja wywołuje UseMvc lub UseSignalR migruje aplikację do routingu punktów końcowych , jeśli jest to możliwe.If an app calls UseMvc or UseSignalR, migrate the app to Endpoint Routing if possible. Aby zwiększyć zgodność routingu punktów końcowych z poprzednimi wersjami MVC, zostały przywrócone niektóre zmiany w generowaniu adresów URL wprowadzone w ASP.NET Core 2,2.To improve Endpoint Routing compatibility with previous versions of MVC, we've reverted some of the changes in URL generation introduced in ASP.NET Core 2.2. Jeśli wystąpią problemy z użyciem routingu punktów końcowych w 2,2, należy oczekiwać ulepszeń w ASP.NET Core 3,0 z następującymi wyjątkami:If you experienced problems using Endpoint Routing in 2.2, expect improvements in ASP.NET Core 3.0 with the following exceptions:

  • Jeśli aplikacja implementuje IRouter lub dziedziczy po Route , należy użyć DynamicRouteValuesTransformer jako zamiennika.If the app implements IRouter or inherits from Route, use DynamicRouteValuesTransformer as the replacement.
  • Jeśli aplikacja bezpośrednio uzyskuje dostęp RouteData.Routers do wewnątrz MVC do analizowania adresów URL, można ją zastąpić za pomocą LinkParser. ParsePathByEndpointName.If the app directly accesses RouteData.Routers inside MVC to parse URLs, you can replace this with use of LinkParser.ParsePathByEndpointName.
    • Zdefiniuj trasę przy użyciu nazwy trasy.Define the route with a route name.
    • Użyj LinkParser.ParsePathByEndpointName i przekaż żądaną nazwę trasy.Use LinkParser.ParsePathByEndpointName and pass in the desired route name.

Routing punktów końcowych obsługuje tę samą składnię wzorca trasy i funkcje tworzenia wzorców tras IRouter .Endpoint Routing supports the same route pattern syntax and route pattern authoring features as IRouter. Obsługa routingu punktów końcowych IRouteConstraint .Endpoint Routing supports IRouteConstraint. Routing punktów końcowych obsługuje [Route] , [HttpGet] i inne atrybuty routingu MVC.Endpoint routing supports [Route], [HttpGet], and the other MVC routing attributes.

W przypadku większości aplikacji wymagane są jedynie Startup zmiany.For most applications, only Startup requires changes.

Migrowanie Startup.ConfigurujMigrate Startup.Configure

Ogólne porady:General advice:

  • Dodaj UseRouting .Add UseRouting.

  • Jeśli aplikacja jest wywoływana UseStaticFiles , umieść UseStaticFiles przed UseRouting .If the app calls UseStaticFiles, place UseStaticFiles before UseRouting.

  • Jeśli aplikacja używa funkcji uwierzytelniania/autoryzacji, takich jak AuthorizePage lub [Authorize] , należy umieścić wywołanie do UseAuthentication i UseAuthorization : po , UseRouting i UseCors , ale przed UseEndpoints :If the app uses authentication/authorization features such as AuthorizePage or [Authorize], place the call to UseAuthentication and UseAuthorization: after , UseRouting and UseCors, but before UseEndpoints:

    public void Configure(IApplicationBuilder app)
    {
      ...
    
      app.UseStaticFiles();
    
      app.UseRouting();
      app.UseCors();
    
      app.UseAuthentication();
      app.UseAuthorization();
    
      app.UseEndpoints(endpoints => {
         endpoints.MapControllers();
      });
    
  • Zamień UseMvc lub UseSignalR na UseEndpoints .Replace UseMvc or UseSignalR with UseEndpoints.

  • Jeśli aplikacja używa scenariuszy CORS , takich jak [EnableCors] , należy umieścić wywołanie UseCors przed dowolnym innym oprogramowanie pośredniczące, które używa mechanizmu CORS (na przykład Umieść UseCors przed UseAuthentication , UseAuthorization , i UseEndpoints ).If the app uses CORS scenarios, such as [EnableCors], place the call to UseCors before any other middleware that use CORS (for example, place UseCors before UseAuthentication, UseAuthorization, and UseEndpoints).

  • Zamień IHostingEnvironment na IWebHostEnvironment i Dodaj using instrukcję dla Microsoft.Extensions.Hosting przestrzeni nazw.Replace IHostingEnvironment with IWebHostEnvironment and add a using statement for the Microsoft.Extensions.Hosting namespace.

  • Zamień IApplicationLifetime na IHostApplicationLifetime ( Microsoft.Extensions.Hosting przestrzeń nazw).Replace IApplicationLifetime with IHostApplicationLifetime (Microsoft.Extensions.Hosting namespace).

  • Zamień EnvironmentName na Environments ( Microsoft.Extensions.Hosting przestrzeń nazw).Replace EnvironmentName with Environments (Microsoft.Extensions.Hosting namespace).

Poniższy kod jest przykładem Startup.Configure w typowej aplikacji ASP.NET Core 2,2:The following code is an example of Startup.Configure in a typical 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?}");
    });
}

Po zaktualizowaniu poprzedniego Startup.Configure kodu:After updating the previous Startup.Configure code:

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?}");
    });
}

Ostrzeżenie

W przypadku większości aplikacji wywołania UseAuthentication , UseAuthorization i UseCors muszą znajdować się między wywołaniami UseRouting i, UseEndpoints Aby obowiązywać.For most apps, calls to UseAuthentication, UseAuthorization, and UseCors must appear between the calls to UseRouting and UseEndpoints to be effective.

Kontrole kondycjiHealth Checks

Kontrole kondycji korzystają z routingu punktu końcowego z hostem ogólnym.Health Checks use endpoint routing with the Generic Host. W programie Startup.Configure Wywołaj program MapHealthChecks Endpoint Builder z adresem URL punktu końcowego lub ścieżką względną:In Startup.Configure, call MapHealthChecks on the endpoint builder with the endpoint URL or relative path:

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

Punkty końcowe sprawdzania kondycji mogą:Health Checks endpoints can:

  • Określ jeden lub więcej dozwolonych hostów/portów.Specify one or more permitted hosts/ports.
  • Wymagaj autoryzacji.Require authorization.
  • Wymagaj mechanizmu CORS.Require CORS.

Aby uzyskać więcej informacji, zobacz Kontrole kondycji w ASP.NET Core.For more information, see Kontrole kondycji w ASP.NET Core.

Wskazówki dotyczące oprogramowania pośredniczącego zabezpieczeńSecurity middleware guidance

Obsługa autoryzacji i mechanizmu CORS jest ujednolicona dla podejścia pośredniczącego .Support for authorization and CORS is unified around the middleware approach. Pozwala to korzystać z tego samego oprogramowania pośredniczącego i funkcji w tych scenariuszach.This allows use of the same middleware and functionality across these scenarios. Zaktualizowane oprogramowanie pośredniczące autoryzacji jest dostępne w tej wersji, a oprogramowanie do obsługi mechanizmu CORS jest ulepszone, aby można było zrozumieć atrybuty używane przez kontrolery MVC.An updated authorization middleware is provided in this release, and CORS Middleware is enhanced so that it can understand the attributes used by MVC controllers.

CORSCORS

Wcześniej mechanizm CORS może być trudny do skonfigurowania.Previously, CORS could be difficult to configure. Oprogramowanie pośredniczące zostało dostarczone do użycia w niektórych przypadkach użycia, ale filtry MVC były przeznaczone do użycia bez oprogramowania pośredniczącego w innych przypadkach użycia.Middleware was provided for use in some use cases, but MVC filters were intended to be used without the middleware in other use cases. W ASP.NET Core 3,0 zalecamy, aby wszystkie aplikacje wymagające mechanizmu CORS korzystały z oprogramowania pośredniczącego CORS wspólnie z routingiem punktów końcowych.With ASP.NET Core 3.0, we recommend that all apps that require CORS use the CORS Middleware in tandem with Endpoint Routing. UseCors można podać przy użyciu domyślnych zasad i można [EnableCors] [DisableCors] użyć atrybutów, aby zastąpić zasady domyślne, gdy jest to wymagane.UseCors can be provided with a default policy, and [EnableCors] and [DisableCors] attributes can be used to override the default policy where required.

W poniższym przykładzie:In the following example:

  • Funkcja CORS jest włączona dla wszystkich punktów końcowych z default nazwanymi zasadami.CORS is enabled for all endpoints with the default named policy.
  • MyControllerKlasa wyłącza funkcję CORS z [DisableCors] atrybutem.The MyController class disables CORS with the [DisableCors] attribute.
public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseCors("default");

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

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

AutoryzacjaAuthorization

We wcześniejszych wersjach ASP.NET Core Obsługa autoryzacji była świadczona za pośrednictwem [Authorize] atrybutu.In earlier versions of ASP.NET Core, authorization support was provided via the [Authorize] attribute. Oprogramowanie pośredniczące autoryzacji nie jest dostępne.Authorization middleware wasn't available. W ASP.NET Core 3,0 wymagane jest oprogramowanie pośredniczące autoryzacji.In ASP.NET Core 3.0, authorization middleware is required. Zalecamy natychmiastowe umieszczenie oprogramowania pośredniczącego autoryzacji ASP.NET Core ( UseAuthorization ) UseAuthentication .We recommend placing the ASP.NET Core Authorization Middleware (UseAuthorization) immediately after UseAuthentication. Oprogramowanie pośredniczące autoryzacji można także skonfigurować przy użyciu zasad domyślnych, które mogą zostać zastąpione.The Authorization Middleware can also be configured with a default policy, which can be overridden.

W ASP.NET Core 3,0 lub nowszej UseAuthorization jest wywoływana w Startup.Configure , a następujące elementy HomeController wymagają zalogowanego użytkownika:In ASP.NET Core 3.0 or later, UseAuthorization is called in Startup.Configure, and the following HomeController requires a signed in user:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

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

W przypadku korzystania z routingu punktów końcowych zalecamy skonfigurowanie usługi <xref:Microsoft.AspNetCore.Mvc.Authorization.AuthorizeFilter> i zamianę opartej na oprogramowaniu pośredniczącym autoryzacji.When using endpoint routing, we recommend against configuring <xref:Microsoft.AspNetCore.Mvc.Authorization.AuthorizeFilter> and instead relying on the Authorization middleware. Jeśli aplikacja używa AuthorizeFilter jako filtru globalnego w MVC, zalecamy refaktoryzację kodu w celu zapewnienia zasad w wywołaniu AddAuthorization .If the app uses an AuthorizeFilter as a global filter in MVC, we recommend refactoring the code to provide a policy in the call to AddAuthorization.

DefaultPolicyPoczątkowo skonfigurowano wymaganie uwierzytelniania, dlatego nie jest wymagana żadna dodatkowa konfiguracja.The DefaultPolicy is initially configured to require authentication, so no additional configuration is required. W poniższym przykładzie punkty końcowe MVC są oznaczone jako RequireAuthorization tak, że wszystkie żądania muszą być autoryzowane na podstawie DefaultPolicy .In the following example, MVC endpoints are marked as RequireAuthorization so that all requests must be authorized based on the DefaultPolicy. Jednak zezwala na HomeController dostęp bez logowania użytkownika do aplikacji z powodu [AllowAnonymous] :However, the HomeController allows access without the user signing into the app due to [AllowAnonymous]:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

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

Autoryzacja dla określonych punktów końcowychAuthorization for specific endpoints

Autoryzację można również skonfigurować dla określonych klas punktów końcowych.Authorization can also be configured for specific classes of endpoints. Poniższy kod stanowi przykład konwersji aplikacji MVC, która skonfigurowała globalne AuthorizeFilter dla aplikacji z określonymi zasadami wymagającymi autoryzacji:The following code is an example of converting an MVC app that configured a global AuthorizeFilter to an app with a specific policy requiring authorization:

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

Zasady można także dostosować.Policies can also be customized. DefaultPolicySkonfigurowano wymaganie uwierzytelniania:The DefaultPolicy is configured to require authentication:

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
{

Alternatywnie wszystkie punkty końcowe można skonfigurować tak, aby wymagały autoryzacji, bez konieczności [Authorize] RequireAuthorization konfigurowania FallbackPolicy .Alternatively, all endpoints can be configured to require authorization without [Authorize] or RequireAuthorization by configuring a FallbackPolicy. FallbackPolicyRóżni się od DefaultPolicy .The FallbackPolicy is different from the DefaultPolicy. DefaultPolicyJest wyzwalany przez [Authorize] lub RequireAuthorization , podczas gdy FallbackPolicy jest wyzwalane, gdy nie ustawiono żadnych innych zasad.The DefaultPolicy is triggered by [Authorize] or RequireAuthorization, while the FallbackPolicy is triggered when no other policy is set. FallbackPolicy jest początkowo skonfigurowana do zezwalania na żądania bez autoryzacji.FallbackPolicy is initially configured to allow requests without authorization.

Poniższy przykład jest taki sam jak w poprzednim DefaultPolicy przykładzie, ale używa FallbackPolicy do zawsze Wymagaj uwierzytelniania we wszystkich punktach końcowych, z wyjątkiem sytuacji, gdy [AllowAnonymous] jest określony:The following example is the same as the preceding DefaultPolicy example but uses the FallbackPolicy to always require authentication on all endpoints except when [AllowAnonymous] is specified:

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
{
    ...
}

Autoryzacja przez oprogramowanie pośredniczące działa bez struktury, która ma konkretną wiedzę o autoryzacji.Authorization by middleware works without the framework having any specific knowledge of authorization. Na przykład kontrole kondycji nie mają określonej znajomości autoryzacji, ale kontrole kondycji mogą mieć konfigurowalne zasady autoryzacji stosowane przez oprogramowanie pośredniczące.For instance, health checks has no specific knowledge of authorization, but health checks can have a configurable authorization policy applied by the middleware.

Ponadto każdy punkt końcowy może dostosować wymagania dotyczące autoryzacji.Additionally, each endpoint can customize its authorization requirements. W poniższym przykładzie program UseAuthorization przetwarza autoryzację przy użyciu DefaultPolicy , ale /healthz punkt końcowy sprawdzania kondycji wymaga admin użytkownika:In the following example, UseAuthorization processes authorization with the DefaultPolicy, but the /healthz health check endpoint requires an admin user:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

Ochrona jest zaimplementowana w niektórych scenariuszach.Protection is implemented for some scenarios. Punkty końcowe oprogramowanie pośredniczące zgłasza wyjątek, jeśli zasady autoryzacji lub mechanizmu CORS zostały pominięte ze względu na brak oprogramowania pośredniczącego.Endpoints Middleware throws an exception if an authorization or CORS policy is skipped due to missing middleware. Obsługa analizatora, aby zapewnić dodatkową opinię na temat niedziałania konfiguracji.Analyzer support to provide additional feedback about misconfiguration is in progress.

Niestandardowe programy obsługi autoryzacjiCustom authorization handlers

Jeśli aplikacja używa niestandardowych programów obsługi autoryzacji, routing punktu końcowego przekazuje inny typ zasobu do obsługi niż MVC.If the app uses custom authorization handlers, endpoint routing passes a different resource type to handlers than MVC. Programy obsługi, które oczekują, że zasób kontekstu procedury obsługi autoryzacji ma typ AuthorizationFilterContext (typ zasobu dostarczony przez filtry MVC) będzie musiał zostać zaktualizowany w celu obsługi zasobów typu RouteEndpoint (typ zasobu podany dla programów obsługi autoryzacji według routingu punktów końcowych).Handlers that expect the authorization handler context resource to be of type AuthorizationFilterContext (the resource type provided by MVC filters) will need to be updated to handle resources of type RouteEndpoint (the resource type given to authorization handlers by endpoint routing).

MVC nadal używa AuthorizationFilterContext zasobów, więc jeśli aplikacja używa filtrów autoryzacji MVC wraz z autoryzacją routingu punktu końcowego, może być konieczne obsługę obu typów zasobów.MVC still uses AuthorizationFilterContext resources, so if the app uses MVC authorization filters along with endpoint routing authorization, it may be necessary to handle both types of resources.

SignalR

Mapowanie SignalR centrów odbywa się teraz w obrębie UseEndpoints .Mapping of SignalR hubs now takes place inside UseEndpoints.

Mapuj każde centrum za pomocą MapHub .Map each hub with MapHub. Tak jak w poprzednich wersjach, każde centrum jest jawnie wymienione.As in previous versions, each hub is explicitly listed.

W poniższym przykładzie ChatHub SignalR Dodano obsługę centrum:In the following example, support for the ChatHub SignalR hub is added:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

Istnieje nowa opcja kontrolowania limitów rozmiaru komunikatów od klientów.There is a new option for controlling message size limits from clients. Na przykład w Startup.ConfigureServices :For example, in Startup.ConfigureServices:

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

W ASP.NET Core 2,2 można ustawić TransportMaxBufferSize i, który efektywnie kontroluje maksymalny rozmiar komunikatu.In ASP.NET Core 2.2, you could set the TransportMaxBufferSize and that would effectively control the maximum message size. W ASP.NET Core 3,0 ta opcja teraz kontroluje maksymalny rozmiar tylko przed zaobserwowaniem wartości.In ASP.NET Core 3.0, that option now only controls the maximum size before backpressure is observed.

Kontrolery MVCMVC controllers

Teraz trwa mapowanie kontrolerów UseEndpoints .Mapping of controllers now takes place inside UseEndpoints.

Dodaj MapControllers , jeśli aplikacja używa routingu atrybutów.Add MapControllers if the app uses attribute routing. Ponieważ Routing obejmuje obsługę wielu struktur w ASP.NET Core 3,0 lub nowszych, Dodawanie kontrolerów z obsługą atrybutu jest zgodą.Since routing includes support for many frameworks in ASP.NET Core 3.0 or later, adding attribute-routed controllers is opt-in.

Zastąp następujące:Replace the following:

  • MapRoute się MapControllerRouteMapRoute with MapControllerRoute
  • MapAreaRoute się MapAreaControllerRouteMapAreaRoute with MapAreaControllerRoute

Ponieważ Routing obejmuje teraz obsługę więcej niż tylko MVC, terminologia zmieniła się w taki sposób, że te metody jasno określają to, co robią.Since routing now includes support for more than just MVC, the terminology has changed to make these methods clearly state what they do. Trasy konwencjonalne, takie jak MapControllerRoute / MapAreaControllerRoute / MapDefaultControllerRoute są stosowane w kolejności, w jakiej zostały dodane.Conventional routes such as MapControllerRoute/MapAreaControllerRoute/MapDefaultControllerRoute are applied in the order that they're added. Najpierw umieść bardziej szczegółowe trasy (takie jak trasy dla obszaru).Place more specific routes (such as routes for an area) first.

W poniższym przykładzie:In the following example:

  • MapControllers dodaje obsługę kontrolerów z routingiem z atrybutami.MapControllers adds support for attribute-routed controllers.
  • MapAreaControllerRoute dodaje konwencjonalne trasy dla kontrolerów w obszarze.MapAreaControllerRoute adds a conventional route for controllers in an area.
  • MapControllerRoute dodaje konwencjonalne trasy dla kontrolerów.MapControllerRoute adds a conventional route for controllers.
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?}");
    });
}

Usuwanie sufiksu asynchronicznego z nazw akcji kontroleraAsync suffix removal from controller action names

W ASP.NET Core 3,0 ASP.NET Core MVC usuwa Async sufiks z nazw akcji kontrolera.In ASP.NET Core 3.0, ASP.NET Core MVC removes the Async suffix from controller action names. Ta nowa wartość domyślna ma wpływ na generowanie routingu i linków.Both routing and link generation are impacted by this new default. Przykład:For example:

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

Przed ASP.NET Core 3,0:Prior to ASP.NET Core 3.0:

  • Do powyższej akcji można uzyskać dostęp w marszrucie produkty/ListAsync .The preceding action could be accessed at the Products/ListAsync route.

  • Wymagana jest generacja linku określająca Async sufiks.Link generation required specifying the Async suffix. Przykład:For example:

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

W ASP.NET Core 3,0:In ASP.NET Core 3.0:

  • Poprzednią akcję można uzyskać przy użyciu trasy produkty/lista .The preceding action can be accessed at the Products/List route.

  • Generowanie łącza nie wymaga określenia Async sufiksu.Link generation doesn't require specifying the Async suffix. Przykład:For example:

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

Ta zmiana nie ma wpływu na nazwy określone przy użyciu [ActionName] atrybutu.This change doesn't affect names specified using the [ActionName] attribute. Zachowanie domyślne można wyłączyć przy użyciu następującego kodu w programie Startup.ConfigureServices :The default behavior can be disabled with the following code in Startup.ConfigureServices:

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

Zgodnie z opisem w dokumentacji dotyczącej różnic między wcześniejszymi wersjami routinguistnieją pewne różnice w generowaniu linków ( Url.Link na przykład przy użyciu i podobne interfejsy API).As explained in documentation on differences from earlier versions of routing, there are some differences in link generation (using Url.Link and similar APIs, for example). Należą do nich:These include:

  • Domyślnie podczas korzystania z routingu punktów końcowych wielkość liter w parametrach trasy w wygenerowanych identyfikatorach URI nie musi być zachowywana.By default, when using endpoint routing, casing of route parameters in generated URIs is not necessarily preserved. Takie zachowanie może być kontrolowane za pomocą IOutboundParameterTransformer interfejsu.This behavior can be controlled with the IOutboundParameterTransformer interface.
  • Generowanie identyfikatora URI dla nieprawidłowej trasy (kontroler/akcja lub strona, która nie istnieje) spowoduje utworzenie pustego ciągu w ramach routingu punktu końcowego zamiast tworzenia nieprawidłowego identyfikatora URI.Generating a URI for an invalid route (a controller/action or page that doesn't exist) will produce an empty string under endpoint routing instead of producing an invalid URI.
  • Wartości otoczenia (parametry trasy z bieżącego kontekstu) nie są automatycznie używane w generacji linków z routingiem punktów końcowych.Ambient values (route parameters from the current context) are not automatically used in link generation with endpoint routing. Wcześniej podczas generowania linku do innej akcji (lub strony) nieokreślone wartości trasy byłyby wywnioskowane na podstawie bieżących wartości w otoczeniu tras.Previously, when generating a link to another action (or page), unspecified route values would be inferred from the current routes ambient values. W przypadku korzystania z routingu punktów końcowych wszystkie parametry trasy muszą być jawnie określone podczas generowania łącza.When using endpoint routing, all route parameters must be specified explicitly during link generation.

Razor PageRazor Pages

Na Razor stronach mapowania teraz odbywa się wewnątrz UseEndpoints .Mapping Razor Pages now takes place inside UseEndpoints.

Dodaj MapRazorPages , jeśli aplikacja używa Razor stron.Add MapRazorPages if the app uses Razor Pages. Ponieważ Routing punktów końcowych obejmuje obsługę wielu struktur, Dodawanie Razor stron jest teraz zgodą.Since Endpoint Routing includes support for many frameworks, adding Razor Pages is now opt-in.

W następującej Startup.Configure metodzie program MapRazorPages dodaje obsługę Razor stron:In the following Startup.Configure method, MapRazorPages adds support for Razor Pages:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

Korzystanie z MVC bez routingu punktu końcowegoUse MVC without Endpoint Routing

Użycie MVC przez UseMvc lub UseMvcWithDefaultRoute w ASP.NET Core 3,0 wymaga jawnej zgody w wewnątrz Startup.ConfigureServices .Using MVC via UseMvc or UseMvcWithDefaultRoute in ASP.NET Core 3.0 requires an explicit opt-in inside Startup.ConfigureServices. Jest to wymagane, ponieważ MVC musi wiedzieć, czy może polegać na oprogramowaniu pośredniczącym i oprogramowaniu CORS podczas inicjacji.This is required because MVC must know whether it can rely on the authorization and CORS Middleware during initialization. Zostanie dostarczony Analizator ostrzegający, czy aplikacja próbuje użyć nieobsługiwanej konfiguracji.An analyzer is provided that warns if the app attempts to use an unsupported configuration.

Jeśli aplikacja wymaga starszej IRouter obsługi, należy wyłączyć EnableEndpointRouting Korzystanie z następujących metod w programie Startup.ConfigureServices :If the app requires legacy IRouter support, disable EnableEndpointRouting using any of the following approaches 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);

Kontrole kondycjiHealth checks

Kontrole kondycji mogą służyć jako oprogramowanie do przesyłania i kierowania punktów końcowych.Health checks can be used as a router-ware with Endpoint Routing.

Dodawanie MapHealthChecks do korzystania z kontroli kondycji przy użyciu routingu punktu końcowego.Add MapHealthChecks to use health checks with Endpoint Routing. MapHealthChecksMetoda akceptuje argumenty podobne do UseHealthChecks .The MapHealthChecks method accepts arguments similar to UseHealthChecks. Zaletą korzystania z tej funkcji MapHealthChecks UseHealthChecks jest możliwość zastosowania autoryzacji i zwiększenia szczegółowej kontroli nad pasującymi zasadami.The advantage of using MapHealthChecks over UseHealthChecks is the ability to apply authorization and to have greater fine-grained control over the matching policy.

W poniższym przykładzie MapHealthChecks jest wywoływana dla punktu końcowego sprawdzania kondycji w /healthz :In the following example, MapHealthChecks is called for a health check endpoint at /healthz:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

HostBuilder zastępuje WebHostBuilderHostBuilder replaces WebHostBuilder

Szablony ASP.NET Core 3,0 korzystają z hosta ogólnego.The ASP.NET Core 3.0 templates use Generic Host. Poprzednie wersje używają hosta sieci Web.Previous versions used Web Host. Poniższy kod przedstawia klasę ASP.NET Core 3,0 wygenerowaną przez szablon Program :The following code shows the ASP.NET Core 3.0 template generated Program class:

// 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>();
            });
}

Poniższy kod przedstawia klasę ASP.NET Core 2,2 wygenerowaną przez szablon Program :The following code shows the ASP.NET Core 2.2 template-generated Program class:

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 pozostanie w 3,0 i jest typem webBuilder widocznym w poprzednim przykładzie kodu.IWebHostBuilder remains in 3.0 and is the type of the webBuilder seen in the preceding code sample. WebHostBuilder będzie przestarzałe w przyszłej wersji i zastąpione przez HostBuilder .WebHostBuilder will be deprecated in a future release and replaced by HostBuilder.

Najbardziej znacząca zmiana z WebHostBuilder do na HostBuilder jest iniekcją zależności (di).The most significant change from WebHostBuilder to HostBuilder is in dependency injection (DI). W przypadku korzystania HostBuilder z programu można wstrzyknąć tylko następujące elementy do Startup konstruktora:When using HostBuilder, you can only inject the following into Startup's constructor:

HostBuilderOgraniczenia di:The HostBuilder DI constraints:

  • Zezwól na kompilowanie kontenera DI tylko raz.Enable the DI container to be built only one time.
  • Pozwala uniknąć problemów z okresem istnienia obiektów, takich jak rozpoznawanie wielu wystąpień pojedynczych.Avoids the resulting object lifetime issues like resolving multiple instances of singletons.

Aby uzyskać więcej informacji, zobacz unikanie iniekcji usługi uruchamiania w ASP.NET Core 3.For more information, see Avoiding Startup service injection in ASP.NET Core 3.

Element addauthorization został przeniesiony do innego zestawuAddAuthorization moved to a different assembly

ASP.NET Core 2,2 i niższa AddAuthorization Metoda w Microsoft.AspNetCore.Authorization.dll :The ASP.NET Core 2.2 and lower AddAuthorization methods in Microsoft.AspNetCore.Authorization.dll :

  • Zmieniono nazwę AddAuthorizationCore .Have been renamed AddAuthorizationCore.
  • Zostały przeniesione do Microsoft.AspNetCore.Authorization.Policy.dll .Have been moved to Microsoft.AspNetCore.Authorization.Policy.dll .

Nie ma to wpływu na aplikacje używające zarówno Microsoft.AspNetCore.Authorization.dll , jak i Microsoft.AspNetCore.Authorization.Policy.dll .Apps that are using both Microsoft.AspNetCore.Authorization.dll and Microsoft.AspNetCore.Authorization.Policy.dll aren't impacted.

Aplikacje, które nie używają Microsoft.AspNetCore.Authorization.Policy.dll powinny wykonać jedną z następujących czynności:Apps that are not using Microsoft.AspNetCore.Authorization.Policy.dll should do one of the following:

  • Dodaj odwołanie do Microsoft.AspNetCore.Authorization.Policy.dll .Add a reference to Microsoft.AspNetCore.Authorization.Policy.dll . Ta metoda działa w przypadku większości aplikacji i jest wymagana.This approach works for most apps and is all that is required.
  • Przełącz do korzystania z AddAuthorizationCoreSwitch to using AddAuthorizationCore

Aby uzyskać więcej informacji, zobacz artykuł dotyczący nadmiernej zmiany w programie AddAuthorization(o => ) w innym zestawie #386.For more information, see Breaking change in AddAuthorization(o =>) overload lives in a different assembly #386.

Identity INTERFEJSU użytkownikaIdentity UI

Identity Aktualizacje interfejsu użytkownika dla ASP.NET Core 3,0:Identity UI updates for ASP.NET Core 3.0:

SignalR

SignalRKlient JavaScript zmienił @aspnet/signalr się z na @microsoft/signalr .The SignalR JavaScript client has changed from @aspnet/signalr to @microsoft/signalr. Aby reagować na tę zmianę, Zmień odwołania w package.jsw plikach, require instrukcjach i import instrukcjach języka ECMAScript.To react to this change, change the references in package.json files, require statements, and ECMAScript import statements.

System.Text.Jsjest domyślnym protokołemSystem.Text.Json is the default protocol

System.Text.Json jest teraz domyślnym protokołem centrum używanym przez klienta i serwer.System.Text.Json is now the default Hub protocol used by both the client and server.

W programie Startup.ConfigureServices Wywołaj polecenie, AddJsonProtocol Aby ustawić opcje serializatora.In Startup.ConfigureServices, call AddJsonProtocol to set serializer options.

ServerServer:

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

KlientClient:

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

Przełącz do Newtonsoft.JsnaSwitch to Newtonsoft.Json

Jeśli używasz funkcji Newtonsoft.Jsw programie, które nie są obsługiwane w programie System.Text.Json, możesz przełączyć się z powrotem do systemu Newtonsoft.Json .If you're using features of Newtonsoft.Json that aren't supported in System.Text.Json, you can switch back to Newtonsoft.Json. Zobacz używanie Newtonsoft.Jsw programie w SignalR projekcie ASP.NET Core 3,0 wcześniej w tym artykule.See Use Newtonsoft.Json in an ASP.NET Core 3.0 SignalR project earlier in this article.

Rozproszone pamięci podręczne RedisRedis distributed caches

Pakiet Microsoft. Extensions. buforowania. Redis nie jest dostępny dla aplikacji ASP.NET Core 3,0 lub nowszych.The Microsoft.Extensions.Caching.Redis package isn't available for ASP.NET Core 3.0 or later apps. Zastąp odwołanie do pakietu pakietem Microsoft. Extensions. buforowanie. StackExchangeRedis.Replace the package reference with Microsoft.Extensions.Caching.StackExchangeRedis. Aby uzyskać więcej informacji, zobacz Rozproszone buforowanie w ASP.NET Core.For more information, see Rozproszone buforowanie w ASP.NET Core.

Zezwól na kompilację środowiska uruchomieniowegoOpt in to runtime compilation

Przed ASP.NET Core 3,0, kompilacja widoków w środowisku uruchomieniowym była niejawną funkcją struktury.Prior to ASP.NET Core 3.0, runtime compilation of views was an implicit feature of the framework. Kompilacja środowiska uruchomieniowego uzupełnia kompilację widoków w czasie kompilacji.Runtime compilation supplements build-time compilation of views. Umożliwia ona programowi Kompilowanie Razor widoków i stron (plików . cshtml ), gdy pliki są modyfikowane, bez konieczności ponownego kompilowania całej aplikacji.It allows the framework to compile Razor views and pages ( .cshtml files) when the files are modified, without having to rebuild the entire app. Ta funkcja obsługuje scenariusz tworzenia szybkiej edycji w środowisku IDE i odświeżania przeglądarki w celu wyświetlenia zmian.This feature supports the scenario of making a quick edit in the IDE and refreshing the browser to view the changes.

W ASP.NET Core 3,0, Kompilacja środowiska uruchomieniowego jest scenariuszem wyboru.In ASP.NET Core 3.0, runtime compilation is an opt-in scenario. Kompilacja czasu kompilacji jest jedynym mechanizmem kompilacji, który jest domyślnie włączony.Build-time compilation is the only mechanism for view compilation that's enabled by default. Środowisko uruchomieniowe korzysta z programu Visual Studio lub dotnet-Watch w Visual Studio Code, aby ponownie skompilować projekt po wykryciu zmian w plikach . cshtml .The runtime relies on Visual Studio or dotnet-watch in Visual Studio Code to rebuild the project when it detects changes to .cshtml files. W programie Visual Studio zmiany w plikach CS , cshtml lub . Razor w projekcie są uruchamiane ( Ctrl + F5), ale nie są debugowane ( F5), wyzwalają ponowną kompilację projektu.In Visual Studio, changes to .cs , .cshtml , or .razor files in the project being run (Ctrl+F5), but not debugged (F5), trigger recompilation of the project.

Aby włączyć kompilację środowiska uruchomieniowego w projekcie ASP.NET Core 3,0:To enable runtime compilation in your ASP.NET Core 3.0 project:

  1. Zainstaluj pakiet Microsoft. AspNetCore. MVC. Razor . Pakiet NuGet RuntimeCompilation.Install the Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet package.

  2. Aktualizacja Startup.ConfigureServices do wywołania AddRazorRuntimeCompilation :Update Startup.ConfigureServices to call AddRazorRuntimeCompilation:

    W przypadku ASP.NET Core MVC Użyj następującego kodu:For ASP.NET Core MVC, use the following code:

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

    W przypadku Razor stron ASP.NET Core Użyj następującego kodu:For ASP.NET Core Razor Pages, use the following code:

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

W przykładzie https://github.com/aspnet/samples/tree/master/samples/aspnetcore/mvc/runtimecompilation pokazano przykład włączania kompilacji środowiska uruchomieniowego warunkowo w środowiskach programistycznych.The sample at https://github.com/aspnet/samples/tree/master/samples/aspnetcore/mvc/runtimecompilation shows an example of enabling runtime compilation conditionally in Development environments.

Aby uzyskać więcej informacji na temat Razor kompilowania plików, zobacz Razor kompilacja pliku w ASP.NET Core .For more information on Razor file compilation, see Razor kompilacja pliku w ASP.NET Core.

Migrowanie bibliotek poprzez wiele elementów docelowychMigrate libraries via multi-targeting

Biblioteki często muszą obsługiwać wiele wersji ASP.NET Core.Libraries often need to support multiple versions of ASP.NET Core. Większość bibliotek, które zostały skompilowane przed poprzednimi wersjami ASP.NET Core, powinna działać bez problemów.Most libraries that were compiled against previous versions of ASP.NET Core should continue working without issues. Następujące warunki wymagają, aby aplikacja była skompilowana w sposób krzyżowy:The following conditions require the app to be cross-compiled:

  • Biblioteka korzysta z funkcji, która ma istotną zmianęw postaci binarnej.The library relies on a feature that has a binary breaking change.
  • Biblioteka chce korzystać z nowych funkcji w ASP.NET Core 3,0.The library wants to take advantage of new features in ASP.NET Core 3.0.

Przykład:For example:

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

Użyj #ifdefs , aby włączyć interfejsy API specyficzne dla ASP.NET Core 3,0:Use #ifdefs to enable ASP.NET Core 3.0-specific APIs:

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

Aby uzyskać więcej informacji na temat używania interfejsów API ASP.NET Core w bibliotece klas, zobacz Używanie ASP.NET Core interfejsów API w bibliotece klas .For more information on using ASP.NET Core APIs in a class library, see Używanie ASP.NET Core interfejsów API w bibliotece klas.

Różne zmianyMiscellaneous changes

System sprawdzania poprawności w programie .NET Core 3,0 lub nowszy traktuje parametry niedopuszczające wartości null lub właściwości powiązane tak, jakby miały [Required] atrybut.The validation system in .NET Core 3.0 and later treats non-nullable parameters or bound properties as if they had a [Required] attribute. Aby uzyskać więcej informacji, zobacz [Required] Attribute.For more information, see [Required] attribute.

PublikowaniePublish

Usuń foldery bin i obj w katalogu projektu.Delete the bin and obj folders in the project directory.

TestServerTestServer

W przypadku aplikacji, które używają TestServer bezpośrednio z hostem ogólnym, Utwórz za pomocą TestServer IWebHostBuilder w ConfigureWebHost :For apps that use TestServer directly with the Generic Host, create the TestServer on an IWebHostBuilder in ConfigureWebHost:

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

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

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

Przerywanie zmian interfejsu APIBreaking API changes

Przejrzyj istotne zmiany:Review breaking changes:

Routing punktów końcowych za pomocą parametru catch-allEndpoint routing with catch-all parameter

Ostrzeżenie

Parametr "catch-all" może być zgodny z niepoprawnymi trasami z powodu błędu w routingu.A catch-all parameter may match routes incorrectly due to a bug in routing. Aplikacje, na które ma wpływ ta usterka, mają następującą charakterystykę:Apps impacted by this bug have the following characteristics:

  • Trasa przechwycenia, na przykład {**slug}"A catch-all route, for example, {**slug}"
  • Trasa catch-all nie będzie zgodna z żądaniami, które powinny być zgodne.The catch-all route fails to match requests it should match.
  • Usunięcie innych tras spowoduje rozpoczęcie pracy z całą trasą.Removing other routes makes catch-all route start working.

Zobacz błędy usługi GitHub 18677 i 16579 , aby zobaczyć przykładowe przypadki, w których trafili ten błąd.See GitHub bugs 18677 and 16579 for example cases that hit this bug.

Poprawka dotycząca tej usterki jest zawarta w programie .NET Core 3.1.301 SDK i nowszych.An opt-in fix for this bug is contained in .NET Core 3.1.301 SDK and later. Poniższy kod ustawia przełącznik wewnętrzny, który naprawia tę usterkę:The following code sets an internal switch that fixes this bug:

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 na Azure App Service.NET Core 3.0 on Azure App Service

Wdrażanie programu .NET Core do Azure App Service zostało zakończone.The rollout of .NET Core to Azure App Service is finished. Środowisko .NET Core 3,0 jest dostępne we wszystkich Azure App Service centrach danych..NET Core 3.0 is available in all Azure App Service datacenters.