Razor Routage des pages et conventions d’application dans ASP.NET Core

Découvrez comment utiliser des conventions de fournisseur de routage de page et de modèle d’application pour contrôler le routage des pages, la découverte et le traitement dans les Razor applications 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 de @page 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.

Afficher ou télécharger un exemple de code (comment télécharger)

Scenario	L’exemple illustre
Conventions de modèle Conventions.Add IPageRouteModelConvention IPageApplicationModelConvention IPageHandlerModelConvention	Ajoutez un modèle de routage et un en-tête aux pages d’une application.
Conventions d’action de routage de page AddFolderRouteModelConvention AddPageRouteModelConvention AddPageRoute	Ajoutez un modèle d’itinéraire aux pages d’un dossier et à une seule page.
Conventions d’action du modèle de page AddFolderApplicationModelConvention AddPageApplicationModelConvention ConfigureFilter (classe de filtre, expression lambda ou fabrique de filtre)	Ajoutez un en-tête aux pages d’un dossier, ajoutez un en-tête à une page unique et configurez une fabrique de filtre pour ajouter un en-tête aux pages d’une application.

Razor Les conventions de pages sont configurées à l’aide d’une AddRazorPages surcharge permettant de configurer 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 de routage

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

Ordre de routage	Behavior
-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) entraîne l’itinéraire Order à être défini par défaut sur 0 (zéro) 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 les mêmes Order paramètres 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 au PageConventionCollection.

Évitez, si possible, de dépendre d'un ordre de traitement d'itinéraires établi. En règle générale, le routage sélectionne l’itinéraire approprié avec la correspondance d’URL. Si vous devez définir correctement les propriétés de routage pour acheminer Order 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 pratique de définir l’itinéraire Order dans les applications de production.

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

Conventions de modèle

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

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

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

L’exemple d’application contient la GlobalTemplatePageRouteModelConvention classe pour ajouter un {globalTemplate?} modèle de routage à 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 :

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

Razor Les options de Pages, telles que l’ajout de Conventions, sont ajoutées lorsque Razor Pages est ajouté à 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 Order propriété de l’objet AttributeRouteModel est définie sur 1. Cela garantit le comportement de correspondance des routes suivant dans l'application d'exemple :

• 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 (nullOrder = 0), il correspond donc avant le modèle d’itinéraire {globalTemplate?} qui a Order = 1.

• Le {aboutTemplate?} modèle d’itinéraire est affiché dans le code précédent. Le {aboutTemplate?} modèle est doté d'un Order de 2. Lorsque la page About est demandée à l’adresse /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 Order propriété.

• Le {otherPagesTemplate?} modèle d’itinéraire est affiché dans le code précédent. Le {otherPagesTemplate?} modèle est doté d'un Order de 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 "xyz" des données de routage est chargée dans RouteData.Values["globalTemplate"] (Order = 1).

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

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

Demandez la page de l'échantillon à Aboutlocalhost:{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. En utilisant localhost:{port}/About/GlobalRouteValue, le journal affiche la requête, le 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 un IPageApplicationModelConvention à la collection d’instances de IPageConvention qui sont appliquées lors de la construction du modèle d'application de la page.

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

L’exemple d’application utilise la AddHeaderAttribute classe 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 À propos de l’exemple à localhost:{port}/About et inspectez les en-têtes afin de voir le résultat :

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

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

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

Conventions d’action de routage de page

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

Convention du modèle de routage de dossiers

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

L’exemple d’application utilise AddFolderRouteModelConvention pour ajouter un modèle d’itinéraire {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 Order propriété de l’objet AttributeRouteModel est définie sur 2. Cela garantit que le modèle pour {globalTemplate?} (défini précédemment dans la rubrique 1) est prioritaire pour la première position de valeur de données de routage lorsqu’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 Order propriété.

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

Demandez la page Page1 de l'échantillon à localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue et inspectez le résultat :

Convention du modèle de routage de page

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

L’exemple d’application utilise AddPageRouteModelConvention pour ajouter un modèle de {aboutTemplate?} routage à 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 Order propriété de l’objet AttributeRouteModel est définie sur 2. Cela garantit que le modèle pour {globalTemplate?} (défini précédemment dans la rubrique 1) est prioritaire pour la première position de valeur de données de routage lorsqu’une valeur de routage unique est fournie. Si la page About est demandée avec une valeur de paramètre de routage à l’adresse /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 Order propriété.

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

Sollicitez la page À propos de l'exemple à localhost:{port}/About/GlobalRouteValue/AboutRouteValue et inspectez le résultat :

La page 'À propos' est demandée avec des segments de route pour GlobalRouteValue et AboutRouteValue. La page rendue montre que les valeurs des données de route sont capturées dans la méthode OnGet de la page.

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

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

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

Voir transformateurs de paramètres.

Configurer un itinéraire de page

Utilisez AddPageRoute pour configurer une route vers une page au chemin d’accès spécifié. Les liens générés vers la page utilisent l’itinéraire spécifié. AddPageRoute utilise AddPageRouteModelConvention pour établir l’itinéraire.

L'exemple d'application crée un itinéraire vers la page /TheContactPageContactRazor.

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

La Contact page peut également être accessible à l’adresse /Contact1 par le biais de son itinéraire par défaut.

L’itinéraire personnalisé de l’exemple d’application vers la Contact page autorise un segment de routage facultatif text ({text?}). La page inclut également ce segment facultatif dans sa @page directive au cas où le visiteur accède à la page à son /Contact itinéraire :

@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 rendue reflète l’itinéraire mis à jour :

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

Conventions d’action du modèle de page

Le fournisseur de modèles de page par défaut qui implémente IPageApplicationModelProvider invoque des conventions conçues pour fournir des points d'extensibilité pour la configuration des modèles de page. Ces conventions sont utiles lors de la création et de 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 AddHeaderAttribute classe, qui est un ResultFilterAttribute, 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 du modèle d'application de dossier

Utilisez AddFolderApplicationModelConvention pour créer et ajouter un IPageApplicationModelConvention qui déclenche une action sur les instances de PageApplicationModel pour toutes les pages sous le dossier spécifié.

L’exemple illustre l’utilisation de AddFolderApplicationModelConvention en ajoutant un en-tête, OtherPagesHeader, aux pages du dossier OtherPages de l’application :

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

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

Convention du modèle d’application de page

Utilisez AddPageApplicationModelConvention pour créer et ajouter un IPageApplicationModelConvention qui exécute une action sur 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 À propos :

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

Demandez la page À propos de l’exemple à localhost:5000/About et inspectez les en-têtes afin de voir le résultat :

Configurer un filtre

ConfigureFilter configure le filtre spécifié à appliquer. Vous pouvez implémenter une classe de filtre, mais l’exemple d’application montre comment implémenter un filtre dans une expression lambda, qui est implémentée en arrière-plan comme une factory qui renvoie 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 remplie, un en-tête est ajouté. Si ce n'est pas le cas, EmptyFilter est appliqué.

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

Demandez la page Page2 de l’exemple à localhost:5000/OtherPages/Page2 et inspectez 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 Razor pages.

L’exemple d’application fournit un exemple d’utilisation d’une fabrique de filtres en ajoutant un en-tête, FilterFactoryHeaderavec 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 À propos de l’exemple à localhost:5000/About et inspectez les en-têtes afin de 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 utilisent des méthodes de gestionnaire. D’autres types de filtres MVC sont disponibles pour vous permettre d’utiliser : autorisation, exception, ressource et résultat. Pour plus d’informations, consultez la rubrique Filtres .

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

Ressources supplémentaires

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