ASP.NET Core のタグ ヘルパー

作成者: Rick Anderson

タグ ヘルパーとは

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

タグ ヘルパーは、 Razor コンポーネントではサポートされていません。 詳細については、「ASP.NET Core Razor コンポーネント」を参照してください。

タグ ヘルパーが提供するもの

HTML に優しい開発エクスペリエンス

通常、タグ ヘルパーを使用 Razor マークアップは標準の HTML のようになります。 HTML/CSS/JavaScript で会話するフロントエンド デザイナーは、C# Razor構文を学習せずにRazorを編集できます。

HTML および Razor マークアップを作成するための豊富な IntelliSense 環境

これは、HTML ヘルパーとは対照的です。これは、 Razor ビューでのサーバー側のマークアップの作成に対する以前のアプローチです。 タグ ヘルパーと HTML ヘルパーの違 いについて詳しく説明します。 タグ ヘルパーの IntelliSense サポートでは、 IntelliSense 環境について説明します。 Razor C# 構文を使用した開発者でも、C# Razor マークアップを記述するよりもタグ ヘルパーを使用した方が生産性が高くなります。

サーバーでのみ使用可能な情報を使用して、生産性を高め、より堅牢で信頼性の高い保守可能なコードを生成できるようにする方法

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

ほとんどの組み込みタグ ヘルパーは、標準の HTML 要素を対象とし、要素のサーバー側属性を提供します。 たとえば、<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属性は、ForのLabelTagHelper プロパティで使用できます。 詳細については、「タグヘルパーの著者」を参照してください。

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

タグ ヘルパー スコープは、 @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 適用すると、指定したタグ ヘルパーがビューから削除されます。 @removeTagHelper ファイルでViews/Folder/_ViewImports.cshtmlを使用すると、指定したタグ ヘルパーが Folder 内のすべてのビューから削除されます。

_ViewImports.cshtml ファイルを使用したタグ ヘルパー スコープの制御

任意のビュー フォルダーに _ViewImports.cshtml を追加できます。ビュー エンジンは、そのファイルと Views/_ViewImports.cshtml ファイルの両方からディレクティブを適用します。 Views/Home/_ViewImports.cshtml ビューに空のHome ファイルを追加した場合、_ViewImports.cshtml ファイルが追加されているため、変更はありません。 @addTagHelper ファイルに追加するViews/Home/_ViewImports.cshtmlディレクティブ (既定のViews/_ViewImports.cshtml ファイルには含まれません) は、それらのタグ ヘルパーを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>要素には対応していません。

Razor ラベルと入力要素名のタグ ヘルパー プレフィックスが

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

自己終了タグ支援機能

多くのタグ ヘルパーは、自己終了タグとして使用できません。 一部のタグ ヘルパーは、自己終了タグとして設計されています。 自己終了するように設計されていないタグ ヘルパーを使用すると、レンダリングされた出力が抑制されます。 タグ ヘルパーを自己終了すると、レンダリングされた出力で自己終了タグが作成されます。 詳細については、「タグ ヘルパーの作成」のこのメモを参照してください。

タグヘルパーの属性/宣言におけるC#

タグ ヘルパーは、要素の属性またはタグ宣言領域で C# を許可しません。 たとえば、次のコードは無効です。

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

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

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

通常、 @ 演算子は、レンダリングされた HTML マークアップに式のテキスト表現を挿入します。 ただし、式が論理 falseに評価されると、フレームワークは代わりに属性を削除します。 前の例では、disabledまたはtrueがModelされている場合、LicenseId属性はnullに設定されます。

タグヘルパーの初期化子

属性を使用してタグ ヘルパーの個々のインスタンスを構成できますが、 ITagHelperInitializer<TTagHelper> を使用して、特定の種類のすべてのタグ ヘルパー インスタンスを構成できます。 アプリ内のasp-append-versionのすべてのインスタンスのAppendVersion属性またはScriptTagHelper プロパティを構成するタグ ヘルパー初期化子の次の例を考えてみましょう。

public class AppendVersionTagHelperInitializer : ITagHelperInitializer<ScriptTagHelper>
{
    public void Initialize(ScriptTagHelper helper, ViewContext context)
    {
        helper.AppendVersion = true;
    }
}

初期化子を使用するには、アプリケーションのスタートアップの一部として登録して初期化子を構成します。

builder.Services.AddSingleton
    <ITagHelperInitializer<ScriptTagHelper>, AppendVersionTagHelperInitializer>();

タグ ヘルパーの自動バージョン生成 (wwwroot 以外)

wwwroot外の静的ファイルのバージョンを生成するタグ ヘルパーについては、「複数の場所からファイルを提供する」を参照してください。

タグ ヘルパーの IntelliSense サポート

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

キーボードに「l」と入力すると、IntelliSense によって、

HTML ヘルプだけでなく、アイコン (下に "<>" が付いた "@" 記号) も表示されます。

下に

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

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

<label入力すると、IntelliSense によって使用可能な HTML/CSS 属性とタグ ヘルパーターゲット属性が一覧表示されます。

ユーザーが左角かっこと HTML 要素名

IntelliSense ステートメント補完を使用すると、タブキーを押すと、選択した値でステートメントを完了できます。

ユーザーは、開始角かっこ、HTML 要素名

タグ ヘルパー属性が入力されるとすぐに、タグと属性のフォントが変更されます。 既定の Visual Studio の "Blue" または "Light" の色テーマを使用すると、フォントは太字の紫色になります。 "濃色" テーマを使用している場合、フォントは太字になります。 このドキュメントの画像は、既定のテーマを使用して作成されました。

ユーザーが

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

ユーザーは、

IntelliSense には、ページ上のモデルで使用できるプロパティとメソッドが一覧表示されます。 豊富な IntelliSense 環境は、CSS クラスを選択するのに役立ちます。

ユーザーが

ユーザーは、

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

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

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

at (@) 記号は、Razor この部分がコードの先頭であることを示します。 次の 2 つのパラメーター ("FirstName" と "First Name:") は文字列であるため、 IntelliSense は役に立たない。 最後の引数:

new {@class="caption"}

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

LabelTagHelperを使用すると、同じマークアップを次のように記述できます。

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

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

ユーザーがキーボードに「l」と入力します。IntelliSense では、

IntelliSense は、行全体を記述するのに役立ちます。

次のコード画像は、Visual Studio に含まれる ASP.NET 4.5.x MVC テンプレートから生成された Views/Account/Register.cshtmlRazor ビューのフォーム部分を示しています。

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

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

@Html.AntiForgeryToken()

は灰色の背景で表示されます。 [登録] ビューのマークアップのほとんどは C# です。 タグ ヘルパーを使用して同等のアプローチと比較します。

Razor ASP.NET Core プロジェクト テンプレートの [ Razor 登録] ビューのフォーム部分のタグ ヘルパーを使用したマークアップ

マークアップは、HTML ヘルパー アプローチよりもはるかにクリーンで、読み取り、編集、保守が容易です。 C# コードは、サーバーが認識する必要がある最小限のコードに減らされます。 Visual Studio エディターでは、タグ ヘルパーの対象となるマークアップが独特のフォントで表示されます。

電子メール グループについて考えてみましょう。

<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 ヘルパー アプローチのほとんどのコードに対してヘルプを提供しません。 タグ ヘルパーに対する IntelliSense のサポート については、Visual Studio エディターでのタグ ヘルパーの操作について詳しく説明します。

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

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

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

  • Web サーバー コントロールを使用すると、クライアント コントロールを使用して、クライアント DOM 要素に機能を追加できます。 タグ ヘルパーには DOM がありません。

  • Web サーバー コントロールには、ブラウザーの自動検出が含まれます。 タグ ヘルパーには、ブラウザーに関する知識がありません。

  • 通常、Web サーバー コントロールを作成することはできませんが、複数のタグ ヘルパーは同じ要素に対して動作できます ( 「タグ ヘルパーの競合の回避」を参照)。

  • タグ ヘルパーは、スコープが設定されている HTML 要素のタグとコンテンツを変更できますが、ページ上の他の要素を直接変更することはできません。 Web サーバー コントロールは特定の範囲が少なく、ページの他の部分に影響を与えるアクションを実行することができます。これにより、意図しない副作用を引き起こす可能性があります。

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

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

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

フォントと色付けは、 Tools>Options>Environment>Fonts および Colors からカスタマイズできます。

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

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

錨

キャッシュ

コンポーネント

分散キャッシュ

環境

フォーム

フォーム アクション

イメージ

インプット

Label

リンク

部分的

コンポーネントの状態を保持する

スクリプト

選択

Textarea

検証メッセージ

検証の概要

その他のリソース

  • Last updated on