ASP.NET Core のアンカータグヘルパー

[アーティクル]
11/30/2023

アンカータグヘルパーは、新しい属性を追加することで標準の HTML アンカー (<a ... ></a>) タグを拡張します。規則では、属性名の前に asp- が付きます。レンダリングされたアンカー要素の href 属性値は、asp- 属性の値によって決まります。

タグヘルパーの概要については、「ASP.NET Core のタグヘルパー」を参照してください。

サンプルコードを表示またはダウンロードします (ダウンロード方法)。

SpeakerController は、このドキュメント全体にわたってサンプルとして使用されます。

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;

public class SpeakerController : Controller
{
    private List<Speaker> Speakers =
        new List<Speaker>
        {
            new Speaker {SpeakerId = 10},
            new Speaker {SpeakerId = 11},
            new Speaker {SpeakerId = 12}
        };

    [Route("Speaker/{id:int}")]
    public IActionResult Detail(int id) =>
        View(Speakers.FirstOrDefault(a => a.SpeakerId == id));

    [Route("/Speaker/Evaluations", 
           Name = "speakerevals")]
    public IActionResult Evaluations() => View();

    [Route("/Speaker/EvaluationsCurrent",
           Name = "speakerevalscurrent")]
    public IActionResult Evaluations(
        int speakerId,
        bool currentYear) => View();

    public IActionResult Index() => View(Speakers);
}

public class Speaker
{
    public int SpeakerId { get; set; }
}

アンカータグヘルパーの属性

asp-controller

asp-controller 属性は、URL の生成に使用するコントローラーを割り当てます。次のマークアップでは、すべてのスピーカーが一覧表示されます。

<a asp-controller="Speaker"
   asp-action="Index">All Speakers</a>

生成される HTML:

<a href="/Speaker">All Speakers</a>

asp-controller 属性が指定されていて、asp-action が指定されていない場合は、既定値 asp-action が現在実行中のビューに関連付けられたコントローラーアクションです。 asp-action が前のマークアップから省略されていて、アンカータグヘルパーが HomeController の Index ビュー (/Home) で使用されている場合、次の HTML が生成されます:

<a href="/Home">All Speakers</a>

asp-action

asp-action 属性値は、生成された href 属性に含まれるコントローラーアクション名を表します。次のマークアップは、生成された href 属性値をスピーカー評価ページに設定します。

<a asp-controller="Speaker"
   asp-action="Evaluations">Speaker Evaluations</a>

生成される HTML:

<a href="/Speaker/Evaluations">Speaker Evaluations</a>

asp-controller 属性が指定されていない場合、現在のビューを実行しているビューを呼び出す既定のコントローラーが使用されます。

属性値 asp-action が Index で、URL にアクションが何も追加されていない場合、既定の Index の操作が呼び出されます。指定された (または既定の) 操作が、asp-controller で参照されるコントローラーに存在する必要があります。

asp-route-{value}

asp-route-{value} 属性は、ワイルドカードルートプレフィックスを有効にします。 {value} プレースホルダーに入っている値はすべて、潜在的なルートのパラメーターとして解釈されます。既定のルートが見つからない場合は、このルートプレフィックスが生成された href に要求パラメーターおよび値として追加されます。見つかった場合は、そのルートがルートテンプレートで置き換えられます。

次のコントローラーアクションがあるとします。

private List<Speaker> Speakers =
    new List<Speaker>
    {
        new Speaker {SpeakerId = 10},
        new Speaker {SpeakerId = 11},
        new Speaker {SpeakerId = 12}
    };

[Route("Speaker/{id:int}")]
public IActionResult Detail(int id) =>
    View(Speakers.FirstOrDefault(a => a.SpeakerId == id));

既定のルートテンプレートは Startup.Configure に定義されています。

app.UseMvc(routes =>
{
    // need route and attribute on controller: [Area("Blogs")]
    routes.MapRoute(name: "mvcAreaRoute",
                    template: "{area:exists}/{controller=Home}/{action=Index}");

    // default route for non-areas
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

MVC ビューは、次のように、アクションによって提供されるモデルを使用します。

@model Speaker
<!DOCTYPE html>
<html>
<body>
    <a asp-controller="Speaker"
       asp-action="Detail" 
       asp-route-id="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
</body>
</html>

既定のルートの {id?} プレースホルダーが一致しました。生成される HTML:

<a href="/Speaker/Detail/12">SpeakerId: 12</a>

次の MVC ビューのように、ルートプレフィックスが一致するルーティングテンプレートに含まれないものとします。

@model Speaker
<!DOCTYPE html>
<html>
<body>
    <a asp-controller="Speaker"
       asp-action="Detail"
       asp-route-speakerid="@Model.SpeakerId">SpeakerId: @Model.SpeakerId</a>
<body>
</html>

speakerid が一致するルートに見つからなかったため、次の HTML が生成されます。

<a href="/Speaker/Detail?speakerid=12">SpeakerId: 12</a>

asp-controller または asp-action のどちらかが指定されていない場合は、asp-route 属性の場合と同じ既定の処理に従います。

asp-route

asp-route 属性は、名前付きのルートに直接 URL リンクを作成するために使用します。ルーティング属性を使用すると、SpeakerController に示されているようにルートに名前を付け、その Evaluations アクションで使用することができます。

[Route("/Speaker/Evaluations", 
       Name = "speakerevals")]

次のマークアップでは、asp-route 属性が名前付きのルートを参照します。

<a asp-route="speakerevals">Speaker Evaluations</a>

アンカータグヘルパーは URL /Speaker/Evaluations を使用してそのコントローラーアクションに直接ルートを生成します。生成される HTML:

<a href="/Speaker/Evaluations">Speaker Evaluations</a>

asp-controller または asp-action が asp-route の他に指定されていると、想定と異なるルートが生成される場合があります。ルートの競合を防ぐには、asp-route を属性 asp-controller および asp-action とともに使用してはいけません。

asp-all-route-data

asp-all-route-data 属性は、キー/値ペアのディクショナリの作成をサポートします。キーはパラメーターの名前で、値はパラメーターの値です。

次の例では、ディクショナリが初期化され、Razor ビューに渡されます。データがモデルによって渡される場合もあります。

@{
var parms = new Dictionary<string, string>
            {
                { "speakerId", "11" },
                { "currentYear", "true" }
            };
}

<a asp-route="speakerevalscurrent"
   asp-all-route-data="parms">Speaker Evaluations</a>

上のコードを実行すると、次の HTML が生成されます。

<a href="/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true">Speaker Evaluations</a>

asp-all-route-data ディクショナリは、オーバーロードされた Evaluations アクションの要件を満たすクエリ文字列を生成するためにフラット化されます。

public IActionResult Evaluations() => View();

[Route("/Speaker/EvaluationsCurrent",
       Name = "speakerevalscurrent")]
public IActionResult Evaluations(

ディクショナリ内のいずれかのキーがルートパラメーターと一致する場合は、その値がルートで適宜置き換えられます。その他の一致しない値は要求パラメーターとして生成されます。

asp-fragment

asp-fragment 属性では URL に追加される URL フラグメントが定義されます。アンカータグヘルパーにより、ハッシュ文字 (#) が追加されます。次のマークアップがあるとします。

<a asp-controller="Speaker"
   asp-action="Evaluations"
   asp-fragment="SpeakerEvaluations">Speaker Evaluations</a>

生成される HTML:

<a href="/Speaker/Evaluations#SpeakerEvaluations">Speaker Evaluations</a>

ハッシュタグはクライアント側アプリを構築するときに便利です。たとえば、JavaScript でのマーク付けや検索を簡単にするために使用できます。

asp-area

asp-area 属性は、適切なルートの設定に使用する領域名を設定します。 asp-area 属性によってどのようにルートの再マップが行われるかの例を以下に示します。

Razor Pages での使用法

Razor Pages の領域は、ASP.NET Core 2.1 以降でサポートされます。

次のディレクトリ階層があるとします。

{プロジェクト名}
- wwwroot
- 領域
  - セッション
    - ページ
      - _ViewStart.cshtml
      - Index.cshtml
      - Index.cshtml.cs
- ページ

Sessions 領域の IndexRazor Page を参照するマークアップは次のとおりです:

<a asp-area="Sessions"
   asp-page="/Index">View Sessions</a>

生成される HTML:

<a href="/Sessions">View Sessions</a>

ヒント

Razor Pages アプリで領域をサポートするには、Startup.ConfigureServices で次のいずれかを行います。

互換性バージョンに 2.1 以降を設定します。

RazorPagesOptions.AllowAreas プロパティを true に設定します。

services.AddMvc()
        .AddRazorPagesOptions(options => options.AllowAreas = true);

MVC の使用法

次のディレクトリ階層があるとします。

{プロジェクト名}
- wwwroot
- 領域
  - ブログ
    - コントローラー
      - HomeController.cs
    - ビュー
      - Home
        
        AboutBlog.cshtml
        
        Index.cshtml
      - _ViewStart.cshtml
- コントローラー

asp-area を [ブログ] に設定すると、このアンカータグの関連付けられているコントローラーとビューのルートに、ディレクトリ Areas/Blogs のプレフィックスが付けられます。 AboutBlog ビューを参照するマークアップは次のとおりです。

<a asp-area="Blogs"
   asp-controller="Home"
   asp-action="AboutBlog">About Blog</a>

生成される HTML:

<a href="/Blogs/Home/AboutBlog">About Blog</a>

ヒント

MVC アプリで領域をサポートするには、ルートテンプレートに領域への参照 (存在する場合) が含まれている必要があります。そのテンプレートは、Startup.Configure の routes.MapRoute メソッド呼び出しの 2 番目のパラメーターで表されます

app.UseMvc(routes =>
{
    // need route and attribute on controller: [Area("Blogs")]
    routes.MapRoute(name: "mvcAreaRoute",
                    template: "{area:exists}/{controller=Home}/{action=Index}");

    // default route for non-areas
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

asp-protocol

asp-protocol 属性は URL に (https などの) プロトコルを指定するためにあります。次に例を示します。

<a asp-protocol="https"
   asp-controller="Home"
   asp-action="About">About</a>

生成される HTML:

<a href="https://localhost/Home/About">About</a>

例ではホスト名が localhost です。アンカータグヘルパーは、URL を生成するときに Web サイトのパブリックドメインを使用します。

asp-host

asp-host 属性は URL のホスト名を指定するためにあります。次に例を示します。

<a asp-protocol="https"
   asp-host="microsoft.com"
   asp-controller="Home"
   asp-action="About">About</a>

生成される HTML:

<a href="https://microsoft.com/Home/About">About</a>

asp-page

Razor Pages では、asp-page 属性が使用されます。アンカータグの href 属性の値を特定のページに設定するために使用します。ページ名の先頭に / を付けると、アプリのルートから一致するページの URL が作成されます:

サンプルコードでは、次のマークアップによって出席者 Razor Page へのリンクが作成されます:

<a asp-page="/Attendee">All Attendees</a>

生成される HTML:

<a href="/Attendee">All Attendees</a>

asp-page 属性は asp-route、asp-controller、asp-action の各属性と相互に排他的です。ただし、asp-page は、次のマークアップのサンプルで示されているように、asp-route-{value} とともに使用してルーティングを制御できます。

<a asp-page="/Attendee"
   asp-route-attendeeid="10">View Attendee</a>

生成される HTML:

<a href="/Attendee?attendeeid=10">View Attendee</a>

参照先ページが存在しない場合は、要求のアンビエント値を使用して、現在のページへのリンクが生成されます。デバッグログレベルを除き、警告は表示されません。

asp-page-handler

Razor Pages では、asp-page-handler 属性が使用されます。特定のページハンドラーへのリンクが目的です。

次のページハンドラーがあるとします。

public void OnGetProfile(int attendeeId)
{
    ViewData["AttendeeId"] = attendeeId;

    // code omitted for brevity
}

ページモデルの関連するマークアップが OnGetProfile ページハンドラーにリンクしています。ページハンドラーのメソッド名の On<Verb> プレフィックスは asp-page-handler 属性値では省略されることに注意してください。メソッドが非同期の場合は、Async サフィックスも省略されます。

<a asp-page="/Attendee"
   asp-page-handler="Profile"
   asp-route-attendeeid="12">Attendee Profile</a>

生成される HTML:

<a href="/Attendee?attendeeid=12&handler=Profile">Attendee Profile</a>

ASP.NET Core のアンカータグヘルパー

アンカータグヘルパーの属性

asp-controller

asp-action

asp-route-{value}

asp-route

asp-all-route-data

asp-fragment

asp-area

Razor Pages での使用法

MVC の使用法

asp-protocol

asp-host

asp-page

asp-page-handler

その他のリソース

フィードバック

その他のリソース

ASP.NET Core のアンカー タグ ヘルパー

アンカー タグ ヘルパーの属性

asp-controller

asp-action

asp-route-{value}

asp-route

asp-all-route-data

asp-fragment

asp-area

Razor Pages での使用法

MVC の使用法

asp-protocol

asp-host

asp-page

asp-page-handler

その他のリソース

フィードバック

その他のリソース

ASP.NET Core のアンカータグヘルパー

アンカータグヘルパーの属性