Anchor-Tag-Hilfsprogramm in ASP.NET Core

Von Peter Kellner und Scott Addie

Das Anchor-Taghilfsprogramm verbessert das HTML-Anchor-Tag (<a ... ></a>), indem neue Attribute hinzugefügt werden. Per Konvention erhalten Attributnamen das Präfix asp-. Der Attributwert href des gerenderten Anchor-Elements wird von den Werten der asp--Attribute bestimmt.

Eine Übersicht der Taghilfsprogramme finden Sie unter Taghilfsprogramme in ASP.NET Core.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Der folgende SpeakerController wird in den Beispielen in diesem Dokument verwendet:

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; }
}

Attribute des Anchor-Taghilfsprogramms

asp-controller

Das Attribut asp-controller weist den Controller zu, der zum Generieren der URL verwendet wird. Im folgenden Markup werden alle Lautsprecher aufgeführt:

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

Der generierte HTML-Code:

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

Wenn das Attribut asp-controller angegeben wird und asp-action nicht, entspricht der asp-action-Standardwert der Controlleraktion, die der aktuell ausgeführten Ansicht zugeordnet ist. Wenn asp-action im vorangehenden Markup ausgelassen wird und das Anchor-Taghilfselement in der Indexansicht des Home Controllers( ) verwendet wird, /Home lautet der generierte HTML-Code:

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

asp-action

Der Attributwert asp-action repräsentiert den Namen der Controlleraktion, die im generierten href-Attribut enthalten ist. Im folgenden Markup wird der generierte href-Attributwert auf die Auswertungsseite des Lautsprechers festgelegt:

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

Der generierte HTML-Code:

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

Wenn kein asp-controller-Attribut angegeben ist, wird der Standardcontroller zum Aufruf der Ansicht verwendet, die die aktuelle Ansicht ausführt.

Wenn der Wert des asp-action-Attribut Index lautet, wird keine Aktion an die URL angefügt, was zum Aufruf der Index-Standardaktion führt. Die angegebene (oder standardmäßige) Aktion muss im Controller vorhanden sein, auf den in asp-controller verwiesen wird.

asp-route-{value}

Das Attribut asp-route{value} aktiviert ein Platzhalterroutenpräfix. Ein beliebiger Wert im Platzhalter {value} wird als potenzieller Routenparameter interpretiert. Wenn keine Standardroute gefunden wird, wird dieses Routenpräfix als Anforderungsparameter und -wert an das generierte href-Attribut angefügt. Andernfalls wird es in der Routenvorlage ersetzt.

Betrachten Sie die folgende Controlleraktion:

public IActionResult AnchorTagHelper(int id)
{
    var speaker = new Speaker
    {
        SpeakerId = id
    };

    return View(speaker);
}

Mit einer in Startup.Configure definierten Standardroutenvorlage:

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?}");
});

Die MVC-Ansicht verwendet das von der Aktion bereitgestellte Modell wie folgt:

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

Der {id?}-Platzhalter der Standardroute wurde abgeglichen. Der generierte HTML-Code:

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

Angenommen, das Routenpräfix ist (wie in der folgenden MVC-Ansicht gezeigt) nicht Teil der übereinstimmenden Routingvorlage:

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

Der folgende HTML-Code wird generiert, weil speakerid nicht in der übereinstimmenden Route gefunden wurde:

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

Wenn entweder asp-controller oder asp-action nicht angegeben werden, erfolgt der gleiche Standardverarbeitungsprozess wie beim asp-route-Attribut.

asp-route

Das Attribut asp-route wird zum Erstellen einer URL verwendet, die direkt auf eine benannte Route verweist. Mit der Verwendung von Routingattributen kann eine Route wie in SpeakerController gezeigt benannt und in der zugehörigen Evaluations-Aktion verwendet werden:

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

Im folgenden Markup verweist das asp-route-Attribut auf die benannte Route:

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

Das Anchor-Taghilfsprogramm generiert eine Route direkt zu dieser Controlleraktion. Dabei wird die URL /Speaker/Evaluations verwendet. Der generierte HTML-Code:

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

Wenn asp-controller oder asp-action zusätzlich zu asp-route angegeben sind, entspricht die generierte Route möglicherweise nicht Ihren Erwartungen. Um einen Routenkonflikt zu vermeiden, darf asp-route nicht mit den Attributen asp-controller oder asp-action verwendet werden.

asp-all-route-data

Das Attribut asp-all-route-data unterstützt das Erstellen eines Wörterbuchs aus Schlüssel-Wert-Paaren. Der Schlüssel ist der Parametername, der Wert ist der Parameterwert.

Im folgenden Beispiel wird ein Wörterbuch initialisiert und an eine Razor Sicht übergeben. Alternativ können die Daten auch mit Ihrem Modell übergeben werden.

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

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

Der oben gezeigte Code generiert den folgenden HTML-Code:

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

Das asp-all-route-data-Wörterbuch wird vereinfacht, um eine Abfragezeichenfolge zu erstellen, die die Anforderungen der überladenen Evaluations-Aktion erfüllt:

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

Wenn ein beliebiger Schlüssel im Wörterbuch mit einem Routenparameter übereinstimmt, werden die Werte entsprechend in der Route eingesetzt. Die nicht übereinstimmenden Werte werden als Anforderungsparameter generiert.

asp-fragment

Das Attribut asp-fragment definiert ein URL-Fragment, das an die URL angefügt werden soll. Das Anchor-Taghilfsprogramm fügt das Hashzeichen (#) hinzu. Sehen Sie sich das folgende Markup an:

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

Der generierte HTML-Code:

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

Hashtags sind beim Erstellen von clientseitigen Apps nützlich. Sie können beispielsweise zum einfachen Markieren und Suchen in JavaScript verwendet werden.

asp-area

Das Attribut asp-area legt den Bereichsnamen zum Festlegen der geeigneten Route fest. Die folgenden Beispiele zeigen, wie das asp-area-Attribut eine Neuzuordnung von Routen verursacht.

Verwendung in Razor Pages

Razor Seitenbereiche werden in ASP.NET Core 2.1 oder höher unterstützt.

Betrachten Sie die folgende Verzeichnishierarchie:

  • {Projektname}
    • wwwroot
    • Bereiche
      • Sitzungen
        • Seiten
          • _ViewStart.cshtml
          • Index.cshtml
          • Index.cshtml.cs
    • Seiten

Das Markup, auf das auf die Indexseite des Sitzungsbereichs verwiesen Razor werden soll, ist:

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

Der generierte HTML-Code:

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

Tipp

Um Bereiche in einer Razor Pages-App zu unterstützen, gehen Sie wie folgt Startup.ConfigureServices vor:

Verwendung in MVC

Betrachten Sie die folgende Verzeichnishierarchie:

  • {Projektname}
    • wwwroot
    • Bereiche
      • Blogs
        • Controller
          • HomeController.cs
        • Ansichten
          • Home
            • AboutBlog.cshtml
            • Index.cshtml
          • _ViewStart.cshtml
    • Controller

Das Festlegen von asp-area auf „Blogs“ stellt das Verzeichnis Areas/Blogs den Routen der zugeordneten Controller und Ansichten für dieses Anchor-Tag voran. Das Markup zum Verweisen auf die AboutBlog-Ansicht lautet:

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

Der generierte HTML-Code:

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

Tipp

Die Routenvorlage muss einen Verweis auf den Bereich enthalten, damit Bereiche in einer MVC-App unterstützt werden. Diese Vorlage wird durch den zweiten Parameter des routes.MapRoute Methodenaufrufs in Startup.Configure dargestellt:

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

Das Attribut asp-protocol gibt ein Protokoll in Ihrer URL an (z.B. https). Beispiel:

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

Der generierte HTML-Code:

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

Der Hostname im Beispiel ist „localhost“. Das Anchor-Taghilfsprogramm verwendet die öffentliche Domäne der Website, wenn es die URL generiert.

asp-host

Mit dem Attribut asp-host wird ein Hostname in Ihrer URL angegeben. Beispiel:

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

Der generierte HTML-Code:

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

asp-page

Das asp-page-Attribut wird mit Razor Pages verwendet. Mit ihm wird der href-Attributwerts des Anchor-Tags auf eine bestimmte Seite festgelegt. Wenn Sie dem Seitennamen einen Schrägstrich „/“ voranstellen, wird die URL erstellt.

Im folgenden Beispiel wird auf die Razor Teilnehmerseite hingewiesen:

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

Der generierte HTML-Code:

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

Das asp-page-Attribut und die asp-route-, asp-controller- und asp-action-Attribute schließen sich gegenseitig aus. Allerdings kann asp-page mit asp-route-{value} genutzt werden, um das Routing zu steuern, wie im folgenden Markup veranschaulicht wird:

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

Der generierte HTML-Code:

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

asp-page-handler

Das asp-page-handler-Attribut wird mit Razor Pages verwendet. Es dient zur Verknüpfung mit bestimmten Seitenhandlern.

Betrachten Sie den folgenden Seitenhandler:

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

    // code omitted for brevity
}

Das Markup des Seitenmodells verweist auf den Seitenhandler OnGetProfile. Beachten Sie, dass das Präfix On<Verb> für den Namen der Seitenhandlermethode im Attributwert asp-page-handler weggelassen wurde. Wenn die Methode asynchron ist, wird auch das Suffix Async weggelassen.

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

Der generierte HTML-Code:

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

Zusätzliche Ressourcen