blazor-expert

Blazor エキスパート - オーケストレーションハブ

JavaScript の代わりに C# を使用してインタラクティブな Web UI を構築する Microsoft のフレームワーク、Blazor を使ったアプリケーション開発に関するエキスパートレベルのガイダンスです。

クイックリファレンス：読み込むリソースの選び方

タスク	読み込むリソース	主なトピック
コンポーネントの構築、ライフサイクルイベントの処理	components-lifecycle.md	コンポーネントの構造、ライフサイクルメソッド、パラメーター、カスケード値、RenderFragment の合成
コンポーネントの状態管理、イベント処理	state-management-events.md	ローカル状態、EventCallback、データバインディング、カスケード状態、サービスベースの状態管理
ルートの設定、ページ間の移動	routing-navigation.md	ルートパラメーター、制約、ナビゲーション、NavLink、クエリ文字列、レイアウト
フォームの構築、ユーザー入力の検証	forms-validation.md	EditForm、入力コンポーネント、DataAnnotations による検証、カスタムバリデーター
認証と認可のセットアップ	authentication-authorization.md	認証のセットアップ、AuthorizeView、Authorize 属性、ポリシー、クレーム
パフォーマンスの最適化、JavaScript 相互運用の利用	performance-advanced.md	レンダリングの最適化、仮想化、JS 相互運用、遅延読み込み、WASM のベストプラクティス

オーケストレーションプロトコル

フェーズ 1：タスク分析

主な目的を特定します。

• UI の構築 → components-lifecycle.md を読み込む
• 状態の処理 → state-management-events.md を読み込む
• ナビゲーション → routing-navigation.md を読み込む
• データ入力 → forms-validation.md を読み込む
• ユーザーアクセス → authentication-authorization.md を読み込む
• 速度／効率 → performance-advanced.md を読み込む

フェーズ 2：リソースの読み込み

推奨されるリソースファイルを開き、Ctrl+F を使って必要な情報を検索します。各リソースはトピック別に構成されており、動作するコード例が含まれています。

フェーズ 3：実装と検証

• リソースのコードパターンに従います
• 個々の要件に合わせて調整します
• 適切なホスティングモデル（Server/WASM/Hybrid）でテストします
• 問題が発生した場合は、トラブルシューティングのセクションを確認します

Blazor のホスティングモデルの概要

Blazor Server

• 仕組み：SignalR 経由でサーバー上で実行されます
• 最適な用途：業務アプリ、.NET ランタイム全体が必要な場合、ダウンロードサイズを小さくしたい場合
• トレードオフ：レイテンシが高い、接続が必要、サーバーリソースを多く消費する

Blazor WebAssembly

• 仕組み：WebAssembly 経由でブラウザー内で実行されます
• 最適な用途：PWA、オフラインアプリ、サーバーへの依存がないアプリ、クライアント側の処理が多いアプリケーション
• トレードオフ：初回ダウンロードサイズが大きい、利用できる .NET API が限られる、コールドスタートが遅い

Blazor Hybrid

• 仕組み：Blazor UI を使用して MAUI/WPF/WinForms 上で実行されます
• 最適な用途：クロスプラットフォームのデスクトップ／モバイルアプリ
• トレードオフ：プラットフォーム固有の考慮事項、追加の依存関係

選択基準：デプロイ環境、オフライン要件、サーバーの制約に基づいて選択します。

一般的な実装ワークフロー

シナリオ 1：データ入力コンポーネントの構築

1. components-lifecycle.md の「コンポーネントの構造」セクションを読みます
2. state-management-events.md の「EventCallback パターン」を読みます
3. forms-validation.md の「EditForm コンポーネント」を読みます
4. 組み合わせ：パラメーターを持つコンポーネントを作成 → ユーザー入力を取得 → 検証 → 親に通知

シナリオ 2：ユーザー認証と保護されたページの実装

1. authentication-authorization.md の「セットアップ」セクションを読みます
2. routing-navigation.md の「レイアウト」セクションを読みます
3. authentication-authorization.md の「AuthorizeView」セクションを読みます
4. 組み合わせ：認証を設定 → ログインページを作成 → ルートを保護 → コンポーネント内で認証状態を確認

シナリオ 3：検索／フィルター機能付きのインタラクティブなリストを構築する

1. routing-navigation.md のクエリ文字列のセクションを読む
2. state-management-events.md のデータバインディングのセクションを読む
3. performance-advanced.md の仮想化のセクションを読む
4. 組み合わせる：検索入力を取得 → URL クエリを更新 → フィルター済みデータを取得 → データが大きい場合は仮想化する

シナリオ 4：既存アプリのパフォーマンスを最適化する

1. performance-advanced.md のすべてのセクションを読む
2. ボトルネックを特定する：
   • 不要な再レンダリング？→ ShouldRender のオーバーライド、@key ディレクティブ
   • 大きなリスト？→ 仮想化
   • JS の遅延？→ モジュール分離パターン
3. リソースから対象を絞った最適化を適用する

Blazor の主要な概念

コンポーネントアーキテクチャ

• コンポーネント：ロジックを任意で含められる、自己完結型の UI 単位
• パラメーター：コンポーネントへの入力。再利用を可能にします
• カスケード値：明示的なパラメーターを使わずに、子孫コンポーネントと状態を共有します
• イベント：EventCallback を介した子から親への通信
• レイアウト：一貫したページ構成を実現する親ラッパー

状態管理

• ローカル状態：コンポーネント固有のフィールドとプロパティ
• カスケード値：子孫コンポーネントと状態を共有します
• サービス：依存性注入によるアプリケーション全体の状態
• イベントバインディング：ユーザーの操作に応答します
• データバインディング：UI と双方向に同期します

ルーティングとナビゲーション

• @page ディレクティブ：コンポーネントをルーティング可能にします
• ルートパラメーター：URL（{id:int}）を介してデータを渡します
• ナビゲーション：NavigationManager によるプログラムからのナビゲーション
• NavLink：アクティブなルートをハイライト表示する UI コンポーネント
• レイアウト：共通の構成でページをラップします

フォームと検証

• EditForm：検証をサポートするフォームコンポーネント
• 入力コンポーネント：型付きコントロール（InputText、InputNumber など）
• バリデーター：DataAnnotations 属性またはカスタムロジック
• EventCallback：フォームの変更を親に通知します
• メッセージ：検証エラーをユーザーに表示します

認証と認可

• クレームとロール：ユーザーを識別し、アクセスレベルを定義します
• ポリシー：きめ細かな認可ルール
• Authorize 属性：未認証のアクセスからページを保護します
• AuthorizeView：権限に基づいて条件付きでレンダリングします
• AuthenticationStateProvider：現在のユーザー情報を取得します

パフォーマンス最適化

• ShouldRender()：不要な再レンダリングを防ぎます
• @key ディレクティブ：差分アルゴリズムによるリスト項目の照合を支援します
• 仮想化：大きなリストのうち、表示されている項目だけをレンダリングします
• JS Interop：C# から JavaScript を呼び出し、その逆も行います
• AOT／Trimming：WASM のダウンロードサイズを削減します（本番環境）

ベストプラクティスの要点

コンポーネント設計

✅ 単一責任 - 各コンポーネントの目的を明確に 1 つにします
✅ コンポジション - 柔軟なレイアウトには RenderFragments を使用します
✅ パラメーターの明確化 - 説明的な名前を使用し、必須項目には [EditorRequired] を指定します
✅ 適切な破棄処理 - IDisposable を実装してリソースを解放します
✅ イベントベースの通信 - 子から親への更新には EventCallback を使用します

状態管理

✅ Action より EventCallback - 非同期処理を適切に扱えます
✅ 不変の更新 - オブジェクトやコレクションは変更せず、新しく作成します
✅ サービスベースの状態管理 - 共有状態にはスコープ付きサービスを使用します
✅ イベントの購読解除 - Dispose でメモリーリークを防ぎます
✅ バックグラウンドスレッドでは InvokeAsync を使用 - スレッドセーフな状態更新を実現します

ルーティングとナビゲーション

✅ ルート制約 - :int、:guid などを使用して形式を検証します
✅ NavLink コンポーネント - アクティブ状態を自動的にハイライト表示します
✅ ログアウト後に forceLoad を使用 - クライアント側の状態をクリアします
✅ ReturnUrl パターン - ログイン後に元の場所へリダイレクトします
✅ クエリ文字列 - ナビゲーションをまたいでフィルターやページネーションを保持します

フォームと検証

✅ EditForm + DataAnnotationsValidator - 組み込みの検証 ✅ ValidationMessage - フィールド単位のエラーを表示 ✅ カスタムバリデーター - 複雑なルールに対応するよう拡張 ✅ 非同期検証 - 送信前にサーバーの利用可否を確認 ✅ 読み込み状態 - 処理中は送信ボタンを無効化

認証と認可

✅ サーバー側での検証 - クライアント側のチェックだけを決して信用しない ✅ ロールよりポリシー - より柔軟な認可ルール ✅ 詳細情報にはクレームを使用 - ユーザー属性をクレームに保存 ✅ Cascading AuthenticationState - すべてのコンポーネントで利用可能 ✅ エラーバウンダリ - 適切なエラー処理

パフォーマンス

✅ リストでの@key - 項目の照合を最適化 ✅ ShouldRenderのオーバーライド - 不要な再レンダリングを防止 ✅ 大規模リストの仮想化 - 表示中の項目のみをレンダリング ✅ JSモジュールの分離 - JSモジュールを効率的に読み込み、キャッシュ ✅ WASMのAOT - 本番環境へのデプロイ

よくあるトラブルシューティング

コンポーネントが再レンダリングされない

• 原因：再代入ではなく変更を行っている
• 解決策：新しいオブジェクト／コレクションを作成する：items = items.Append(item).ToList()
• または：StateHasChanged()を手動で呼び出す

パラメーターが更新されない

• 原因：親が再レンダリングされていない、または同じオブジェクト参照を使用している
• 解決策：親を再レンダリングし、オブジェクトには新しい参照を使用する
• デバッグ：OnParametersSetが呼び出されているか確認する

JS相互運用のエラー

• 原因：スクリプトの読み込み前に呼び出している、または関数名が間違っている
• 解決策：firstRenderを確認し、JSファイルのパスを検証する
• パターン：モジュールの分離を使用する：await JS.InvokeAsync("import", "./script.js")

認証状態を利用できない

• 原因：カスケードパラメーターが提供されていない、またはタイミングに問題がある
• 解決策：AuthenticationStateProviderが構成されていることを確認する
• パターン：常にnullチェックを行い、コードブロック内でawait AuthStateTask!を使用する

大規模リストのパフォーマンス問題

• 原因：すべての項目をDOMにレンダリングしている
• 解決策：1000件以上の項目にはVirtualizeコンポーネントを使用する
• 代替策：ボタンによるページネーション／無限スクロールを使用する

Blazor Serverの接続問題

• 原因：SignalR接続が切断された、または構成に問題がある
• 解決策：再接続UIを実装し、タイムアウトを延長する
• 構成：CircuitOptions.DisconnectedCircuitRetentionPeriodを調整する

リソースファイルの概要

components-lifecycle.md

コンポーネントの構造、ライフサイクルメソッド、パラメーター、カスケード値、コンポジションパターンに関する完全なガイドです。Blazorコンポーネントの基本を理解するうえで不可欠です。

state-management-events.md

ローカル状態とサービスベースの状態、EventCallbackによるイベント処理、データバインディングのパターン、コンポーネント間の通信を包括的に解説します。インタラクティブなUIの構築に不可欠です。

routing-navigation.md

ルートパラメーター、制約、プログラムによるナビゲーション、クエリ文字列、レイアウト管理を含む、ルーティングの完全なリファレンスです。複数ページのアプリに不可欠です。

forms-validation.md

EditFormコンポーネント、入力コントロール、DataAnnotationsによる検証、カスタムバリデーター、フォームのパターンを含む、フォームAPIの全容です。データ入力のシナリオで必要です。

authentication-authorization.md

ServerとWASMの完全な認証設定、AuthorizeView、ポリシー、クレームベースのアクセス制御、ログイン／ログアウトのパターンを解説します。セキュリティが必要なアプリケーションで必要です。

performance-advanced.md

ShouldRender、仮想化、JavaScript相互運用のパターン、遅延読み込み、WASMのベストプラクティスを含む、パフォーマンス最適化の手法を解説します。本番環境のアプリに不可欠です。

---

実装アプローチ

Blazorの機能を実装する際は、次の手順に従います。

1. タスクを特定する - 上記の判断表と照合する
2. 関連リソースを読み込む - 該当する.mdファイルを読む
3. コード例を探す - リソース内で類似した実装を検索する
4. コンテキストに合わせて調整する - 特定の要件に合わせて変更する
5. 十分にテストする - ホスティングモデルで検証する
6. トラブルシューティングを参照する - 問題が発生した場合はリソースを確認する

Next Steps

• New to Blazor? Start with components-lifecycle.md
• Building Data App? Move through: components → state → forms → validation
• Scaling Existing App? Focus on performance-advanced.md
• Adding Security? Follow authentication-authorization.md

---

Version: 2.0 - Modular Orchestration Pattern
Last Updated: December 4, 2025
Status: Production Ready ✅