ASP.NET Core Blazor の基礎

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

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

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"

<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 変数の値を増やします。

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

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

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

• DOM の概要 (MDN ドキュメント)
• レベル 1 ドキュメント オブジェクト モデルの仕様 (W3C)

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

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

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

• クラス ライブラリ: クライアント側ブラウザー互換性アナライザー
• 特定のプラットフォームでサポートされていない API に注釈を付ける (dotnet/designs GitHub リポジトリ

サンプル アプリ

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

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

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

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

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

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

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

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

バイト倍数

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

サポート リクエスト

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

• Stack Overflow (タグ: blazor)
• 一般的な ASP.NET Core Slack チーム
• Blazor Gitter

フレームワークの潜在的なバグまたは製品のフィードバックについては、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」をご覧ください。