Tag Helpers dans ASP.NET Core

Par Rick Anderson

Présentation des Tag Helpers

Les tag Helpers permettent au code côté serveur de participer à la création et au rendu d’éléments HTML dans des Razor fichiers. Par exemple, le composant ImageTagHelper intégré peut ajouter un numéro de version au nom de l’image. Chaque fois que l’image change, le serveur génère une nouvelle version unique pour l’image, de sorte que les clients sont assurés d’obtenir l’image actuelle (au lieu d’une image mise en cache obsolète). Il existe de nombreux Tag Helpers intégrés pour les tâches courantes, telles que la création de formulaires, de liens, le chargement de ressources, et encore plus disponibles dans les référentiels GitHub publics et en tant que packages NuGet. Les tag Helpers sont créés en C#, et ciblent des éléments HTML en fonction du nom de l’élément, du nom d’attribut ou de la balise parente. Par exemple, l’élément intégré LabelTagHelper peut cibler l’élément HTML <label> lorsque les LabelTagHelper attributs sont appliqués. Si vous êtes familier avec les helpers HTML, les Tag Helpers réduisent les transitions explicites entre HTML et C# dans les vues Razor. Dans de nombreux cas, les helpers HTML fournissent une autre approche d’un Tag Helper spécifique, mais il est important de reconnaître que les Tag Helpers ne remplacent pas les helpers HTML et qu’il n’y a pas de Tag Helper pour chaque assistance HTML. Les Tag Helpers comparés aux Helpers HTML expliquent les différences plus en détail.

Les Tag Helpers ne sont pas pris en charge dans les composants Razor. Pour plus d’informations, consultez Composants ASP.NET Core Razor.

Ce que fournissent les Tag Helpers

L'expérience de développement conviviale pour HTML

Dans la plupart des cas, Razor le balisage utilisant Tag Helpers ressemble à du code HTML standard. Les concepteurs frontaux conversant avec HTML/CSS/JavaScript peuvent modifier Razor sans apprendre la syntaxe C# Razor .

Un environnement IntelliSense riche pour la création de code HTML et Razor de balisage

Cela contraste fortement avec les Helpers HTML, l’approche précédente de la création de balisage côté serveur dans les vues Razor. Les Tag Helpers comparés aux Helpers HTML expliquent les différences plus en détail. La prise en charge d’IntelliSense pour Tag Helpers explique l’environnement IntelliSense. Même les développeurs expérimentés avec Razor la syntaxe C# sont plus productifs à l’aide de Tag Helpers que d’écrire le balisage C# Razor .

Un moyen de vous rendre plus productif et capable de produire du code plus robuste, fiable et gérable à l’aide d’informations uniquement disponibles sur le serveur

Par exemple, historiquement, le mantra sur la mise à jour des images était de modifier le nom de l’image lorsque vous modifiez l’image. Les images doivent être mises en cache de manière agressive pour des raisons de performances et, sauf si vous modifiez le nom d’une image, vous risquez que les clients obtiennent une copie obsolète. Historiquement, une fois qu’une image a été modifiée, le nom devait être modifié et chaque référence à l’image dans l’application web devait être mise à jour. Non seulement est-ce très gourmand en travail, c’est également sujet aux erreurs (vous pourriez manquer une référence, entrer accidentellement la chaîne incorrecte, etc.) Le composant ImageTagHelper intégré peut le faire automatiquement. ImageTagHelper peut ajouter un numéro de version au nom de l'image. Ainsi, chaque fois que l'image change, le serveur génère automatiquement une nouvelle version unique. Les clients sont assurés d’obtenir l’image actuelle. Cette robustesse et les économies de main-d’œuvre sont essentiellement gratuites en utilisant le ImageTagHelper.

La plupart des Tag Helpers intégrés ciblent des éléments HTML standard et fournissent des attributs côté serveur pour l’élément. Par exemple, l’élément <input> utilisé dans de nombreux affichages dans le dossier Views/Account contient l’attribut asp-for . Cet attribut extrait le nom de la propriété de modèle spécifiée dans le code HTML rendu. Considérez une Razor vue avec le modèle suivant :

public class Movie
{
    public int ID { get; set; }
    public string Title { get; set; }
    public DateTime ReleaseDate { get; set; }
    public string Genre { get; set; }
    public decimal Price { get; set; }
}

Le balisage suivant Razor :

<label asp-for="Movie.Title"></label>

Génère le code HTML suivant :

<label for="Movie_Title">Title</label>

L’attribut asp-for est mis à disposition par la For propriété dans le LabelTagHelper. Pour plus d’informations, consultez Author Tag Helpers .

Gestion de l'étendue de Tag Helper

L'étendue des Tag Helpers est contrôlée par une combinaison de @addTagHelper, de @removeTagHelper et du caractère d'exclusion "!".

@addTagHelper rend les Tag Helpers disponibles

Si vous créez une application web ASP.NET Core nommée AuthoringTagHelpers, le fichier suivant Views/_ViewImports.cshtml est ajouté à votre projet :

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

La @addTagHelper directive rend les Tag Helpers disponibles pour l’affichage. Dans ce cas, le fichier d’affichage est Pages/_ViewImports.cshtml, qui par défaut est hérité par tous les fichiers dans le dossier Pages et les sous-dossiers ; rend les Tag Helpers disponibles. Le code ci-dessus utilise la syntaxe générique (« * ») pour spécifier que tous les Tag Helpers de l’assembly spécifié (Microsoft.AspNetCore.Mvc.TagHelpers) seront disponibles pour chaque fichier d’affichage dans le répertoire Views ou le sous-répertoire. Le premier paramètre après @addTagHelper spécifie les Tag Helpers à charger (nous utilisons « * » pour tous les Tag Helpers), et le deuxième paramètre « Microsoft.AspNetCore.Mvc.TagHelpers » spécifie l'assemblage contenant les Tag Helpers. Microsoft.AspNetCore.Mvc.TagHelpers est l’assembly pour les tag Helpers intégrés ASP.NET Core.

Pour exposer tous les Tag Helpers dans ce projet (qui crée un assembly nommé AuthoringTagHelpers), vous devez utiliser les éléments suivants :

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

Si votre projet contient un EmailTagHelper avec l'espace de noms par défaut (AuthoringTagHelpers.TagHelpers.EmailTagHelper), vous pouvez fournir le nom complet qualifié (NC) du Tag Helper :

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

Pour ajouter un Tag Helper à une vue en utilisant un nom totalement qualifié (FQN), vous ajoutez d’abord le nom totalement qualifié (AuthoringTagHelpers.TagHelpers.EmailTagHelper), puis le nom de l’assembly (AuthoringTagHelpers). La plupart des développeurs préfèrent utiliser la syntaxe générique « * ». La syntaxe générique vous permet d’insérer le caractère générique « * » comme suffixe dans un nom de domaine complet. Par exemple, l’une des directives suivantes importe le EmailTagHelper :

@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers

Comme mentionné précédemment, l’ajout de la @addTagHelper directive au Views/_ViewImports.cshtml fichier rend le Tag Helper disponible pour tous les fichiers d’affichage dans le répertoire Views et les sous-répertoires. Vous pouvez utiliser la @addTagHelper directive dans des fichiers d’affichage spécifiques si vous souhaitez choisir d’exposer tag Helper uniquement à ces vues.

@removeTagHelper supprime les Tag Helpers

Il @removeTagHelper a les mêmes deux paramètres que @addTagHelper, et il supprime un Tag Helper qui a été ajouté précédemment. Par exemple, @removeTagHelper appliqué à une vue spécifique supprime le Tag Helper spécifié de l’affichage. Utiliser @removeTagHelper dans un fichier Views/Folder/_ViewImports.cshtml supprime le Tag Helper spécifié de toutes les vues du dossier.

Contrôle de l’étendue Tag Helper avec le fichier _ViewImports.cshtml

Vous pouvez ajouter un _ViewImports.cshtml à n’importe quel dossier de vue, et le moteur de rendu applique les directives de ce fichier et du fichier Views/_ViewImports.cshtml. Si vous avez ajouté un fichier vide Views/Home/_ViewImports.cshtml pour les Home vues, il n’y aurait aucune modification, car le _ViewImports.cshtml fichier est additif. Toutes les @addTagHelper directives que vous ajoutez au Views/Home/_ViewImports.cshtml fichier (qui ne figurent pas dans le fichier par défaut Views/_ViewImports.cshtml ) exposent ces Tag Helpers aux affichages uniquement dans le Home dossier.

Désactivation des éléments individuels

Vous pouvez désactiver un Tag Helper au niveau de l’élément avec le caractère de désactivation de Tag Helper (« ! »). Par exemple, Email la validation est désactivée dans le <span> avec le caractère de désactivation de Tag Helper :

<!span asp-validation-for="Email" class="text-danger"></!span>

Vous devez appliquer le caractère de désactivation du Tag Helper à la balise d’ouverture et de fermeture. (L’éditeur Visual Studio ajoute automatiquement le caractère d’opt-out à la balise de fermeture lorsque vous en ajoutez un à la balise d’ouverture). Après avoir ajouté le caractère de désactivation, l'élément et les attributs Tag Helper ne sont plus affichés dans une police distinctive.

Utilisation @tagHelperPrefix pour rendre l’utilisation de Tag Helper explicite

La @tagHelperPrefix directive vous permet de spécifier une chaîne de préfixe de balise pour activer la prise en charge de Tag Helper et pour rendre l’utilisation de Tag Helper explicite. Par exemple, vous pouvez ajouter le balisage suivant au Views/_ViewImports.cshtml fichier :

@tagHelperPrefix th:

Dans l’image de code ci-dessous, le préfixe de Tag Helper est défini sur th:, de sorte que seuls les éléments utilisant le préfixe th: prennent en charge les Tag Helpers (les éléments qui prennent en charge les Tag Helpers ont une police distincte). Les éléments <label> et <input> ont le préfixe Tag Helper et sont compatibles avec Tag Helper, tandis que l’élément <span> ne l’est pas.

Les mêmes règles de hiérarchie qui s’appliquent à @addTagHelper s’appliquent également à @tagHelperPrefix.

Tag Helpers fermant automatiquement

De nombreux Tag Helpers ne peuvent pas être utilisés comme balises de fermeture automatique. Certains Tag Helpers sont conçus pour être des balises de fermeture automatique. L’utilisation d’un Tag Helper qui n’a pas été conçu pour être auto-fermant supprime la sortie rendue. La fermeture automatique d’un Tag Helper entraîne une balise de fermeture automatique dans la sortie rendue. Pour plus d’informations, consultez cette note dans Authoring Tag Helpers.

C# dans l'attribut/déclaration des Tag Helpers

Les Tag Helpers n’autorisent pas C# dans la zone d’attribut ou de déclaration de balise de l’élément. Par exemple, le code suivant n’est pas valide :

<input asp-for="LastName"  
       @(Model?.LicenseId == null ? "disabled" : string.Empty) />

Le code précédent peut être écrit comme suit :

<input asp-for="LastName" 
       disabled="@(Model?.LicenseId == null)" />

Normalement, l’opérateur @ insère une représentation textuelle d’une expression dans le balisage HTML rendu. Toutefois, lorsqu’une expression prend la valeur logique false, l’infrastructure supprime l’attribut à la place. Dans l’exemple précédent, l’attribut disabled est défini à true si Model ou LicenseId est null.

Les initialiseurs de Tag Helpers

Bien que les attributs puissent être utilisés pour configurer des instances individuelles d’assistance de balise, ITagHelperInitializer<TTagHelper> ils peuvent être utilisés pour configurer toutes les instances de tag helper d’un type spécifique. Prenons l’exemple suivant d’un initialiseur de tag helper qui configure l'attribut asp-append-version ou la propriété AppendVersion pour toutes les instances de ScriptTagHelper dans l’application :

public class AppendVersionTagHelperInitializer : ITagHelperInitializer<ScriptTagHelper>
{
    public void Initialize(ScriptTagHelper helper, ViewContext context)
    {
        helper.AppendVersion = true;
    }
}

Pour utiliser l’initialiseur, configurez-le en l’inscrivant dans le cadre du démarrage de l’application :

builder.Services.AddSingleton
    <ITagHelperInitializer<ScriptTagHelper>, AppendVersionTagHelperInitializer>();

Génération automatique de version Tag Helper en dehors de wwwroot

Pour qu’un Tag Helper génère une version pour un fichier statique en dehors wwwroot, consultez Server des fichiers à partir de plusieurs emplacements

Prise en charge d’IntelliSense pour les Tag Helpers

Envisagez d’écrire un élément HTML <label> . Dès que vous entrez <l dans l’éditeur Visual Studio, IntelliSense affiche les éléments correspondants :

Non seulement vous obtenez de l’aide HTML, mais aussi l’icône (le symbole « @ » avec «<> » sous celui-ci).

L’icône identifie l’élément comme ciblé par Tag Helpers. Les éléments HTML purs (tels que le fieldset) affichent l’icône «<> ».

Une balise HTML <label> pure affiche la balise HTML (avec le thème de couleur Visual Studio par défaut) dans une police brune, les attributs en rouge et les valeurs d’attribut en bleu.

Après avoir entré <label, IntelliSense répertorie les attributs HTML/CSS disponibles et les attributs ciblés par Tag Helper :

La saisie semi-automatique de l’instruction IntelliSense vous permet d’appuyer sur la touche Tabulation pour compléter l’instruction avec la valeur sélectionnée.

Dès qu’un attribut Tag Helper est entré, les polices d’étiquette et d’attribut changent. À l’aide du thème de couleur « Bleu » ou « Clair » de Visual Studio par défaut, la police est violette en gras. Si vous utilisez le thème « Dark », la police est en gras. Les images de ce document ont été prises à l’aide du thème par défaut.

Vous pouvez entrer le raccourci Visual Studio CompleteWord (Ctrl +barre d’espace est la valeur par défaut) entre guillemets doubles (« »), et vous êtes maintenant en C#, comme vous le feriez dans une classe C#. IntelliSense affiche toutes les méthodes et propriétés du modèle de page. Les méthodes et les propriétés sont disponibles, car le type de propriété est ModelExpression. Dans l’image ci-dessous, je modifie l’affichage Register, donc RegisterViewModel est disponible.

IntelliSense répertorie les propriétés et méthodes disponibles pour le modèle sur la page. L’environnement IntelliSense enrichi vous aide à sélectionner la classe CSS :

Tag Helpers comparés aux HTML Helpers

Les Tag Helpers s’attachent aux éléments HTML dans Razor les vues, tandis que les assistants HTML sont appelés en tant que méthodes intégrées dans le code HTML dans Razor les vues. Considérez le balisage suivant Razor , qui crée une étiquette HTML avec la classe CSS « caption » :

@Html.Label("FirstName", "First Name:", new {@class="caption"})

Le symbole at (@) indique Razor qu’il s’agit du début du code. Les deux paramètres suivants (« FirstName » et « First Name : ») sont des chaînes. IntelliSense ne peut donc pas vous aider. Dernier argument :

new {@class="caption"}

Objet anonyme utilisé pour représenter des attributs. Étant donné qu’il class s’agit d’un mot clé réservé en C#, vous utilisez le @ symbole pour forcer C# à interpréter @class= comme symbole (nom de propriété). Pour un concepteur frontal (quelqu’un familiarisé avec HTML/CSS/JavaScript et d’autres technologies clientes, mais pas familiarisé avec C# et Razor), la plupart du code semble étranger. La ligne entière doit être créée sans aide d’IntelliSense.

À l’aide du LabelTagHelper, le même balisage peut être écrit comme suit :

<label class="caption" asp-for="FirstName"></label>

Avec la version tag Helper, dès que vous entrez <l dans l’éditeur Visual Studio, IntelliSense affiche les éléments correspondants :

IntelliSense vous aide à écrire toute la ligne.

L’image de code suivante montre la partie Formulaire de la Views/Account/Register.cshtmlRazor vue générée à partir du modèle ASP.NET 4.5.x MVC inclus avec Visual Studio.

Razor

L’éditeur Visual Studio affiche le code C# avec un arrière-plan gris. Par exemple, l'assistant AntiForgeryToken HTML :

@Html.AntiForgeryToken()

s’affiche avec un arrière-plan gris. La majeure partie du balisage dans la vue Registre est C#. Comparez cela à l’approche équivalente à l’aide de Tag Helpers :

Le balisage est beaucoup plus propre et plus facile à lire, modifier et gérer que l’approche des helpers HTML. Le code C# est réduit au minimum que le serveur doit connaître. L’éditeur Visual Studio affiche le balisage ciblé par un Tag Helper dans une police distincte.

Considérez le groupe e-mail :

<div class="form-group">
    <label asp-for="Email" class="col-md-2 control-label"></label>
    <div class="col-md-10">
        <input asp-for="Email" class="form-control" />
        <span asp-validation-for="Email" class="text-danger"></span>
    </div>
</div>

Chacun des attributs « asp- » a la valeur « Email », mais « Email » n’est pas une chaîne. Dans ce contexte, « Email » est la propriété d’expression de modèle C# pour le RegisterViewModel.

L'éditeur Visual Studio vous aide à écrire tout le balisage dans l'approche Tag Helper du formulaire d'inscription, tandis que pour l'approche HTML Helpers, Visual Studio ne fournit aucune aide pour la majorité du code. La prise en charge d’IntelliSense pour les Tag Helpers explore en détail le travail avec les Tag Helpers dans l'éditeur Visual Studio.

Tag Helpers comparé aux contrôles de serveur web

• Les Tag Helpers ne possèdent pas l’élément auquel ils sont associés ; ils participent simplement au rendu de l’élément et du contenu. Les contrôles de serveur Web ASP.NET sont déclarés et utilisés sur une page.

• ASP.NET contrôles de serveur web ont un cycle de vie non trivial qui peut rendre le développement et le débogage difficiles.

• Les contrôles serveur web vous permettent d’ajouter des fonctionnalités aux éléments DOM clients à l’aide d’un contrôle client. Les Tag Helpers n’ont pas de DOM.

• Les contrôles serveur web incluent la détection automatique du navigateur. Les Tag Helpers n’ont aucune connaissance du navigateur.

• Plusieurs Tag Helpers peuvent agir sur le même élément (voir Éviter les conflits Tag Helper) alors que vous ne pouvez généralement pas composer de contrôles serveur web.

• Les tag Helpers peuvent modifier la balise et le contenu des éléments HTML auxquels ils sont limités, mais ne modifient pas directement d’autre chose sur une page. Les contrôles serveur web ont une étendue moins spécifique et peuvent effectuer des actions qui affectent d’autres parties de votre page ; activation d’effets secondaires inattendus.

• Les contrôles web Server utilisent des convertisseurs de types pour convertir des chaînes en objets. Avec Tag Helpers, vous travaillez en mode natif en C#. Vous n’avez donc pas besoin d’effectuer de conversion de type.

• Les contrôles serveur web utilisent System.ComponentModel pour implémenter le comportement au moment de l’exécution et au moment du design des composants et des contrôles. System.ComponentModel inclut les classes de base et les interfaces pour l’implémentation d’attributs et de convertisseurs de types, la liaison à des sources de données et les composants de licence. Contrairement aux Tag Helpers, qui dérivent généralement de TagHelper, et la TagHelper classe de base expose seulement deux méthodes, Process et ProcessAsync.

Personnalisation de la police de l’élément Tag Helper

Vous pouvez personnaliser la police et la colorisation à partir de Outils>Options>Environnement>Polices et couleurs :

Helpers de balises intégrés ASP.NET Core

Ancre

Cache

Composant

Cache distribué

Environnement

Formulaire

Action de formulaire

Image

Entrée

Étiquette

Lien

Partiel

Conserver l’état du composant

Script

Sélectionner

Textarea

Message de Validation

Résumé de la validation

Ressources supplémentaires

• Créer des Tag Helpers
• Utilisation des formulaires
• TagHelperSamples sur GitHub contient des exemples Tag Helper pour utiliser Bootstrap.