ASP.NET Core Blazor の基礎

[アーティクル]
02/09/2024

メモ

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

重要

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

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

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

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

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

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

クライアント側のレンダリング (CSR) は、最終的な HTML マークアップがクライアント上の Blazor 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 コンポーネントは静的にレンダリングされるか、対話形式でレンダリングされます。

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

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

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

Razor のコンポーネント

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

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

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

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

プロジェクトのコード、ファイルのパスと名前、プロジェクトテンプレート名、その他の特殊な用語は、英語 (米国) で表記され、通常は 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 ステートメント、その他のディレクティブの順序でアルファベット順に配置されます。 Razor ディレクティブの順序付けの詳細については、「ASP.NET Core Razor コンポーネント」の "Razor の構文" セクションを参照してください。
記事の例では、アクセス修飾子が使われています。たとえば、フィールドは既定では private ですが、コンポーネントのコードに明示的に含まれています。たとえば、maxAllowedFiles という名前のフィールドを宣言するには、private を private int maxAllowedFiles = 3; のように記述します。
コンポーネントパラメータの値は、Razor 予約 @ 記号で始まりますが、これは必須ではありません。コンポーネントパラメータ値としてのリテラル (ブール値など)、キーワード (this など)、null に @ のプレフィックスは付けられていませんが、これも単なるドキュメント規則です。ご自身のコードでは、必要に応じてリテラルに @ のプレフィックスを付けることができます。
一般に、例は ASP.NET Core と C# のコーディング規則およびエンジニアリングガイドラインに従っています。詳しくは、次のリソースをご覧ください。
- エンジニアリングガイドライン (dotnet/aspnetcore GitHub リポジトリ)
- C# コーディング規則 (C# ガイド)

次に示すのは、カウンターコンポーネントの例と、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"

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

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

次の表は、Blazor Web アプリで 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 アプリ
Blazor WebAssembly
Blazor Web アプリと EF Core (ASP.NET Core Blazor と Entity Framework Core (EF Core))
Blazor Web アプリと SignalR (ASP.NET Core SignalR と Blazor を使用)
OIDC を使用した Blazor Web アプリ (OpenID Connect (OIDC) を使用して ASP.NET Core Blazor Web アプリをセキュリティで保護する)
Blazor WebAssembly スコープが有効なログ (ASP.NET Core Blazor のログ)
Blazor WebAssembly と ASP.NET Core Identity (セキュリティ保護された ASP.NET Core Blazor WebAssembly と ASP.NET Core Identity)

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

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

詳細については、Blazor サンプル GitHub レポジトリ README.md ファイルを参照してください。

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 の記事に関する問題である可能性がある場合は、ドキュメントのイシューを開きます。ドキュメントのイシューを開くには、記事の下部にある [このページ] フィードバックボタンとフォームを使って、開始コメントを作成するときにメタデータを残します。メタデータにより、追跡データが提供され、記事の作成者に自動的に通知されます。その問題について製品ユニットで説明されていた場合は、ドキュメントのイシュー開始コメントに、エンジニアリングイシューへのクロスリンクを付けておきます。

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 リソースへのコミュニティ リンク

フィードバック

その他のリソース

レンダーモード

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

サンプルアプリ

サポートリクエスト

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