Partage via


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
Ajouter un modèle de route et un en-tête aux pages d’une application.
Conventions d’actions de routage de pages Ajouter un modèle de route aux pages d’un dossier et à une page unique.
Conventions d’actions de modèle de page 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 :

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 :

The About page is requested with a route segment of GlobalRouteValue. The rendered page shows that the route data value is captured in the OnGet method of the page.

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 :

Response headers of the About page show that the GlobalHeader has been added.

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 :

Page1 in the OtherPages folder is requested with a route segment of GlobalRouteValue and OtherPagesRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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 :

About page is requested with route segments for GlobalRouteValue and AboutRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the 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?}

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 :

Sample app Contact link in the navigation bar

Inspecting the Contact link in the rendered HTML indicates that the href is set to '/TheContactPage'

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 :

Edge browser example of supplying an optional 'text' route segment of 'TextValue' in the URL. The rendered page shows the 'text' segment value.

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 :

Response headers of the OtherPages/Page1 page show that the OtherPagesHeader has been added.

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 :

Response headers of the About page show that the AboutHeader has been added.

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 :

The OtherPagesPage2Header is added to the response for Page2.

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 :

Response headers of the About page show that two FilterFactoryHeader headers have been added.

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

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.

Quand vous devez configurer des routages de pages personnalisés pour des pages individuelles, configurez le routage vers les pages avec la convention AddPageRoute décrite plus loin dans cette rubrique.

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 Razor Pages sont configurées à l’aide d’une surcharge AddRazorPages qui configure RazorPagesOptions dans Startup.ConfigureServices. Les exemples de convention suivants sont expliqués plus loin dans cette rubrique :

public void ConfigureServices(IServiceCollection services)
{
    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).

JSON 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 ajoute un modèle de routage {globalTemplate?} à toutes les pages de l’application :

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 la rubrique. L’itinéraire de la page Contact a un ordre par défaut de null (Order = 0), et correspond donc avant le modèle d’itinéraire {globalTemplate?}.
  • Un modèle d’itinéraire {aboutTemplate?} est ajouté plus loin dans la rubrique. 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.
  • Un modèle d’itinéraire {otherPagesTemplate?} est ajouté plus loin dans la rubrique. Le modèle {otherPagesTemplate?} reçoit l’ordre Order avec la valeur 2. 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é.

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

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

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

The About page is requested with a route segment of GlobalRouteValue. The rendered page shows that the route data value is captured in the OnGet method of the page.

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" }));
    }
}

Startup.cs:

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

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

Response headers of the About page show that the GlobalHeader has been added.

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
    }
}

Startup.cs:

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

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 :

Page1 in the OtherPages folder is requested with a route segment of GlobalRouteValue and OtherPagesRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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:5000/About/GlobalRouteValue/AboutRouteValue et examinez le résultat :

About page is requested with route segments for GlobalRouteValue and AboutRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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

Les itinéraires de page générés par ASP.NET Core peuvent être personnalisés à l’aide d’un transformateur de paramètres. Un transformateur de paramètre implémente IOutboundParameterTransformer et transforme la valeur des paramètres. Par exemple, un transformateur de paramètre SlugifyParameterTransformer personnalisé transforme la valeur de la route SubscriptionManagement en subscription-management.

La convention de modèle d’itinéraire de page PageRouteTransformerConvention applique un transformateur de paramètres aux segments de noms de dossiers et de noms de fichiers des itinéraires de page générés automatiquement dans une application. Par exemple, le fichier Razor Pages sur /Pages/SubscriptionManagement/ViewAll.cshtml serait réécrit de /SubscriptionManagement/ViewAll vers /subscription-management/view-all.

PageRouteTransformerConvention transforme uniquement les segments générés automatiquement d’un itinéraire de page provenant du nom de dossier et de fichier Razor Pages. Elle ne transforme pas les segments de routage ajoutés avec la directive @page. La convention ne transforme pas non plus les itinéraires ajoutés par AddPageRoute.

PageRouteTransformerConvention est inscrit en tant qu’option dans Startup.ConfigureServices :

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages(options =>
    {
        options.Conventions.Add(
            new PageRouteTransformerConvention(
                new SlugifyParameterTransformer()));
    });
}
public class SlugifyParameterTransformer : IOutboundParameterTransformer
{
    public string TransformOutbound(object value)
    {
        if (value == null) { return null; }

        return Regex.Replace(value.ToString(),
                             "([a-z])([A-Z])",
                             "$1-$2",
                             RegexOptions.CultureInvariant,
                             TimeSpan.FromMilliseconds(100)).ToLowerInvariant();
    }
}

Avertissement

Lorsque vous utilisez System.Text.RegularExpressions pour traiter une entrée non approuvée, passez un délai d’expiration. Un utilisateur malveillant peut fournir une entrée à RegularExpressions, provoquant une attaque par déni de service. Les API d’infrastructure ASP.NET Core qui utilisent RegularExpressions passent un délai d’expiration.

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 que vous avez spécifié. AddPageRoute utilise AddPageRouteModelConvention pour établir le routage.

L’exemple d’application crée un itinéraire vers /TheContactPage pour Contact.cshtml :

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

La page Contact est également accessible sur /Contact 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 :

Sample app Contact link in the navigation bar

Inspecting the Contact link in the rendered HTML indicates that the href is set to '/TheContactPage'

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 :

Edge browser example of supplying an optional 'text' route segment of 'TextValue' in the URL. The rendered page shows the 'text' segment value.

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 :

Response headers of the OtherPages/Page1 page show that the OtherPagesHeader has been added.

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 :

Response headers of the About page show that the AboutHeader has been added.

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 :

The OtherPagesPage2Header is added to the response for Page2.

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 :

Response headers of the About page show that two FilterFactoryHeader headers have been added.

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

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.

Quand vous devez configurer des routages de pages personnalisés pour des pages individuelles, configurez le routage vers les pages avec la convention AddPageRoute décrite plus loin dans cette rubrique.

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 Razor Pages sont ajoutées et configurées à l’aide de la méthode d’extension AddRazorPagesOptions pour AddMvc sur la collection de services dans la classe Startup. Les exemples de convention suivants sont expliqués plus loin dans cette rubrique :

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddRazorPagesOptions(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).

JSON 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 ajoute un modèle de routage {globalTemplate?} à toutes les pages de l’application :

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 la rubrique. L’itinéraire de la page Contact a un ordre par défaut de null (Order = 0), et correspond donc avant le modèle d’itinéraire {globalTemplate?}.
  • Un modèle d’itinéraire {aboutTemplate?} est ajouté plus loin dans la rubrique. 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.
  • Un modèle d’itinéraire {otherPagesTemplate?} est ajouté plus loin dans la rubrique. Le modèle {otherPagesTemplate?} reçoit l’ordre Order avec la valeur 2. 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é.

Les options Razor Pages, comme l’ajout de Conventions, sont ajoutées au moment de l’ajout de MVC à la collection de services dans Startup.ConfigureServices. Pour obtenir un exemple, consultez l’exemple d’application.

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

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

The About page is requested with a route segment of GlobalRouteValue. The rendered page shows that the route data value is captured in the OnGet method of the page.

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" }));
    }
}

Startup.cs:

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

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

Response headers of the About page show that the GlobalHeader has been added.

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
    }
}

Startup.cs:

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

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 :

Page1 in the OtherPages folder is requested with a route segment of GlobalRouteValue and OtherPagesRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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:5000/About/GlobalRouteValue/AboutRouteValue et examinez le résultat :

About page is requested with route segments for GlobalRouteValue and AboutRouteValue. The rendered page shows that the route data values are captured in the OnGet method of the page.

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 que vous avez spécifié. AddPageRoute utilise AddPageRouteModelConvention pour établir le routage.

L’exemple d’application crée un itinéraire vers /TheContactPage pour Contact.cshtml :

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

La page Contact est également accessible sur /Contact 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 :

Sample app Contact link in the navigation bar

Inspecting the Contact link in the rendered HTML indicates that the href is set to '/TheContactPage'

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 :

Edge browser example of supplying an optional 'text' route segment of 'TextValue' in the URL. The rendered page shows the 'text' segment value.

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 :

Response headers of the OtherPages/Page1 page show that the OtherPagesHeader has been added.

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 :

Response headers of the About page show that the AboutHeader has been added.

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 :

The OtherPagesPage2Header is added to the response for Page2.

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 :

Response headers of the About page show that two FilterFactoryHeader headers have been added.

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