Conventions des routes et des applications pour Razor Pages dans ASP.NET Core

Découvrez comment utiliser les conventions du fournisseur de modèles de routes et d’applications de pages pour contrôler le routage, la découverte et le traitement des pages dans les applications Razor Pages.

Pour spécifier un itinéraire de page, ajoutez des segments de routage ou ajoutez des paramètres à un itinéraire, utilisez la directive @page de la page. Pour plus d’informations, consultez Itinéraires personnalisés.

Il existe des mots réservés qui ne peuvent pas être utilisés comme segments de routage ou noms de paramètres. Pour plus d’informations, consultez Routage : noms de routage réservés.

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

Scénario	L'exemple montre
Conventions de modèle Conventions.Add IPageRouteModelConvention IPageApplicationModelConvention IPageHandlerModelConvention	Ajouter un modèle de route et un en-tête aux pages d’une application.
Conventions d’actions de routage de pages AddFolderRouteModelConvention AddPageRouteModelConvention AddPageRoute	Ajouter un modèle de route aux pages d’un dossier et à une page unique.
Conventions d’actions de modèle de page AddFolderApplicationModelConvention AddPageApplicationModelConvention ConfigureFilter (classe de filtre, expression lambda ou fabrique de filtres)	Ajouter un en-tête dans les pages d’un dossier, ajouter un en-tête dans une page unique et configurer une fabrique de filtres pour ajouter un en-tête dans les pages d’une application.

Les conventions de pages Razor sont configurées à l’aide d’une surcharge AddRazorPages qui configure RazorPagesOptions. Les exemples de convention suivants sont expliqués plus loin dans cette rubrique :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages(options =>
    {
        options.Conventions.Add( ... );
        options.Conventions.AddFolderRouteModelConvention(
            "/OtherPages", model => { ... });
        options.Conventions.AddPageRouteModelConvention(
            "/About", model => { ... });
        options.Conventions.AddPageRoute(
            "/Contact", "TheContactPage/{text?}");
        options.Conventions.AddFolderApplicationModelConvention(
            "/OtherPages", model => { ... });
        options.Conventions.AddPageApplicationModelConvention(
            "/About", model => { ... });
        options.Conventions.ConfigureFilter(model => { ... });
        options.Conventions.ConfigureFilter( ... );
    });
}

Ordre d’itinéraire

Les itinéraires spécifient Order pour un traitement (correspondance d’itinéraire).

Ordre d’itinéraire	Comportement
-1	L’itinéraire est traité avant que d’autres itinéraires ne soient traités.
0	L’ordre n’est pas spécifié (valeur par défaut). Ne pas attribuer Order (Order = null) attribue par défaut la valeur 0 à l’itinéraire Order pour le traitement.
1, 2, … n	Spécifie l’ordre de traitement de l’itinéraire.

Le traitement des itinéraires est établi par convention :

• Les itinéraires sont traités dans l’ordre séquentiel (-1, 0, 1, 2, ... n).
• Lorsque les itinéraires ont le même Order, l’itinéraire le plus spécifique est mis en correspondance en premier, suivi d’itinéraires moins spécifiques.
• Lorsque les itinéraires avec le même Order et le même nombre de paramètres correspondent à une URL de requête, les itinéraires sont traités dans l’ordre dans lequel ils sont ajoutés à PageConventionCollection.

Si possible, évitez de déprendre d’un ordre de traitement d’itinéraire établie. En règle générale, le routage sélectionne l’itinéraire approprié avec la correspondance d’URL. Si vous devez définir les propriétés de routage Order pour acheminer correctement les demandes, le schéma de routage de l’application est probablement déroutant pour les clients et fragile à maintenir. Cherchez à simplifier le schéma de routage de l’application. L’exemple d’application nécessite un ordre de traitement de routage explicite pour illustrer plusieurs scénarios de routage à l’aide d’une seule application. Toutefois, vous devez tenter d’éviter la définition de l’itinéraire Order dans les applications de production.

Le routage de Razor Pages et celui du contrôleur MVC partagent une implémentation. Les informations sur l’ordre de routage dans les rubriques MVC sont disponibles dans Routage vers les actions du contrôleur : classement des itinéraires d’attributs.

Conventions de modèle

Ajoutez un délégué pour IPageConvention afin d’ajouter des conventions de modèles qui s’appliquent à Razor Pages.

Ajouter une convention de modèle de routage à toutes les pages

Utilise Conventions pour créer et ajouter IPageRouteModelConvention à la collection d’instances IPageConvention appliquées pendant la construction du modèle de routage de page.

L’exemple d’application contient la classe GlobalTemplatePageRouteModelConvention pour ajouter un modèle de routage {globalTemplate?} à toutes les pages de l’application :

using Microsoft.AspNetCore.Mvc.ApplicationModels;
namespace SampleApp.Conventions;

public class GlobalTemplatePageRouteModelConvention : IPageRouteModelConvention
{
    public void Apply(PageRouteModel model)
    {
        var selectorCount = model.Selectors.Count;
        for (var i = 0; i < selectorCount; i++)
        {
            var selector = model.Selectors[i];
            model.Selectors.Add(new SelectorModel
            {
                AttributeRouteModel = new AttributeRouteModel
                {
                    Order = 1,
                    Template = AttributeRouteModel.CombineTemplates(
                        selector.AttributeRouteModel!.Template, 
                        "{globalTemplate?}"),
                }
            });
        }
    }
}

Dans le code précédent :

• PageRouteModel est passé à la méthode Apply.
• PageRouteModel.Selectors obtient le nombre de sélecteurs.
• Un nouveau SelectorModel est ajouté qui contient AttributeRouteModel

Les options Razor Pages, telles que l’ajout de Conventions, sont ajoutées lorsque Razor Pages sont ajoutées à la collection de services. Pour obtenir un exemple, consultez l’exemple d’application.

using Microsoft.AspNetCore.Mvc.ApplicationModels;
using Microsoft.EntityFrameworkCore;
using SampleApp.Conventions;
using SampleApp.Data;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
                                   options.UseInMemoryDatabase("InMemoryDb"));

builder.Services.AddRazorPages(options =>
   {
       options.Conventions.Add(new GlobalTemplatePageRouteModelConvention());

       options.Conventions.AddFolderRouteModelConvention("/OtherPages", model =>
       {
           var selectorCount = model.Selectors.Count;
           for (var i = 0; i < selectorCount; i++)
           {
               var selector = model.Selectors[i];
               model.Selectors.Add(new SelectorModel
               {
                   AttributeRouteModel = new AttributeRouteModel
                   {
                       Order = 2,
                       Template = AttributeRouteModel.CombineTemplates(
                           selector.AttributeRouteModel!.Template,
                           "{otherPagesTemplate?}"),
                   }
               });
           }
       });

       options.Conventions.AddPageRouteModelConvention("/About", model =>
       {
           var selectorCount = model.Selectors.Count;
           for (var i = 0; i < selectorCount; i++)
           {
               var selector = model.Selectors[i];
               model.Selectors.Add(new SelectorModel
               {
                   AttributeRouteModel = new AttributeRouteModel
                   {
                       Order = 2,
                       Template = AttributeRouteModel.CombineTemplates(
                           selector.AttributeRouteModel!.Template,
                           "{aboutTemplate?}"),
                   }
               });
           }
       });

   });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAuthorization();
app.MapRazorPages();
app.Run();

Considérons la classe GlobalTemplatePageRouteModelConvention :

using Microsoft.AspNetCore.Mvc.ApplicationModels;
namespace SampleApp.Conventions;

public class GlobalTemplatePageRouteModelConvention : IPageRouteModelConvention
{
    public void Apply(PageRouteModel model)
    {
        var selectorCount = model.Selectors.Count;
        for (var i = 0; i < selectorCount; i++)
        {
            var selector = model.Selectors[i];
            model.Selectors.Add(new SelectorModel
            {
                AttributeRouteModel = new AttributeRouteModel
                {
                    Order = 1,
                    Template = AttributeRouteModel.CombineTemplates(
                        selector.AttributeRouteModel!.Template, 
                        "{globalTemplate?}"),
                }
            });
        }
    }
}

La propriété Order de AttributeRouteModel a la valeur 1. Cela garantit le comportement de correspondance d’itinéraire suivant dans l’exemple d’application :

• Un modèle d’itinéraire pour TheContactPage/{text?} est ajouté plus loin dans cette rubrique. L’itinéraire Contact Page a un ordre par défaut de null (Order = 0), et correspond donc avant le modèle d’itinéraire {globalTemplate?} qui a Order = 1.

• Le modèle d’itinéraire {aboutTemplate?} est affiché dans le code précédent. Le modèle {aboutTemplate?} reçoit l’ordre Order avec la valeur 2. Quand la page About est demandée sur /About/RouteDataValue, « RouteDataValue » est chargé dans RouteData.Values["globalTemplate"] (Order = 1) et non RouteData.Values["aboutTemplate"] (Order = 2) en raison de la définition de la propriété Order.

• Le modèle d’itinéraire {otherPagesTemplate?} est affiché dans le code précédent. Le modèle {otherPagesTemplate?} reçoit l’ordre Order avec la valeur 2. Quand une page du dossier Pages/OtherPages est demandée avec un paramètre d’itinéraire :

• Par exemple : /OtherPages/Page1/xyz

• La valeur de données de routage "xyz" est chargée dans RouteData.Values["globalTemplate"] (Order = 1).

• RouteData.Values["otherPagesTemplate"] avec (Order = 2) n’est pas chargé en raison de la propriété Order2 ayant une valeur plus élevée.

Si possible, ne définissez pas Order. Si Order n’est pas définie, la valeur par défaut est Order = 0. Utilisez le routage pour sélectionner l’itinéraire approprié plutôt que la propriété Order.

Demandez la page About de l’exemple à localhost:{port}/About/GlobalRouteValue et inspectez le résultat :

L’exemple d’application utilise le package NuGet Rick.Docs.Samples.RouteInfo pour afficher les informations de routage dans la sortie de journalisation. À l’aide de localhost:{port}/About/GlobalRouteValue, l’enregistreur d’événements affiche la requête, Order et le modèle utilisé :

info: SampleApp.Pages.AboutModel[0]
       /About/GlobalRouteValue   Order = 1 Template = About/{globalTemplate?}

Ajouter une convention de modèle d’application à toutes les pages

Utilisez Conventions pour créer et ajouter IPageApplicationModelConvention à la collection d’instances IPageConvention appliquées pendant la construction du modèle d’application de page.

Pour illustrer cette convention et bien d’autres, plus loin dans cette rubrique, l’exemple d’application inclut une classe AddHeaderAttribute. Le constructeur de classe accepte une chaîne name et un tableau de chaînes values. Ces valeurs sont utilisées dans sa méthode OnResultExecuting pour définir un en-tête de réponse. La classe complète est affichée dans la section Conventions d’actions de modèle de page, plus loin dans cette rubrique.

L’exemple d’application utilise la classe AddHeaderAttribute pour ajouter un en-tête, GlobalHeader, à toutes les pages de l’application :

public class GlobalHeaderPageApplicationModelConvention 
    : IPageApplicationModelConvention
{
    public void Apply(PageApplicationModel model)
    {
        model.Filters.Add(new AddHeaderAttribute(
            "GlobalHeader", new string[] { "Global Header Value" }));
    }
}

Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseInMemoryDatabase("InMemoryDb"));

builder.Services.AddRazorPages(options =>
   {
       options.Conventions.Add(new GlobalTemplatePageRouteModelConvention());

       options.Conventions.Add(new GlobalHeaderPageApplicationModelConvention());

Demandez la page About de l’exemple sur localhost:{port}/About et examinez les en-têtes pour voir le résultat :

Ajouter une convention de modèle de gestionnaire à toutes les pages

Utilisez Conventions pour créer et ajouter IPageHandlerModelConvention à la collection d’instances IPageConvention appliquées pendant la construction du modèle de gestionnaire de page.

public class GlobalPageHandlerModelConvention
    : IPageHandlerModelConvention
{
    public void Apply(PageHandlerModel model)
    {
        // Access the PageHandlerModel
    }
}

Conventions d’actions de routage de pages

Le fournisseur de modèle de routage par défaut qui dérive de IPageRouteModelProvider appelle des conventions conçues pour fournir des points d’extensibilité pour la configuration des itinéraires de page.

Convention de modèle de routage de dossier

Utilisez AddFolderRouteModelConvention pour créer et ajouter un IPageRouteModelConvention qui appelle une action sur le PageRouteModel pour toutes les pages sous le dossier spécifié.

L’exemple d’application utilise AddFolderRouteModelConvention pour ajouter un modèle de routage {otherPagesTemplate?} aux pages du dossier OtherPages :

options.Conventions.AddFolderRouteModelConvention("/OtherPages", model =>
{
    var selectorCount = model.Selectors.Count;
    for (var i = 0; i < selectorCount; i++)
    {
        var selector = model.Selectors[i];
        model.Selectors.Add(new SelectorModel
        {
            AttributeRouteModel = new AttributeRouteModel
            {
                Order = 2,
                Template = AttributeRouteModel.CombineTemplates(
                    selector.AttributeRouteModel!.Template,
                    "{otherPagesTemplate?}"),
            }
        });
    }
});

La propriété Order de AttributeRouteModel a la valeur 2. Cela permet de garantir que le modèle de {globalTemplate?} (défini plus tôt dans cette rubrique sur 1) est prioritaire pour la première position de la valeur des données de routage quand une valeur de routage unique est fournie. Si une page du dossier Pages/OtherPages est demandée avec une valeur de paramètre de routage (par exemple, /OtherPages/Page1/RouteDataValue), « RouteDataValue » est chargé dans RouteData.Values["globalTemplate"] (Order = 1) et non RouteData.Values["otherPagesTemplate"] (Order = 2) en raison de la définition de la propriété Order.

Dans la mesure du possible, ne définissez pas Order, qui entraîne Order = 0. Utilisez le routage pour sélectionner l’itinéraire approprié.

Demandez la page Page1 de l’exemple sur localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue et examinez le résultat :

Convention de modèle de routage de page

Utilisez AddPageRouteModelConvention pour créer et ajouter IPageRouteModelConvention qui appelle une action sur le PageRouteModel de la page avec le nom spécifié.

L’exemple d’application utilise AddPageRouteModelConvention pour ajouter un modèle de routage {aboutTemplate?} à la page About :

options.Conventions.AddPageRouteModelConvention("/About", model =>
{
    var selectorCount = model.Selectors.Count;
    for (var i = 0; i < selectorCount; i++)
    {
        var selector = model.Selectors[i];
        model.Selectors.Add(new SelectorModel
        {
            AttributeRouteModel = new AttributeRouteModel
            {
                Order = 2,
                Template = AttributeRouteModel.CombineTemplates(
                    selector.AttributeRouteModel!.Template,
                    "{aboutTemplate?}"),
            }
        });
    }
});

La propriété Order de AttributeRouteModel a la valeur 2. Cela permet de garantir que le modèle de {globalTemplate?} (défini plus tôt dans cette rubrique sur 1) est prioritaire pour la première position de la valeur des données de routage quand une valeur de routage unique est fournie. Si la page About est demandée avec une valeur de paramètre de routage sur /About/RouteDataValue, « RouteDataValue » est chargé dans RouteData.Values["globalTemplate"] (Order = 1) et non RouteData.Values["aboutTemplate"] (Order = 2) en raison de la définition de la propriété Order.

Dans la mesure du possible, ne définissez pas Order, qui entraîne Order = 0. Utilisez le routage pour sélectionner l’itinéraire approprié.

Demandez la page About de l’exemple sur localhost:{port}/About/GlobalRouteValue/AboutRouteValue et examinez le résultat :

La sortie de l’enregistreur d'événements s’affiche :

info: SampleApp.Pages.AboutModel[0]
       /About/GlobalRouteValue/AboutRouteValue   Order = 2 Template = About/{globalTemplate?}/{aboutTemplate?}

Utilisez un transformateur de paramètres pour personnaliser les itinéraires de page

Voir Transformateurs de paramètres.

Configurer un routage de page

Utilisez AddPageRoute pour configurer un routage vers une page située dans le chemin spécifié. Les liens générés qui pointent vers la page utilisent le routage spécifié. AddPageRoute utilise AddPageRouteModelConvention pour établir le routage.

L’exemple d’application crée un itinéraire vers /TheContactPage pour la page ContactRazor :

options.Conventions.AddPageRoute("/Contact", "TheContactPage/{text?}");

La page Contact est également accessible sur /Contact1` via son routage par défaut.

Le routage personnalisé de l’exemple d’application vers la page Contact permet un segment de routage text facultatif ({text?}). Cette page inclut également ce segment facultatif dans sa directive @page, au cas où le visiteur accèderait à la page via le routage /Contact :

@page "{text?}"
@model ContactModel
@{
    ViewData["Title"] = "Contact";
}

<h1>@ViewData["Title"]</h1>
<h2>@Model.Message</h2>

<address>
    One Microsoft Way<br>
    Redmond, WA 98052-6399<br>
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

<address>
    <strong>Support:</strong> <a href="mailto:Support@example.com">Support@example.com</a><br>
    <strong>Marketing:</strong> <a href="mailto:Marketing@example.com">Marketing@example.com</a>
</address>

<p>@Model.RouteDataTextTemplateValue</p>

Notez que l’URL générée pour le lien Contact dans la page affichée reflète le routage mis à jour :

Visitez la page Contact via son routage ordinaire, /Contact ou via le routage personnalisé, /TheContactPage. Si vous indiquez un segment de routage text supplémentaire, la page affiche le segment HTML que vous fournissez :

Conventions d’actions de modèle de page

Le fournisseur de modèles de pages par défaut, qui implémente IPageApplicationModelProvider, appelle des conventions conçues pour fournir des points d’extensibilité permettant de configurer les modèles de pages. Ces conventions sont utiles durant la génération et la modification de scénarios de découverte et de traitement de pages.

Pour les exemples de cette section, l’exemple d’application utilise une classe AddHeaderAttribute, qui est un ResultFilterAttribute, et qui applique un en-tête de réponse :

public class AddHeaderAttribute : ResultFilterAttribute
{
    private readonly string _name;
    private readonly string[] _values;

    public AddHeaderAttribute(string name, string[] values)
    {
        _name = name;
        _values = values;
    }

    public override void OnResultExecuting(ResultExecutingContext context)
    {
        context.HttpContext.Response.Headers.Add(_name, _values);
        base.OnResultExecuting(context);
    }
}

À l’aide de conventions, l’exemple montre comment appliquer l’attribut à toutes les pages d’un dossier et à une seule page.

Convention de modèle d’application de dossier

Utilisez AddFolderApplicationModelConvention pour créer et ajouter IPageApplicationModelConvention qui appelle une action sur les instances PageApplicationModel pour toutes les pages du dossier spécifié.

L’exemple illustre l’utilisation de AddFolderApplicationModelConvention en ajoutant un en-tête, OtherPagesHeader, aux pages situées dans le dossier OtherPages de l’application :

options.Conventions.AddFolderApplicationModelConvention("/OtherPages", model =>
{
    model.Filters.Add(new AddHeaderAttribute(
        "OtherPagesHeader", new string[] { "OtherPages Header Value" }));
});

Demandez la page Page1 de l’exemple sur localhost:5000/OtherPages/Page1 et examinez les en-têtes pour voir le résultat :

Convention de modèle d’application de page

Utilisez AddPageApplicationModelConvention pour créer et ajouter IPageApplicationModelConvention qui appelle une action sur le PageApplicationModel pour la page avec le nom spécifié.

L’exemple illustre l’utilisation de AddPageApplicationModelConvention en ajoutant un en-tête, AboutHeader, à la page About :

options.Conventions.AddPageApplicationModelConvention("/About", model =>
{
    model.Filters.Add(new AddHeaderAttribute(
        "AboutHeader", new string[] { "About Header Value" }));
});

Demandez la page About de l’exemple sur localhost:5000/About et examinez les en-têtes pour voir le résultat :

Configurer un filtre

ConfigureFilter configure le filtre spécifié à appliquer. Vous pouvez implémenter une classe de filtre. Toutefois, l’exemple d’application montre comment implémenter un filtre dans une expression lambda, laquelle est implémentée en arrière-plan en tant que fabrique qui retourne un filtre :

options.Conventions.ConfigureFilter(model =>
{
    if (model.RelativePath.Contains("OtherPages/Page2"))
    {
        return new AddHeaderAttribute(
            "OtherPagesPage2Header",
            new string[] { "OtherPages/Page2 Header Value" });
    }
    return new EmptyFilter();
});

Le modèle d’application de page est utilisé pour vérifier le chemin relatif des segments qui mènent à la page Page2 dans le dossier OtherPages. Si la condition est satisfaite, un en-tête est ajouté. Sinon, EmptyFilter est appliqué.

EmptyFilter est un filtre d’action. Étant donné que les filtres d’action sont ignorés par Razor Pages, EmptyFilter n’a aucun effet comme prévu si le chemin d’accès ne contient pas OtherPages/Page2.

Demandez la page Page2 de l’exemple sur localhost:5000/OtherPages/Page2 et examinez les en-têtes pour voir le résultat :

Configurer une fabrique de filtres

ConfigureFilter configure la fabrique spécifiée pour appliquer des filtres à toutes les pages Razor.

L’exemple d’application illustre l’utilisation d’une fabrique de filtres en ajoutant un en-tête, FilterFactoryHeader, et deux valeurs aux pages de l’application :

options.Conventions.ConfigureFilter(new AddHeaderWithFactory());

AddHeaderWithFactory.cs:

public class AddHeaderWithFactory : IFilterFactory
{
    // Implement IFilterFactory
    public IFilterMetadata CreateInstance(IServiceProvider serviceProvider)
    {
        return new AddHeaderFilter();
    }

    private class AddHeaderFilter : IResultFilter
    {
        public void OnResultExecuting(ResultExecutingContext context)
        {
            context.HttpContext.Response.Headers.Add(
                "FilterFactoryHeader", 
                new string[] 
                { 
                    "Filter Factory Header Value 1",
                    "Filter Factory Header Value 2"
                });
        }

        public void OnResultExecuted(ResultExecutedContext context)
        {
        }
    }

    public bool IsReusable
    {
        get
        {
            return false;
        }
    }
}

Demandez la page About de l’exemple sur localhost:5000/About et examinez les en-têtes pour voir le résultat :

Filtres MVC et filtre de page (IPageFilter)

Les filtres d’action MVC sont ignorés par les Razor Pages, car les Razor Pages utilise des méthodes de gestionnaire. Vous pouvez utiliser d’autres types de filtre MVC : Autorisation, Exception, Ressource et Résultat. Pour plus d’informations, consultez la rubrique Filtres.

Le filtre page (IPageFilter) est un filtre qui s’applique à Razor Pages. Pour plus d’informations, consultez méthodes de filtres pour Razor Pages.

Ressources supplémentaires

• Routage de Razor Pages
• Conventions des autorisations de Razor Pages dans ASP.NET Core
• Zones dans ASP.NET Core