ASP.NET Core Blazor の基礎

[アーティクル]
11/12/2024

メモ

これは、この記事の最新バージョンではありません。現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

警告

このバージョンの ASP.NET Core はサポート対象から除外されました。詳細については、 .NET および .NET Core サポートポリシーを参照してください。現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

重要

この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

"基礎" に関する記事では、Blazor の基本概念に関するガイダンスを提供します。いくつかの概念は "Razor コンポーネント" の基本的な理解に結び付いており、それについてはこの記事の次のセクションおよび "コンポーネント" に関する記事で詳しく説明します。

静的および対話型のレンダリングの概念

Razor コンポーネントは静的にレンダリングされるか、対話形式でレンダリングされます。

静的、または静的レンダリングは、ユーザーと .NET/C# コード間の相互作用の容量なしでコンポーネントがレンダリングされることを意味するサーバー側のシナリオです。 JavaScript イベントと HTML DOM イベントは影響を受けませんが、クライアント上のユーザーイベントはサーバー上で実行されている .NET で処理できません。

対話型 または 対話型のレンダリング は、コンポーネントが C# コードを介して .NET イベントを処理する容量を持っていることを意味します。 .NET イベントは、ASP.NET Core ランタイムによってサーバー上で処理されるか、WebAssembly ベースの Blazor ランタイムによってクライアント上のブラウザーで処理されます。

重要

Blazor Web App を使用する場合、Blazor ドキュメントのほとんどのサンプルコンポーネントを機能させ、記事で説明されている概念を実証するには、インタラクティビティが必要です。記事で提供されるコンポーネントの例をテストする場合は、アプリがグローバルなインタラクティビティを採用しているか、またはコンポーネントが対話型レンダリングモードを採用していることを確認してください。

これらの概念と、静的レンダリングと対話型レンダリングを制御する方法の詳細は、Blazor ドキュメントの後半にある「ASP.NET Core Blazor レンダリングモード」の記事に記載されています。

クライアントとサーバーのレンダリングの概念

Blazor ドキュメント全体を通じて、ユーザーのシステムで行われるアクティビティは、クライアント上で、またはクライアント側で発生すると言われます。サーバー上で行われるアクティビティは、サーバー上またはサーバー側で発生すると言われます。

レンダリングという用語は、ブラウザーが表示する HTML マークアップを生成することを意味します。

クライアント側レンダリング (CSR) は、最終的な HTML マークアップがクライアント上の .NET WebAssembly ランタイムによって生成されることを意味します。アプリのクライアントによって生成された UI の HTML は、この種類のレンダリングのためにサーバーからクライアントに送信されません。ユーザーとページのやりとりが想定されます。 "静的" なクライアント側のレンダリングという概念はありません。 CSR は対話型と見なされるため、""対話型" クライアント側レンダリング" と ""対話型" CSR" は業界や Blazor のドキュメントでは使用されません。
サーバー側のレンダリング (SSR) は、最終的な HTML マークアップがサーバー上の ASP.NET Core ランタイムによって生成されることを意味します。 HTML は、ネットワーク経由でクライアントに送られて、そのクライアントのブラウザで表示されます。この種類のレンダリング用に、クライアントによってアプリのサーバーによって生成された UI の HTML は作成されません。 SSR には、次の 2 種類があります。
- 静的 SSR: サーバーでは、ユーザーインタラクティビティや Razor コンポーネントの状態の保持を提供しない静的 HTML を生成します。
- 対話型 SSR: Blazor イベントによってユーザーインタラクティビティが許可され、Razor コンポーネントの状態は Blazor フレームワークによって保持されます。
プリレンダリングは、レンダリングされたコントロールのイベントハンドラーを有効にせずに、最初にサーバーにページコンテンツをレンダリングするプロセスです。サーバーは、最初の要求に応じてできるだけ早くページの HTML UI を出力します。これにより、アプリはユーザーに対してより応答性が高くなります。プリレンダリングでは、検索エンジンがページランクの計算に使用する初期 HTTP 応答のコンテンツをレンダリングすることで、検索エンジンの最適化 (SEO) を向上させることもできます。プリレンダリングの後には、常にサーバーまたはクライアント上の最終レンダリングが続きます。

Razor のコンポーネント

Blazor アプリは "Razor コンポーネント" が基になっており、単に "コンポーネント" と呼ばれることがよくあります。 "コンポーネント" とは、ページ、ダイアログ、データ入力フォームといった UI の要素です。コンポーネントは、.NET アセンブリに組み込まれている .NET C# クラスです。

Razor は、クライアント側の UI ロジックと構成用に Razor マークアップページの形式でコンポーネントが通常記述される方法を示しています。 Razor とは、開発者の生産性のために設計された、C# コードに HTML マークアップを結合するための構文です。 Razor ファイルでは、.razor ファイル拡張子が使われます。

"Blazor コンポーネント" という用語を使用する Blazor 開発者やオンラインリソースもありますが、このドキュメントではそれは使わず、一貫して "Razor コンポーネント" または "コンポーネント" を使います。

Blazor のドキュメントでは、コンポーネントを示したり説明したりするためにいくつかの規則が使われています。

一般に、例は ASP.NET Core と C# のコーディング規則およびエンジニアリングガイドラインに従っています。詳細については次のリソースをご覧ください。
- ASP.NET Core フレームワークエンジニアリングガイドライン (dotnet/aspnetcore GitHub リポジトリ)
- C# コーディング規則 (C# ガイド)
プロジェクトのコード、ファイルのパスと名前、プロジェクトテンプレート名、その他の特殊な用語は、英語 (米国) で表記され、通常は code で囲まれています。
コンポーネントは、通常、C# のクラス名 (パスカルケース) の後に "コンポーネント" を付けて参照されます。たとえば、一般的なファイルアップロードコンポーネントは "FileUpload コンポーネント" と呼ばれます。
通常、コンポーネントの C# クラス名は、そのファイル名と同じです。
通常、ルーティング可能なコンポーネントの相対 URL は、コンポーネントのクラス名のケバブケース (ハイフンでつないだもの) に設定されます。たとえば、FileUpload コンポーネントに含まれるルーティング構成では、レンダリングされるコンポーネントに到達するために /file-upload という相対 URL が使われます。ルーティングとナビゲーションについては「ASP.NET Core の Blazor ルーティングとナビゲーション」をご覧ください。
コンポーネントの複数のバージョンが使われている場合は、順番に番号が付けられます。たとえば、FileUpload3 コンポーネントは /file-upload-3 で到達されます。
コンポーネント定義 (.razor file) の先頭にある Razor ディレクティブは、@page、@rendermode (.NET 8 以降)、@using ステートメント、その他のディレクティブの順序でアルファベット順に配置されます。
private メンバーには必要ありませんが、記事の例とサンプルアプリではアクセス修飾子が使用されています。たとえば、maxAllowedFiles という名前のフィールドを宣言するには、private を private int maxAllowedFiles = 3; のように記述します。
コンポーネントパラメータの値は、Razor 予約 @ 記号で始まりますが、これは必須ではありません。コンポーネントパラメータ値としてのリテラル (ブール値など)、キーワード (this など)、null に @ のプレフィックスは付けられていませんが、これも単なるドキュメント規則です。ご自身のコードでは、必要に応じてリテラルに @ のプレフィックスを付けることができます。
C# クラスでは、this キーワードを使用し、コンストラクターで割り当てられているアンダースコア (_) でフィールドのプレフィックスを付けないようにします。これは、ASP.NET Core フレームワークエンジニアリングガイドラインとは異なります。
プライマリコンストラクター (C# 12 以降) を使用する例では、通常、プライマリコンストラクターパラメーターはクラスメンバーによって直接使用されます。

Razor コンポーネント構文の詳細は、ASP.NET Core Razor コンポーネントの「Razor の構文」セクションにあります。

次に示すのは、カウンターコンポーネントの例と、Blazor プロジェクトテンプレートから作成されるアプリの一部です。コンポーネントの詳細については、このドキュメントで後述する "コンポーネント" の記事を参照してください。次の例では、このドキュメントで後述する "コンポーネント" についての記事の前にある "基礎" に関する記事で説明されているコンポーネントの概念を示します。

Counter.razor:

コンポーネントでは、対話型レンダリングモードが親コンポーネントから継承されるか、アプリにグローバルに適用されるものと想定されています。

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

前の Counter コンポーネントは次のようなものです。

最初の行の @page ディレクティブでルートを設定します。
ページのタイトルと見出しを設定します。
@currentCount で現在のカウントをレンダリングします。 currentCount は、@code ブロックの C# コードで定義されている整数変数です。
IncrementCount メソッドをトリガーするボタンを表示します。このメソッドは @code ブロックにあり、currentCount 変数の値を増やします。

レンダーモード

"基本" ノードの記事では、レンダリングモードの概念を参照します。このトピックの詳細については、"コンポーネント" ノードの「ASP.NET Core Blazor レンダリングモード」の記事で詳しく説明されています。記事の "基本" ノードの後に記載されています。

レンダリングモードの概念に関するこのノードの記事では、初期の参照については、現時点では以下の点にのみ注意してください：

Blazor Web App のすべてのコンポーネントは、レンダリングモードを採用して、使用するホスティングモデル、レンダリングされる場所、サーバー上で静的にレンダリングされるかどうか、サーバー上でユーザーの対話機能を使用してレンダリングされるかどうか、またはクライアント上のユーザー対話機能 (通常はサーバー上でプリレンダリング) 用にレンダリングされるかどうかを判断します。

.NET 8 以前の ASP.NET Core リリースの Blazor Server と Blazor WebAssembly アプリは、レンダリングモードではなく、ホスティングモデルの概念に固定されたままです。レンダリングモードは、概念的には .NET 8 以降の Blazor Web App に適用されます。

次の表は、Blazor Web App で Razor コンポーネントをレンダリングするために使用できるレンダーモードを示しています。レンダリングモードは、コンポーネントインスタンスまたはコンポーネント定義に関する @rendermode 指令があるコンポーネントに適用されます。アプリ全体のレンダリングモードを設定することもできます。

名前	説明	レンダーの場所	Interactive
静的サーバー	静的サーバー側レンダリング (静的 SSR)	[サーバー]	いいえ
対話型サーバー	Blazor Server を使用した対話型サーバー側レンダリング (対話型 SSR)	[サーバー]	はい
対話型 WebAssembly	Blazor WebAssembly を使用したクライアント側レンダリング (CSR)†	クライアント	はい
対話型自動	最初に Blazor Server、その後 Blazor バンドルのダウンロード後の後続のアクセスに CSR を使用する、対話型 SSR	サーバー、その後クライアント	はい

†クライアント側レンダリング (CSR) は対話型と見なされます。 ""対話型" クライアント側レンダリング" と ""対話型" CSR" は業界や Blazor のドキュメントでは使用されません。

レンダリングモードに関する上記の情報は、"基本" ノードの記事を理解するために知る必要のあるすべてです。 Blazor を利用するのが初めてで、目次の順に Blazor 記事を読まれている場合、"コンポーネント"　ノードの「ASP.NET Core Blazor レンダリングモード」の記事に到達するまでは、レンダリングモードに関する詳細な情報の使用を遅らせることができます。

ドキュメントオブジェクトモデル (DOM)

ドキュメントオブジェクトモデルへの参照では、省略形 DOM を使用します。

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

Blazor WebAssembly アプリ用 .NET API のサブセット

Blazor WebAssembly のブラウザーでサポートされている特定の .NET API のキュレーションされた一覧は使用できません。ただし、手動で [UnsupportedOSPlatform("browser")] の注釈が付いた .NET API の一覧を検索して、WebAssembly でサポートされていない .NET API を見つけることができます。

Note

通常、.NET 参照ソースへのドキュメントリンクを使用すると、リポジトリの既定のブランチが読み込まれます。このブランチは、.NET の次回リリースに向けて行われている現在の開発を表します。特定のリリースのタグを選択するには、[Switch branches or tags](ブランチまたはタグの切り替え) ドロップダウンリストを使います。詳細については、「ASP.NET Core ソースコードのバージョンタグを選択する方法」 (dotnet/AspNetCore.Docs #26205) を参照してください。

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

サンプルアプリ

ドキュメントサンプルアプリを調べたりダウンロードしたりできます。

Blazor サンプル GitHub リポジトリ (dotnet/blazor-samples)

使用している .NET のバージョンと一致するバージョンフォルダーを最初に選択して、サンプルアプリを見つけます。

リポジトリ内のサンプルアプリ:

Blazor Web App
Blazor WebAssembly
Blazor Web App と EF Core (ASP.NET Core Blazor と Entity Framework Core (EF Core))
Blazor Web App と SignalR (ASP.NET Core SignalR と Blazor を使用する)
2 つの Blazor Web App と Web (サーバー) API を呼び出すための Blazor WebAssembly アプリ (ASP.NET Core Blazor アプリから Web API を呼び出す)
OIDC を使用した Blazor Web App (BFF および BFF 以外のパターン) (OpenID Connect (OIDC) を使用して ASP.NET Core Blazor Web App をセキュリティで保護する)
Blazor WebAssembly スコープが有効なログ (ASP.NET Core Blazor のログ)
Blazor WebAssembly と ASP.NET Core Identity (セキュリティ保護された ASP.NET Core Blazor WebAssembly と ASP.NET Core Identity)
Blazor Web App と、Razor クラスライブラリ (RCL) によって提供される共有 UI を使用した .NET MAUIBlazor Hybrid アプリ (Blazor Web App を使用して .NET MAUIBlazor Hybrid アプリを構築する)

サンプルリポジトリには、2 種類のサンプルが含まれています。

サンプルアプリのスニペットが、記事に表示されているコード例を提供します。これらのアプリはコンパイルされますが、必ずしも実行可能なアプリではありません。これらのアプリは、記事に表示されるコード例を取得するだけの場合に便利です。
Blazor の記事に付随するサンプルアプリは、次のシナリオでコンパイルして実行できます。
- EF Core を含む Blazor Server
- SignalR を使用する Blazor Server と Blazor WebAssembly
- Blazor WebAssembly スコープ対応のログ記録

リポジトリ内のサンプルの詳細と一覧については、gitHub リポジトリ README.md ファイル Blazor サンプルを参照してください。

ASP.NET Core リポジトリの基本テストアプリは、さまざまな Blazor シナリオに役立つサンプルのセットでもあります:

ASP.NET Core 参照ソースの BasicTestApp (dotnet/aspnetcore)

メモ

サンプルアプリをダウンロードするには:

Blazor サンプルリポジトリ ZIP ファイルをダウンロードします。
ファイルを解凍します。

バイト倍数

.NET バイトサイズでは、1024 の累乗に基づいて、10 進数以外のバイトの倍数にメトリックプレフィックスが使用されます。

名前 (略称)	サイズ	例
キロバイト (KB)	1,024 バイト	1 KB = 1,024 バイト
メガバイト (MB)	1,024² バイト	1 MB = 1,048,576 バイト
ギガバイト (GB)	1,024³ バイト	1 GB = 1,073,741,824 バイト

サポートリクエスト

dotnet/AspNetCore.Docs リポジトリには、ドキュメント関連のイシューのみが適しています。 製品のサポートの場合は、ドキュメントのイシューを開かないでください。 次のサポートチャネルの 1 つまたは複数でサポートを受けることができます:

フレームワークの潜在的なバグまたは製品のフィードバックについては、dotnet/aspnetcore のイシューで ASP.NET Core 製品ユニットに対するイシューを開いてください。通常、バグレポートには次のものが "必要です"。

問題の明確な説明: イシューを開くと製品ユニットによって提供される GitHub イシューテンプレートの手順に従います。
最小限の再現プロジェクト: 製品ユニットエンジニアがダウンロードして実行できるように、プロジェクトを GitHub に置きます。イシューの開始コメントにプロジェクトをクロスリンクします。

Blazor の記事に関する問題である可能性がある場合は、ドキュメントのイシューを開きます。ドキュメントの問題を開くには、記事の下部にある [ドキュメントの問題を開く] フィードバックリンクを使用します。問題に追加されたメタデータにより、追跡データが提供され、記事の作成者に自動的に ping が送信されます。ドキュメントの問題を開くまえに、その件について製品ユニットで説明されていた場合は、ドキュメントの問題の開始コメントに、エンジニアリング問題へのクロスリンクを付けておきます。

Visual Studio に関する問題またはフィードバックについては、Visual Studio 内から問題の報告または機能の提案のジェスチャを使用して、Visual Studio の内部のイシューを開きます。詳しくは、Visual Studio のフィードバックに関するページをご覧ください。

Visual Studio Code の問題については、コミュニティサポートフォーラムでサポートを依頼してください。バグレポートと製品のフィードバックについては、microsoft/vscodeGitHub リポジトリでイシューを開いてください。

Blazor ドキュメントに関する GitHub のイシューは、Blazor.Docs プロジェクト (dotnet/AspNetCore.Docs GitHub リポジトリ) でトリアージのために自動的にマークされます。応答があるまでしばらくお待ちください (特に週末や休日)。通常、平日であればドキュメントの作成者が 24 時間以内に応答します。

Blazor リソースへのコミュニティリンク

コミュニティによって管理されている Blazor リソースへのリンクのコレクションについては、「Awesome Blazor」をご覧ください。

メモ

Microsoft は、Awesome Blazor およびそこで説明やリンクされているほとんどのコミュニティ製品やサービスを、所有、保守、またはサポートしていません。

次の方法で共有

ASP.NET Core Blazor の基礎

静的および対話型のレンダリングの概念

クライアントとサーバーのレンダリングの概念

Razor のコンポーネント

レンダーモード

ドキュメントオブジェクトモデル (DOM)

Blazor WebAssembly アプリ用 .NET API のサブセット

サンプルアプリ

バイト倍数

サポートリクエスト

Blazor リソースへのコミュニティリンク

その他のリソース

次の方法で共有

ASP.NET Core Blazor の基礎

静的および対話型のレンダリングの概念

クライアントとサーバーのレンダリングの概念

Razor のコンポーネント

レンダー モード

ドキュメント オブジェクト モデル (DOM)

Blazor WebAssembly アプリ用 .NET API のサブセット

サンプル アプリ

バイト倍数

サポート リクエスト

Blazor リソースへのコミュニティ リンク

その他のリソース

レンダーモード

ドキュメントオブジェクトモデル (DOM)

サンプルアプリ

サポートリクエスト

Blazor リソースへのコミュニティリンク