create-blazor-project

Blazor Web アプリを作成する

開始前 — 要件を確認する

ユーザーのリクエストから以下の内容が明確でない場合は、スキャフォールディングを開始する前に確認してください。

1. アプリで何をしますか？ 主な画面や機能を挙げてください（例：「検索機能とショッピングカートを備えた商品カタログ」）。
2. どのようなインタラクティブ機能が必要ですか？ データやフォームの表示ですか？ リアルタイム更新ですか？ オフライン対応ですか？ 高度なドラッグ＆ドロップ UI ですか？
3. デプロイ環境はどのようなものですか？ インターネットに公開しますか？ イントラネットですか？ 通信速度が遅い環境を使うモバイルユーザーはいますか？
4. 認証は必要ですか？ 匿名ですか？ 個別アカウントですか？ 組織向け（Azure AD）ですか？

適切なインタラクティビティレベルを選ぶ

Blazor のレンダーモードは段階的に選択できます。要件を満たす最もシンプルなレベルから始め、具体的な理由がある場合にのみ上のレベルへ移行してください。

Static SSR ──→ SSR + Enhanced Nav ──→ Interactive Server ──→ Interactive WebAssembly
 simplest                                                           most complex

選択ルール

アプリに必要な機能	使用するもの	理由
データの表示、シンプルなフォーム、ページ間のリンク	静的 SSR（-int None）	JS ランタイムも回線も WebAssembly のダウンロードも不要です。フォームは HTML POST で動作します。拡張ナビゲーションにより、軽快に感じられます。
上記すべてに加え、クライアント側の動作が必要なコンポーネントが少数ある（ライブ検索、リアルタイム更新、複雑なフォームウィザードなど）	インタラクティブサーバー、ページ単位（-int Server）	インタラクティビティが必要なコンポーネントだけが、@rendermode で有効化されます。それ以外は静的なままです。サーバー側で実行され、.NET の全機能を利用でき、API レイヤーも不要です。
ほとんどのページで高度なインタラクティビティが必要（ダッシュボード、ドラッグ＆ドロップ、チャットなど）	インタラクティブサーバー、グローバル（-int Server -ai）	すべてのコンポーネントが既定でインタラクティブになります。UX に一貫性があり、概念モデルもシンプルです。トレードオフとして、サーバー上で各ユーザーが SignalR 回線を保持します。
ネットワーク遅延が問題になる、モバイルユーザーや通信環境の悪いユーザーがいる、またはアプリをオフラインで動作させる必要がある	インタラクティブ WebAssembly（-int WebAssembly）	コードはブラウザーで実行されます。往復遅延を解消できますが、.Client プロジェクトと、データアクセス用の API レイヤーが必要です。また、初回アクセス時に .NET ランタイムをブラウザーにダウンロードします。オフライン対応には、スキャフォールディング後にサービスワーカーとマニフェストを追加して PWA を有効にしてください（テンプレートには既定で含まれていません）。
初回読み込みを高速化（サーバー）し、その後の遅延を低く抑える（WebAssembly）	インタラクティブ Auto（-int Auto）	初回アクセスではサーバーを使用し、以降のアクセスではキャッシュされた WebAssembly ランタイムを使用します。最も複雑なセットアップです。以下の Auto の制約を参照してください。サーバーと WebAssembly の両方の制約が該当する場合にのみ選択してください。

既定の推奨事項： -int Server（ページ単位）から始めてください。ほとんどのアプリで十分です。特定の要件により必要となる場合にのみ、グローバルまたは WebAssembly に切り替えてください。

Auto モードの制約

Auto モードでは、コンポーネントのコードはまずサーバーで実行され、その後のアクセスではブラウザーで実行されます。これには、実際の制約があります。

• すべてのインタラクティブコンポーネントは .Client プロジェクトに配置する必要があります — WebAssembly と同様です。
• インタラクティブコンポーネントからサーバーに直接アクセスすることはできません — EF の DbContext、ファイルシステム、サーバー専用サービスは使用できません。すべてのデータアクセスは HTTP API 経由で行う必要があります。
• 両方の Program.cs ファイルで、対応するサービスを登録する必要があります — サーバーとクライアントの DI コンテナーの両方に、インタラクティブコンポーネントが挿入する各サービスの実装が必要です。
• コードで実行環境を前提にしてはいけません — HttpContext へのアクセスや、RendererInfo による確認なしでのブラウザー専用 API の使用は避けてください。
• 両方のモードでテストしてください — 開発中にサーバーで動作するコンポーネントでも、本番環境の WebAssembly（2 回目以降のアクセス）で問題が発生する場合があります。両方の経路をテストしてください。

避けるべきこと

• WebAssembly を「かっこいいから」という理由だけで選ばないでください — .Client プロジェクトが追加され、データアクセスは API 経由に限定され、初回アクセス時にブラウザーへ約 10MB がダウンロードされます。
• サーバー単独でも WebAssembly 単独でも不十分な理由を説明できない場合は、Auto を選ばないでください。
• ほとんどのページが読み取り専用コンテンツであるアプリでは、グローバルインタラクティビティを選ばないでください — ページ単位にすれば、静的ページを高速に保ち、サーバーメモリの使用量を抑えられます。

プロジェクトをスキャフォールディングする

静的 SSR のみ（データ表示＋シンプルなフォーム）

dotnet new blazor -o {AppName} -int None

インタラクティブなランタイムはありません。blazor.web.js により、拡張ナビゲーションがデフォルトで有効になります。

ページごとのインタラクティブサーバー（推奨のデフォルト）

dotnet new blazor -o {AppName} -int Server

ページはデフォルトで静的です。インタラクティブ機能が必要なコンポーネントに @rendermode InteractiveServer を追加します。

グローバルなインタラクティブサーバー

dotnet new blazor -o {AppName} -int Server -ai

App.razor の <Routes @rendermode="InteractiveServer" /> により、すべてのページがインタラクティブになります。

ページごとのインタラクティブ WebAssembly

dotnet new blazor -o {AppName} -int WebAssembly

{AppName}（サーバー）と {AppName}.Client（WebAssembly）のプロジェクトが作成されます。インタラクティブコンポーネントは .Client に配置する必要があります。

グローバルなインタラクティブ WebAssembly

dotnet new blazor -o {AppName} -int WebAssembly -ai

ページごとのインタラクティブ Auto

dotnet new blazor -o {AppName} -int Auto

グローバルなインタラクティブ Auto

dotnet new blazor -o {AppName} -int Auto -ai

認証あり

上記のコマンドのいずれかに -au Individual を追加します。

dotnet new blazor -o {AppName} -int Server -au Individual

-au Individual は、SQLite（CLI）または SQL Server（Visual Studio）を使用する ASP.NET Core Identity をスキャフォールディングします。Identity ページは常に静的 SSR であり、インタラクティブレンダーモードは使用しません。

blazor テンプレートがサポートするのは -au Individual のみです。組織認証（Microsoft Entra ID、Azure AD B2C）の場合は、まず -au Individual でスキャフォールディングし、その後 Identity プロバイダーを Microsoft.Identity.Web／OIDC ミドルウェアに置き換え、appsettings.json でテナントを構成します。

テンプレートで作成されるもの

単一プロジェクト（静的 SSR、サーバー）

{AppName}/
├── Components/
│   ├── App.razor              # Root component — sets <HeadOutlet> and <Routes>
│   ├── Routes.razor           # Wraps <Router> with route discovery
│   ├── Layout/
│   │   ├── MainLayout.razor   # App shell with nav, header, footer
│   │   └── MainLayout.razor.css
│   └── Pages/
│       └── Home.razor         # @page "/" — first page
├── Program.cs                 # Service registration and middleware
├── wwwroot/                   # Static files (CSS, images)
└── {AppName}.csproj

2 つのプロジェクト（WebAssembly、Auto）

{AppName}/                     # Server project — hosts the app
├── Components/                # Server-only components (static SSR pages, layouts)
│   ├── App.razor
│   ├── Routes.razor
│   └── Layout/
├── Program.cs                 # Server Program.cs
└── {AppName}.Client/          # Client project — WebAssembly components
    ├── Pages/                 # Interactive components go HERE
    ├── Program.cs             # Client Program.cs
    └── _Imports.razor

ルール： InteractiveWebAssembly または InteractiveAuto を使用するコンポーネントは、.Client プロジェクトに配置する必要があります。共有コードは参照できますが、サーバー専用の型（EF DbContext、サーバー側サービス）は参照できません。

Program.cs の配線

テンプレートは、選択したモードに応じた正しい Program.cs を生成します。以下の登録が意図どおりであることを確認してください。

静的 SSR のみ

// Program.cs
builder.Services.AddRazorComponents();

// ...

app.MapRazorComponents<App>();

サーバー（ページごと、またはグローバル）

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

// ...

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

WebAssembly（ページごと、またはグローバル）

// Server Program.cs
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

// ...

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly);

// Client Program.cs
builder.Services.AddAuthorizationCore();
// Register HttpClient, other client-side services

プロジェクトの AGENTS.md を作成する

スキャフォールディング後、プロジェクトのルート（.csproj の隣）に AGENTS.md ファイルを作成します。2 プロジェクト構成の場合は、サーバープロジェクトのルートに配置します。

選択したモードに応じて、assets/agents-md/ から対応するテンプレートを選びます。

モード	テンプレートファイル
静的 SSR（-int None）	assets/agents-md/ssr-none.md
サーバー、ページごと（-int Server）	assets/agents-md/server-per-page.md
サーバー、グローバル（-int Server -ai）	assets/agents-md/server-global.md
WebAssembly、ページごと（-int WebAssembly）	assets/agents-md/webassembly-per-page.md
WebAssembly、グローバル（-int WebAssembly -ai）	assets/agents-md/webassembly-global.md
Auto、ページごと（-int Auto）	assets/agents-md/auto-per-page.md
Auto、グローバル（-int Auto -ai）	assets/agents-md/auto-global.md

テンプレートの内容をプロジェクトの AGENTS.md にコピーし、すべての {AppName} を実際のプロジェクト名に置き換えます。認証をスキャフォールディングした場合（-au Individual）、ASP.NET Core Identity が構成済みであること、および Components/Account/ 配下の Identity ページは常に静的 SSR であることを記載した ## Authentication セクションを追加します。これらのページには @rendermode を追加しないでください。

プロジェクトのスキャフォールディングと AGENTS.md の作成後は、ユーザーが依頼した機能の実装を続けてください。 デフォルトのテンプレートページ（Counter、Weather）を削除し、実際のアプリケーションページに置き換えます。

Auto（ページごと、またはグローバル）

// Server Program.cs
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

// ...

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly);

App.razor — グローバルとページごとの違い

グローバルとページごとのインタラクティブ機能の違いは、すべて App.razor にあります。

ページごと（デフォルト）

<!DOCTYPE html>
<html>
<head>
    <HeadOutlet />
</head>
<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

<Routes> または <HeadOutlet> に @rendermode を指定しません。個々のページで有効にします。

グローバル

<!DOCTYPE html>
<html>
<head>
    <HeadOutlet @rendermode="InteractiveServer" />
</head>
<body>
    <Routes @rendermode="InteractiveServer" />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

InteractiveServer を、適切な InteractiveWebAssembly または InteractiveAuto に置き換えます。

スキャフォールディング後

1. ビルドを確認します： dotnet build
2. 実行します： dotnet run（2 プロジェクト構成の場合は、サーバープロジェクトで実行します）
3. 最初のページを追加します： サーバープロジェクトの Components/Pages/、または WebAssembly コンポーネントの場合は .Client プロジェクトの Pages/ に .razor ファイルを作成します。

やってはいけないこと

• dotnet new blazorwasm は使用しないでください。サーバー側レンダリングのないスタンドアロンの WebAssembly SPA が作成されます。代わりに、-int WebAssembly を指定して blazor テンプレートを使用してください。
• -int None で作成したプロジェクトに AddInteractiveServerComponents() を手動で追加して、動作することを期待しないでください。@rendermode ディレクティブと、場合によっては App.razor の変更も必要です。モードを根本的に変更する必要がある場合は、再度スキャフォールディングしてください。
• WebAssembly を対象とするコンポーネントをサーバープロジェクトに配置しないでください。プリレンダリング中は動作しますが、引き継ぎ後に失敗します。