Tag Helper Ancre dans ASP.NET Core
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 le Tag Helper Ancre est utilisé dans la vue Index de HomeController (/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¤tYear=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
- Sessions
- 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
:
Définir la version de compatibilité sur 2.1 ou au-dessus.
Affectez la valeur
true
à la propriété RazorPagesOptions.AllowAreas :services.AddMvc() .AddRazorPagesOptions(options => options.AllowAreas = true);
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
- Home
- Contrôleurs
- Blogs
- 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>