Tag Helper Ancre dans ASP.NET Core

  • Article

Par Peter Kellner et Scott Addie

Le Tag Helper Ancre améliore la balise d’ancrage HTML standard (<a ... ></a>) en ajoutant de nouveaux attributs. Par convention, les noms d’attribut commencent par asp-. La valeur d’attribut de l’élément d’ancrage rendu href est déterminée par les valeurs des attributs asp-.

Pour obtenir une vue d’ensemble des Tag Helpers, consultez Tag Helpers dans ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

SpeakerController est utilisé dans les exemples dans ce document :

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

Attributs de Tag Helper Ancre

asp-controller

L’attribut asp-controller assigne le contrôleur utilisé pour générer l’URL. Le balisage suivant répertorie tous les présentateurs :

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

Code HTML généré :

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

Si l’attribut asp-controller est spécifié et que asp-action ne l’est pas, la valeur par défaut asp-action est l’action du contrôleur associée à la vue en cours d’exécution. Si asp-action est omis du balisage précédent, et l’ancre Tag Helper est utilisée dans la vue Index du Homecontrôleur (/Home), le code HTML généré est :

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

asp-action

La valeur de l’attribut asp-action représente le nom d’action du contrôleur inclus dans l’attribut href généré. Le balisage suivant définit la valeur de l’attribut href généré sur la page d’évaluations du présentateur :

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

Code HTML généré :

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

Si aucun attribut asp-controller n’est spécifié, le contrôleur par défaut qui appelle la vue exécutant la vue actuelle est utilisé.

Si la valeur de l’attribut asp-action est Index, aucune action n’est ajoutée à l’URL, ce qui aboutit à l’appel de l’action Index par défaut. L’action spécifiée (ou par défaut) doit exister dans le contrôleur référencé dans asp-controller.

asp-route-{value}

L’attribut asp-route-{value} active un préfixe d’itinéraire générique. Toute valeur occupant l’espace réservé {value} est interprétée comme un paramètre d’itinéraire potentiel. Si aucune route par défaut n’est trouvée, ce préfixe de routage est ajouté à l’attribut href généré en tant que valeur et paramètre de requête. Dans le cas contraire, il est remplacé dans le modèle de routage.

Examinons l’action du contrôleur ci-dessous :

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

Avec un modèle d’itinéraire par défaut défini dans 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?}");
});

La vue MVC utilise le modèle, fourni par l’action, comme suit :

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

L’espace réservé {id?} de l’itinéraire par défaut a été mis en correspondance. Code HTML généré :

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

Supposons que le préfixe d’itinéraire ne fait pas partie du modèle de routage correspondant, comme dans la vue MVC suivante :

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

Le code HTML suivant est généré, car speakerid n’a pas été trouvé dans l’itinéraire correspondant :

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

Si asp-controller ou asp-action ne sont pas spécifiés, le même traitement par défaut est appliqué que dans l’attribut asp-route.

asp-route

L’attribut asp-route est utilisé pour créer une URL reliant directement à un itinéraire nommé. À l’aide des attributs de routage, un itinéraire peut être nommé comme indiqué dans SpeakerController et utilisé dans son action Evaluations :

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

Dans le balisage suivant, l’attribut asp-route fait référence à l’itinéraire nommé :

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

Le Tag Helper Ancre génère un itinéraire directement vers cette action de contrôleur à l’aide de l’URL /Speaker/Evaluations. Code HTML généré :

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

Si asp-controller ou asp-action est spécifié en plus de asp-route, la route générée ne correspond peut-être pas à ce que vous attendez. asp-route ne doit pas être utilisé avec les attributs asp-controller ou asp-action afin d’éviter un conflit de routage.

asp-all-route-data

L’attribut asp-all-route-data prend en charge la création d’un dictionnaire de paires clé-valeur. La clé est le nom du paramètre et la valeur est la valeur du paramètre.

Dans l’exemple suivant, un dictionnaire est initialisé et transmis à une vue Razor. Les données peuvent également être transmises avec votre modèle.

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

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

Le code précédent génère le code HTML suivant :

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

Le dictionnaire asp-all-route-data est aplati pour produire une chaîne de requête conforme aux exigences de l’action Evaluations surchargée :

public IActionResult Evaluations() => View();

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

Si des clés dans le dictionnaire correspondent aux paramètres d’itinéraire, ces valeurs sont substituées dans l’itinéraire comme il convient. Les autres valeurs non correspondantes sont générées en tant que paramètres de la requête.

asp-fragment

L’attribut asp-fragment définit un fragment d’URL à ajouter à l’URL. Le Tag Helper Ancre ajoute le caractère de hachage (#). Examinons le balisage suivant :

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

Code HTML généré :

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

Les balises de hachage sont utiles lors de la création des applications côté client. Elles peuvent servir à faciliter le marquage et la recherche en JavaScript, par exemple.

asp-area

L’attribut asp-area définit le nom de la zone utilisé pour définir l’itinéraire approprié. Les exemples suivants décrivent la façon dont l’attribut asp-area entraîne un remappage des itinéraires.

Utilisation dans les pages Razor

Les zones de pages Razor sont prises en charge dans ASP.NET Core 2.1 ou les versions ultérieures.

Considérez la hiérarchie de répertoires suivante :

  • {Nom du projet}
    • wwwroot
    • Zones (Areas)
      • Sessions
        • Pages
          • _ViewStart.cshtml
          • Index.cshtml
          • Index.cshtml.cs
    • Pages

Le balisage pour faire référence à la zone Sessions de la page IndexRazor est :

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

Code HTML généré :

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

Conseil

Pour prendre en charge des zones dans une application de pages Razor, effectuez l’une des opérations suivantes dans Startup.ConfigureServices :

Utilisation dans MVC

Considérez la hiérarchie de répertoires suivante :

  • {Nom du projet}
    • wwwroot
    • Zones (Areas)
      • Blogs
        • Contrôleurs
          • HomeController.cs
        • Views
          • Home
            • AboutBlog.cshtml
            • Index.cshtml
          • _ViewStart.cshtml
    • Contrôleurs

L’affectation de la valeur « Blogs » à asp-area préfixe le répertoire Areas/Blogs dans les itinéraires des vues et contrôleurs associés pour cette balise d’ancrage. Le balisage pour faire référence à la vue AboutBlog est :

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

Code HTML généré :

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

Conseil

Pour prendre en charge les zones dans une application MVC, le modèle de routage doit inclure une référence à la zone si elle existe. Ce modèle est représenté par le deuxième paramètre de l’appel de méthode routes.MapRoute dans 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?}");
});

asp-protocol

L’attribut asp-protocol permet de spécifier un protocole (tel que https) dans l’URL. Par exemple :

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

Code HTML généré :

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

Le nom d’hôte dans l’exemple est localhost. Le Tag Helper Ancre utilise le domaine public du site web lors de la génération de l’URL.

asp-host

L’attribut asp-host est destiné à spécifier un nom d’hôte dans votre URL. Par exemple :

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

Code HTML généré :

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

asp-page

L’attribut asp-page est utilisé avec les pages Razor. Utilisez-le pour définir la valeur d’attribut href d’une balise d’ancrage sur une page spécifique. Attribuer / comme préfixe du nom de la page crée une URL pour une page correspondante à partir de la racine de l’application :

Avec l’exemple de code, le balisage suivant crée un lien vers la page Razor du participant :

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

Code HTML généré :

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

L’attribut asp-page et les attributs asp-route, asp-controller et asp-action s’excluent mutuellement. Toutefois, asp-page peut être utilisé avec asp-route-{value} pour contrôler le routage, comme illustré dans le balisage suivant :

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

Code HTML généré :

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

Si la page référencée n’existe pas, un lien vers la page active est généré au moyen d’une valeur ambiante de la requête. Aucun avertissement n’est indiqué, excepté dans le journal de débogage.

asp-page-handler

L’attribut asp-page-handler est utilisé avec les pages Razor. Il est destiné à la liaison à des gestionnaires de page spécifiques.

Prenons le gestionnaire de page suivant :

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

    // code omitted for brevity
}

Le balisage associé au modèle de page est lié au gestionnaire de page OnGetProfile. Notez que le préfixe On<Verb> du nom de la méthode du gestionnaire de page est omis dans la valeur d’attribut asp-page-handler. Lorsque la méthode est asynchrone, le suffixe Async est également omis.

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

Code HTML généré :

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

Ressources supplémentaires