Миграция из ASP.NET Core в .NET 7 в .NET 8

В этой статье объясняется, как обновить существующий ASP.NET Core в проекте .NET 7 до .NET 8.

Предпосылки

  • Visual Studio 2022 с рабочей нагрузкой ASP.NET и разработка веб-приложений.

    Рабочие нагрузки установщика VS22

Обновление версии пакета SDK для .NET в global.json

Если вы используете global.json файл, нацеленный на определённую версию .NET SDK, обновите version свойство до версии SDK для .NET 8, которая в данный момент установлена. Рассмотрим пример.

{
  "sdk": {
-    "version": "7.0.100"
+    "version": "8.0.100"
  }
}

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

Обновите идентификатор целевой платформы (TFM) в файле проекта на:net8.0

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

  <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

</Project>

Обновление ссылок на пакеты

В файле проекта обновите атрибут Microsoft.AspNetCore.* каждой ссылки на пакеты Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*, System.Net.Http.Json и Version до версии 8.0.0 или более поздней. Рассмотрим пример.

<ItemGroup>
-   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="7.0.12" />
-   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.12" />
-   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="7.0.0" />
-   <PackageReference Include="System.Net.Http.Json" Version="7.0.1" />
+   <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="8.0.0" />
+   <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="8.0.0" />
+   <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="8.0.0" />
+   <PackageReference Include="System.Net.Http.Json" Version="8.0.0" />
</ItemGroup>

Blazor

Рассматриваются следующие сценарии миграции:

Рекомендации по добавлению Blazor поддержки в приложение ASP.NET Core см. в статье "Интеграция компонентов ASP.NET Core Razor с MVC или Razor Pages".

Blazor Server Обновление приложения

Рекомендуется использовать Blazor Web Apps в .NET 8, но Blazor Server поддерживается. Чтобы продолжить использование Blazor Server с .NET 8, следуйте инструкциям в первых трех разделах этой статьи:

Новые Blazor функции, представленные для приложенийBlazor Web App, недоступны для Blazor Serverзапуска в .NET 8. Если вы хотите внедрить новые функции .NET 8 Blazor , следуйте инструкциям в любом из следующих разделов:

Принятие всех Blazor Web App соглашений

Чтобы при необходимости принять все новые Blazor Web App соглашения, рекомендуется выполнить следующий процесс:

  • Создайте приложение из Blazor Web App шаблона проекта. Дополнительные сведения см. в разделе "Инструменты для ASP.NET Core Blazor".
  • Переместите компоненты и код приложения в новый Blazor Web App, внося изменения в новые функции.
  • Обновите макет и стили объекта Blazor Web App.

Новые функции .NET 8 рассматриваются в новых возможностях ASP.NET Core в .NET 8. При обновлении приложения с .NET 6 или более ранней версии, см. заметки о миграции и выпуске (статьи Что нового) для промежуточных выпусков.

Blazor Server Преобразование приложения в приложениеBlazor Web App

Blazor Server приложения поддерживаются в .NET 8 без каких-либо изменений кода. Используйте следующее руководство, чтобы преобразовать Blazor Server приложение в эквивалентный .NET 8, что делает все Blazor Web App .NET 8 доступными.

Это важно

В этом разделе рассматриваются минимальные изменения, необходимые для преобразования приложения .NET 7 Blazor Server в .NET 8 Blazor Web App. Чтобы принять все новые Blazor Web App соглашения, следуйте указаниям в разделе "Принятие всех Blazor Web App соглашений ".

  1. Следуйте инструкциям в первых трех разделах этой статьи:

  2. Переместите содержимое App компонента () в новый файл компонента (App.razorRoutes), добавленный в корневую Routes.razor папку проекта. Оставьте пустой App.razor файл в приложении в корневой папке проекта.

  3. Добавьте запись в _Imports.razor файл, чтобы сделать режимы отрисовки доступными для приложения:

    @using static Microsoft.AspNetCore.Components.Web.RenderMode

  4. Переместите содержимое _Host страницы (Pages/_Host.cshtml) в пустой App.razor файл. Перейдите к следующим изменениям компонента App .

    Замечание

    В следующем примере пространство имен проекта — BlazorServerApp. Настройте пространство имен, чтобы соответствовать проекту.

    Удалите следующие строки из верхней части файла:

    - @page "/"
- @using Microsoft.AspNetCore.Components.Web
- @namespace BlazorServerApp.Pages
- @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

    Замените предыдущие строки строк линией, которая внедряет IHostEnvironment экземпляр:

    @inject IHostEnvironment Env

    Удалите тильду (~) из href тега <base> и замените базовым путем для приложения:

    - <base href="~/" />
+ <base href="/" />

    Удалите вспомогательный компонент HeadOutlet тега компонента и замените его компонентом HeadOutlet .

    Удалите следующую строку:

    - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

    Замените предыдущую строку следующим образом:

    <HeadOutlet @rendermode="InteractiveServer" />

    Удалите вспомогательный компонент App тега компонента и замените его компонентом Routes .

    Удалите следующую строку:

    - <component type="typeof(App)" render-mode="ServerPrerendered" />

    Замените предыдущую строку следующим образом:

    <Routes @rendermode="InteractiveServer" />

    Замечание

    В предыдущей конфигурации предполагается, что компоненты приложения принимают интерактивную отрисовку сервера. Дополнительные сведения о том, как внедрить статическую отрисовку на стороне сервера (SSR), см. в ASP.NET Blazor Core.

    Удалите вспомогательные функции тегов среды для пользовательского интерфейса ошибки и замените их следующим Razor разметкой.

    Удалите следующие строки.

    - <environment include="Staging,Production">
-     An error has occurred. This application may no longer respond until reloaded.
- </environment>
- <environment include="Development">
-     An unhandled exception has occurred. See browser dev tools for details.
- </environment>

    Замените предыдущие строки следующими:

    @if (Env.IsDevelopment())
{
    <text>
        An unhandled exception has occurred. See browser dev tools for details.
    </text>
}
else
{
    <text>
        An error has occurred. This app may no longer respond until reloaded.
    </text>
}

    Изменение скрипта Blazor на blazor.server.jsblazor.web.js:

    - <script src="_framework/blazor.server.js"></script>
+ <script src="_framework/blazor.web.js"></script>

  5. Удалите файл Pages/_Host.cshtml.

  6. Обновление Program.cs:

    Замечание

    В следующем примере пространство имен проекта — BlazorServerApp. Настройте пространство имен, чтобы соответствовать проекту.

    using Добавьте инструкцию в начало файла для пространства имен проекта:

    using BlazorServerApp;

    Замените AddServerSideBlazor на AddRazorComponents и прицепоченный вызов AddInteractiveServerComponents.

    Удалите следующую строку:

    - builder.Services.AddServerSideBlazor();

    Замените предыдущую строку службами Razor компонентов и интерактивных компонентов сервера. Вызов AddRazorComponents добавляет службы антифоргерии (AddAntiforgery) по умолчанию.

    builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

    Удалите следующую строку:

    - app.MapBlazorHub();

    Замените предыдущую строку вызовом MapRazorComponents, предоставляя App компонент в качестве типа корневого компонента и добавляя прицепленный вызов AddInteractiveServerRenderMode:

    app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

    Удалите следующую строку:

    - app.MapFallbackToPage("/_Host");

    Удаление ПО промежуточного слоя маршрутизации:

    - app.UseRouting();

    Добавьте Промежуточное ПО для антифоргерии в конвейер обработки запросов после строки, которая добавляет Промежуточное ПО для перенаправления HTTPS (app.UseHttpsRedirection):

    app.UseAntiforgery();

    Предыдущий вызов app.UseAntiforgery должен быть помещен после вызовов, если он присутствует, в app.UseAuthentication и app.UseAuthorization. Нет необходимости явно добавлять службы антифоргерии (builder.Services.AddAntiforgery), так как они добавляются автоматически AddRazorComponents, что было описано ранее.

  7. Blazor Server Если приложение было настроено для отключения предварительной подготовки, можно продолжить отключение предварительной отрисовки для обновленного приложения. В компоненте измените значение, назначенное App@rendermodeRazor атрибутам директивы для HeadOutlet компонентов и Routes компонентов.

    Измените значение атрибута @rendermode директивы как для компонентов, так HeadOutlet и Routes для отключения предварительной подготовки:

    - @rendermode="InteractiveServer"
+ @rendermode="new InteractiveServerRenderMode(prerender: false)"

    Дополнительные сведения см. в ASP.NET CoreBlazor режимах рендеринга.

Blazor WebAssembly Обновление приложения

Следуйте инструкциям в первых трех разделах этой статьи:

Для приложений, которые используют отложенную загрузку сборок, измените расширение файла с .dll на .wasm в реализации приложения, чтобы отразить внедрение Blazor WebAssembly.

До выпуска .NET 8 руководство по макету развертывания для приложений, размещенных на ASP.NET Core Blazor WebAssembly направлено на среды, которые блокируют клиентов от загрузки и выполнения DLL с помощью подхода многокомпонентной упаковки. В .NET 8 или более поздней версии Blazor используется формат файла Webcil для решения этой проблемы. Многопартийное объединение с помощью экспериментального пакета NuGet, описанного в статье макета развертывания WebAssembly, не поддерживается для Blazor приложений в .NET 8 или более поздней версии. Если вы хотите продолжить использование пакета с несколькими частями в приложениях .NET 8 или более поздних версий, вы можете использовать инструкции в статье для создания собственного пакета NuGet с несколькими частями, но он не будет поддерживаться корпорацией Майкрософт.

Преобразование размещенного Blazor WebAssembly приложения в Blazor Web App

Blazor WebAssembly приложения поддерживаются в .NET 8 без каких-либо изменений кода. Используйте следующее руководство, чтобы преобразовать размещенное Blazor WebAssembly приложение ASP.NET Core в эквивалентное .NET 8 Blazor Web App, что делает все новые функции .NET 8 доступными.

Это важно

В этом разделе рассматриваются минимальные изменения, необходимые для преобразования размещенного Blazor WebAssembly приложения .NET 7 ASP.NET Core в .NET 8 Blazor Web App. Чтобы принять все новые Blazor Web App соглашения, следуйте указаниям в разделе "Принятие всех Blazor Web App соглашений ".

  1. Следуйте инструкциям в первых трех разделах этой статьи:

    Это важно

    Используя предыдущее руководство, обновите .Client.Serverи .Shared проекты решения.

  2. .Client В файле проекта (.csproj) добавьте следующие свойства MSBuild:

    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
<StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode>

    Кроме того, в .Client файле проекта удалите ссылку Microsoft.AspNetCore.Components.WebAssembly.DevServer на пакет:

    - <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer"... />

  3. Переместите содержимое файла из .Client/wwwroot/index.html файла в новый App файл компонента (App.razor), созданный в корне .Server проекта. После перемещения содержимого файла удалите index.html файл.

    Переименуйте App.razor.Client в проект Routes.razorв .

    В Routes.razor, обновите значение атрибута AppAssembly на typeof(Program).Assembly.

  4. .Client В проекте добавьте запись _Imports.razor в файл, чтобы сделать режимы отрисовки доступными для приложения:

    @using static Microsoft.AspNetCore.Components.Web.RenderMode

    Создайте копию .Client файла проекта _Imports.razor и добавьте его в .Server проект.

  5. Внесите указанные ниже изменения в файл App.razor.

    Замените название веб-сайта по умолчанию (<title>...</title>) компонентом HeadOutlet . Запишите название веб-сайта для использования позже и удалите теги заголовка и заголовок:

    - <title>...</title>

    Где вы удалили заголовок, поместите HeadOutlet компонент, назначив режим интерактивной отрисовки WebAssembly (предварительно отключено):

    <HeadOutlet @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

    Измените пакет стилей CSS:

    - <link href="{CLIENT PROJECT ASSEMBLY NAME}.styles.css" rel="stylesheet">
+ <link href="{SERVER PROJECT ASSEMBLY NAME}.styles.css" rel="stylesheet">

    Заполнители в предыдущем коде:

    • {CLIENT PROJECT ASSEMBLY NAME}: имя сборки клиентского проекта. Пример: BlazorSample.Client
    • {SERVER PROJECT ASSEMBLY NAME}: имя сборки проекта сервера. Пример: BlazorSample.Server

    Найдите следующую <div>...</div> разметку HTML:

    - <div id="app">
-     ...
- </div>

    Замените предыдущую <div>...</div> разметку Routes HTML компонентом с помощью режима интерактивной отрисовки WebAssembly (отключена предварительная отрисовка):

    <Routes @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />

    Обновите скрипт следующими способами blazor.webassembly.jsblazor.web.js:

    - <script src="_framework/blazor.webassembly.js"></script>
+ <script src="_framework/blazor.web.js"></script>

  6. .Client Откройте файл макета проекта (.Client/Shared/MainLayout.razor) и добавьте PageTitle компонент с заголовком веб-сайта по умолчанию ({TITLE}заполнитель):

    <PageTitle>{TITLE}</PageTitle>

    Замечание

    Другие файлы макета также должны получать компонент с заголовком PageTitle веб-сайта по умолчанию.

    Дополнительные сведения см. в статье Управление содержимым head в приложениях ASP.NET Core Blazor.

  7. Удалите следующие строки из .Client/Program.cs:

    - builder.RootComponents.Add<App>("#app");
- builder.RootComponents.Add<HeadOutlet>("head::after");

  8. Обновление .Server/Program.cs:

    Добавьте Razor в проект компоненты и интерактивные службы компонентов WebAssembly. Вызов с прицеленным вызовом AddRazorComponentsAddInteractiveWebAssemblyComponents. Вызов AddRazorComponents добавляет службы антифоргерии (AddAntiforgery) по умолчанию.

    builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

    Добавьте промежуточное программное обеспечение защиты от подделок в конвейер обработки запросов.

    Поместите следующую строку после вызова app.UseHttpsRedirection. app.UseAntiforgery Вызов должен быть помещен после вызовов, если он присутствует, в app.UseAuthentication и app.UseAuthorization. Нет необходимости явно добавлять службы антифоргерии (builder.Services.AddAntiforgery), так как они добавляются автоматически AddRazorComponents, что было описано ранее.

    app.UseAntiforgery();

    Удалите следующую строку:

    - app.UseBlazorFrameworkFiles();

    Удалите следующую строку:

    - app.MapFallbackToFile("index.html");

    Замените предыдущую строку вызовом MapRazorComponents, предоставляя App компонент в качестве типа корневого компонента, и добавляйте к ним связанные вызовы AddInteractiveWebAssemblyRenderMode и AddAdditionalAssemblies:

    app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({CLIENT APP NAMESPACE}._Imports).Assembly);

    В предыдущем примере {CLIENT APP NAMESPACE} заполнитель — это пространство .Client имен проекта (например, HostedBlazorApp.Client).

  9. Запустите решение из .Server проекта:

    Для Visual Studio убедитесь, что .Server проект выбран в обозревателе решений при запуске приложения.

    При использовании .NET CLI запустите проект из .Server папки проекта.

Обновление конфигурации параметра службы и конечной точки

После выпуска Blazor Web Apps в .NET 8 Blazor конфигурация параметра параметра службы и конечной точки обновляется с введением нового API для интерактивных служб компонентов и конфигурации конечной точки компонента.

Обновленные рекомендации по настройке отображаются в следующих расположениях:

Удаление Blazor Server с обходным решением маршрутизации Yarp

Если вы ранее следовали инструкциям в статье Blazor Server для миграции приложения с Yarp на .NET 6 или .NET 7, вы можете отменить шаги, которых вы придерживались, выполняя рекомендации статьи. Маршрутизация и глубокая привязка для Blazor Server с Yarp работают правильно в .NET 8.

Перенос CascadingValue компонентов в компонентах макета

Каскадные параметры не передают данные между границами режима отрисовки, а макеты статически отрисовываются в других интерактивных приложениях. Таким образом, приложения, которые стремятся использовать каскадные параметры в интерактивных отрисованных компонентах, не смогут каскадировать значения из макета.

Ниже приведены два подхода к миграции.

Дополнительные сведения см. в разделе Каскадные значения и параметры и границы режима отрисовки.

BlazorEnableCompression Перенос свойства MSBuild

Для Blazor WebAssembly приложений, которые отключают сжатие и целевые версии .NET 7 или более ранних версий, но создаются с помощью пакета SDK для .NET 8, BlazorEnableCompression свойство MSBuild изменилось на CompressionEnabled:

<PropertyGroup>
-   <BlazorEnableCompression>false</BlazorEnableCompression>
+   <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

При использовании команды публикации .NET CLI используйте новое свойство:

dotnet publish -p:CompressionEnabled=false

Дополнительные сведения см. в следующих ресурсах:

Перенос компонента в <CascadingAuthenticationState> каскадные службы проверки подлинности

В .NET 7 или более ранней CascadingAuthenticationState версии компонент упаковывается вокруг части дерева пользовательского интерфейса, например вокруг Blazor маршрутизатора, чтобы обеспечить каскадное состояние проверки подлинности:

<CascadingAuthenticationState>
    <Router ...>
        ...
    </Router>
</CascadingAuthenticationState>

В .NET 8 не используйте CascadingAuthenticationState компонент:

- <CascadingAuthenticationState>
      <Router ...>
          ...
      </Router>
- </CascadingAuthenticationState>

Вместо этого добавьте каскадные службы проверки подлинности в коллекцию служб, вызвав AddCascadingAuthenticationState в Program файле:

builder.Services.AddCascadingAuthenticationState();

Дополнительные сведения см. в следующих ресурсах:

Новая статья о проблемах кэширования HTTP

Мы добавили новую статью, в которой рассматриваются некоторые распространенные проблемы с кэшированием HTTP, которые могут возникнуть при обновлении Blazor приложений в основных версиях и устранении проблем с кэшированием HTTP.

Дополнительные сведения см. в разделе Blazor.

Новая статья о классовых библиотеках со статическим рендерингом на стороне сервера (SSR)

Мы добавили новую статью, которая обсуждает создание библиотек компонентов в Razor библиотеках классов (RCL) с использованием статического рендеринга на стороне сервера (static SSR).

Дополнительные сведения см. в разделе Библиотеки классов ASP.NET Core Razor (RCLs) со статическим серверным рендерингом (статический SSR).

Обнаружение компонентов из дополнительных сборок

При миграции с приложения Blazor Server на приложение Blazor Web App смотрите руководство по маршрутизации ASP.NET CoreBlazor, если приложение использует маршрутизируемые компоненты из дополнительных сборок, например, библиотек классов компонентов.

Удаление [Parameter] атрибута при указании параметра из строки запроса

Атрибут [Parameter] больше не требуется при предоставлении параметра из строки запроса:

- [Parameter]
  [SupplyParameterFromQuery]

Blazor Server Авторизация резервной политики скрипта

В .NET 7 Blazor Server скрипт (blazor.server.js) обслуживается промежуточным слоем для статических файлов. Размещение вызова посредника для статических файлов (UseStaticFiles) в конвейере обработки запросов перед вызовом посредника авторизации (UseAuthorization) достаточно в приложениях .NET 7 для предоставления скрипта Blazor анонимным пользователям.

В .NET 8 Blazor Server скрипт обслуживается собственной конечной точкой, используя маршрутизацию конечных точек. Это изменение внесено с исправлением ошибки - передача параметров в UseStaticFiles приводит к сбою (Blazor Server #45897).

Рассмотрим сценарий с несколькими клиентами, где:

  • Политики по умолчанию и резервные политики задаются одинаково.
  • Клиент разрешается с помощью первого сегмента в пути запроса (например, tld.com/tenant-name/...).
  • Запросы к конечным точкам арендатора проходят проверку подлинности с помощью дополнительной схемы проверки подлинности, которая добавляет дополнительное удостоверение к субъекту запроса.
  • Политика резервной авторизации имеет требования, которые проверяют утверждения с помощью дополнительного удостоверения.

Запросы к файлу скрипта Blazor (blazor.server.js) обслуживаются /_framework/blazor.server.jsпо адресу, который жестко закодирован в платформе. Запросы к файлу не проходят проверку подлинности по дополнительной схеме проверки подлинности для клиентов, но по-прежнему оспариваются резервной политикой, что приводит к возврату несанкционированного результата.

Эта проблема рассматривается для новой функции платформы в MapRazorComponents, нарушенной с помощью FallbackPolicy RequireAuthenticatedUser (dotnet/aspnetcore 51836), которая в настоящее время запланирована на выпуск .NET 9 в ноябре 2024 года. До тех пор вы можете обойти эту проблему с помощью любого из следующих трех подходов:

  • Не используйте резервную политику. [Authorize] Примените атрибут в _Imports.razor файле, чтобы применить его ко всем компонентам приложения. Для конечных точек, отличных от blazor, явно используйте [Authorize] или RequireAuthorization.

  • Добавьте [AllowAnonymous] в конечную точку /_framework/blazor.server.js в Program файле:

    app.MapBlazorHub().Add(endpointBuilder =>
{
    if (endpointBuilder is 
        RouteEndpointBuilder
        { 
            RoutePattern: { RawText: "/_framework/blazor.server.js" }
        })
    {
        endpointBuilder.Metadata.Add(new AllowAnonymousAttribute());
    }
});

  • Зарегистрируйте пользовательский AuthorizationHandler, который проверяет HttpContext, чтобы разрешить файл /_framework/blazor.server.js.

Докер

Обновление образов Docker

Для приложений с помощью Docker обновите инструкции и скрипты DockerfileFROM . Используйте базовый образ, включающий среду выполнения .NET 8. Рассмотрим следующее docker pull различие между ASP.NET Core в .NET 7 и .NET 8:

- docker pull mcr.microsoft.com/dotnet/aspnet:7.0
+ docker pull mcr.microsoft.com/dotnet/aspnet:8.0

Обновление порта Docker

Порт по умолчанию ASP.NET Core, настроенный в образах контейнеров .NET, обновлен с порта 80 до 8080.

Новая ASPNETCORE_HTTP_PORTS переменная среды была добавлена в качестве более простой альтернативы ASPNETCORE_URLS.

Дополнительные сведения можно найти здесь

Кардинальные изменения

Используйте статьи в статье Критические изменения в .NET, чтобы найти критические изменения , которые могут применяться при обновлении приложения до более новой версии .NET.

  • Last updated on