Миграция с ASP.NET Core 2,2 на 3,0Migrate from ASP.NET Core 2.2 to 3.0

• 11/12/2019
• Время чтения: 22 мин
• • 
  • 
  • 

Скотт Эдди ( и Рик Андерсон (By Scott Addie and Rick Anderson

В этой статье объясняется, как обновить существующий проект ASP.NET Core 2,2 до 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.

Необходимые компонентыPrerequisites

Обновление версии пакета SDK для .NET Core в файле global.jsonUpdate .NET Core SDK version in global.json

Если решение использует файл Global. JSON , предназначенный для конкретной версии пакет SDK для .NET Core, обновите свойство version до версии 3,0, установленной на компьютере.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"
  }
}

Обновление файла проектаUpdate the project file

Обновление целевой платформыUpdate the Target Framework

ASP.NET Core 3,0 и более поздних версий работают только в .NET Core.ASP.NET Core 3.0 and later only run on .NET Core. Задайте для моникера целевой платформы (TFM) значение netcoreapp3.0:Set the Target Framework Moniker (TFM) to netcoreapp3.0:

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

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

</Project>

Удалить устаревшие ссылки на пакетыRemove obsolete package references

ASP.NET Core больше не создает большого количества функций пакетов NuGet.ASP.NET Core no longer produces a large number of NuGet packages features. Эти ссылки на пакеты должны быть удалены из файла проекта.These package references should be removed from your project file. Например, созданный шаблоном файл проекта для веб-приложения ASP.NET Core 2,2:For example, the template-generated 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>

Обновленный файл проекта ASP.NET Core 3,0:The updated ASP.NET Core 3.0 project file:

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

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

</Project>

Обновленный файл проекта ASP.NET Core 3,0:The updated ASP.NET Core 3.0 project file:

• В <PropertyGroup>:In the <PropertyGroup>:

  • Обновляет TFM до netcoreapp3.0Updates the TFM to netcoreapp3.0
  • Удаляет элемент <AspNetCoreHostingModel>.Removes the <AspNetCoreHostingModel> element. Дополнительные сведения см. в разделе внутрипроцессного размещения модели в этом документе.For more information, see In-process hosting model in this document.

• В <ItemGroup>:In the <ItemGroup>:

  • Microsoft.AspNetCore.App удалено.Microsoft.AspNetCore.App is removed. Дополнительные сведения см. в справочнике по платформе в этом документе.For more information, see Framework reference in this document.
  • Microsoft.AspNetCore.Razor.Design удалена, и в следующем списке пакетов больше не создается.Microsoft.AspNetCore.Razor.Design is removed and in the following list of packages no longer being produced.

Чтобы просмотреть полный список пакетов, которые больше не создаются, выберите следующий список развертывания:To see the full list of packages that are no longer produced, select the following expand list:

Проверка критических измененийReview breaking changes

Проверка критических измененийReview breaking changes

Справочник по платформеFramework reference

Функции ASP.NET Core, которые были доступны в одном из перечисленных выше пакетов, доступны в составе общей платформы Microsoft.AspNetCore.App.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. Общая платформа — это набор сборок (DLL -файлов), установленных на компьютере и включающий компонент среды выполнения и пакет нацеливания.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. Дополнительную информацию см. в этой публикации об общей платформе.For more information, see The shared framework.

• Проекты, предназначенные для пакета SDK Microsoft.NET.Sdk.Web, неявно ссылаются на платформу Microsoft.AspNetCore.App.Projects that target the Microsoft.NET.Sdk.Web SDK implicitly reference the Microsoft.AspNetCore.App framework.

  Для этих проектов не требуются дополнительные ссылки:No additional references are required for these projects:

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

• Проекты, предназначенные для Microsoft.NET.Sdk или Microsoft.NET.Sdk.Razor пакета SDK, должны добавить явное FrameworkReference в 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>
  

Сборки, зависящие от платформы, с помощью DOCKERFramework-dependent builds using Docker

Зависящие от платформы сборки консольных приложений, использующих пакет, который зависит от ASP.NET Core общей платформы , может предоставить следующую ошибку времени выполнения: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 — это общая платформа, содержащая среду выполнения ASP.NET Core, и она имеется только в образе DOCKER /Core/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. Пакет SDK 3,0 сокращает размер сборок, зависимых от платформы, с помощью asp.net Core, не включая дублированные копии библиотек, доступных в общей платформе.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. Это может привести к экономии до 18 МБ, но для запуска приложения необходимо, чтобы среда выполнения ASP.NET Core присутствовала или была установлена.This is a potential savings of up to 18 MB but it requires that the ASP.NET Core runtime must be present / installed to run the app.

Чтобы определить, имеет ли приложение зависимость (прямую или косвенную) на ASP.NET Core общей платформе, изучите файл runtimeconfig. JSON , созданный во время сборки или публикации приложения.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. В следующем JSON-файле показана зависимость от ASP.NET Core общей платформы: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
    }
  }
}

Если приложение использует DOCKER, используйте базовый образ, включающий ASP.NET Core 3,0.If your app is using docker, use a base image that includes ASP.NET Core 3.0. Например, docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.For example, docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.

Добавление ссылок на пакеты для удаленных сборокAdd package references for removed assemblies

ASP.NET Core 3,0 удаляет некоторые сборки, которые ранее были частью ссылки на пакет Microsoft.AspNetCore.App.ASP.NET Core 3.0 removes some assemblies that were previously part of the Microsoft.AspNetCore.App package reference. Чтобы продолжить использование функций, предоставляемых этими сборками, сослаться на версии 3,0 соответствующих пакетов.To continue using features provided by these assemblies, reference the 3.0 versions of the corresponding packages:

• Веб-приложение, созданное шаблоном с отдельными учетными записями пользователей , требует добавления следующих пакетов:A template-generated web app with Individual User Accounts requires adding the following packages:

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

• Microsoft. EntityFrameworkCoreMicrosoft.EntityFrameworkCore

  Дополнительные сведения об обращении к пакету для конкретного поставщика базы данных см. в разделе поставщики баз данных.For more information on referencing the database provider-specific package, see Database Providers.

• Пользовательский интерфейс удостоверенийIdentity UI

  Поддержку пользовательского интерфейса идентификации можно добавить, обратившись к пакету Microsoft. AspNetCore. Identity. UI .Support for Identity UI can be added by referencing the Microsoft.AspNetCore.Identity.UI package.

• Службы SPASPA Services

  • Microsoft.AspNetCore.SpaServices;Microsoft.AspNetCore.SpaServices
  • Microsoft. AspNetCore. Спасервицес. ExtensionsMicrosoft.AspNetCore.SpaServices.Extensions

• Проверка подлинности –. Поддержка сторонних потоков аутентификации доступна в виде пакетов NuGet:Authentication – Support for third-party authentication flows are available as NuGet packages:

  • Facebook OAuth (Microsoft. AspNetCore. Authentication. Facebook)Facebook OAuth (Microsoft.AspNetCore.Authentication.Facebook)
  • Google OAuth (Microsoft. AspNetCore. Authentication. Google)Google OAuth (Microsoft.AspNetCore.Authentication.Google)
  • Токен носителя OpenID Connect Connect (Microsoft. AspNetCore. Authentication. JwtBearer)OpenID Connect bearer token (Microsoft.AspNetCore.Authentication.JwtBearer)
  • Проверка подлинности учетной записи Майкрософт (Microsoft. AspNetCore. Authentication. MicrosoftAccount)Microsoft Account authentication (Microsoft.AspNetCore.Authentication.MicrosoftAccount)
  • Проверка подлинности OpenID Connect Connect (Microsoft. AspNetCore. Authentication. OpenIdConnect)OpenID Connect authentication (Microsoft.AspNetCore.Authentication.OpenIdConnect)
  • Twitter OAuth (Microsoft. AspNetCore. Authentication. Twitter)Twitter OAuth (Microsoft.AspNetCore.Authentication.Twitter)
  • Проверка подлинности WsFederation (Microsoft. AspNetCore. Authentication. WsFederation)WsFederation authentication (Microsoft.AspNetCore.Authentication.WsFederation)

• Поддержка форматирования и согласования содержимого для System.Net.HttpClient – пакет NuGet Microsoft. AspNet. WebApi. Client предоставляет полезную расширяемость для System.Net.HttpClient с помощью таких интерфейсов API, как ReadAsAsync, PostJsonAsync и т. д.Formatting and content negotiation support for System.Net.HttpClient – The Microsoft.AspNet.WebApi.Client NuGet package provides useful extensibility to System.Net.HttpClient with APIs such as ReadAsAsync, PostJsonAsync etc.

• Компиляция среды выполнения Razor – поддержка компиляции представлений и страниц Razor в среде выполнения теперь является частью Microsoft. AspNetCore. MVC. Razor. рунтимекомпилатион.Razor runtime compilation – Support for runtime compilation of Razor views and pages is now part of Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

• Платформа MVC Newtonsoft.Json поддерживает – поддержку использования MVC с Newtonsoft.Json теперь является частью Microsoft. AspNetCore. MVC. невтонсофтжсон.MVC Newtonsoft.Json support – Support for using MVC with Newtonsoft.Json is now part of Microsoft.AspNetCore.Mvc.NewtonsoftJson.

Изменения при запускеStartup changes

На следующем рисунке показаны удаленные и измененные строки в веб-приложении ASP.NET Core 2,2 Razor Pages.The following image shows the deleted and changed lines in an ASP.NET Core 2.2 Razor Pages Web app:

На предыдущем рисунке удаленный код показан красным цветом.In the preceding image, deleted code is shown in red. Удаленный код не отображает код параметров файла cookie, который был удален до сравнения файлов.The deleted code doesn't show cookie options code, which was deleted prior to comparing the files.

На следующем рисунке показаны добавленные и измененные строки в веб-приложении ASP.NET Core 3,0 Razor Pages.The following image shows the added and changed lines in an ASP.NET Core 3.0 Razor Pages Web app:

На предыдущем рисунке добавлен код, показанный зеленым цветом.In the preceding image, added code is shown in green. Сведения о следующих изменениях:For information on the following changes:

• services.AddMvc в services.AddRazorPages см. в статье Регистрация службы MVC в этом документе.services.AddMvc to services.AddRazorPages, see MVC service registration in this document.
• CompatibilityVersion см. в разделе Совместимая версия для ASP.NET Core MVC.CompatibilityVersion, see Совместимая версия для ASP.NET Core MVC.
• IHostingEnvironment в IWebHostEnvironment см. в этом объявлении GitHub.IHostingEnvironment to IWebHostEnvironment, see this GitHub announcement.
• app.UseAuthorization был добавлен в шаблоны для отображения промежуточного слоя авторизации заказа.app.UseAuthorization was added to the templates to show the order authorization middleware must be added. Если приложение не использует авторизацию, можно безопасно удалить вызов app.UseAuthorization.If the app doesn't use authorization, you can safely remove the call to app.UseAuthorization.
• app.UseEndpoints см. в разделе Razor Pages или Миграция запуска. Настройка в этом документе.app.UseEndpoints, see Razor Pages or Migrate Startup.Configure in this document.

Поддержка анализатораAnalyzer support

Проекты, предназначенные для Microsoft.NET.Sdk.Web, неявно ссылаются на анализаторы, ранее поставляемые в составе пакета Microsoft. AspNetCore. MVC. Analyzers .Projects that target Microsoft.NET.Sdk.Web implicitly reference analyzers previously shipped as part of the Microsoft.AspNetCore.Mvc.Analyzers package. Для включения этих дополнительных ссылок не требуется.No additional references are required to enable these.

Если приложение использует анализаторы API , которые ранее поставлялись с пакетом Microsoft. AspNetCore. MVC. API. Analyzers , измените файл проекта, чтобы он ссылался на анализаторы, поставляемые в составе веб-пакета SDK .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>

Библиотека классов RazorRazor Class Library

Проекты библиотеки классов Razor, предоставляющие компоненты пользовательского интерфейса для MVC, должны устанавливать свойство AddRazorSupportForMvc в файле проекта:Razor Class Library projects that provide UI components for MVC must set the AddRazorSupportForMvc property in the project file:

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

Модель внутрипроцессного размещенияIn-process hosting model

По умолчанию в проектах используется модель внутрипроцессного размещения в ASP.NET Core 3,0 или более поздней версии.Projects default to the in-process hosting model in ASP.NET Core 3.0 or later. При необходимости вы можете удалить свойство <AspNetCoreHostingModel> в файле проекта, если его значение равно InProcess.You may optionally remove the <AspNetCoreHostingModel> property in the project file if its value is InProcess.

KestrelKestrel

Параметр ConfigurationConfiguration

Перенесите конфигурацию Kestrel в построитель веб-узлов, предоставленный 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>();
        });

Если приложение создает узел вручную с HostBuilder, вызовите UseKestrel в построителе веб-узлов в 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();
}

По промежуточного слоя соединения заменяет Адаптеры подключенийConnection Middleware replaces Connection Adapters

Адаптеры подключений (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) были удалены из Kestrel.Connection Adapters (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) have been removed from Kestrel. Замените адаптеры подключений по промежуточного слоя соединения.Replace Connection Adapters with Connection Middleware. По промежуточного слоя соединения аналогично по промежуточного слоя HTTP в ASP.NET Core конвейере, но для соединений более низкого уровня.Connection Middleware is similar to HTTP Middleware in the ASP.NET Core pipeline but for lower-level connections. Протокол HTTPS и регистрация подключения:HTTPS and connection logging:

• Были перемещены из адаптеров соединений в по промежуточного слоя соединения.Have been moved from Connection Adapters to Connection Middleware.
• Эти методы расширения работают как в предыдущих версиях ASP.NET Core.These extension methods work as in previous versions of ASP.NET Core.

Дополнительные сведения см. в примере тлсфилтерконнектионхандлер в разделе листеноптионс. Protocols статьи Kestrel.For more information, see the TlsFilterConnectionHandler example in the ListenOptions.Protocols section of the Kestrel article.

Абстракции транспорта перемещены и сделаны открытымиTransport abstractions moved and made public

Транспортный уровень Kestrel предоставляется как открытый интерфейс в Connections.Abstractions.The Kestrel transport layer has been exposed as a public interface in Connections.Abstractions. В состав этих обновлений:As part of these updates:

• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions и связанные типы были удалены.Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions and associated types have been removed.
• NoDelay был перемещен из ListenOptions в параметры транспорта.NoDelay was moved from ListenOptions to the transport options.
• Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode был удален из KestrelServerOptions.Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode was removed from KestrelServerOptions.

Дополнительные сведения см. в следующих ресурсах GitHub:For more information, see the following GitHub resources:

• Абстракции сети "клиент-сервер" (ASPNET/AspNetCore #10308)Client/server networking abstractions (aspnet/AspNetCore #10308)
• Реализуйте новую абстракцию прослушивателя основой и повторно Plat Kestrel на вершине (ASPNET/AspNetCore #10321)Implement new bedrock listener abstraction and re-plat Kestrel on top (aspnet/AspNetCore #10321)

Заголовков анонса запроса KestrelKestrel Request trailer headers

Для приложений, предназначенных для более ранних версий ASP.NET Core:For apps that target earlier versions of ASP.NET Core:

• Kestrel добавляет заголовки поблочного трейлера HTTP/1.1 в коллекцию заголовков запросов.Kestrel adds HTTP/1.1 chunked trailer headers into the request headers collection.
• Трейлеры доступны после считывания текста запроса в конец.Trailers are available after the request body is read to the end.

Это вызывает некоторые проблемы, связанные с неоднозначностью заголовков и трейлеров, поэтому эти трейлеры были перемещены в новую коллекцию (RequestTrailerExtensions) в 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.

Запросы HTTP/2:HTTP/2 request trailers are:

• Недоступно в ASP.NET Core 2,2.Not available in ASP.NET Core 2.2.
• Доступно в 3,0 как RequestTrailerExtensions.Available in 3.0 as RequestTrailerExtensions.

Для доступа к этим трейлерам имеются новые методы расширения запроса.New request extension methods are present to access these trailers. Как и в случае с HTTP/1.1, трейлеры доступны после считывания текста запроса в конец.As with HTTP/1.1, trailers are available after the request body is read to the end.

Для выпуска 3,0 доступны следующие методы RequestTrailerExtensions:For the 3.0 release, the following RequestTrailerExtensions methods are available:

• GetDeclaredTrailers – получает заголовок Request Trailer, в котором указывается, какие трейлеры должны рассчитываться после текста.GetDeclaredTrailers – Gets the request Trailer header that lists which trailers to expect after the body.
• SupportsTrailers – указывает, поддерживает ли запрос получение заголовков трейлеров.SupportsTrailers – Indicates if the request supports receiving trailer headers.
• CheckTrailersAvailable – проверяет, поддерживает ли запрос трейлеры и доступны ли они для чтения.CheckTrailersAvailable – Checks if the request supports trailers and if they're available to be read. Эта проверка не предполагает наличие трейлеров для чтения.This check doesn't assume that there are trailers to read. Возможно, не существует трейлеров для чтения, даже если этот метод возвращает true.There might be no trailers to read even if true is returned by this method.
• GetTrailer – получает запрошенный конечный заголовок из ответа.GetTrailer – Gets the requested trailing header from the response. Проверьте SupportsTrailers перед вызовом GetTrailer или NotSupportedException может произойти, если запрос не поддерживает конечные заголовки.Check SupportsTrailers before calling GetTrailer, or a NotSupportedException may occur if the request doesn't support trailing headers.

Дополнительные сведения см. в разделе помещение запроса на постановку в отдельную коллекцию (ASPNET/AspNetCore #10410).For more information, see Put request trailers in a separate collection (aspnet/AspNetCore #10410).

Алловсинчронаусио отключенаAllowSynchronousIO disabled

AllowSynchronousIO включает или отключает синхронные API-интерфейсы ввода-вывода, такие как HttpRequest.Body.Read, HttpResponse.Body.Write и Stream.Flush.AllowSynchronousIO enables or disables synchronous IO APIs, such as HttpRequest.Body.Read, HttpResponse.Body.Write, and Stream.Flush. Эти API-интерфейсы являются источником нехватка потоков, ведущих к сбоям приложений.These APIs are a source of thread starvation leading to app crashes. В 3.0 AllowSynchronousIO отключен по умолчанию.In 3.0, AllowSynchronousIO is disabled by default. Дополнительные сведения см. в разделе синхронный ввод-вывод статьи Kestrel.For more information, see the Synchronous IO section in the Kestrel article.

Если требуется синхронный ввод-вывод, его можно включить, настроив параметр AllowSynchronousIO на используемом сервере (при вызове ConfigureKestrel, например при использовании Kestrel).If synchronous IO is needed, it can be enabled by configuring the AllowSynchronousIO option on the server being used (when calling ConfigureKestrel, for example, if using Kestrel). Обратите внимание, что у серверов (Kestrel, HttpSys, TestServer и т. д.) есть собственный параметр AllowSynchronousIO, который не влияет на другие серверы.Note that servers (Kestrel, HttpSys, TestServer, etc.) all have their own AllowSynchronousIO option which won't affect other servers. Синхронный ввод-вывод можно включить для всех серверов на основе каждого запроса с помощью параметра IHttpBodyControlFeature.AllowSynchronousIO:Synchronous IO 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;
}

При возникновении проблем с реализациями TextWriter или другими потоками, которые вызывают синхронные API-интерфейсы в Dispose, вызывайте новый DisposeAsync API.If you have trouble with TextWriter implementations or other streams that call synchronous APIs in Dispose, call the new DisposeAsync API instead.

Дополнительные сведения см. в разделе [объявление] алловсинчронаусио Disabled On All Servers (ASPNET/AspNetCore #7644).For more information, see [Announcement] AllowSynchronousIO disabled in all servers (aspnet/AspNetCore #7644).

Удалена сборка Microsoft. AspNetCore. Server. Kestrel. HTTPSMicrosoft.AspNetCore.Server.Kestrel.Https assembly removed

В ASP.NET Core 2,1 содержимое Microsoft. AspNetCore. Server. Kestrel. HTTPS. dll было перемещено в файл 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. Это не критическое обновление с использованием атрибутов TypeForwardedTo.This was a non-breaking update using TypeForwardedTo attributes. Для 3,0 пустая сборка Microsoft. AspNetCore. Server. Kestrel. HTTPS. dll и пакет NuGet удалены.For 3.0, the empty Microsoft.AspNetCore.Server.Kestrel.Https.dll assembly and the NuGet package have been removed.

Библиотеки, ссылающиеся на Microsoft. AspNetCore. Server. Kestrel. HTTPS , должны обновлять зависимости ASP.NET Core до 2,1 или более поздней версии.Libraries referencing Microsoft.AspNetCore.Server.Kestrel.Https should update ASP.NET Core dependencies to 2.1 or later.

Приложения и библиотеки, предназначенные для ASP.NET Core 2,1 или более поздней версии, должны удалять все прямые ссылки на пакет 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.

Поддержка Json.NETJson.NET support

В рамках работы по улучшению ASP.NET Core общей платформы JSON.NET был удален из ASP.NET Core общей платформы.As part of the work to improve the ASP.NET Core shared framework, Json.NET has been removed from the ASP.NET Core shared framework.

По умолчанию для ASP.NET Core теперь используется System. Text. JSON, который является новым в .net Core 3,0.The default for ASP.NET Core is now System.Text.Json, which is new in .NET Core 3.0. По возможности рекомендуется использовать System.Text.Json.Consider using System.Text.Json when possible. Это высокопроизводительное и не требует дополнительной зависимости библиотеки.It's high-performance and doesn't require an additional library dependency. Однако, поскольку System.Text.Json является новым, в настоящее время могут отсутствовать функции, необходимые для приложения.However, since System.Text.Json is new, it might currently be missing features that your app needs.

Для приложения может потребоваться интеграция Newtonsoft.Json, если в ней используются функции Newtonsoft.Json, такие как Жсонпатч или преобразователи, или если он форматирует типы Newtonsoft.Json.Your app may require Newtonsoft.Json integration if it uses Newtonsoft.Json-specific feature such as JsonPatch or converters or if it formats Newtonsoft.Json-specific types.

Сведения об использовании Json.NET в проекте ASP.NET Core 3,0 SignalR см. в разделе Переключение на Newtonsoft. JSON в этом документе.To use Json.NET in an ASP.NET Core 3.0 SignalR project, see Switch to Newtonsoft.Json in this document.

Чтобы использовать Json.NET в проекте ASP.NET Core 3,0, выполните следующие действия.To use Json.NET in an ASP.NET Core 3.0 project:

• Добавьте ссылку на пакет в Microsoft.AspNetCore.Mvc.NewtonsoftJson.Add a package reference to Microsoft.AspNetCore.Mvc.NewtonsoftJson.

• Обновите Startup.ConfigureServices, чтобы вызвать AddNewtonsoftJson.Update Startup.ConfigureServices to call AddNewtonsoftJson.

  services.AddMvc()
      .AddNewtonsoftJson();
  

  AddNewtonsoftJson совместим с новыми методами регистрации службы MVC:AddNewtonsoftJson is compatible with the new MVC service registration methods:

  • AddRazorPages
  • AddControllersWithViews
  • AddControllers

  services.AddControllers()
      .AddNewtonsoftJson();
  

  Параметры Json.NET можно задать в вызове AddNewtonsoftJson:Json.NET settings can be set in the call to AddNewtonsoftJson:

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

Регистрация службы MVCMVC service registration

ASP.NET Core 3,0 добавляет новые параметры для регистрации сценариев MVC в Startup.ConfigureServices.ASP.NET Core 3.0 adds new options for registering MVC scenarios inside Startup.ConfigureServices.

Доступны три новых метода расширения верхнего уровня, связанные с сценариями MVC на IServiceCollection.Three new top-level extension methods related to MVC scenarios on IServiceCollection are available. Шаблоны используют эти новые методы вместо AddMvc.Templates use these new methods instead of AddMvc. Однако AddMvc продолжит вести себя так же, как в предыдущих выпусках.However, AddMvc continues to behave as it has in previous releases.

В следующем примере добавлена поддержка контроллеров и функций, связанных с API, но не представлений и страниц.The following example adds support for controllers and API-related features, but not views or pages. Шаблон API использует следующий код:The API template uses this code:

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

В следующем примере добавлена поддержка контроллеров, функций, связанных с API, и представлений, но не страниц.The following example adds support for controllers, API-related features, and views, but not pages. В шаблоне веб-приложения (MVC) используется следующий код:The Web Application (MVC) template uses this code:

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

В следующем примере добавлена поддержка Razor Pages и минимальной поддержки контроллера.The following example adds support for Razor Pages and minimal controller support. В шаблоне веб-приложения используется следующий код:The Web Application template uses this code:

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

Новые методы также можно сочетать.The new methods can also be combined. Следующий пример эквивалентен вызову AddMvc в 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();
}

Код запуска маршрутизацииRouting startup code

Если приложение вызывает UseMvc или UseSignalR, перенесите приложение в службу маршрутизации конечных точек , если это возможно.If an app calls UseMvc or UseSignalR, migrate the app to Endpoint Routing if possible. Чтобы улучшить совместимость маршрутизации конечных точек с предыдущими версиями MVC, мы отправили некоторые изменения в формировании URL-адресов, появившиеся в 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. Если у вас возникли проблемы с маршрутизацией конечных точек в 2,2, предполагаю, что улучшения ASP.NET Core 3,0, за исключением следующих:If you experienced problems using Endpoint Routing in 2.2, expect improvements in ASP.NET Core 3.0 with the following exceptions:

• Если приложение реализует IRouter или наследует от Route, используйте динамикраутевалуестрансформер в качестве замены.If the app implements IRouter or inherits from Route, use DynamicRouteValuesTransformer as the replacement.

• Если приложение получает прямой доступ к RouteData.Routers в MVC для анализа URL-адресов, его можно заменить на использование LinkParser.ParsePathByEndpointName.If the app directly accesses RouteData.Routers inside MVC to parse URLs, you can replace this with use of LinkParser.ParsePathByEndpointName.

• Определите маршрут с именем маршрута.Define the route with a route name.

• Используйте LinkParser.ParsePathByEndpointName и передайте имя нужного маршрута.Use LinkParser.ParsePathByEndpointName and pass in the desired route name.

Маршрутизация конечных точек поддерживает тот же синтаксис шаблона маршрута и функции создания шаблона маршрута, что и IRouter.Endpoint Routing supports the same route pattern syntax and route pattern authoring features as IRouter. Маршрутизация конечных точек поддерживает IRouteConstraint.Endpoint Routing supports IRouteConstraint. Маршрутизация конечных точек поддерживает [Route], [HttpGet]и другие атрибуты маршрутизации MVC.Endpoint routing supports [Route], [HttpGet], and the other MVC routing attributes.

Для большинства приложений только Startup требует внесения изменений.For most applications, only Startup requires changes.

Миграция запуска. НастройкаMigrate Startup.Configure

Общие рекомендации:General advice:

• Добавьте UseRouting.Add UseRouting.

• Если приложение вызывает UseStaticFiles, поместите UseStaticFiles перед UseRouting.If the app calls UseStaticFiles, place UseStaticFiles before UseRouting.

• Если приложение использует функции проверки подлинности и авторизации, такие как AuthorizePage или [Authorize], поместите вызов в UseAuthentication и UseAuthorization: After, UseRouting и UseCors, но до 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();
    });
  

• Замените UseMvc или UseSignalR на UseEndpoints.Replace UseMvc or UseSignalR with UseEndpoints.

• Если приложение использует сценарии CORS , например [EnableCors], поместите вызов UseCors перед любым другим по промежуточного слоя, использующим CORS (например UseCors, перед UseAuthentication, UseAuthorizationи 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).

• Замените IHostingEnvironment на IWebHostEnvironment и добавьте оператор using для пространства имен Microsoft.Extensions.Hosting.Replace IHostingEnvironment with IWebHostEnvironment and add a using statement for the Microsoft.Extensions.Hosting namespace.

• Замените IApplicationLifetime на IHostApplicationLifetime (пространство имен Microsoft.Extensions.Hosting).Replace IApplicationLifetime with IHostApplicationLifetime (Microsoft.Extensions.Hosting namespace).

• Замените EnvironmentName на Environments (пространство имен Microsoft.Extensions.Hosting).Replace EnvironmentName with Environments (Microsoft.Extensions.Hosting namespace).

Ниже приведен пример кода Startup.Configure в типичном приложении 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?}");
    });
}

После обновления предыдущего кода Startup.Configure: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?}");
    });
}

Проверки работоспособностиHealth Checks

Для проверок работоспособности используется маршрутизация конечных точек с универсальным узлом.Health Checks use endpoint routing with the Generic Host. В Startup.Configure вызовите MapHealthChecks для построителя конечной точки с URL-адресом конечной точки или относительным путем:In Startup.Configure, call MapHealthChecks on the endpoint builder with the endpoint URL or relative path:

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

Конечные точки проверки работоспособности могут:Health Checks endpoints can:

• указать один или несколько разрешенных узлов или портов;Specify one or more permitted hosts/ports.
• требовать авторизацию;Require authorization.
• требовать CORS.Require CORS.

Для получения дополнительной информации см. Проверки работоспособности в ASP.NET Core.For more information, see Проверки работоспособности в ASP.NET Core.

Руководство по по промежуточного слоя безопасностиSecurity middleware guidance

Поддержка авторизации и CORS унифицирована на основе подхода по промежуточного слоя .Support for authorization and CORS is unified around the middleware approach. Это позволяет использовать одно и то же по промежуточного слоя и функциональные возможности в этих сценариях.This allows use of the same middleware and functionality across these scenarios. В этом выпуске реализовано обновленное по по промежуточного слоя авторизации, а по промежуточного слоя CORS улучшено, чтобы он мог понять, какие атрибуты используются контроллерами 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

Ранее CORS было сложно настроить.Previously, CORS could be difficult to configure. По промежуточного слоя было предоставлено для использования в некоторых случаях, но фильтры MVC предназначены для использования без по промежуточного слоя в других вариантах использования.Middleware was provided for use in some use cases, but MVC filters were intended to be used without the middleware in other use cases. В ASP.NET Core 3,0 рекомендуется, чтобы все приложения, требующие CORS, использовали по промежуточного слоя CORS в сочетании с маршрутизацией конечных точек.With ASP.NET Core 3.0, we recommend that all apps that require CORS use the CORS Middleware in tandem with Endpoint Routing. UseCors может быть предоставлена с политикой по умолчанию, а атрибуты [EnableCors] и [DisableCors] можно использовать для переопределения политики по умолчанию, если это необходимо.UseCors can be provided with a default policy, and [EnableCors] and [DisableCors] attributes can be used to override the default policy where required.

В следующем примере:In the following example:

• CORS включается для всех конечных точек с именованной политикой default.CORS is enabled for all endpoints with the default named policy.
• Класс MyController отключает CORS с помощью атрибута [DisableCors].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
{
    ...
}

АвторизацияAuthorization

В более ранних версиях ASP.NET Core Поддержка авторизации была предоставлена с помощью атрибута [Authorize].In earlier versions of ASP.NET Core, authorization support was provided via the [Authorize] attribute. По промежуточного слоя авторизации недоступно.Authorization middleware wasn't available. В ASP.NET Core 3,0 требуется по промежуточного слоя авторизации.In ASP.NET Core 3.0, authorization middleware is required. Рекомендуется размещать ASP.NET Core по промежуточного слоя авторизации (UseAuthorization) сразу после UseAuthentication.We recommend placing the ASP.NET Core Authorization Middleware (UseAuthorization) immediately after UseAuthentication. По промежуточного слоя авторизации также можно настроить политику по умолчанию, которую можно переопределить.The Authorization Middleware can also be configured with a default policy, which can be overridden.

В ASP.NET Core 3,0 или более поздней версии UseAuthorization вызывается в Startup.Configure, а для следующего HomeController требуется пользователь, выполнивший вход: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 : ControllerBase
{
    [Authorize]
    public IActionResult BuyWidgets()
    {
        ...
    }
}

Если приложение использует AuthorizeFilter в качестве глобального фильтра в MVC, рекомендуется выполнить рефакторинг кода, чтобы предоставить политику в вызове 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.

Изначально DefaultPolicy настроена для обязательной проверки подлинности, поэтому дополнительная настройка не требуется.The DefaultPolicy is initially configured to require authentication, so no additional configuration is required. В следующем примере конечные точки MVC помечаются как RequireAuthorization, поэтому все запросы должны быть разрешены на основе DefaultPolicy.In the following example, MVC endpoints are marked as RequireAuthorization so that all requests must be authorized based on the DefaultPolicy. Однако HomeController предоставляет доступ без входа пользователя в приложение из-за [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 : ControllerBase
{
    ...
}

Политики также можно настроить.Policies can also be customized. Основываясь на предыдущем примере, DefaultPolicy настроена для требования проверки подлинности и определенной области:Building upon the previous example, the DefaultPolicy is configured to require authentication and a specific scope:

public void ConfigureServices(IServiceCollection services)
{
    ...

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

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

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

Кроме того, для всех конечных точек можно настроить требование авторизации без [Authorize] или RequireAuthorization, настроив FallbackPolicy.Alternatively, all endpoints can be configured to require authorization without [Authorize] or RequireAuthorization by configuring a FallbackPolicy. FallbackPolicy отличается от DefaultPolicy.The FallbackPolicy is different from the DefaultPolicy. DefaultPolicy активируется [Authorize] или RequireAuthorization, а FallbackPolicy активируется, если не задана другая политика.The DefaultPolicy is triggered by [Authorize] or RequireAuthorization, while the FallbackPolicy is triggered when no other policy is set. FallbackPolicy изначально настроен на разрешение запросов без авторизации.FallbackPolicy is initially configured to allow requests without authorization.

Следующий пример аналогичен приведенному выше DefaultPolicy примере, но использует FallbackPolicy, чтобы всегда требовать проверку подлинности для всех конечных точек, за исключением случаев, когда [AllowAnonymous] указана: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 : ControllerBase
{
    ...
}

Авторизация по промежуточного слоя работает без каких бы то ни было конкретных знаний авторизации.Authorization by middleware works without the framework having any specific knowledge of authorization. Например, проверки работоспособности не имеют определенных знаний авторизации, но проверки работоспособности могут иметь настраиваемую политику авторизации по промежуточного слоя.For instance, health checks has no specific knowledge of authorization, but health checks can have a configurable authorization policy applied by the middleware.

Кроме того, каждая конечная точка может настраивать свои требования к авторизации.Additionally, each endpoint can customize its authorization requirements. В следующем примере UseAuthorization обрабатывает авторизацию с DefaultPolicy, но для конечной точки проверки работоспособности /healthz требуется пользователь admin: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", });
    });
}

Защита реализована в некоторых сценариях.Protection is implemented for some scenarios. По промежуточного слоя конечных точек создает исключение, если политика авторизации или CORS пропускается из-за отсутствия по промежуточного слоя.Endpoints Middleware throws an exception if an authorization or CORS policy is skipped due to missing middleware. Поддержка анализатора для предоставления дополнительных отзывов о ненастроенном состоянии.Analyzer support to provide additional feedback about misconfiguration is in progress.

Пользовательские обработчики авторизацииCustom authorization handlers

Если приложение использует пользовательские обработчики авторизации, имейте в виду, что маршрутизация конечных точек передает обработчикам различные типы ресурсов, чем MVC.If the app uses custom authorization handlers, be aware that endpoint routing passes a different resource type to handlers than MVC. Обработчики, которые предполагают, что ресурс контекста обработчика авторизации имеет тип AuthorizationFilterContext (тип ресурса, предоставляемый фильтрами MVC), необходимо обновить для обработки ресурсов типа RouteEndpoint (тип ресурса, предоставленный для обработчиков авторизации по маршрутизации конечной точки).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 по-прежнему использует ресурсы AuthorizationFilterContext, поэтому, если приложение использует фильтры авторизации MVC вместе с авторизацией маршрутизации конечных точек, может потребоваться обрабатывать оба типа ресурсов.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

Сопоставление концентраторов SignalR теперь выполняется в UseEndpoints.Mapping of SignalR hubs now takes place inside UseEndpoints.

Сопоставьте каждый концентратор с MapHub.Map each hub with MapHub. Как и в предыдущих версиях, каждый концентратор явно указан.As in previous versions, each hub is explicitly listed.

В следующем примере добавляется поддержка центра SignalR ChatHub: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>();
    });
}

Существует новый параметр управления ограничениями на размер сообщений от клиентов.There is a new option for controlling message size limits from clients. Например, в Startup.ConfigureServices:For example, in Startup.ConfigureServices:

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

В ASP.NET Core 2,2 можно установить TransportMaxBufferSize и эффективно управлять максимальным размером сообщения.In ASP.NET Core 2.2, you could set the TransportMaxBufferSize and that would effectively control the maximum message size. В ASP.NET Core 3,0 этот параметр теперь позволяет управлять только максимальным размером до подавления нехватки.In ASP.NET Core 3.0, that option now only controls the maximum size before backpressure is observed.

Контроллеры MVCMVC controllers

Теперь сопоставление контроллеров выполняется в UseEndpoints.Mapping of controllers now takes place inside UseEndpoints.

Добавьте MapControllers, если приложение использует маршрутизацию атрибутов.Add MapControllers if the app uses attribute routing. Так как маршрутизация включает поддержку многих платформ в ASP.NET Core 3,0 или более поздней версии, Добавление контроллеров с маршрутизацией с атрибутами является явным согласием.Since routing includes support for many frameworks in ASP.NET Core 3.0 or later, adding attribute-routed controllers is opt-in.

Замените следующее:Replace the following:

• MapRoute с MapControllerRouteMapRoute with MapControllerRoute
• MapAreaRoute с MapAreaControllerRouteMapAreaRoute with MapAreaControllerRoute

Так как маршрутизация теперь включает поддержку не только для MVC, терминология была изменена, чтобы эти методы были четко изменяли то, что они делают.Since routing now includes support for more than just MVC, the terminology has changed to make these methods clearly state what they do. Стандартные маршруты, такие как MapControllerRoute / MapAreaControllerRoute / MapDefaultControllerRoute, применяются в порядке их добавления.Conventional routes such as MapControllerRoute/MapAreaControllerRoute/MapDefaultControllerRoute are applied in the order that they're added. Сначала разместите более конкретные маршруты (например, маршруты для области).Place more specific routes (such as routes for an area) first.

В следующем примере:In the following example:

• MapControllers добавляет поддержку контроллеров с маршрутизацией на основе атрибутов.MapControllers adds support for attribute-routed controllers.
• MapAreaControllerRoute добавляет стандартный маршрут для контроллеров в области.MapAreaControllerRoute adds a conventional route for controllers in an area.
• MapControllerRoute добавляет стандартный маршрут для контроллеров.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?}");
    });
}

Удаление асинхронного суффикса из имен действий контроллераAsync suffix removal from controller action names

В ASP.NET Core 3,0 ASP.NET Core MVC удаляет суффикс Async из имен действий контроллера.In ASP.NET Core 3.0, ASP.NET Core MVC removes the Async suffix from controller action names. Это новое значение по умолчанию затрагивает маршрутизацию и создание ссылок.Both routing and link generation are impacted by this new default. Пример:For example:

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

До ASP.NET Core 3,0:Prior to ASP.NET Core 3.0:

• Предыдущее действие можно было получить в маршруте Products/ListAsync .The preceding action could be accessed at the Products/ListAsync route.

• Требуется создание ссылки с указанием суффикса Async.Link generation required specifying the Async suffix. Пример:For example:

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

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

• Предыдущее действие можно получить с помощью маршрута Products/List .The preceding action can be accessed at the Products/List route.

• Для создания канала не требуется указывать суффикс Async.Link generation doesn't require specifying the Async suffix. Пример:For example:

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

Это изменение не влияет на имена, указанные с помощью атрибута [ActionName] .This change doesn't affect names specified using the [ActionName] attribute. Поведение по умолчанию можно отключить с помощью следующего кода в Startup.ConfigureServices:The default behavior can be disabled with the following code in Startup.ConfigureServices:

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

Изменения в поколении ссылокChanges to link generation

Как описано в документации по различиям между предыдущими версиями маршрутизации, существуют некоторые различия в создании ссылок (например, с помощью Url.Link и аналогичных интерфейсов 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). Сюда входит следующее.These include:

• По умолчанию при использовании маршрутизации конечных точек регистр параметров маршрута в созданных URI не обязательно сохраняется.By default, when using endpoint routing, casing of route parameters in generated URIs is not necessarily preserved. Это поведение можно контролировать с помощью интерфейса IOutboundParameterTransformer.This behavior can be controlled with the IOutboundParameterTransformer interface.
• Создание URI для недопустимого маршрута (несуществующий контроллер, действие или страница) создаст пустую строку в разделе "Маршрутизация конечных точек" вместо создания недопустимого 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.
• Значения окружения (параметры маршрута из текущего контекста) не используются автоматически в создании ссылок с маршрутизацией конечных точек.Ambient values (route parameters from the current context) are not automatically used in link generation with endpoint routing. Ранее при создании ссылки на другое действие (или страницу) неопределенные значения маршрута выводятся из значений окружающей среды текущих маршрутов.Previously, when generating a link to another action (or page), unspecified route values would be inferred from the current routes ambient values. При использовании маршрутизации конечных точек все параметры маршрута должны быть заданы явным образом во время создания ссылки.When using endpoint routing, all route parameters must be specified explicitly during link generation.

Razor PagesRazor Pages

Сопоставление Razor Pages теперь выполняется в UseEndpoints.Mapping Razor Pages now takes place inside UseEndpoints.

Добавьте MapRazorPages, если приложение использует Razor Pages.Add MapRazorPages if the app uses Razor Pages. Так как маршрутизация конечных точек включает поддержку многих платформ, добавление Razor Pages теперь является явной.Since Endpoint Routing includes support for many frameworks, adding Razor Pages is now opt-in.

В следующем методе Startup.Configure MapRazorPages добавляет поддержку Razor Pages:In the following Startup.Configure method, MapRazorPages adds support for Razor Pages:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

Использовать MVC без маршрутизации конечных точекUse MVC without Endpoint Routing

Использование MVC с помощью UseMvc или UseMvcWithDefaultRoute в ASP.NET Core 3,0 требует явного согласия внутри Startup.ConfigureServices.Using MVC via UseMvc or UseMvcWithDefaultRoute in ASP.NET Core 3.0 requires an explicit opt-in inside Startup.ConfigureServices. Это необходимо, так как MVC должен определить, может ли он полагаться на по промежуточного слоя авторизации и CORS во время инициализации.This is required because MVC must know whether it can rely on the authorization and CORS Middleware during initialization. Предоставляется анализатор, предупреждающий, попытается ли приложение использовать неподдерживаемую конфигурацию.An analyzer is provided that warns if the app attempts to use an unsupported configuration.

Если для приложения требуется устаревшая поддержка IRouter, отключите EnableEndpointRouting, используя любой из следующих подходов в 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);

Проверки работоспособностиHealth checks

Проверки работоспособности можно использовать в качестве маршрутизатора — вредоносные программы с маршрутизацией конечных точек.Health checks can be used as a router-ware with Endpoint Routing.

Добавьте MapHealthChecks, чтобы использовать проверки работоспособности с маршрутизацией конечных точек.Add MapHealthChecks to use health checks with Endpoint Routing. Метод MapHealthChecks принимает аргументы, аналогичные UseHealthChecks.The MapHealthChecks method accepts arguments similar to UseHealthChecks. Преимуществом использования MapHealthChecks поверх UseHealthChecks является возможность применения авторизации и более точного контроля над политикой сопоставления.The advantage of using MapHealthChecks over UseHealthChecks is the ability to apply authorization and to have greater fine-grained control over the matching policy.

В следующем примере для конечной точки проверки работоспособности в /healthz вызывается MapHealthChecks: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() { });
    });
}

Хостбуилдер заменяет WebHostBuilderHostBuilder replaces WebHostBuilder

Шаблоны ASP.NET Core 3,0 используют универсальный узел.The ASP.NET Core 3.0 templates use Generic Host. В предыдущих версиях использовался веб-узел.Previous versions used Web Host. В следующем коде показан шаблон ASP.NET Core 3,0, созданный 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>();
            });
}

В следующем коде показан класс ASP.NET Core 2,2, созданный шаблоном 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 остается в 3,0 и является типом webBuilder, показанным в предыдущем примере кода.IWebHostBuilder remains in 3.0 and is the type of the webBuilder seen in the preceding code sample. WebHostBuilder будет считаться устаревшим в будущих выпусках и заменено на HostBuilder.WebHostBuilder will be deprecated in a future release and replaced by HostBuilder.

Наиболее существенным изменением с WebHostBuilder до HostBuilder является внедрение зависимостей (DI).The most significant change from WebHostBuilder to HostBuilder is in dependency injection (DI). При использовании HostBuilderв конструктор Startupможно ввести только следующее:When using HostBuilder, you can only inject the following into Startup's constructor:

• IConfiguration
• Microsoft.Extensions.Hosting.IHostEnvironment
• IWebHostEnvironment

Ограничения на DI HostBuilder:The HostBuilder DI constraints:

• Включите построение контейнера DI только один раз.Enable the DI container to be built only one time.
• Позволяет избежать итоговых проблем со временем существования объектов, таких как разрешение нескольких экземпляров Singleton.Avoids the resulting object lifetime issues like resolving multiple instances of singletons.

Аддаусоризатион перемещен в другую сборкуAddAuthorization moved to a different assembly

Методы ASP.NET Core 2,2 и ниже AddAuthorization в Microsoft. AspNetCore. Authorization. dll:The ASP.NET Core 2.2 and lower AddAuthorization methods in Microsoft.AspNetCore.Authorization.dll:

• Были переименованы AddAuthorizationCore.Have been renamed AddAuthorizationCore.
• Были перемещены в Microsoft. AspNetCore. Authorization. Policy. dll.Have been moved to Microsoft.AspNetCore.Authorization.Policy.dll.

Приложения, использующие Microsoft. AspNetCore. Authorization. dll и Microsoft. AspNetCore. Authorization. Policy. dll , не затрагиваются.Apps that are using both Microsoft.AspNetCore.Authorization.dll and Microsoft.AspNetCore.Authorization.Policy.dll aren't impacted.

Приложения, которые не используют Microsoft. AspNetCore. Authorization. Policy. dll , должны выполнять одно из следующих действий:Apps that are not using Microsoft.AspNetCore.Authorization.Policy.dll should do one of the following:

• Добавьте ссылку на Microsoft. AspNetCore. Authorization. Policy. dll.Add a reference to Microsoft.AspNetCore.Authorization.Policy.dll. Этот подход работает для большинства приложений и является обязательным.This approach works for most apps and is all that is required.
• Переключиться на использование AddAuthorizationCoreSwitch to using AddAuthorizationCore

Дополнительные сведения см. в разделе критическое изменение перегрузки AddAuthorization(o =>) находится в другой сборке #386.For more information, see Breaking change in AddAuthorization(o =>) overload lives in a different assembly #386.

Пользовательский интерфейс удостоверенийIdentity UI

Обновления пользовательского интерфейса удостоверений для ASP.NET Core 3,0:Identity UI updates for ASP.NET Core 3.0:

• Добавьте ссылку на пакет в Microsoft. AspNetCore. Identity. UI.Add a package reference to Microsoft.AspNetCore.Identity.UI.
• Приложения, которые не используют Razor Pages, должны вызывать MapRazorPages.Apps that don't use Razor Pages must call MapRazorPages. См. Razor Pages в этом документе.See Razor Pages in this document.
• Начальная загрузка 4 является инфраструктурой пользовательского интерфейса по умолчанию.Bootstrap 4 is the default UI framework. Задайте свойство проекта IdentityUIFrameworkVersion, чтобы изменить значение по умолчанию.Set an IdentityUIFrameworkVersion project property to change the default. Дополнительные сведения см. в этом объявлении GitHub.For more information, see this GitHub announcement.

SignalR

SignalR клиент JavaScript изменился с @aspnet/signalr на @microsoft/signalr.The SignalR JavaScript client has changed from @aspnet/signalr to @microsoft/signalr. Чтобы реагировать на это изменение, измените ссылки в файлах Package. JSON , require, а также в инструкциях ECMAScript import.To react to this change, change the references in package.json files, require statements, and ECMAScript import statements.

System. Text. JSON является протоколом по умолчаниюSystem.Text.Json is the default protocol

System.Text.Json теперь является протоколом концентратора по умолчанию, используемым как клиентом, так и сервером.System.Text.Json is now the default Hub protocol used by both the client and server.

В Startup.ConfigureServices вызовите AddJsonProtocol, чтобы задать параметры сериализатора.In Startup.ConfigureServices, call AddJsonProtocol to set serializer options.

СерверомServer:

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

Клиент:Client:

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

Переключиться на Newtonsoft. JSONSwitch to Newtonsoft.Json

Если вы используете функции Newtonsoft.Json, которые не поддерживаются в System.Text.Json, можно переключиться обратно на 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:

1. Установите Microsoft. AspNetCore.SignalR. Пакет NuGet protocols. Невтонсофтжсон .Install the Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson NuGet package.

2. На клиенте привязать вызов метода AddNewtonsoftJsonProtocol к экземпляру HubConnectionBuilder:On the client, chain an AddNewtonsoftJsonProtocol method call to the HubConnectionBuilder instance:

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

3. На сервере привязать вызов метода AddNewtonsoftJsonProtocol к вызову метода AddSignalR в Startup.ConfigureServices:On the server, chain an AddNewtonsoftJsonProtocol method call to the AddSignalR method call in Startup.ConfigureServices:

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

Согласие на компиляцию среды выполненияOpt in to runtime compilation

До ASP.NET Core 3,0, компиляция представлений во время выполнения была неявной функцией платформы.Prior to ASP.NET Core 3.0, runtime compilation of views was an implicit feature of the framework. Компиляция среды выполнения дополняет компиляцию представлений во время сборки.Runtime compilation supplements build-time compilation of views. Она позволяет платформе компилировать представления Razor и страницы (CSHTML -файлы) при изменении файлов без необходимости перестроения всего приложения.It allows the framework to compile Razor views and pages (.cshtml files) when the files are modified, without having to rebuild the entire app. Эта функция поддерживает сценарий выполнения быстрого редактирования в интегрированной среде разработки и обновления браузера для просмотра изменений.This feature supports the scenario of making a quick edit in the IDE and refreshing the browser to view the changes.

В ASP.NET Core 3,0 компиляция среды выполнения является сценарием согласия.In ASP.NET Core 3.0, runtime compilation is an opt-in scenario. Компиляция во время сборки — единственный механизм для просмотра компиляции, включенный по умолчанию.Build-time compilation is the only mechanism for view compilation that's enabled by default. Среда выполнения полагается на Visual Studio или DotNet-Watch в Visual Studio Code, чтобы перестроить проект, когда обнаруживает изменения в 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. В Visual Studio изменения в файлах CS, CSHTMLили Razor в выполняемом проекте (CTRL + F5), но не в режиме отладки (F5) активируют повторную компиляцию проекта.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.

Включение компиляции во время выполнения в проекте ASP.NET Core 3,0:To enable runtime compilation in your ASP.NET Core 3.0 project:

1. установить пакет NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.Install the Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation NuGet package.

2. Обновите Startup.ConfigureServices, чтобы вызвать AddRazorRuntimeCompilation:Update Startup.ConfigureServices to call AddRazorRuntimeCompilation:

   Для ASP.NET Core MVC используйте следующий код:For ASP.NET Core MVC, use the following code:

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

   Для ASP.NET Core Razor Pages используйте следующий код:For ASP.NET Core Razor Pages, use the following code:

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

Пример в https://github.com/aspnet/samples/tree/master/samples/aspnetcore/mvc/runtimecompilation показывает пример включения условия компиляции среды выполнения в средах разработки.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.

Дополнительные сведения о компиляции файла Razor см. в разделе Компиляция файлов Razor в ASP.NET Core.For more information on Razor file compilation, see Компиляция файлов Razor в ASP.NET Core.

Миграция библиотек через многоплатформенную нацеливаниеMigrate libraries via multi-targeting

Библиотекам часто требуется поддержка нескольких версий ASP.NET Core.Libraries often need to support multiple versions of ASP.NET Core. Большинство библиотек, которые были скомпилированы в предыдущих версиях ASP.NET Core, должны продолжать работать без проблем.Most libraries that were compiled against previous versions of ASP.NET Core should continue working without issues. Для следующих условий требуется перекрестная компиляция приложения:The following conditions require the app to be cross-compiled:

• Библиотека использует функцию с двоичным критическим изменением.The library relies on a feature that has a binary breaking change.
• Библиотека хочет воспользоваться преимуществами новых функций в ASP.NET Core 3,0.The library wants to take advantage of new features in ASP.NET Core 3.0.

Пример: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>

Чтобы включить API-интерфейсы ASP.NET Core 3,0, используйте #ifdefs: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

ПубликацияPublish

Удалите папки bin и obj в каталоге проекта.Delete the bin and obj folders in the project directory.

TestServerTestServer

Для приложений, которые используют TestServer непосредственно с универсальным узлом, создайте TestServer на IWebHostBuilder в 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);
}

Прерывание изменений APIBreaking API changes

Ознакомьтесь с критическими изменениями:Review breaking changes:

• Полный список критических изменений в выпуске ASP.NET Core 3,0Complete list of breaking changes in the ASP.NET Core 3.0 release
• Прерывание изменений API в подделке, CORS, диагностике, MVC и маршрутизации.Breaking API changes in Antiforgery, CORS, Diagnostics, MVC, and Routing. Этот список содержит критические изменения для параметров совместимости.This list includes breaking changes for compatibility switches.
• Сводные сведения о критических изменениях 2,2-3,0 в .NET Core, ASP.NET Core и Entity Framework Core см. в разделе критические изменения для миграции с версии 2,2 на 3,0.For a summary of 2.2-to-3.0 breaking changes across .NET Core, ASP.NET Core, and Entity Framework Core, see Breaking changes for migration from version 2.2 to 3.0.
• Некоторые файлы cookie SameSite значения по умолчанию изменены на None (ASPNET/Announcements #348).Some Cookie SameSite defaults changed to None (aspnet/Announcements #348).

.NET Core 3,0 в службе приложений Azure.NET Core 3.0 on Azure App Service

Сведения о ходе развертывания .NET Core в службе приложений Azure см. на странице официальное приложение .NET Core на веб-сайте службы приложений.For progress on the rollout of .NET Core to Azure App Service, see the official .NET Core on App Service website. Пока .NET Core 3,0 не будет доступен в службе приложений Azure, следуйте инструкциям в статье развертывание ASP.NET Core предварительной версии в службе приложений Azure.Until .NET Core 3.0 is available on Azure App Service, follow the instructions at Deploy ASP.NET Core preview release to Azure App Service. Аддаусоризатион перемещен в другую сборкуAddAuthorization moved to a different assembly