Поделиться через

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

  • Статья

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

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

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

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

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

Если вы используете global.json файл для конкретной версии пакета SDK для .NET Core, обновите version свойство до установленной версии пакета SDK для .NET 8.0. Например:

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

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

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

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

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

</Project>

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

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

<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 " в приложения ASP.NET Core.

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

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

Новые Blazor функции, представленные для приложенийBlazor Server, недоступны для Blazor Web Appзапуска в .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 8.0. При обновлении приложения из .NET 6 или более ранней версии см. заметки о миграции и выпуске (новые статьи) для взаимодействия с выпусками.

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

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

Внимание

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

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

  2. Переместите содержимое App компонента () в новый файл компонента (App.razorRoutes.razor), добавленный в корневую Routes папку проекта. Оставьте пустой 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 режимах отрисовки CoreBlazor.

    Удалите вспомогательные функции тегов среды для пользовательского интерфейса ошибки и замените их следующим 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.js blazor.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. Если есть вызовы app.UseRouting и app.UseEndpoints, вызов app.UseAntiforgery должен пройти между ними. Вызов app.UseAntiforgery должен быть помещен после вызовов app.UseAuthentication и app.UseAuthorization. Нет необходимости добавлять службы антифоргерии (builder.Services.AddAntiforgery()), так как они добавляются автоматически AddRazorComponents, что было описано ранее.

    app.UseAntiforgery();

  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внедрение упаковки сборки Webcil.

До выпуска .NET 8 руководство по макету развертывания для ASP.NET Основные размещенные 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.js blazor.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. Вызов с прицеленным вызовом AddRazorComponents AddInteractiveWebAssemblyComponents. Вызов AddRazorComponents добавляет службы антифоргерии (AddAntiforgery) по умолчанию.

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

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

    Поместите следующий код:

    • После вызова app.UseRouting.
    • Если есть вызовы app.UseRouting и app.UseEndpoints, вызов app.UseAntiforgery должен пройти между ними.
    • app.UseAntiforgery Вызов должен быть помещен после вызова 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

Если вы ранее следовали инструкциям в статье Enable ASP.NET Core Blazor Server support with Yarp incremental migration for migrationing a Blazor Server app with Yarp to .NET 6 or .NET 7, вы можете отменить обходные действия, которые вы предприняли при выполнении рекомендаций статьи. Маршрутизация и глубокая привязка для Blazor Server работы с Yarp работает правильно в .NET 8.

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

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

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

  • (Рекомендуется) Передать состояние в качестве каскадного значения корневого уровня. Дополнительные сведения см. в разделе каскадных значений корневого уровня.
  • Переключите маршрутизатор в Routes компонент с CascadingValue помощью компонента и сделайте Routes компонент интерактивным отрисовкой. Пример см 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.

Дополнительные сведения см. в разделе "Избегание проблем с кэшированием HTTP" при обновлении приложений ASP.NET CoreBlazor.

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

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

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

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

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

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

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

- [Parameter]
  [SupplyParameterFromQuery]

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

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

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

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

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

Запросы к файлу скрипта 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

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

- 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 Core .NET 7.0 до 8.0 см. в разделе "Критические изменения" в .NET 8, включающем разделы ASP.NET Core и Entity Framework Core .