Informations de référence sur la syntaxe Razor pour ASP.NET Core

Par Rick Anderson, Taylor Mullen, et Dan Vicarel

Razor est une syntaxe de majoration qui permet d’incorporer du code basé sur .NET dans des pages web. La syntaxe Razor est constituée de balises Razor, ainsi que de code C# et HTML. Les fichiers contenant de la syntaxe Razor ont généralement l’extension de fichier .cshtml. Razor se trouve également dans les Razor fichiers de composants (.razor). La syntaxe Razor est similaire aux moteurs de templating de diverses infrastructures d’application monopage (SPA) JavaScript, telles que Angular, React, VueJs et Svelte. Pour plus d’informations, consultez Les fonctionnalités décrites dans cet article sont obsolètes depuis ASP.NET Core 3.0.

Présentation de la programmation web ASP.NET à l’aide de Razor La syntaxe fournit de nombreux exemples de programmation avec Razor la syntaxe. Bien que la rubrique ait été écrite pour ASP.NET plutôt que pour ASP.NET Core, la plupart des exemples s’appliquent à ASP.NET Core.

Rendu HTML

Le langageRazor par défaut est HTML. Le rendu HTML d’un balisage Razor n’est pas différent du rendu HTML d’un fichier en HTML. Le balisage HTML dans les fichiers .cshtmlRazor est rendu par le serveur inchangé.

Syntaxe de Razor

Razor prend en charge le langage C# et utilise le symbole @ pour convertir du code HTML en C#. Razor évalue les expressions C# et les affiche dans la sortie HTML.

Quand un symbole @ est suivi d’un Razormot clé réservé, il est converti en balise spécifiqueRazor. Sinon, il est converti en code HTML brut.

Pour échapper à un symbole @ dans une baliseRazor, il faut utiliser un deuxième symbole @ :

<p>@@Username</p>

Le code est affiché en HTML avec un seul symbole @ :

<p>@Username</p>

Les attributs et le code HTML contenant des adresses e-mail ne traitent pas le symbole @ comme un caractère de conversion. Dans l’exemple suivant, les adresses e-mail ne sont pas modifiées par l’analyse Razor :

<a href="mailto:Support@contoso.com">Support@contoso.com</a>

SVG (Scalable Vector Graphics)

Les éléments SVG foreignObject sont pris en charge :

@{
    string message = "foreignObject example with Scalable Vector Graphics (SVG)";
}

<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg">
    <rect x="0" y="0" rx="10" ry="10" width="200" height="200" stroke="black" 
        fill="none" />
    <foreignObject x="20" y="20" width="160" height="160">
        <p>@message</p>
    </foreignObject>
</svg>

Expressions Razor implicites

Les expressions Razor implicites commencent par @ suivi de code C# :

<p>@DateTime.Now</p>
<p>@DateTime.IsLeapYear(2016)</p>

À l’exception du mot clé await C#, les expressions implicites ne doivent pas contenir d’espaces. Si l’instruction C# se termine de façon non ambigüe, il est possible d’insérer des espaces n’importe où dans la chaîne :

<p>@await DoSomething("hello", "world")</p>

Les expressions implicites ne doivent pas contenir de caractères génériques C#, car les caractères entre crochets (<>) sont interprétés comme une balise HTML. Le code suivant n’est pas valide :

<p>@GenericMethod<int>()</p>

Le code précédent génère l’un des types d’erreur de compilateur suivants :

• L’élément « int » n’a pas été fermé. Tous les éléments doivent se fermer automatiquement ou contenir une balise de fin correspondante.
• Impossible de convertir le groupe de méthodes 'GenericMethod' en type non-délégué 'object'. Souhaitiez-vous appeler la méthode ?

Les appels de méthode générique doivent être inclus dans un wrapper dans une expression Razor explicite ou dans un Razorbloc de code.

Expressions Razor explicites

Les expressions Razor explicites se composent d’un symbole @ suivi d’un contenu entre parenthèses. Pour afficher l’heure de la semaine précédente, utilisez le balisage Razor suivant :

<p>Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))</p>

Le contenu situé entre les parenthèses @() est évalué et affiché dans la sortie.

Les expressions implicites, décrites dans la section précédente, ne doivent généralement pas contenir d’espaces. Dans le code suivant, une semaine n’est pas déduite de l’heure actuelle :

<p>Last week: @DateTime.Now - TimeSpan.FromDays(7)</p>

Le code s’affiche en HTML de la façon suivante :

<p>Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)</p>

Les expressions explicites peuvent servir à concaténer du texte avec un résultat d’expression :

@{
    var joe = new Person("Joe", 33);
}

<p>Age@(joe.Age)</p>

Sans l’expression explicite, <p>Age@joe.Age</p> est traité comme une adresse e-mail, et <p>Age@joe.Age</p> est affiché. Avec une expression explicite, <p>Age33</p> est affiché.

Les expressions explicites peuvent être utilisées pour afficher la sortie de méthodes génériques dans les fichiers .cshtml. Le balisage suivant montre comment corriger l’erreur affichée précédemment provoquée par les crochets d’un générique C#. Le code est écrit sous forme d’expression explicite :

<p>@(GenericMethod<int>())</p>

Encodage des expressions

Les expressions C# évaluées qui correspondent à une chaîne sont encodées en HTML. Les expressions C# évaluées qui correspondent à IHtmlContent sont affichées directement par IHtmlContent.WriteTo. Les expressions C# évaluées qui ne correspondent pas à IHtmlContent sont converties en chaîne par ToString et sont encodées avant d’être affichées.

@("<span>Hello World</span>")

Le code précédent affiche le code HTML suivant :

<span>Hello World</span>

Le code HTML est affiché dans le navigateur sous forme de texte brut :

<span> Hello World</span>

La sortie HtmlHelper.Raw n’est pas encodée, mais elle est affichée sous forme de balisage HTML.

Avertissement

Utiliser HtmlHelper.Raw sur des entrées utilisateur non nettoyées présente un risque pour la sécurité. Les entrées utilisateur peuvent contenir du code malveillant JavaScript ou d’un autre type. Le nettoyage des entrées utilisateur est difficile. C’est pourquoi il est préférable de ne pas utiliser HtmlHelper.Raw sur des entrées utilisateur.

@Html.Raw("<span>Hello World</span>")

Le code s’affiche en HTML de la façon suivante :

<span>Hello World</span>

Razor blocs de code

Les blocs de code Razor commencent par @ et sont délimités par {}. Contrairement aux expressions, le code C# figurant dans des blocs de code n’est pas affiché. Les blocs de code et les expressions dans une vue ont la même étendue et sont définis dans l’ordre :

@{
    var quote = "The future depends on what you do today. - Mahatma Gandhi";
}

<p>@quote</p>

@{
    quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.";
}

<p>@quote</p>

Le code s’affiche en HTML de la façon suivante :

<p>The future depends on what you do today. - Mahatma Gandhi</p>
<p>Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.</p>

Dans des blocs de code, déclarez des fonctions locales avec des balises servant de méthodes de création de modèles :

@{
    void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }

    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

Le code s’affiche en HTML de la façon suivante :

<p>Name: <strong>Mahatma Gandhi</strong></p>
<p>Name: <strong>Martin Luther King, Jr.</strong></p>

Transitions implicites

Un bloc de code utilise le langage C# par défaut, mais la page Razor peut le reconvertir en HTML :

@{
    var inCSharp = true;
    <p>Now in HTML, was in C# @inCSharp</p>
}

Conversion délimitée explicite

Pour définir une sous-section d’un bloc de code qui doit s’afficher en HTML, placez les caractères à afficher dans la balise Razor<text> suivante :

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    <text>Name: @person.Name</text>
}

Utilisez cette approche pour afficher du code HTML qui n’est pas entouré d’une balise HTML. Sans la balise HTML ou Razor, une erreur d’exécution Razor se produit.

La balise <text> est utile pour contrôler les espaces blancs dans le contenu affiché :

• Seul le contenu situé dans la balise <text> est affiché.
• Aucun espace blanc avant ou après la balise <text> ne s’affiche dans la sortie HTML.

Conversion de ligne explicite

Pour afficher le reste d’une ligne entière en HTML à l’intérieur d’un bloc de code, utilisez la syntaxe @: :

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    @:Name: @person.Name
}

Sans la balise @: dans le code, une erreur d’exécution Razor se produit.

La présence de caractères @ en trop dans un fichier Razor risque de provoquer des erreurs du compilateur au niveau des instructions suivantes dans le bloc. Ces erreurs supplémentaires @ du compilateur :

• Peuvent être difficiles à comprendre, car elles se produisent en réalité avant les erreurs signalées.
• Est courant après la combinaison de plusieurs expressions implicites et explicites dans un même bloc de code.

Rendu d’attribut conditionnel

Razor omet automatiquement les attributs qui ne sont pas nécessaires. Si la valeur passée est null ou false, l’attribut n’est pas rendu.

Prenons par exemple le razor suivant :

<div class="@false">False</div>
<div class="@null">Null</div>
<div class="@("")">Empty</div>
<div class="@("false")">False String</div>
<div class="@("active")">String</div>
<input type="checkbox" checked="@true" name="true" />
<input type="checkbox" checked="@false" name="false" />
<input type="checkbox" checked="@null" name="null" />

La balise Razor précédente génère le code HTML suivant :

<div>False</div>
<div>Null</div>
<div class="">Empty</div>
<div class="false">False String</div>
<div class="active">String</div>
<input type="checkbox" checked="checked" name="true">
<input type="checkbox" name="false">
<input type="checkbox" name="null">

Structures de contrôle

Les structures de contrôle sont une extension des blocs de code. Toutes les caractéristiques des blocs de code (conversion de balisage, Inline C#) valent aussi pour les structures suivantes :

Conditions @if, else if, else, and @switch

@if contrôle l’exécution du code :

@if (value % 2 == 0)
{
    <p>The value was even.</p>
}

else et else if ne nécessitent pas le symbole @ :

@if (value % 2 == 0)
{
    <p>The value was even.</p>
}
else if (value >= 1337)
{
    <p>The value is large.</p>
}
else
{
    <p>The value is odd and small.</p>
}

Le balisage suivant montre comment utiliser une instruction switch :

@switch (value)
{
    case 1:
        <p>The value is 1!</p>
        break;
    case 1337:
        <p>Your number is 1337!</p>
        break;
    default:
        <p>Your number wasn't 1 or 1337.</p>
        break;
}

Boucle @for, @foreach, @while, and @do while

Le rendu HTML peut être réalisé à partir d'instructions de contrôle de boucle. Pour afficher une liste de personnes :

@{
    var people = new Person[]
    {
          new Person("Weston", 33),
          new Person("Johnathon", 41),
          ...
    };
}

Les instructions de boucle suivantes sont prises en charge :

@for

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    <p>Name: @person.Name</p>
    <p>Age: @person.Age</p>
}

@foreach

@foreach (var person in people)
{
    <p>Name: @person.Name</p>
    <p>Age: @person.Age</p>
}

@while

@{ var i = 0; }
@while (i < people.Length)
{
    var person = people[i];
    <p>Name: @person.Name</p>
    <p>Age: @person.Age</p>

    i++;
}

@do while

@{ var i = 0; }
@do
{
    var person = people[i];
    <p>Name: @person.Name</p>
    <p>Age: @person.Age</p>

    i++;
} while (i < people.Length);

Instruction composée @using

En C#, une instruction using est utilisée pour garantir la dispose d’un objet. Dans Razor, le même mécanisme permet de créer des HTML Helpers avec du contenu supplémentaire. Dans le code suivant, les HTML Helpers affichent une balise <form> à l’aide de l’instruction @using :

@using (Html.BeginForm())
{
    <div>
        Email: <input type="email" id="Email" value="">
        <button>Register</button>
    </div>
}

@try, catch, finally

La gestion des exceptions est similaire à C# :

@try
{
    throw new InvalidOperationException("You did something invalid.");
}
catch (Exception ex)
{
    <p>The exception message: @ex.Message</p>
}
finally
{
    <p>The finally statement.</p>
}

@lock

Razor permet de verrouiller les sections critiques par des instructions lock :

@lock (SomeLock)
{
    // Do critical section work
}

Commentaires

Razor prend en charge les commentaires HTML et C# :

@{
    /* C# comment */
    // Another C# comment
}
<!-- HTML comment -->

Le code s’affiche en HTML de la façon suivante :

<!-- HTML comment -->

Le serveur supprime les commentaires Razor avant d’afficher la page web. Razor délimite les commentaires avec @* *@. Le code suivant est commenté pour indiquer au serveur de ne pas afficher le balisage :

@*
    @{
        /* C# comment */
        // Another C# comment
    }
    <!-- HTML comment -->
*@

Directives

Les directives Razor sont représentées par des expressions implicites constituées du symbole @ suivi de mots clés réservés. En règle générale, une directive change la manière dont une vue est analysée ou active une fonctionnalité différente.

Pour mieux comprendre le fonctionnement des directives, vous devez bien comprendre comment Razor génère le code pour une vue.

@{
    var quote = "Getting old ain't for wimps! - Anonymous";
}

<div>Quote of the Day: @quote</div>

Le code génère une classe semblable à celle-ci :

public class _Views_Something_cshtml : RazorPage<dynamic>
{
    public override async Task ExecuteAsync()
    {
        var output = "Getting old ain't for wimps! - Anonymous";

        WriteLiteral("/r/n<div>Quote of the Day: ");
        Write(output);
        WriteLiteral("</div>");
    }
}

Plus loin dans cet article, la section Inspecter la classe C# Razor générée pour une vue explique comment afficher cette classe générée.

@attribute

La directive @attribute permet d’ajouter l’attribut donné à la classe de la page ou de la vue générée. L’exemple suivant ajoute l’attribut [Authorize] :

@attribute [Authorize]

La @attribute directive peut également être utilisée pour fournir un modèle d’itinéraire basé sur des constantes dans un Razor composant. Dans l’exemple suivant, la directive @page d’un composant est remplacée par la directive @attribute et le modèle de route basé sur des constantes dans Constants.CounterRoute, qui a la valeur « /counter » ailleurs dans l’application :

- @page "/counter"
+ @attribute [Route(Constants.CounterRoute)]

@code

Ce scénario s’applique uniquement aux composants Razor (.razor).

Le blob @code permet à un Razorcomposant d’ajouter des membres C# (champs, propriétés et méthodes) à un composant :

@code {
    // C# members (fields, properties, and methods)
}

Pour les composants Razor, @code est un alias @functions et est recommandé sur @functions. Plus d’un bloc @code est autorisé.

@functions

La directive @functions permet d’ajouter des membres C# (champs, propriétés et méthodes) à la classe générée :

@functions {
    // C# members (fields, properties, and methods)
}

Dans les Razorcomposants, utilisez @code sur @functions pour ajouter des membres C#.

Par exemple :

@functions {
    public string GetHello()
    {
        return "Hello";
    }
}

<div>From method: @GetHello()</div> 

Le code génère le balisage HTML suivant :

<div>From method: Hello</div>

Le code suivant correspond à la classe C# Razor générée :

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Razor;

public class _Views_Home_Test_cshtml : RazorPage<dynamic>
{
    // Functions placed between here 
    public string GetHello()
    {
        return "Hello";
    }
    // And here.
#pragma warning disable 1998
    public override async Task ExecuteAsync()
    {
        WriteLiteral("\r\n<div>From method: ");
        Write(GetHello());
        WriteLiteral("</div>\r\n");
    }
#pragma warning restore 1998

Les méthodes @functions servent de méthodes de création de modèles lorsqu’elles comprennent des balises :

@{
    RenderName("Mahatma Gandhi");
    RenderName("Martin Luther King, Jr.");
}

@functions {
    private void RenderName(string name)
    {
        <p>Name: <strong>@name</strong></p>
    }
}

Le code s’affiche en HTML de la façon suivante :

<p>Name: <strong>Mahatma Gandhi</strong></p>
<p>Name: <strong>Martin Luther King, Jr.</strong></p>

@implements

La directive @implements implémente une interface pour la classe générée.

L’exemple suivant implémente System.IDisposable afin que la méthode Dispose puisse être appelée :

@implements IDisposable

<h1>Example</h1>

@functions {
    private bool _isDisposed;

    ...

    public void Dispose() => _isDisposed = true;
}

@inherits

La directive @inherits fournit un contrôle complet de la classe héritée par la vue :

@inherits TypeNameOfClassToInheritFrom

Le code suivant est un type de page Razor personnalisé :

using Microsoft.AspNetCore.Mvc.Razor;

public abstract class CustomRazorPage<TModel> : RazorPage<TModel>
{
    public string CustomText { get; } = 
        "Gardyloo! - A Scottish warning yelled from a window before dumping" +
        "a slop bucket on the street below.";
}

Le CustomText s’affiche dans une vue :

@inherits CustomRazorPage<TModel>

<div>Custom text: @CustomText</div>

Le code s’affiche en HTML de la façon suivante :

<div>
    Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping
    a slop bucket on the street below.
</div>

@model et @inherits peuvent s’utiliser dans la même vue. @inherits peut se trouver dans un fichier _ViewImports.cshtml que la vue importe :

@inherits CustomRazorPage<TModel>

Le code suivant est un exemple de vue fortement typée :

@inherits CustomRazorPage<TModel>

<div>The Login Email: @Model.Email</div>
<div>Custom text: @CustomText</div>

Si « rick@contoso.com » est passé au modèle, la vue génère le balisage HTML suivant :

<div>The Login Email: rick@contoso.com</div>
<div>
    Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping
    a slop bucket on the street below.
</div>

@inject

La directive @inject permet à la page Razor d’injecter un service dans une vue à partir du conteneur de services. Pour plus d’informations, consultez Injection de dépendances dans les vues.

@layout

Ce scénario s’applique uniquement aux composants Razor (.razor).

La @layout directive spécifie une disposition pour les composants routables Razor qui ont une @page directive. Les composants de disposition sont utilisés pour éviter la duplication et l’incohérence de code. Pour plus d’informations, consultez layouts ASP.NET Core Blazor.

@model

Ce scénario s’applique uniquement aux vues MVC et à Pages Razor (.cshtml).

La directive @model spécifie le type du modèle passé à une vue ou une page :

@model TypeNameOfModel

Dans une application ASP.NET Core MVC ou Razor Pages créée avec des comptes d’utilisateur individuels, Views/Account/Login.cshtml contient la déclaration de modèle suivante :

@model LoginViewModel

La classe générée hérite de RazorPage<LoginViewModel> :

public class _Views_Account_Login_cshtml : RazorPage<LoginViewModel>

Razor expose une propriété Model pour accéder au modèle passé à la vue :

<div>The Login Email: @Model.Email</div>

La directive @model spécifie le type de la propriété Model. La directive spécifie le type T dans RazorPage<T> pour la classe générée dont dérive la vue. Si la directive @model n’est pas spécifiée, la propriété Model est de type dynamic. Pour plus d’informations, consultez Strongly typed models and the @model keyword.

@namespace

La directive @namespace :

• Définit l’espace de noms de la classe de la page Razor, de la vue MVC ou du composant Razor généré.
• Définit les espaces de noms dérivés racine d’une classe de pages, de vues ou de composants à partir du fichier d’importations le plus proche dans l’arborescence de répertoires, _ViewImports.cshtml (vues ou pages) ou _Imports.razor (composants Razor).

@namespace Your.Namespace.Here

Pour l’exemple de Razor Pages illustré dans le tableau suivant :

• Chaque page importe Pages/_ViewImports.cshtml.
• Pages/_ViewImports.cshtml contient @namespace Hello.World.
• Chaque page a Hello.World comme racine de son espace de noms.

Page	Espace de noms
Pages/Index.cshtml	Hello.World
Pages/MorePages/Page.cshtml	Hello.World.MorePages
Pages/MorePages/EvenMorePages/Page.cshtml	Hello.World.MorePages.EvenMorePages

Les relations précédentes s’appliquent aux fichiers d’importation utilisés avec les vues MVC et les composants Razor.

Lorsque plusieurs fichiers d’importation ont une directive @namespace, le fichier le plus proche de la page, de la vue ou du composant dans l’arborescence de répertoires est utilisé pour définir l’espace de noms racine.

Si le dossier EvenMorePages dans l’exemple précédent comprend un fichier d’importations avec @namespace Another.Planet (ou si le fichier Pages/MorePages/EvenMorePages/Page.cshtml contient @namespace Another.Planet), le résultat est indiqué dans le tableau suivant.

Page	Espace de noms
Pages/Index.cshtml	Hello.World
Pages/MorePages/Page.cshtml	Hello.World.MorePages
Pages/MorePages/EvenMorePages/Page.cshtml	Another.Planet

@page

La directive @page a des effets différents selon le type du fichier dans lequel elle apparaît. La directive :

• Dans un fichier .cshtml indique qu’un fichier est une Page Razor. Pour plus d’informations, consultez Itinéraires personnalisés et Présentation des Razor pages dans ASP.NET Core.
• Spécifie qu’un composant Razor doit gérer les requêtes directement. Pour plus d’informations, consultez Routage et navigation ASP.NET Core Blazor.

@preservewhitespace

Ce scénario s’applique uniquement aux composants Razor (.razor).

Lorsque la valeur est définie false sur (par défaut), l’espace blanc dans le balisage rendu des Razor composants (.razor) est supprimé si :

• Espace blanc de début ou de fin au sein d’un élément.
• Commençant ou finissant dans un paramètre RenderFragment. Par exemple, le contenu enfant est passé à un autre composant.
• Espace blanc précédant ou suivant un bloc de code C#, comme @if ou @foreach.

@rendermode

Ce scénario s’applique uniquement aux composants Razor (.razor).

Définit le mode de rendu d’un composant Razor :

• InteractiveServer : applique le rendu interactif du serveur à l’aide de Blazor Server.
• InteractiveWebAssembly : applique le rendu WebAssembly interactif à l’aide de Blazor WebAssembly.
• InteractiveAuto : applique dans un premier temps le rendu WebAssembly interactif à l’aide de Blazor Server, puis applique le rendu interactif WebAssembly à l’aide de WebAssembly lors des visites ultérieures après le téléchargement de l’offre groupée Blazor.

Pour une instance de composant :

<... @rendermode="InteractiveServer" />

Dans la définition du composant :

@rendermode InteractiveServer

Remarque

Les modèles Blazor incluent une directive statique using pour RenderMode dans le fichier _Imports de l’application (Components/_Imports.razor) pour une syntaxe de @rendermode plus courte :

@using static Microsoft.AspNetCore.Components.Web.RenderMode

Sans la directive précédente, les composants doivent spécifier explicitement la classe statique RenderMode dans la syntaxe de @rendermode :

<Dialog @rendermode="RenderMode.InteractiveServer" />

Pour plus d’informations, notamment des conseils sur la désactivation du prérendu avec l’attribut directive/directive, consultez Modes de rendu Blazor d’ASP.NET Core.

@section

Ce scénario s’applique uniquement aux vues MVC et à Pages Razor (.cshtml).

La directive @section est utilisée conjointement avec des layouts MVC et RazorPages pour permettre aux vues et aux pages d’afficher le contenu dans différentes parties de la page HTML. Pour plus d’informations, consultez Disposition dans ASP.NET Core.

@typeparam

Ce scénario s’applique uniquement aux composants Razor (.razor).

La directive @typeparam déclare un paramètre de type générique pour la classe de composant générée :

@typeparam TEntity

Les types génériques avec where des contraintes de type sont pris en charge :

@typeparam TEntity where TEntity : IEntity

Pour plus d’informations, consultez les articles suivants :

• ASP.NET CoreRazor prise en charge du type générique de composant
• Composants basés sur un modèle Blazor ASP.NET Core

@using

La directive @using ajoute la directive using C# à la vue générée :

@using System.IO
@{
    var dir = Directory.GetCurrentDirectory();
}
<p>@dir</p>

Dans des Razor composants, @using contrôle également les composants dans la portée.

Attributs de directive

Les attributs de directives Razor sont représentés par des expressions implicites constituées du symbole @ suivi de mots clés réservés. En règle générale, un attribut de directive change la manière dont un élément est analysé ou active une fonctionnalité différente.

@attributes

Ce scénario s’applique uniquement aux composants Razor (.razor).

@attributes permet à un composant de restituer des attributs non déclarés. Pour plus d’informations, consultez ASP.NET Core Blazor paramètres de platissement d’attributs et arbitraires.

@bind

Ce scénario s’applique uniquement aux composants Razor (.razor).

La liaison de données dans des composants s’effectue avec l’attribut @bind. Pour plus d’informations, consultez Composants ASP.NET Core Blazorliaison de données.

@bind:culture

Ce scénario s’applique uniquement aux composants Razor (.razor).

Utilisez l’attribut @bind:culture avec l’attribut @bind pour fournir un System.Globalization.CultureInfo pour l’analyse et la mise en forme d’une valeur. Pour plus d’informations, consultez Globalisation et localisation d’ASP.NET Core Blazor.

@formname

Ce scénario s’applique uniquement aux composants Razor (.razor).

@formname attribue un nom de formulaire à un formulaire HTML brut d’un composant Razor ou un formulaire basé sur EditForm (Editform documentation). La valeur de @formname doit être unique, ce qui empêche les collisions de forme dans les situations suivantes :

• Un formulaire est placé dans un composant avec plusieurs formulaires.
• Un formulaire provient d’une bibliothèque de classes externe, généralement un paquetage NuGet, pour un composant avec plusieurs formulaires, et l’auteur de l’application ne contrôle pas le code source de la bibliothèque pour définir un nom de formulaire externe différent de celui utilisé par un autre formulaire dans le composant.

Pour plus d’informations et d’exemples, consultez ASP.NET Core Blazor ASP.NET Core.

@on{EVENT}

Ce scénario s’applique uniquement aux composants Razor (.razor).

Razor fournit des fonctionnalités de gestion des événements pour les composants. Pour plus d’informations, consultez Gestion des événements ASP.NET CoreBlazor.

@on{EVENT}:preventDefault

Ce scénario s’applique uniquement aux composants Razor (.razor).

Empêche l’action par défaut pour l’événement.

@on{EVENT}:stopPropagation

Ce scénario s’applique uniquement aux composants Razor (.razor).

Arrête la propagation de l’événement.

@key

Ce scénario s’applique uniquement aux composants Razor (.razor).

L’attribut de directive @key amène les composants à comparer l’algorithme afin de garantir la préservation des éléments ou des composants en fonction de la valeur de la clé. Pour plus d’informations, consultez Conserver les relations d’élément, de composant et de modèle dans ASP.NET Core Blazor.

@ref

Ce scénario s’applique uniquement aux composants Razor (.razor).

Les références de composants (@ref) permettent de référencer une instance de composant afin que vous puissiez émettre des commandes vers cette instance. Pour plus d’informations, consultez Composants ASP.NET Core Razor.

Délégués Razor modèles

Ce scénario s’applique uniquement aux vues MVC et à Pages Razor (.cshtml).

Les modèles Razor vous permettent de définir un extrait de code d’interface utilisateur avec le format suivant :

@<tag>...</tag>

L’exemple suivant montre comment spécifier un délégué Razor basé sur un modèle comme Func<T,TResult>. Le type dynamique est spécifié pour le paramètre de la méthode encapsulée par le délégué. Un type objet est spécifié comme valeur de retour du délégué. Le modèle est utilisé avec une List<T> de Pet qui a une propriété Name.

public class Pet
{
    public string Name { get; set; }
}

@{
    Func<dynamic, object> petTemplate = @<p>You have a pet named <strong>@item.Name</strong>.</p>;

    var pets = new List<Pet>
    {
        new Pet { Name = "Rin Tin Tin" },
        new Pet { Name = "Mr. Bigglesworth" },
        new Pet { Name = "K-9" }
    };
}

Le modèle est rendu avec des éléments pets fournis par une instruction foreach :

@foreach (var pet in pets)
{
    @petTemplate(pet)
}

Sortie rendue :

<p>You have a pet named <strong>Rin Tin Tin</strong>.</p>
<p>You have a pet named <strong>Mr. Bigglesworth</strong>.</p>
<p>You have a pet named <strong>K-9</strong>.</p>

Vous pouvez également fournir un modèle Razor inline en tant qu’argument à une méthode. Dans l’exemple suivant, la méthode Repeat reçoit un modèle Razor. La méthode utilise le modèle pour produire du contenu HTML avec des répétitions d’éléments fournis à partir d’une liste :

@using Microsoft.AspNetCore.Html

@functions {
    public static IHtmlContent Repeat(IEnumerable<dynamic> items, int times,
        Func<dynamic, IHtmlContent> template)
    {
        var html = new HtmlContentBuilder();

        foreach (var item in items)
        {
            for (var i = 0; i < times; i++)
            {
                html.AppendHtml(template(item));
            }
        }

        return html;
    }
}

En utilisant la liste d’éléments « pets » de l’exemple précédent, la méthode Repeat est appelée avec :

• List<T> de Pet.
• Nombre de fois que chaque élément « pet » doit être répété.
• Modèle inline à utiliser pour les éléments de liste d’une liste non triée.

<ul>
    @Repeat(pets, 3, @<li>@item.Name</li>)
</ul>

Sortie rendue :

<ul>
    <li>Rin Tin Tin</li>
    <li>Rin Tin Tin</li>
    <li>Rin Tin Tin</li>
    <li>Mr. Bigglesworth</li>
    <li>Mr. Bigglesworth</li>
    <li>Mr. Bigglesworth</li>
    <li>K-9</li>
    <li>K-9</li>
    <li>K-9</li>
</ul>

Tag Helpers

Ce scénario s’applique uniquement aux vues MVC et à Pages Razor (.cshtml).

Il existe trois directives spécifiques aux Tag Helpers.

Directive	Fonction
@addTagHelper	Rend les Tag Helpers disponibles dans une vue.
@removeTagHelper	Supprime les Tag Helpers précédemment ajoutés à une vue.
@tagHelperPrefix	Spécifie un préfixe de balise pour activer la prise en charge des Tag Helpers et rendre leur usage explicite.

Mots clés réservés Razor

Mots clés Razor

• page
• namespace
• functions
• inherits
• model
• section
• helper (non pris en charge par ASP.NET Core)

Les mots clés Razor sont précédés d’une séquence d’échappement @(Razor Keyword) (par exemple, @(functions)).

Mots clés Razor C#

• case
• do
• default
• for
• foreach
• if
• else
• lock
• switch
• try
• catch
• finally
• using
• while

Les mots clés Razor C# doivent être précédés d’une double séquence d’échappement @(@C# Razor Keyword) (par exemple, @(@case)). La première séquence d’échappement @ est pour l’analyseur Razor. La seconde séquence d’échappement @ est pour l’analyseur C#.

Mots clés réservés non utilisés par Razor

• class

Inspecter la classe C# Razor générée pour une vue

Le Razor Kit de développement logiciel (SDK) gère la compilation des fichiersRazor. Par défaut, les fichiers de code générés ne sont pas émis. Pour activer l’émission des fichiers de code, définissez la EmitCompilerGeneratedFiles directive dans le fichier projet (.csproj) sur true :

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

Lors de la génération d’un projet 6.0 (net6.0) dans la configuration de build Debug , le Razor Kit de développement logiciel (SDK) génère un obj/Debug/net6.0/generated/ répertoire à la racine du projet. Son sous-répertoire contient les fichiers de code de page émis Razor.

Recherches de vues et respect de la casse

Le moteur de vue Razor effectue des recherches de vues en respectant la casse. Toutefois, la recherche réellement effectuée est déterminée par le système de fichiers sous-jacent :

• Source basé sur un fichier :
  • Sur les systèmes d’exploitation avec des systèmes de fichiers qui ne respectent pas la casse (par exemple, Windows), les recherches de fournisseurs de fichiers physiques ne respectent pas la casse. Par exemple, les résultats return View("Test") correspondent à /Views/Home/Test.cshtml, /Views/home/test.cshtml, et à toute autre variante de casse.
  • Sur des systèmes de fichiers respectant la casse (par exemple, Linux, OSX, et avec EmbeddedFileProvider), les recherches respectent la casse. Par exemple, return View("Test") correspond spécifiquement à /Views/Home/Test.cshtml.
• Vues précompilées : Avec ASP.NET Core 2.0 et les versions ultérieures, les recherches de vues précompilées ne respectent pas la casse, quels que soient les systèmes d’exploitation. Le comportement est le même que celui du fournisseur de fichiers physiques sur Windows. Si deux vues précompilées diffèrent seulement par leur casse, le résultat de la recherche est non déterministe.

Les développeurs doivent s’efforcer d’utiliser la même casse pour les noms de fichiers et de répertoires que pour les noms des éléments suivants :

• Zone, contrôleur et action
• Razor Pages.

L’utilisation d’une casse identique garantit que les déploiements trouvent toujours les vues associées, indépendamment du système de fichiers sous-jacent.

Importations utilisées par Razor

Les importations suivantes sont générées par les modèles web ASP.NET Core pour prendre en charge les fichiers Razor :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Rendering;
using Microsoft.AspNetCore.Mvc.ViewFeatures;

Ressources supplémentaires

Présentation de la programmation web ASP.NET à l’aide de Razor La syntaxe fournit de nombreux exemples de programmation avec Razor la syntaxe.