Anchor-Tag-Hilfsprogramm in ASP.NET Core

  • Artikel

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 über 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 obigen Markup ausgelassen wird und das Anchor-Taghilfsprogramm in der Ansicht Index von HomeController verwendet wird (/Home), wird folgender HTML-Code generiert:

<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:

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

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")]

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-Ansicht ü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:

public IActionResult Evaluations() => View();

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

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 Pages-Bereiche werden in ASP.NET Core 2.1 oder höher unterstützt.

Betrachten Sie die folgende Verzeichnishierarchie:

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

Das Markup zum Verweisen auf den Sessions-Bereich der Razor Page Index lautet:

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

Der generierte HTML-Code:

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

Tipp

Damit Bereiche in einer Razor Pages-App unterstützt werden, führen Sie in Startup.ConfigureServices einen der folgenden Schritte aus:

Verwendung in MVC

Betrachten Sie die folgende Verzeichnishierarchie:

  • {Projektname}
    • wwwroot
    • Bereichen
      • 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 Attribut asp-page wird mit Razor Pages verwendet. Mit ihm wird der href-Attributwerts des Anchor-Tags auf eine bestimmte Seite festgelegt. Durch Hinzufügen des Präfixes / vor dem Seitennamen, wird eine URL für eine entsprechende Seite im Stammverzeichnis der App erstellt:

Mit dem Beispielcode erstellt das folgende Markup einen Link zur Razor Page mit Teilnehmern:

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

Wenn die referenzierte Seite nicht existiert, wird unter Verwendung eines Umgebungswerts aus der Anforderung ein Link zur aktuellen Seite generiert. Außer auf Debugprotokollebene wird keine Warnung angezeigt.

asp-page-handler

Das Attribut asp-page-handler 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