ASP.NET Core のタグ ヘルパー

作成者: Rick Anderson

タグ ヘルパーとは

タグ ヘルパーを使うと、Razor ファイルでの HTML 要素の作成とレンダリングに、サーバー側コードを組み込むことができます。 たとえば、組み込みの ImageTagHelper では、イメージ名にバージョン番号を追加することができます。 イメージが変更されるたびに、サーバーはイメージに対して新しい一意のバージョンを生成するため、クライアントは (キャッシュされた古いイメージではなく) 現在のイメージを確実に取得できます。 フォームやリンクの作成、資産の読み込みなど、一般的なタスクの組み込みのタグ ヘルパーは数多くあります。パブリック GitHub リポジトリで NuGet パッケージとして使用することもできます。 タグ ヘルパーは C# で作成され、要素名、属性名、または親タグに基づく HTML 要素をターゲットとします。 たとえば、LabelTagHelper 属性が適用されている場合、組み込みの LabelTagHelper では HTML <label> 要素をターゲットとすることができます。 Html ヘルパーを使い慣れている場合、タグヘルパーを使用すると、ビューでの Html と C# の間の明示的な切り替えを減らすことができ Razor ます。 多くの場合、HTML ヘルパーでは特定のタグ ヘルパーの代替方法が提供されますが、タグ ヘルパーを HTML ヘルパーの代わりに使用することはできないことと、各 HTML ヘルパーに対応するタグ ヘルパーがないことを認識することが重要です。 2 つの違いの詳細については、「タグ ヘルパーと HTML ヘルパーの比較」を参照してください。

タグ ヘルパーで提供されるもの

HTML を使いやすい開発エクスペリエンス ほとんどの場合、 Razor タグヘルパーを使用したマークアップは、標準 HTML のように見えます。 HTML/CSS/JavaScript で精通するフロントエンドデザイナーは、 Razor C# の構文を学習せずに編集でき Razor ます。

Html および Razor マークアップを作成するための豊富な IntelliSense 環境 は、html ヘルパーとは対照的に、ビューでのマークアップのサーバー側作成に対する従来のアプローチです Razor 。 2 つの違いの詳細については、「タグ ヘルパーと HTML ヘルパーの比較」を参照してください。 IntelliSense 環境については、「Intellisense でのタグ ヘルパーのサポート」を参照してください。 C# の構文に慣れている開発者であっても、 Razor タグヘルパーを使用して c# マークアップを記述するよりも生産性が向上 Razor します。

生産性を高め、サーバーでのみ使用可能な情報を使用することで、より堅牢で信頼できる保守しやすいコードを生成できる方法 たとえば、これまでは、イメージを変更する際にそのイメージ名を変更することがイメージ更新の理念でした。 パフォーマンス上の理由から、イメージを積極的にキャッシュする必要があり、イメージの名前を変更しない限り、クライアントが古いコピーを取得する危険性があります。 これまでは、イメージの編集後に、名前を変更する必要があり、Web アプリでのイメージへの各参照を更新する必要がありました。 非常に手間がかかるだけでなく、エラーも発生しやすくなります (参照を見逃したり、間違った文字列を誤って入力したりする可能性があります)。組み込みのは、 ImageTagHelper 自動的に行うことができます。 ImageTagHelper ではイメージ名にバージョン番号を追加できるため、イメージが変更されるたびに、サーバーはそのイメージに対して新しい一意のバージョンを自動的に生成します。 クライアントは現在のイメージを確実に取得できます。 ImageTagHelper を使用することで、このような堅牢性と省力化を基本的に自由に実現できます。

ほとんどの組み込みタグ ヘルパーは、標準の HTML 要素をターゲットとし、要素に対してサーバー側の属性を提供します。 たとえば、Views/Account フォルダーの多くのビューで使用される <input> 要素には、asp-for 属性が含まれて この属性は、指定されたモデル プロパティの名前をレンダリングされる HTML に抽出します 次のモデルのビューを考えてみましょう Razor 。

public class Movie
{
    public int ID { get; set; }
    public string Title { get; set; }
    public DateTime ReleaseDate { get; set; }
    public string Genre { get; set; }
    public decimal Price { get; set; }
}

次の Razor マークアップ:

<label asp-for="Movie.Title"></label>

次の HTML が生成されます。

<label for="Movie_Title">Title</label>

asp-for 属性は、LabelTagHelperFor プロパティで使用できます。 詳しくは、タグ ヘルパーの作成に関するページをご覧ください。

タグ ヘルパーのスコープの管理

タグ ヘルパーのスコープは、@addTagHelper@removeTagHelper、"!" オプトアウト文字の組み合わせによって制御されます。

@addTagHelper でタグ ヘルパーを使用可能にする

AuthoringTagHelpers という名前の新しい ASP.NET Core Web アプリを作成する場合、以下の Views/_ViewImports.cshtml ファイルがプロジェクトに追加されます。

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

@addTagHelper ディレクティブにより、ビューでタグ ヘルパーが使用可能になります。 この場合、ビュー ファイルは Pages/_ViewImports.cshtml であり、既定では Pages フォルダーとサブフォルダーのすべてのファイルによって継承され、タグ ヘルパーが使用可能になります。 上記のコードではワイルドカード構文 ("*") を使用して、指定されたアセンブリ (Microsoft.AspNetCore.Mvc.TagHelpers) 内のすべてのタグ ヘルパーが、Views ディレクトリまたはサブディレクトリ内のすべてのビュー ファイルで使用可能になるように指定します。 @addTagHelper の後の最初のパラメーターでは読み込むタグ ヘルパーを指定し (すべてのタグ ヘルパーに対して "*" を使用)、2 番目のパラメーター "Microsoft.AspNetCore.Mvc.TagHelpers" ではタグ ヘルパーを含むアセンブリを指定します。 Microsoft.AspNetCore.Mvc.TagHelpers は、組み込み ASP.NET Core タグ ヘルパーのアセンブリです。

すべてのタグ ヘルパーをこのプロジェクト (AuthoringTagHelpers という名前のアセンブリを作成する) で公開するには、以下を使用します。

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

プロジェクトに既定の名前空間がある EmailTagHelper が含まれている場合は (AuthoringTagHelpers.TagHelpers.EmailTagHelper)、タグ ヘルパーの完全修飾名 (FQN) を指定できます。

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

FQN を使用してビューにタグ ヘルパーを追加するには、最初に FQN (AuthoringTagHelpers.TagHelpers.EmailTagHelper) を追加してから、アセンブリ名 (AuthoringTagHelpers) を追加します。 ほとんどの開発者は、"*" ワイルドカード構文を使用するほうを選びます。 ワイルドカード構文を使用することで、FQN のサフィックスとしてワイルドカード文字 "*" を挿入できます。 たとえば、以下のディレクティブのいずれかで EmailTagHelper を取り込みます。

@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers

前述のとおり、@addTagHelper ディレクティブを Views/_ViewImports.cshtml ファイルに追加すると、タグ ヘルパーを Views ディレクトリとサブディレクトリ内のすべてのビュー ファイルで使用できるようになります。 これらのビューにのみタグ ヘルパーを公開することを選択する場合は、特定のビュー ファイルで @addTagHelper ディレクティブを使用できます。

@removeTagHelper でタグ ヘルパーを削除する

@removeTagHelper には @addTagHelper と同じ 2 つのパラメーターがあり、以前に追加されたタグ ヘルパーを削除します。 たとえば、特定のビューに適用された @removeTagHelper では、指定されたタグ ヘルパーをビューから削除します。 Views/Folder/_ViewImports.cshtml ファイルで @removeTagHelper を使用すると、Folder 内のすべてのビューから指定されたタグ ヘルパーが削除されます。

_ViewImports.cshtml ファイルによるタグ ヘルパー スコープの制御

_ViewImports.cshtml を任意のビュー フォルダーに追加することができ、ビュー エンジンではそのファイルと Views/_ViewImports.cshtml ファイルの両方のディレクティブが適用されます。 ビューに空の ビュー/ Home /_ViewImports cshtml ファイルを追加した場合、_ViewImports は追加されるため、変更はあり Home ません。 @addTagHelper Views/ Home /_ViewImports (既定の views/_ViewImports ファイルにはない) ファイルに追加するディレクティブは、そのタグヘルパーをフォルダー内のビューのみに公開します Home

個々の要素の無効化

タグ ヘルパーのオプトアウト文字 ("!") を使用して、要素レベルでタグ ヘルパーを無効にすることができます。 たとえば、Email 検証は、タグ ヘルパーのオプトアウト文字を使用して <span> で無効にすることができます。

<!span asp-validation-for="Email" class="text-danger"></!span>

開始タグと終了タグにタグ ヘルパーのオプトアウト文字を適用する必要があります (Visual Studio エディターでは、ユーザーがオプトアウト文字を開始タグに追加すると、自動的にオプトアウト文字が終了タグに追加されます)。 オプトアウト文字を追加した後、要素とタグ ヘルパーの属性は独特なフォントで表示されなくなります。

@tagHelperPrefix を使用してタグ ヘルパーの使用状況を明確にする

@tagHelperPrefix ディレクティブでは、タグ プレフィックス文字列を指定して、タグ ヘルパーのサポートを有効にしたり、タグ ヘルパーの使用状況を明確にすることができます。 たとえば、Views/_ViewImports.cshtml ファイルに次のマークアップを追加できます。

@tagHelperPrefix th:

以下のコード イメージでは、タグ ヘルパーのプレフィックスが th: に設定されているため、プレフィックス th: を使用する要素のみでタグ ヘルパーがサポートされます (タグ ヘルパーが有効な要素には独特なフォントがあります)。 <label> 要素と <input> 要素にはタグ ヘルパー プレフィックスがあり、タグ ヘルパーが有効ですが、<span> 要素にはありません。

::: no-loc (Razor)::: タグヘルパープレフィックスが "th:" に設定されたラベルと入力要素名のマークアップ

@addTagHelper に適用されるものと同じ階層規則が @tagHelperPrefix にも適用されます。

自己終了タグ ヘルパー

多くのタグ ヘルパーは、自己終了タグとして使用できません。 一部のタグ ヘルパーは、自己終了タグとして設計されています。 自己終了するようになっていないタグ ヘルパーを使用すると、表示される出力が抑制されます。 タグ ヘルパーを自己終了すると、表示される出力の中に自己終了タグが配置されます。 詳細については、タグ ヘルパーの作成に関するページのこちらの注意をご覧ください。

タグ ヘルパーの属性/宣言内の C#

タグ ヘルパーでは要素の属性またはタグ宣言区分の C# は許可されません。 たとえば、次のようなコードは有効ではありません。

<input asp-for="LastName"  
       @(Model?.LicenseId == null ? "disabled" : string.Empty) />

上記のコードは、次のように記述できます。

<input asp-for="LastName" 
       disabled="@(Model?.LicenseId == null)" />

Intellisense でのタグ ヘルパーのサポート

Visual Studio で新しい ASP.NET Core web アプリを作成すると、"AspNetCore." という NuGet パッケージが追加され Razor ます。ツール " これは、タグ ヘルパー ツールを追加するパッケージです。

HTML <label> 要素を書き込むことを検討してください。 Visual Studio エディターで <l を入力するとすぐに、IntelliSense で一致する要素が表示されます。

キーボードに「l」と入力すると、IntelliSense によって、使用可能なタグ名の一覧が "ラベル" で選択されます。

HTML ヘルプだけでなく、アイコン ("@" symbol with "<>") も表示されます。

その下の " @" symbol with "<>"。

アイコンは、タグヘルパーの対象となる要素を識別します。 純粋な HTML 要素 (fieldset など) では "<>" アイコンが表示されます。

純粋な HTML <label> タグの場合、HTML タグ (既定の Visual Studio の配色テーマ) が茶色のフォントで、属性が赤で、属性値が青で表示されます。

"Label" HTMl タグの例

<label を入力した後、IntelliSense では次のように使用可能な HTML/CSS 属性とタグ ヘルパーのターゲットとなる属性がリストされます。

ユーザーが始めかっこと HTML 要素名 "label" を入力しました。 IntelliSense では、使用可能な属性の一覧が表示されます (事前に選択されていません)。

IntelliSense ステートメント入力候補では、Tab キーを入力して、選択した値を使用してステートメントを完了することができます。

ユーザーは、開始角かっこ (HTML 要素名 "label") を入力し、属性名 ("as") の入力を開始します。 IntelliSense では、"asp-for" が選択された候補のダイアログが表示されます。

タグ ヘルパー属性が入力されるとすぐに、タグと属性のフォントが変わります。 既定の Visual Studio の "青" または "ライト" の配色テーマを使用すると、フォントが太字の紫になります。 "ダーク" テーマを使用する場合、フォントは太字の青緑になります。 このドキュメントのイメージは、既定のテーマを使用して取得されたものです。

ユーザーが "asp-for" を選択しました。これは、ユーザーがダーク テーマを使用しないので、太字で紫色になります。

Visual Studio の CompleteWord ショートカット (既定は Ctrl + Space) を二重引用符 ("") 内に入力することができ、C# クラスの場合と同じように C# で使用できるようになりました。 IntelliSense では、ページ モデルですべてのメソッドとプロパティが表示されます。 プロパティの種類が ModelExpression であるため、メソッドとプロパティを使用できます。 次のイメージでは、Register ビューを編集するため、RegisterViewModel を使用できます。

ユーザーは、"asp-for" 属性の値に「e」と入力します。 IntelliSense では、"Email" が選択された場合に入力が提案されます。

IntelliSense では、ページのモデルで使用可能なプロパティとメソッドがリストされます。 豊富な IntelliSense 環境は、CSS クラスを選択する場合に役立ちます。

ユーザーは「cl」と入力して、"input" 要素に属性を追加します。 IntelliSense では、"class" が選択された入力候補の一覧が表示されます。

ユーザーは、"input" 要素の "class" 属性の値として「co」と入力します。 IntelliSense には、"col" が選択された入力候補の一覧が表示されます。

タグ ヘルパーと HTML ヘルパーの比較

タグ ヘルパーはビューの HTML 要素にアタッチされ、HTML ヘルパーはビュー内の HTML と相互に使用されるメソッド Razor として呼び出 Razor されます。 CSS クラス Razor "caption" を使用して HTML ラベルを作成する次のマークアップについて考えます。

@Html.Label("FirstName", "First Name:", new {@class="caption"})

at ( @ ) 記号は、 Razor これがコードの開始を示します。 次の 2 つのパラメーター ("FirstName" と "First Name:") は文字列であるため、IntelliSense では対応できません。 以下が最後の引数です。

new {@class="caption"}

これは属性を表すために使用される匿名オブジェクトです。 class は C# の予約済みのキーワードであるため、@ シンボルを使用して、C# で強制的に @class= をシンボル (プロパティ名) として解釈するようにします。 フロントエンド デザイナー (HTML/CSS/JavaScript や他のクライアント テクノロジに精通しているが、C# や に詳しくない人) にとって、ほとんどの行は Razor 外部です。 IntelliSense に頼らずに行全体を作成する必要があります。

LabelTagHelper を使用すれば、以下と同じマークアップを書き込むことができます。

<label class="caption" asp-for="FirstName"></label>

タグ ヘルパー バージョンを使用して Visual Studio エディターで <l を入力するとすぐに、IntelliSense で一致する要素が表示されます。

ユーザーはキーボードに「l」と入力します。 IntelliSense では、"label" が選択された HTML 要素補完が提案されます。

IntelliSense は行全体を書き込む場合に役立ちます。

次のコードイメージは、ASP.NET 4.5.x MVC テンプレートから生成された views/Account/Register.cshtml ビューのフォーム部分を示しています Razor Visual Studio。

Razor register Razor view for ASP.NET 4.5 MVC プロジェクト テンプレートのフォーム部分のマークアップ

Visual Studio エディターでは、背景が灰色の C# コードが表示されます。 たとえば、次の AntiForgeryToken HTML ヘルパーの場合、

@Html.AntiForgeryToken()

灰色の背景で表示されます。 Register ビューのマークアップのほとんどは C# です。 以下のタグ ヘルパーを使用する同じ方法と比較します。

Razor Register Razor view for a ASP.NET Core プロジェクト テンプレートのフォーム部分のタグ ヘルパーを使用したマークアップ

HTML ヘルパーの方法よりも、マークアップがわかりやすく、読み取り、編集、保持が簡単になります。 C# コードは、サーバーで認識する必要がある最低限まで減っています。 Visual Studio エディターでは、独特なフォントでタグ ヘルパーのターゲットとなるマークアップが表示されます。

たとえば、以下の Email グループについて考えてみます。

<div class="form-group">
    <label asp-for="Email" class="col-md-2 control-label"></label>
    <div class="col-md-10">
        <input asp-for="Email" class="form-control" />
        <span asp-validation-for="Email" class="text-danger"></span>
    </div>
</div>

"asp-" 属性にはそれぞれ "Email" の値がありますが、"Email" は文字列ではありません。 このコンテキストでは、"Email" は RegisterViewModel の C# モデル式のプロパティとなります。

Visual Studio エディターは登録フォームのタグ ヘルパーの方法で すべて のマークアップを書き込む場合に役立ちますが、Visual Studio は HTML ヘルパーの方法ではほとんどのコードに対応できません。 Visual Studio エディターでのタグ ヘルパーの操作の詳細については、「IntelliSense でのタグ ヘルパーのサポート」を参照してください。

タグ ヘルパーと Web サーバー コントロールの比較

  • タグ ヘルパーには関連付けられている要素はなく、要素とコンテンツのレンダリングに参加するだけです。 ASP.NET Web サーバー コントロールは、ページで宣言および呼び出されます。

  • ASP.NET Web サーバー コントロールには、開発とデバッグを困難にする可能性がある、簡単ではないライフサイクルがあります。

  • Web サーバー コントロールではクライアント コントロールを使用して、クライアントのドキュメント オブジェクト モデル (DOM) 要素に機能を追加することができます。 タグ ヘルパーには DOM がありません。

  • Web サーバー コントロールには自動ブラウザー検出が含まれます。 タグ ヘルパーではブラウザーが認識されません。

  • 複数のタグ ヘルパーを同じ要素で実行できますが (タグ ヘルパーの競合の回避に関するページを参照)、通常は Web サーバー コントロールを構成できません。

  • タグ ヘルパーではスコープとなる HTML 要素のタグとコンテンツを変更できますが、ページ上の他のものを直接変更しません。 Web サーバー コントロールではスコープが限定されないため、ページの他の部分に影響を与えるアクションを実行して、予想外の結果となる場合があります。

  • Web サーバー コントロールでは型コンバーターを使用して、文字列をオブジェクトに変換します。 タグ ヘルパーの場合、C# でネイティブに作業するため、型を変換する必要はありません。

  • Web サーバー コントロールでは System.ComponentModel 名前空間を使用して、コンポーネントやコントロールの実行時動作およびデザイン時動作を実装します。 System.ComponentModel には、属性と型コンバーターの実装、データ ソースへのバインド、コンポーネントのライセンス処理のための基底クラスと基底インターフェイスが含まれています。 通常は TagHelper から派生するタグ ヘルパーとは異なり、TagHelper 基底クラスでは ProcessProcessAsync の 2 つのメソッドのみを公開します。

タグ ヘルパー要素のフォントのカスタマイズ

[ツール > ] [オプション][ > 環境] > [フォントおよび色] から、フォントと色付けをカスタマイズできます。

Visual Studio の [オプション] ダイアログ

組み込み ASP.NET Core タグ ヘルパー

アンカー タグ ヘルパー

キャッシュ タグ ヘルパー

コンポーネント タグ ヘルパー

分散キャッシュ タグ ヘルパー

環境タグ ヘルパー

フォーム タグ ヘルパー

フォーム アクション タグ ヘルパー

イメージ タグ ヘルパー

入力タグ ヘルパー

ラベル タグ ヘルパー

リンク タグ ヘルパー

部分タグ ヘルパー

スクリプト タグ ヘルパー

選択タグ ヘルパー

Textarea タグ ヘルパー

検証メッセージ タグ ヘルパー

検証概要タグ ヘルパー

その他のリソース