Tag Helper Ancre dans ASP.NET CoreAnchor Tag Helper in ASP.NET Core

Par Peter Kellner et Scott AddieBy Peter Kellner and Scott Addie

Le Tag Helper Ancre améliore la balise d’ancrage HTML standard (<a ... ></a>) en ajoutant de nouveaux attributs.The Anchor Tag Helper enhances the standard HTML anchor (<a ... ></a>) tag by adding new attributes. Par convention, les noms d’attribut commencent par asp-.By convention, the attribute names are prefixed with asp-. La valeur d’attribut de l’élément d’ancrage rendu href est déterminée par les valeurs des attributs asp-.The rendered anchor element's href attribute value is determined by the values of the asp- attributes.

Pour avoir une vue d’ensemble des Tag Helpers, consultez Tag Helpers dans ASP.NET Core.For an overview of Tag Helpers, see Tag Helpers dans ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

SpeakerController est utilisé dans les exemples dans ce document :SpeakerController is used in samples throughout this 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 AncreAnchor Tag Helper attributes

asp-controllerasp-controller

L’attribut asp-controller assigne le contrôleur utilisé pour générer l’URL.The asp-controller attribute assigns the controller used for generating the URL. Le balisage suivant répertorie tous les présentateurs :The following markup lists all speakers:

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

Code HTML généré :The generated HTML:

<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.If the asp-controller attribute is specified and asp-action isn't, the default asp-action value is the controller action associated with the currently executing view. Si asp-action est omis du balisage précédent, et le Tag Helper Ancre est utilisé dans la vue Index de HomeController ( /Home), le code HTML généré est :If asp-action is omitted from the preceding markup, and the Anchor Tag Helper is used in HomeController's Index view (/Home), the generated HTML is:

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

asp-actionasp-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é.The asp-action attribute value represents the controller action name included in the generated href attribute. Le balisage suivant définit la valeur de l’attribut href généré sur la page d’évaluations du présentateur :The following markup sets the generated href attribute value to the speaker evaluations page:

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

Code HTML généré :The generated HTML:

<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é.If no asp-controller attribute is specified, the default controller calling the view executing the current view is used.

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.If the asp-action attribute value is Index, then no action is appended to the URL, leading to the invocation of the default Index action. L’action spécifiée (ou par défaut) doit exister dans le contrôleur référencé dans asp-controller.The action specified (or defaulted), must exist in the controller referenced in asp-controller.

asp-route-{value}asp-route-{value}

L’attribut asp-route-{value} active un préfixe d’itinéraire générique.The asp-route-{value} attribute enables a wildcard route prefix. Toute valeur occupant l’espace réservé {value} est interprétée comme un paramètre d’itinéraire potentiel.Any value occupying the {value} placeholder is interpreted as a potential route parameter. 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.If a default route isn't found, this route prefix is appended to the generated href attribute as a request parameter and value. Dans le cas contraire, il est remplacé dans le modèle de routage.Otherwise, it's substituted in the route template.

Examinons l’action du contrôleur ci-dessous :Consider the following controller action:

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

    return View(speaker);
}

Avec un modèle d’itinéraire par défaut défini dans Startup.Configure :With a default route template defined in 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 :The MVC view uses the model, provided by the action, as follows:

@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.The default route's {id?} placeholder was matched. Code HTML généré :The generated HTML:

<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 :Assume the route prefix isn't part of the matching routing template, as with the following MVC view:

@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 :The following HTML is generated because speakerid wasn't found in the matching route:

<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.If either asp-controller or asp-action aren't specified, then the same default processing is followed as is in the asp-route attribute.

asp-routeasp-route

L’attribut asp-route est utilisé pour créer une URL reliant directement à un itinéraire nommé.The asp-route attribute is used for creating a URL linking directly to a named route. À l’aide des attributs de routage, un itinéraire peut être nommé comme indiqué dans SpeakerController et utilisé dans son action Evaluations :Using routing attributes, a route can be named as shown in the SpeakerController and used in its Evaluations action:

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

Dans le balisage suivant, l’attribut asp-route fait référence à l’itinéraire nommé :In the following markup, the asp-route attribute references the named route:

<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.The Anchor Tag Helper generates a route directly to that controller action using the URL /Speaker/Evaluations. Code HTML généré :The generated HTML:

<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.If asp-controller or asp-action is specified in addition to asp-route, the route generated may not be what you expect. asp-route ne doit pas être utilisé avec les attributs asp-controller ou asp-action afin d’éviter un conflit de routage.To avoid a route conflict, asp-route shouldn't be used with the asp-controller and asp-action attributes.

asp-all-route-dataasp-all-route-data

L’attribut asp-all-route-data prend en charge la création d’un dictionnaire de paires clé-valeur.The asp-all-route-data attribute supports the creation of a dictionary of key-value pairs. La clé est le nom du paramètre et la valeur est la valeur du paramètre.The key is the parameter name, and the value is the parameter value.

Dans l’exemple suivant, un dictionnaire est initialisé et transmis à une vue Razor.In the following example, a dictionary is initialized and passed to a Razor view. Les données peuvent également être transmises avec votre modèle.Alternatively, the data could be passed in with your model.

@{
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 :The preceding code generates the following HTML:

<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 :The asp-all-route-data dictionary is flattened to produce a querystring meeting the requirements of the overloaded Evaluations action:

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

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.If any keys in the dictionary match route parameters, those values are substituted in the route as appropriate. Les autres valeurs non correspondantes sont générées en tant que paramètres de la requête.The other non-matching values are generated as request parameters.

asp-fragmentasp-fragment

L’attribut asp-fragment définit un fragment d’URL à ajouter à l’URL.The asp-fragment attribute defines a URL fragment to append to the URL. Le Tag Helper Ancre ajoute le caractère de hachage (#).The Anchor Tag Helper adds the hash character (#). Examinons le balisage suivant :Consider the following markup:

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

Code HTML généré :The generated HTML:

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

Les balises de hachage sont utiles lors de la création des applications côté client.Hash tags are useful when building client-side apps. Elles peuvent servir à faciliter le marquage et la recherche en JavaScript, par exemple.They can be used for easy marking and searching in JavaScript, for example.

asp-areaasp-area

L’attribut asp-area définit le nom de la zone utilisé pour définir l’itinéraire approprié.The asp-area attribute sets the area name used to set the appropriate route. Les exemples suivants décrivent la façon dont l’attribut asp-area entraîne un remappage des itinéraires.The following examples depict how the asp-area attribute causes a remapping of routes.

Utilisation dans les pages RazorUsage in Razor Pages

Les zones de pages Razor sont prises en charge dans ASP.NET Core 2.1 ou les versions ultérieures.Razor Pages areas are supported in ASP.NET Core 2.1 or later.

Considérez la hiérarchie de répertoires suivante :Consider the following directory hierarchy:

  • {Nom du projet}{Project name}
    • wwwrootwwwroot
    • ZonesAreas
      • SessionsSessions
        • PagesPages
          • _ViewStart.cshtml_ViewStart.cshtml
          • Index.cshtmlIndex.cshtml
          • Index.cshtml.csIndex.cshtml.cs
    • PagesPages

Le balisage pour faire référence à la zone Sessions de la page Razor Index est :The markup to reference the Sessions area Index Razor Page is:

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

Code HTML généré :The generated HTML:

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

Conseil

Pour prendre en charge des zones dans une application Razor Pages, effectuez l’une des opérations suivantes dans Startup.ConfigureServices:To support areas in a Razor Pages app, do one of the following in Startup.ConfigureServices:

Utilisation dans MVCUsage in MVC

Considérez la hiérarchie de répertoires suivante :Consider the following directory hierarchy:

  • {Nom du projet}{Project name}
    • wwwrootwwwroot
    • ZonesAreas
      • BlogsBlogs
        • ContrôleursControllers
          • HomeController.csHomeController.cs
        • ViewsViews
          • AccueilHome
            • AboutBlog.cshtmlAboutBlog.cshtml
            • Index.cshtmlIndex.cshtml
          • _ViewStart.cshtml_ViewStart.cshtml
    • ContrôleursControllers

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.Setting asp-area to "Blogs" prefixes the directory Areas/Blogs to the routes of the associated controllers and views for this anchor tag. Le balisage pour faire référence à la vue AboutBlog est :The markup to reference the AboutBlog view is:

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

Code HTML généré :The generated HTML:

<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.To support areas in an MVC app, the route template must include a reference to the area, if it exists. Ce modèle est représenté par le deuxième paramètre de l’appel de méthode routes.MapRoute dans Startup.Configure :That template is represented by the second parameter of the routes.MapRoute method call in 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-protocolasp-protocol

L’attribut asp-protocol permet de spécifier un protocole (tel que https) dans l’URL.The asp-protocol attribute is for specifying a protocol (such as https) in your URL. Par exemple :For example:

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

Code HTML généré :The generated HTML:

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

Le nom d’hôte dans l’exemple est localhost.The host name in the example is localhost. Le Tag Helper Ancre utilise le domaine public du site web lors de la génération de l’URL.The Anchor Tag Helper uses the website's public domain when generating the URL.

asp-hostasp-host

L’attribut asp-host est destiné à spécifier un nom d’hôte dans votre URL.The asp-host attribute is for specifying a host name in your URL. Par exemple :For example:

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

Code HTML généré :The generated HTML:

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

asp-pageasp-page

L’attribut asp-page est utilisé avec les Pages Razor.The asp-page attribute is used with Razor Pages. Utilisez-le pour définir la valeur d’attribut href d’une balise d’ancrage sur une page spécifique.Use it to set an anchor tag's href attribute value to a specific page. En ajoutant une barre oblique (« / ») comme préfixe au nom de la page, vous créez l’URL.Prefixing the page name with a forward slash ("/") creates the URL.

L’exemple suivant pointe vers la Page Razor du participant :The following sample points to the attendee Razor Page:

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

Code HTML généré :The generated HTML:

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

L’attribut asp-page et les attributs asp-route, asp-controller et asp-action s’excluent mutuellement.The asp-page attribute is mutually exclusive with the asp-route, asp-controller, and asp-action attributes. Toutefois, asp-page peut être utilisé avec asp-route-{value} pour contrôler le routage, comme illustré dans le balisage suivant :However, asp-page can be used with asp-route-{value} to control routing, as the following markup demonstrates:

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

Code HTML généré :The generated HTML:

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

asp-page-handlerasp-page-handler

L’attribut asp-page-handler est utilisé avec les Pages Razor.The asp-page-handler attribute is used with Razor Pages. Il est destiné à la liaison à des gestionnaires de page spécifiques.It's intended for linking to specific page handlers.

Prenons le gestionnaire de page suivant :Consider the following page handler:

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.The page model's associated markup links to the OnGetProfile page handler. 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.Note the On<Verb> prefix of the page handler method name is omitted in the asp-page-handler attribute value. Lorsque la méthode est asynchrone, le suffixe Async est également omis.When the method is asynchronous, the Async suffix is omitted, too.

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

Code HTML généré :The generated HTML:

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

Ressources supplémentairesAdditional resources