次の方法で共有

.NET 7 の ASP.NET Core から .NET 8 に移行する

  • [アーティクル]

この記事では、既存の ASP.NET Core 7.0 プロジェクトを ASP.NET Core 8.0 に更新する方法について説明します。

前提条件

global.json で .NET SDK のバージョンを更新する

特定の .NET Core SDK バージョンを対象とする global.json ファイルを使用する場合は、version プロパティを、インストールされる .NET 8.0 SDK バージョンに更新します。 次に例を示します。

{
  "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.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 アプリを更新する

.NET 8 で Blazor Web Apps を使用することは推奨されていませんが、Blazor Server はサポートされています。 .NET 8 で Blazor Server を引き続き使用するには、この記事の最初の 3 つのセクションのガイダンスに従ってください。

Blazor Web Apps で導入された新しい Blazor 機能は、.NET 8 の下で実行されるように更新された Blazor Server アプリで利用できません。 新しい .NET 8 Blazor 機能を導入する場合、次のいずれかのセクションのガイドに従ってください。

すべての Blazor Web アプリ規則を導入する

必要に応じて、すべての新しい Blazor Web アプリ規則を導入するには、次のプロセスをお勧めします。

  • Blazor Web アプリ プロジェクト テンプレートから新しいアプリを作成します。 詳しくは、「ASP.NET Core Blazor 用のツール」をご覧ください。
  • アプリのコンポーネントとコードを新しい Blazor Web アプリのアプリに移動し、新機能を導入するように変更します。
  • Blazor Web アプリのレイアウトとスタイルを更新します。

.NET 8 の新しい機能については、「ASP.NET Core 8.0 の新機能」をご覧ください。 .NET 6 以前からアプリを更新する場合は、途中のリリースに関する移行とリリース ノート ("新機能" の記事) をご覧ください。

Blazor Server アプリを Blazor Web アプリに変換する

Blazor Server アプリは、コードを変更しなくても .NET 8 でサポートされています。 Blazor Server アプリを同等の .NET 8 Blazor Web アプリに変換するには、次のガイダンスをご覧ください。これにより、.NET 8 の新機能をすべて利用できるようになります。

重要

このセクションでは、.NET 7 Blazor Server アプリを .NET 8 Blazor Web アプリに変換するために必要な最小限の変更について説明します。 Blazor Web アプリの新しい規則をすべて導入するには、「すべての Blazor Web アプリの規則を導入する」セクションのガイダンスのようにしてください。

  1. この記事の最初の 3 つのセクションのガイダンスに従ってください。

  2. App コンポーネント (App.razor) の内容を、プロジェクトのルート フォルダーに追加された新しい Routes コンポーネント ファイル (Routes.razor) に移動します。 空の App.razor ファイルは、プロジェクトのルート フォルダー内のアプリに残しておきます。

  3. _Imports.razor ファイルにエントリを追加して、アプリで短縮レンダリング モードを使用できるようにします。

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

  4. _Host ページ (Pages/_Host.cshtml) の内容を、空の App.razor ファイルに移動します。 続いて、App コンポーネントを次のように変更します。

    Note

    次の例では、プロジェクトの名前空間は BlazorServerApp です。 名前空間は、実際のプロジェクトに合わせて調整してください。

    json ファイルの先頭から、次の行を削除します。

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

    前の行を、IHostEnvironment インスタンスを挿入する行に置き換えます。

    @inject IHostEnvironment Env

    <base> タグの href からチルダ (~) を削除し、アプリのベース パスに置き換えます。

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

    Note

    上記の構成では、アプリのコンポーネントが対話型サーバー レンダリングを採用しているものと想定しています。 静的サーバー側レンダリング (SSR) を導入する方法など、詳細については、「ASP.NET Core Blazor のレンダー モード」をご覧ください。

    エラー UI の環境タグ ヘルパーを削除し、次の 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:

    Note

    次の例では、プロジェクトの名前空間は 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 の呼び出しの後に置く必要があります。 上記で説明した AddRazorComponents によって自動的に追加されるため、偽造防止サービス (builder.Services.AddAntiforgery()) を追加する必要はありません。

    app.UseAntiforgery();

  7. Blazor Server アプリがプリレンダリングを無効にするように構成されていた場合は、更新されたアプリでもプリレンダリングを無効にしておくことができます。 App コンポーネントで、HeadOutlet と Routes コンポーネントの @rendermodeRazor ディレクティブ属性に割り当てられている値を変更します。

    プリレンダリングを無効にするには、HeadOutlet と Routes の両方のコンポーネントの @rendermode ディレクティブ属性の値を変更します。

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

    詳細については、「ASP.NET Core Blazor レンダリング モード」を参照してください。

Blazor WebAssembly アプリを更新する

この記事の最初の 3 つのセクションのガイダンスに従ってください。

ホストされた Blazor WebAssembly アプリを Blazor Web アプリに変換する

Blazor WebAssembly アプリは、コードを変更しなくても .NET 8 でサポートされています。 ASP.NET Core でホストされた Blazor WebAssembly アプリを同等の .NET 8 Blazor Web アプリに変換するには、次のガイダンスをご覧ください。これにより、.NET 8 の新機能をすべて利用できるようになります。

重要

このセクションでは、.NET 7 ASP.NET Core でホストされた Blazor WebAssembly アプリを .NET 8 Blazor Web アプリに変換するために必要な最小限の変更について説明します。 Blazor Web アプリの新しい規則をすべて導入するには、「すべての Blazor Web アプリの規則を導入する」セクションのガイダンスのようにしてください。

  1. この記事の最初の 3 つのセクションのガイダンスに従ってください。

    重要

    前のガイダンスを使って、ソリューションの .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 ファイルの内容を、.Server プロジェクトのルートに作成された新しい App コンポーネント ファイル (App.razor) に移動します。 ファイルの内容を移動した後、index.html ファイルを削除します。

    .Client プロジェクトの App.razor の名前を、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 ファイルに次の変更を加えます。

    Web サイトの既定の Web サイト タイトル (<title>...</title>) を HeadOutlet コンポーネントに置き換えます。 後で使用するために Web サイトのタイトルをメモし、タイトル タグとタイトルを削除します。

    - <title>...</title>

    タイトルを削除した場所に、Interactive WebAssembly レンダリング モードを割り当てる HeadOutlet コンポーネントを配置します (プリレンダリングは無効)。

    <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> HTML マークアップを、対話型 WebAssembly レンダリング モード (プリレンダリングは無効) を使う Routes コンポーネントに置き換えます。

    <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) を開き、Web サイトの既定のタイトル ({TITLE} プレースホルダー) を含む PageTitle コンポーネントを追加します。

    <PageTitle>{TITLE}</PageTitle>

    Note

    その他のレイアウト ファイルでも、既定の Web サイト タイトルを含む PageTitle コンポーネントを受け取る必要があります。

    詳しくは、「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 コンポーネント サービスをプロジェクトに追加します。 AddInteractiveWebAssemblyComponents へのチェーン呼び出しを含む AddRazorComponents を呼び出します。 AddRazorComponents を呼び出すと、既定で偽造防止サービス (AddAntiforgery) が追加されます。

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

    要求処理パイプラインに、偽造防止ミドルウェアを追加します。

    次のコードを挿入します:

    • app.UseRouting の呼び出しの後。
    • app.UseRouting と app.UseEndpoints の呼び出しがある場合、app.UseAntiforgery の呼び出しはそれらの間に置く必要があります。
    • app.UseAntiforgery への呼び出しは、app.UseAuthorization の呼び出し (存在する場合) の後に行う必要があります。
    • 上記で説明した AddRazorComponents によって自動的に追加されるため、偽造防止サービス (builder.Services.AddAntiforgery()) を追加する必要はありません。
    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 プロジェクトのフォルダーからプロジェクトを実行します。

サービスとエンドポイントのオプション構成を更新する

.NET 8 での Blazor Web Apps のリリースにともない、Blazor サービスとエンドポイントのオプション構成が更新され、インタラクティブなコンポーネント サービスとコンポーネント エンドポイント構成のための新しい API が導入されました。

更新された構成ガイダンスは次の場所に表示されます。

Yarp ルーティングによるドロップ Blazor Server の回避策

以前に、Yarp を使用して Blazor Server アプリを .NET 6 または .NET 7 に移行するための増分移行 で Yarp で ASP.NET Core Blazor Server サポートを有効にする方法に関する記事のガイダンスに従っている場合は、記事のガイダンスに従うときに実行した回避策の手順を元に戻すことができます。 Yarp を使用した Blazor Server のルーティングとディープ リンクは、.NET 8 で正しく機能します。

レイアウト コンポーネント内のCascadingValue コンポーネントを移行する

カスケード パラメーターでレンダー モードの境界を越えてデータが渡されることはなく、それ以外の場合は対話型のアプリで、レイアウトが静的にレンダリングされます。 そのため、対話形式でレンダリングされるコンポーネントでカスケード パラメーターを使用しようとするアプリでは、レイアウトから値をカスケードすることはできません。

移行の 2 つの方法は次のとおりです。

  • (推奨) 状態をルート レベルのカスケード値として渡します。 詳細については、「ルート レベルのカスケード値」を参照してください。
  • Routes コンポーネント内のルーターを CascadingValue コンポーネントでラップし、Routes コンポーネントが対話形式でレンダリングされるようにします。 例については、「CascadingValue コンポーネント」を参照してください。

詳細については、「カスケード値/パラメーターとレンダリング モードの境界」を参照してください。

BlazorEnableCompression MSBuild プロパティを移行する

圧縮を無効にし、.NET 7 以前をターゲットとするが、.NET 8 SDK でビルドされている Blazor WebAssembly アプリの場合、BlazorEnableCompression MSBuild プロパティは CompressionEnabled に変更されています。

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

.NET CLI の publish コマンドを使う場合は、新しいプロパティを使用します。

dotnet publish -p:CompressionEnabled=false

詳細については、次のリソースを参照してください。

<CascadingAuthenticationState> コンポーネントをカスケード認証状態サービスに移行する

.NET 7 以前では、CascadingAuthenticationState コンポーネントは UI ツリーの一部 (Blazor ルーターなど) にラップされ、カスケード認証状態が提供されます。

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

.NET 8 では、CascadingAuthenticationState コンポーネントを使わないでください。

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

代わりに、AddCascadingAuthenticationState を呼び出してカスケード認証状態サービスを Program ファイル内のサービス コレクションに追加します。

builder.Services.AddCascadingAuthenticationState();

詳細については、次のリソースを参照してください。

HTTP キャッシュの問題に関する新しい記事

メジャー バージョン間で Blazor アプリをアップグレードするときに発生する可能性がある HTTP キャッシュに関する一般的な問題と、HTTP キャッシュの問題に対処する方法について説明する新しい記事が追加されました。

詳しくは、「ASP.NET Core Blazor アプリをアップグレードするときに HTTP キャッシュの問題を回避する」をご覧ください。

静的サーバー側レンダリング (静的 SSR) でのクラス ライブラリに関する新しい記事

静的サーバー側レンダリング (静的 SSR) の場合の Razor クラス ライブラリ (RCL) でのコンポーネント ライブラリの作成について説明する新しい記事が追加されました。

詳しくは、「ASP.NET Core の Razor クラス ライブラリ (RCL) と静的サーバー側レンダリング (静的 SSR)」をご覧ください。

追加アセンブリからコンポーネントを検出する

Blazor Server アプリから Blazor Web アプリに移行するとき、コンポーネント クラス ライブラリなどの追加アセンブリのルーティング可能なコンポーネントをアプリで使っている場合は、「ASP.NET Core の Blazor ルーティングとナビゲーション」のガイダンスをご覧ください。

パラメーターがクエリ文字列から指定されたときに [Parameter] 属性を削除する

クエリ文字列からパラメーターを指定するときに [Parameter] 属性は不要になりました。

- [Parameter]
  [SupplyParameterFromQuery]

Blazor Server スクリプトのフォールバック ポリシー承認

.NET 7 では、Blazor Server スクリプト (blazor.server.js) は静的ファイル ミドルウェアによって提供されます。 承認ミドルウェア (UseAuthorization) の呼び出しの前に要求処理パイプラインに静的ファイル ミドルウェア (UseStaticFiles) の呼び出しを配置するだけで、.NET 7 アプリで匿名ユーザーに Blazor スクリプトを提供するのに十分です。

.NET 8 では、Blazor Server スクリプトは、エンドポイント ルーティングを使用して、独自のエンドポイントによって提供されます。 この変更は、バグの修正 - UseStaticFiles にオプションを渡すと Blazor Server が破損する (dotnet/aspnetcore #45897) によって導入されます。

次のようなマルチテナント シナリオについて考えてみましょう。

  • 既定のポリシーとフォールバック ポリシーの両方が同じように設定されます。
  • テナントは、要求パスの最初のセグメント (たとえば、tld.com/tenant-name/...) を使用して解決されます。
  • テナント エンドポイントへの要求は、追加の認証スキームによって認証され、要求プリンシパルに ID が追加されます。
  • フォールバック承認ポリシーには、追加の ID を使用して要求をチェックする要件があります。

Blazor スクリプト ファイル (blazor.server.js) の要求は、フレームワークでハードコーディングされた /_framework/blazor.server.js で処理されます。 ファイルの要求は、テナントの追加の認証スキームによって認証されるのではなく、"フォールバック ポリシーによって引き続きチャレンジされ"、未承認の結果が返されます。

この問題は、FallbackPolicy RequireAuthenticatedUser で破損した MapRazorComponents (dotnet/aspnetcore 51836) で新しいフレームワーク機能の評価中です。これは、2024 年 11 月の .NET 9 のリリースで現在スケジュールされています。 それまでは、次の 3 つの方法のいずれかを使用して、この問題を回避できます。

  • フォールバック ポリシーを使用しません。 _Imports.razor ファイル内の [Authorize] 属性を適用して、アプリのすべてのコンポーネントに適用します。 Blazor 以外のエンドポイントの場合は、[Authorize] または RequireAuthorization を明示的に使用します。

  • Program ファイルの /_framework/blazor.server.js エンドポイントに [AllowAnonymous] を追加します。

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

  • /_framework/blazor.server.js ファイルを許可するために HttpContext をチェックするカスタム AuthorizationHandler を登録します。

Docker

Docker イメージの更新

Docker を使用するアプリの場合、DockerfileFROM ステートメントおよびスクリプトを更新します。 ASP.NET Core 8.0 ランタイムを含む基本イメージを使用します。 ASP.NET Core 7.0 と 8.0 の間では、docker pull コマンドに次の違いがあることに注意してください:

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

Docker ポートを更新する

.NET コンテナー イメージで構成された既定の ASP.NET Core ポートが、ポート 80 から 8080 に更新されました。

新しい ASPNETCORE_HTTP_PORTS の環境変数が、ASPNETCORE_URLS のよりシンプルな代替として追加されました。

詳細については、以下を参照してください:

破壊的変更の確認

.NET Core .NET 7.0 から 8.0 への破壊的変更については、.NET 8 の破壊的変更に関するを記事を参照してください。これには、ASP.NET Core と Entity Framework Core のセクションが含まれています。