Compartir a través de

Razor Enrutamiento de páginas y convenciones de aplicación en ASP.NET Core

Obtenga información sobre cómo usar las convenciones del proveedor de modelos de aplicación y ruta de página para controlar el enrutamiento, la detección y el procesamiento de páginas en Razor aplicaciones de Pages.

Para especificar una ruta de página, agregar segmentos de ruta o añadir parámetros a una ruta, utilice la directiva @page de la página. Para obtener más información, consulte Rutas personalizadas.

Hay palabras reservadas que no se pueden usar como segmentos de ruta o nombres de parámetro. Para obtener más información, vea Enrutamiento: nombres de enrutamiento reservados.

Consulta o descarga el código de ejemplo (cómo descargarlo)

Scenario El ejemplo demuestra
Convenciones de modelo

Conventions.Add		 Agregue una plantilla de ruta y un encabezado a las páginas de una aplicación.
Convenciones de acción de ruta de página Agregue una plantilla de ruta a las páginas de una carpeta y a una sola página.
Convenciones de acción del modelo de página Agregue un encabezado a las páginas de una carpeta, agregue un encabezado a una sola página y configure un generador de filtros para agregar un encabezado a las páginas de una aplicación.

Razor Las convenciones de páginas se configuran mediante una AddRazorPages sobrecarga que configura RazorPagesOptions. Los ejemplos de convención siguientes se explican más adelante en este tema:


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( ... );
    });
}

Orden de ruta

Las rutas especifican un Order para el procesamiento (coincidencia de rutas).

Orden de ruta Behavior
-1 La ruta se procesa antes de procesar otras rutas.
0 El orden no se especifica (valor predeterminado). No asignar Order (Order = null) establece la ruta Order por defecto a 0 (cero) para su procesamiento.
1, 2, … n Especifica el orden de procesamiento de rutas.

El procesamiento de rutas se establece por convención:

  • Las rutas se procesan en orden secuencial (-1, 0, 1, 2, ... n).
  • Cuando las rutas tienen el mismo Order, la ruta más específica coincide primero seguida de rutas menos específicas.
  • Cuando las rutas con el mismo Order y el mismo número de parámetros coinciden con una dirección URL de solicitud, las rutas se procesan en el orden en que se agregan a .PageConventionCollection

Si es posible, evite depender de un orden establecido de procesamiento de rutas. Por lo general, el enrutamiento selecciona la ruta correcta con la coincidencia de direcciones URL. Si debe establecer propiedades de ruta Order para enrutar las solicitudes correctamente, es probable que el esquema de enrutamiento de la aplicación sea confuso para los clientes y frágil para mantener. Busque simplificar el esquema de enrutamiento de la aplicación. La aplicación de ejemplo requiere un orden de procesamiento de rutas explícito para mostrar varios escenarios de enrutamiento mediante una sola aplicación. Sin embargo, debe intentar evitar la práctica de establecer la ruta Order en aplicaciones de producción.

Razor El enrutamiento de páginas y el enrutamiento del controlador MVC comparten una implementación. La información sobre el orden de ruta en los temas de MVC está disponible en Enrutamiento a acciones de controlador: Ordenar rutas de atributo.

Convenciones de modelo

Agregue un delegado para IPageConvention a fin de añadir convenciones de modelo que se aplican a las Razor Páginas.

Adición de una convención de modelo de ruta a todas las páginas

Use Conventions para crear y agregar un IPageRouteModelConvention a la colección de instancias de IPageConvention que se aplican durante la construcción del modelo de ruta de página.

La aplicación de ejemplo contiene la GlobalTemplatePageRouteModelConvention clase para agregar una {globalTemplate?} plantilla de ruta a todas las páginas de la aplicación:

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

En el código anterior:

Razor Las opciones de páginas, como agregar Conventions, se agregan cuando Razor se agrega Pages a la colección de servicios. Para obtener un ejemplo, consulte la aplicación de ejemplo.

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();

Considere la clase 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 propiedad de AttributeRouteModel se establece 1en . Esto garantiza el siguiente comportamiento de coincidencia de rutas en la aplicación de ejemplo:

  • Más adelante en este tema, se agrega una plantilla de ruta para TheContactPage/{text?}. La Contact Page ruta tiene un orden predeterminado de null (Order = 0), por lo que coincide con antes de la {globalTemplate?} plantilla de ruta que tiene Order = 1.

  • La {aboutTemplate?} plantilla de ruta se muestra en el código anterior. A la {aboutTemplate?} plantilla se le asigna un Order valor de 2. Cuando se solicita la página Acerca de en /About/RouteDataValue, "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["aboutTemplate"] (Order = 2) debido a la configuración de la Order propiedad .

  • La {otherPagesTemplate?} plantilla de ruta se muestra en el código anterior. A la {otherPagesTemplate?} plantilla se le asigna un Order valor de 2. Cuando se solicita cualquier página de la carpeta Pages/OtherPages con un parámetro de ruta:

  • Por ejemplo: /OtherPages/Page1/xyz

  • El valor "xyz" de datos de ruta se carga en RouteData.Values["globalTemplate"] (Order = 1).

  • RouteData.Values["otherPagesTemplate"] con (Order = 2) no se carga debido a que la Order propiedad 2 tiene un valor mayor.

Cuando sea posible, no establezca el Order Cuando Order no se establece, el valor predeterminado es Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta en lugar de la Order propiedad .

Solicite la página del About ejemplo en localhost:{port}/About/GlobalRouteValue e inspeccione el resultado:

La página Acerca de se solicita con un segmento de ruta de GlobalRouteValue. La página representada muestra que el valor de los datos de ruta se captura en el método OnGet de la página.

La aplicación de ejemplo usa el paquete NuGet Rick.Docs.Samples.RouteInfo para mostrar información de enrutamiento en la salida del registro. Con localhost:{port}/About/GlobalRouteValue, el registrador muestra la solicitud, Order, y la plantilla usada:

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

Adición de una convención de modelo de aplicación a todas las páginas

Use Conventions para crear y agregar un IPageApplicationModelConvention a la colección de IPageConvention instancias que se aplican durante la construcción del modelo de la aplicación de página.

Para demostrar esto y otras convenciones más adelante en el tema, la aplicación de ejemplo incluye una AddHeaderAttribute clase . El constructor de clase acepta una name cadena y una values matriz de cadenas. Estos valores se usan en su OnResultExecuting método para establecer un encabezado de respuesta. La clase completa se muestra en la sección Convenciones de acción del modelo de página más adelante en el tema.

La aplicación de ejemplo usa la AddHeaderAttribute clase para agregar un encabezado, GlobalHeader, a todas las páginas de la aplicación:

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());

Solicite la página Acerca del ejemplo en localhost:{port}/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se ha añadido el GlobalHeader.

Adición de una convención de modelo de controlador a todas las páginas

Use Conventions para crear y agregar un IPageHandlerModelConvention a la colección de instancias de IPageConvention que se aplican durante la construcción del modelo del controlador de páginas.

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

Convenciones de acción en rutas de página

El proveedor de modelo de ruta predeterminado que se deriva de IPageRouteModelProvider invoca convenciones diseñadas para ofrecer puntos de extensibilidad para configurar las rutas de página.

Convención del modelo de ruta de carpetas

Use AddFolderRouteModelConvention para crear y agregar un IPageRouteModelConvention que invoque una acción en el PageRouteModel para todas las páginas de la carpeta especificada.

La aplicación de ejemplo usa AddFolderRouteModelConvention para agregar una {otherPagesTemplate?} plantilla de ruta a las páginas de la carpeta 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 propiedad de AttributeRouteModel se establece 2en . Esto garantiza que la plantilla de {globalTemplate?} (establecida anteriormente en el tema en 1) tenga prioridad para la primera posición del valor de datos de ruta cuando se proporciona un único valor de ruta. Si se solicita una página en la carpeta Pages/OtherPages con un valor de parámetro de ruta (por ejemplo, /OtherPages/Page1/RouteDataValue), "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["otherPagesTemplate"] (Order = 2) debido a la configuración de la Order propiedad .

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Solicite la página Page1 del ejemplo en localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue e inspeccione el resultado:

Página1 en la carpeta OtherPages se solicita con un segmento de ruta de GlobalRouteValue y OtherPagesRouteValue. La página que se muestra indica que los valores de los datos de ruta se capturan en el método OnGet de la página.

Convención del modelo de ruta de página

Use AddPageRouteModelConvention para crear y agregar un IPageRouteModelConvention que invoque una acción para PageRouteModel la página con el nombre especificado.

La aplicación de ejemplo usa AddPageRouteModelConvention para agregar una {aboutTemplate?} plantilla de ruta a la página 'Acerca de':

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 propiedad de AttributeRouteModel se establece 2en . Esto garantiza que la plantilla de {globalTemplate?} (establecida anteriormente en el tema en 1) tenga prioridad para la primera posición del valor de datos de ruta cuando se proporciona un único valor de ruta. Si se solicita la página acerca de con un valor de parámetro de ruta en /About/RouteDataValue, "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no en RouteData.Values["aboutTemplate"] (Order = 2) debido a la propiedad Order establecida.

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Solicite la página Acerca del ejemplo en localhost:{port}/About/GlobalRouteValue/AboutRouteValue e inspeccione el resultado:

La página 'Acerca de' se solicita utilizando segmentos de ruta para GlobalRouteValue y AboutRouteValue. La página renderizada muestra que los valores de los datos de ruta se capturan en el método OnGet de la página.

La salida del registrador muestra:

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

Uso de un transformador de parámetros para personalizar rutas de página

Consulte Transformadores de parámetros.

Configuración de una ruta de página

Use AddPageRoute para configurar una ruta hacia una página en la ruta especificada de la página. Los vínculos generados a la página usan la ruta especificada. AddPageRoute usa AddPageRouteModelConvention para establecer la ruta.

La aplicación de ejemplo crea una ruta a /TheContactPage para la ContactRazor página:

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

También se puede acceder a la Contact página en /Contact1' a través de su ruta predeterminada.

La ruta personalizada de la aplicación de ejemplo hacia la página Contact permite un segmento de ruta opcional text ({text?}). La página también incluye este segmento opcional en su @page directiva en caso de que el visitante acceda a la página en su /Contact ruta:

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

Tenga en cuenta que la dirección URL generada para el vínculo Contacto en la página representada refleja la ruta actualizada:

Vínculo de contacto de la aplicación de ejemplo en la barra de navegación

Inspeccionar el vínculo Contacto en el HTML representado indica que href está establecido en

Visite la Contact página en su ruta normal, /Contacto en la ruta personalizada, /TheContactPage. Si proporciona un segmento de ruta adicional text , la página muestra el segmento codificado en HTML que se proporciona:

Ejemplo del explorador Edge de proporcionar un segmento de ruta opcional

Convenciones de acción del modelo de página

El proveedor de modelos de página predeterminado que implementa IPageApplicationModelProvider invoca convenciones diseñadas para proporcionar puntos de extensibilidad para configurar modelos de página. Estas convenciones son útiles al compilar y modificar escenarios de procesamiento y detección de páginas.

Para los ejemplos de esta sección, la aplicación de ejemplo utiliza una clase AddHeaderAttribute, que es un ResultFilterAttribute, que aplica un encabezado de respuesta.

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

Usando convenciones, el ejemplo demuestra cómo aplicar el atributo a todas las páginas de una carpeta y a una página individual.

Convención del modelo de aplicación de carpetas

Use AddFolderApplicationModelConvention para crear y añadir un IPageApplicationModelConvention que invoque una acción en las instancias de PageApplicationModel para todas las páginas de la carpeta especificada.

En el ejemplo se muestra el uso de AddFolderApplicationModelConvention agregando un encabezado, OtherPagesHeader, a las páginas dentro de la carpeta OtherPages de la aplicación:

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

Solicite la página Page1 del ejemplo en localhost:5000/OtherPages/Page1 e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página OtherPages/Page1 muestran que se ha agregado OtherPagesHeader.

Convención de modelo de aplicación de página

Use AddPageApplicationModelConvention para crear y agregar un IPageApplicationModelConvention que invoque una acción para PageApplicationModel la página con el nombre especificado.

En el ejemplo se muestra el uso de AddPageApplicationModelConvention agregando un encabezado , AboutHeadera la página Acerca de:

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

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se ha agregado AboutHeader.

Configuración de un filtro

ConfigureFilter configura el filtro especificado que se va a aplicar. Puede implementar una clase de filtro, pero la aplicación de ejemplo muestra cómo implementar un filtro en una expresión lambda, que se implementa en segundo plano como un generador que devuelve un filtro:

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

El modelo de aplicación de páginas se usa para comprobar la ruta de acceso relativa para los segmentos que conducen a la página Page2 de la carpeta OtherPages. Si la condición se cumple, se agrega un encabezado. Si no es así, se aplica EmptyFilter.

EmptyFilter es un filtro de acción. Dado que los filtros de acción son ignorados por Razor Pages, EmptyFilter no surte el efecto previsto si la ruta no contiene OtherPages/Page2.

Solicite la página Page2 del ejemplo en localhost:5000/OtherPages/Page2 e inspeccione los encabezados para ver el resultado:

OtherPagesPage2Header se agrega a la respuesta de Page2.

Configuración de un generador de filtros

ConfigureFilterconfigura el generador especificado para aplicar filtros a todas las RazorPáginas.

La aplicación de ejemplo proporciona un ejemplo de uso de un generador de filtros agregando un encabezado, FilterFactoryHeader, con dos valores a las páginas de la aplicación:

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

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se han agregado dos encabezados FilterFactoryHeader.

Filtros MVC y filtro de página (IPageFilter)

Pages omite Razor de MVC, ya que Razor Pages usa métodos de controlador. Hay otros tipos de filtros de MVC disponibles para su uso: Autorización, Excepción, Recurso y Resultado. Para obtener más información, consulte el tema Filtros .

El filtro Página (IPageFilter) es un filtro que se aplica a Razor Pages. Para obtener más información, vea Métodos de filtrado de Razor Pages.

Recursos adicionales

Obtenga información sobre cómo usar las convenciones del proveedor de modelos de aplicación y ruta de página para controlar el enrutamiento, la detección y el procesamiento de páginas en Razor aplicaciones de Pages.

Cuando necesite configurar rutas de página personalizadas para páginas individuales, configure el enrutamiento a páginas con la convención AddPageRoute descrita más adelante en este tema.

Para especificar una ruta de página, agregar segmentos de ruta o añadir parámetros a una ruta, utilice la directiva @page de la página. Para obtener más información, consulte Rutas personalizadas.

Hay palabras reservadas que no se pueden usar como segmentos de ruta o nombres de parámetro. Para obtener más información, vea Enrutamiento: nombres de enrutamiento reservados.

Consulta o descarga el código de ejemplo (cómo descargarlo)

Scenario En el ejemplo se muestra ...
Convenciones de modelo

Conventions.Add
  • IPageRouteModelConvention
  • IPageApplicationModelConvention
  • IPageHandlerModelConvention
 Agregue una plantilla de ruta y un encabezado a las páginas de una aplicación.
Convenciones de acción de ruta de página
  • AddFolderRouteModelConvention
  • AddPageRouteModelConvention
  • AddPageRoute
 Agregue una plantilla de ruta a las páginas de una carpeta y a una sola página.
Convenciones de acción del modelo de página
  • AddFolderApplicationModelConvention
  • AddPageApplicationModelConvention
  • ConfigureFilter (clase de filtro, expresión lambda o generador de filtros)
 Agregue un encabezado a las páginas de una carpeta, agregue un encabezado a una sola página y configure un generador de filtros para agregar un encabezado a las páginas de una aplicación.

Razor Las convenciones de páginas se configuran mediante una AddRazorPages sobrecarga que configura RazorPagesOptions en Startup.ConfigureServices. Los ejemplos de convención siguientes se explican más adelante en este tema:

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( ... );
    });
}

Orden de ruta

Las rutas especifican un Order para el procesamiento (coincidencia de rutas).

Order Behavior
-1 La ruta se procesa antes de procesar otras rutas.
0 El orden no se especifica (valor predeterminado). No asignar Order (Order = null) establece la ruta Order por defecto a 0 (cero) para su procesamiento.
1, 2, … n Especifica el orden de procesamiento de rutas.

El procesamiento de rutas se establece por convención:

  • Las rutas se procesan en orden secuencial (-1, 0, 1, 2, ... n).
  • Cuando las rutas tienen el mismo Order, la ruta más específica coincide primero seguida de rutas menos específicas.
  • Cuando las rutas con el mismo Order y el mismo número de parámetros coinciden con una dirección URL de solicitud, las rutas se procesan en el orden en que se agregan a .PageConventionCollection

Si es posible, evite depender de un orden establecido de procesamiento de rutas. Por lo general, el enrutamiento selecciona la ruta correcta con la coincidencia de direcciones URL. Si debe establecer propiedades de ruta Order para enrutar las solicitudes correctamente, es probable que el esquema de enrutamiento de la aplicación sea confuso para los clientes y frágil para mantener. Busque simplificar el esquema de enrutamiento de la aplicación. La aplicación de ejemplo requiere un orden de procesamiento de rutas explícito para mostrar varios escenarios de enrutamiento mediante una sola aplicación. Sin embargo, debe intentar evitar la práctica de establecer la ruta Order en aplicaciones de producción.

Razor El enrutamiento de páginas y el enrutamiento del controlador MVC comparten una implementación. La información sobre el orden de ruta en los temas de MVC está disponible en Enrutamiento a acciones de controlador: Ordenar rutas de atributo.

Convenciones de modelo

Agregue un delegado para IPageConvention a fin de añadir convenciones de modelo que se aplican a las Razor Páginas.

Adición de una convención de modelo de ruta a todas las páginas

Use Conventions para crear y agregar un IPageRouteModelConvention a la colección de instancias de IPageConvention que se aplican durante la construcción del modelo de ruta de página.

La aplicación de ejemplo agrega una {globalTemplate?} plantilla de ruta a todas las páginas de la aplicación:

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 propiedad de AttributeRouteModel se establece 1en . Esto garantiza el siguiente comportamiento de coincidencia de rutas en la aplicación de ejemplo:

  • Una plantilla de ruta para TheContactPage/{text?} se agrega más adelante en el tema. La ruta de la Página de Contacto tiene un orden predeterminado de null (Order = 0), por lo que coincide antes que la plantilla de ruta {globalTemplate?}.
  • Una plantilla de ruta {aboutTemplate?} se agrega en el tema más adelante. A la {aboutTemplate?} plantilla se le asigna un Order valor de 2. Cuando se solicita la página Acerca de en /About/RouteDataValue, "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["aboutTemplate"] (Order = 2) debido a la configuración de la Order propiedad .
  • Una plantilla de ruta {otherPagesTemplate?} se agrega en el tema más adelante. A la {otherPagesTemplate?} plantilla se le asigna un Order valor de 2. Cuando se solicita cualquier página de la carpeta Pages/OtherPages con un parámetro de ruta (por ejemplo, /OtherPages/Page1/RouteDataValue), "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["otherPagesTemplate"] (Order = 2) debido a la configuración de la Order propiedad .

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Razor Las opciones de Pages, como agregar Conventions, se agregan cuando Razor Pages se agrega a la colección de servicios en Startup.ConfigureServices. Para obtener un ejemplo, consulte la aplicación de ejemplo.

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

Solicite la página Acerca del ejemplo en localhost:5000/About/GlobalRouteValue e inspeccione el resultado:

La página Acerca de se solicita con un segmento de ruta de GlobalRouteValue. La página representada muestra que el valor de los datos de ruta se captura en el método OnGet de la página.

Adición de una convención de modelo de aplicación a todas las páginas

Use Conventions para crear y agregar un IPageApplicationModelConvention a la colección de IPageConvention instancias que se aplican durante la construcción del modelo de la aplicación de página.

Para demostrar esto y otras convenciones más adelante en el tema, la aplicación de ejemplo incluye una AddHeaderAttribute clase . El constructor de clase acepta una name cadena y una values matriz de cadenas. Estos valores se usan en su OnResultExecuting método para establecer un encabezado de respuesta. La clase completa se muestra en la sección Convenciones de acción del modelo de página más adelante en el tema.

La aplicación de ejemplo usa la AddHeaderAttribute clase para agregar un encabezado, GlobalHeader, a todas las páginas de la aplicación:

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());

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se ha añadido el GlobalHeader.

Adición de una convención de modelo de controlador a todas las páginas

Use Conventions para crear y agregar un IPageHandlerModelConvention a la colección de instancias de IPageConvention que se aplican durante la construcción del modelo del controlador de páginas.

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

Startup.cs:

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

Convenciones de acción en rutas de página

El proveedor de modelo de ruta predeterminado que se deriva de IPageRouteModelProvider invoca convenciones diseñadas para ofrecer puntos de extensibilidad para configurar las rutas de página.

Convención del modelo de ruta de carpetas

Use AddFolderRouteModelConvention para crear y agregar un IPageRouteModelConvention que invoque una acción en el PageRouteModel para todas las páginas de la carpeta especificada.

La aplicación de ejemplo usa AddFolderRouteModelConvention para agregar una {otherPagesTemplate?} plantilla de ruta a las páginas de la carpeta 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 propiedad de AttributeRouteModel se establece 2en . Esto garantiza que la plantilla de {globalTemplate?} (establecida anteriormente en el tema en 1) tenga prioridad para la primera posición del valor de datos de ruta cuando se proporciona un único valor de ruta. Si se solicita una página en la carpeta Pages/OtherPages con un valor de parámetro de ruta (por ejemplo, /OtherPages/Page1/RouteDataValue), "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["otherPagesTemplate"] (Order = 2) debido a la configuración de la Order propiedad .

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Solicite la página Page1 del ejemplo en localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue e inspeccione el resultado:

Página1 en la carpeta OtherPages se solicita con un segmento de ruta de GlobalRouteValue y OtherPagesRouteValue. La página que se muestra indica que los valores de los datos de ruta se capturan en el método OnGet de la página.

Convención del modelo de ruta de página

Use AddPageRouteModelConvention para crear y agregar un IPageRouteModelConvention que invoque una acción para PageRouteModel la página con el nombre especificado.

La aplicación de ejemplo usa AddPageRouteModelConvention para agregar una {aboutTemplate?} plantilla de ruta a la página 'Acerca de':

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 propiedad de AttributeRouteModel se establece 2en . Esto garantiza que la plantilla de {globalTemplate?} (establecida anteriormente en el tema en 1) tenga prioridad para la primera posición del valor de datos de ruta cuando se proporciona un único valor de ruta. Si se solicita la página acerca de con un valor de parámetro de ruta en /About/RouteDataValue, "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no en RouteData.Values["aboutTemplate"] (Order = 2) debido a la propiedad Order establecida.

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Solicite la página Acerca del ejemplo en localhost:5000/About/GlobalRouteValue/AboutRouteValue e inspeccione el resultado:

La página 'Acerca de' se solicita utilizando segmentos de ruta para GlobalRouteValue y AboutRouteValue. La página renderizada muestra que los valores de los datos de ruta se capturan en el método OnGet de la página.

Uso de un transformador de parámetros para personalizar rutas de página

Las rutas de página generadas por ASP.NET Core se pueden personalizar mediante un transformador de parámetros. Un transformador de parámetro implementa IOutboundParameterTransformer y transforma el valor de parámetros. Por ejemplo, un transformador de parámetros personalizado SlugifyParameterTransformer cambia el valor de ruta SubscriptionManagement a subscription-management.

La convención del PageRouteTransformerConvention modelo de ruta de página aplica un transformador de parámetros a los segmentos de nombre de archivo y carpeta de rutas de página generadas automáticamente en una aplicación. Por ejemplo, el Razor archivo Pages en /Pages/SubscriptionManagement/ViewAll.cshtml tendría su ruta reescrita de /SubscriptionManagement/ViewAll a /subscription-management/view-all.

PageRouteTransformerConvention solo transforma los segmentos generados automáticamente de una ruta de página que proceden de la carpeta Pages y el Razor nombre de archivo. No transforma los segmentos de ruta agregados con la @page directiva . La convención tampoco transforma las rutas agregadas por AddPageRoute.

PageRouteTransformerConvention se registra como una opción en 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();
    }
}

Warning

Cuando se usa System.Text.RegularExpressions para procesar entradas que no son de confianza, pase un tiempo de expiración. Un usuario malintencionado puede proporcionar entradas a RegularExpressions y provocar un ataque por denegación de servicio. Las API del marco ASP.NET Core en las que se usa RegularExpressions pasan un tiempo de expiración.

Configuración de una ruta de página

Use AddPageRoute para configurar una ruta hacia una página en la ruta especificada de la página. Los vínculos generados a la página usan la ruta especificada. AddPageRoute usa AddPageRouteModelConvention para establecer la ruta.

La aplicación de ejemplo crea una ruta a /TheContactPage para Contact.cshtml:

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

También se puede acceder a la página Contacto a /Contact través de su ruta predeterminada.

La ruta personalizada de la aplicación de ejemplo a la página Contacto permite un segmento de ruta opcional text ({text?}). La página también incluye este segmento opcional en su @page directiva en caso de que el visitante acceda a la página en su /Contact ruta:

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

Tenga en cuenta que la dirección URL generada para el vínculo Contacto en la página representada refleja la ruta actualizada:

Vínculo de contacto de la aplicación de ejemplo en la barra de navegación

Inspeccionar el vínculo Contacto en el HTML representado indica que href está establecido en

Visite la página Contacto en su ruta normal, /Contact, o la ruta personalizada, /TheContactPage. Si proporciona un segmento de ruta adicional text , la página muestra el segmento codificado en HTML que se proporciona:

Ejemplo del explorador Edge de proporcionar un segmento de ruta opcional

Convenciones de acción del modelo de página

El proveedor de modelos de página predeterminado que implementa IPageApplicationModelProvider invoca convenciones diseñadas para proporcionar puntos de extensibilidad para configurar modelos de página. Estas convenciones son útiles al compilar y modificar escenarios de procesamiento y detección de páginas.

Para los ejemplos de esta sección, la aplicación de ejemplo utiliza una clase AddHeaderAttribute, que es un ResultFilterAttribute, que aplica un encabezado de respuesta.

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

Usando convenciones, el ejemplo demuestra cómo aplicar el atributo a todas las páginas de una carpeta y a una página individual.

Convención del modelo de aplicación de carpetas

Use AddFolderApplicationModelConvention para crear y añadir un IPageApplicationModelConvention que invoque una acción en las instancias de PageApplicationModel para todas las páginas de la carpeta especificada.

En el ejemplo se muestra el uso de AddFolderApplicationModelConvention agregando un encabezado, OtherPagesHeader, a las páginas dentro de la carpeta OtherPages de la aplicación:

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

Solicite la página Page1 del ejemplo en localhost:5000/OtherPages/Page1 e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página OtherPages/Page1 muestran que se ha agregado OtherPagesHeader.

Convención de modelo de aplicación de página

Use AddPageApplicationModelConvention para crear y agregar un IPageApplicationModelConvention que invoque una acción para PageApplicationModel la página con el nombre especificado.

En el ejemplo se muestra el uso de AddPageApplicationModelConvention agregando un encabezado , AboutHeadera la página Acerca de:

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

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se ha agregado AboutHeader.

Configuración de un filtro

ConfigureFilter configura el filtro especificado que se va a aplicar. Puede implementar una clase de filtro, pero la aplicación de ejemplo muestra cómo implementar un filtro en una expresión lambda, que se implementa en segundo plano como un generador que devuelve un filtro:

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

El modelo de aplicación de páginas se usa para comprobar la ruta de acceso relativa para los segmentos que conducen a la página Page2 de la carpeta OtherPages. Si la condición se cumple, se agrega un encabezado. Si no es así, se aplica EmptyFilter.

EmptyFilter es un filtro de acción. Dado que los filtros de acción son ignorados por Razor Pages, EmptyFilter no surte el efecto previsto si la ruta no contiene OtherPages/Page2.

Solicite la página Page2 del ejemplo en localhost:5000/OtherPages/Page2 e inspeccione los encabezados para ver el resultado:

OtherPagesPage2Header se agrega a la respuesta de Page2.

Configuración de un generador de filtros

ConfigureFilterconfigura el generador especificado para aplicar filtros a todas las RazorPáginas.

La aplicación de ejemplo proporciona un ejemplo de uso de un generador de filtros agregando un encabezado, FilterFactoryHeader, con dos valores a las páginas de la aplicación:

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

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se han agregado dos encabezados FilterFactoryHeader.

Filtros MVC y filtro de página (IPageFilter)

Pages omite Razor de MVC, ya que Razor Pages usa métodos de controlador. Hay otros tipos de filtros de MVC disponibles para su uso: Autorización, Excepción, Recurso y Resultado. Para obtener más información, consulte el tema Filtros .

El filtro Página (IPageFilter) es un filtro que se aplica a Razor Pages. Para obtener más información, vea Métodos de filtrado de Razor Pages.

Recursos adicionales

Obtenga información sobre cómo usar las convenciones del proveedor de modelos de aplicación y ruta de página para controlar el enrutamiento, la detección y el procesamiento de páginas en Razor aplicaciones de Pages.

Cuando necesite configurar rutas de página personalizadas para páginas individuales, configure el enrutamiento a páginas con la convención AddPageRoute descrita más adelante en este tema.

Para especificar una ruta de página, agregar segmentos de ruta o añadir parámetros a una ruta, utilice la directiva @page de la página. Para obtener más información, consulte Rutas personalizadas.

Hay palabras reservadas que no se pueden usar como segmentos de ruta o nombres de parámetro. Para obtener más información, vea Enrutamiento: nombres de enrutamiento reservados.

Consulta o descarga el código de ejemplo (cómo descargarlo)

Scenario En el ejemplo se muestra ...
Convenciones de modelo

Conventions.Add
  • IPageRouteModelConvention
  • IPageApplicationModelConvention
  • IPageHandlerModelConvention
 Agregue una plantilla de ruta y un encabezado a las páginas de una aplicación.
Convenciones de acción de ruta de página
  • AddFolderRouteModelConvention
  • AddPageRouteModelConvention
  • AddPageRoute
 Agregue una plantilla de ruta a las páginas de una carpeta y a una sola página.
Convenciones de acción del modelo de página
  • AddFolderApplicationModelConvention
  • AddPageApplicationModelConvention
  • ConfigureFilter (clase de filtro, expresión lambda o generador de filtros)
 Agregue un encabezado a las páginas de una carpeta, agregue un encabezado a una sola página y configure un generador de filtros para agregar un encabezado a las páginas de una aplicación.

Razor Las convenciones de páginas se agregan y configuran utilizando el AddRazorPagesOptions método de extensión en AddMvc en la colección de servicios de la Startup clase. Los ejemplos de convención siguientes se explican más adelante en este tema:

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( ... );
        });
}

Orden de ruta

Las rutas especifican un Order para el procesamiento (coincidencia de rutas).

Order Behavior
-1 La ruta se procesa antes de procesar otras rutas.
0 El orden no se especifica (valor predeterminado). No asignar Order (Order = null) establece la ruta Order por defecto a 0 (cero) para su procesamiento.
1, 2, … n Especifica el orden de procesamiento de rutas.

El procesamiento de rutas se establece por convención:

  • Las rutas se procesan en orden secuencial (-1, 0, 1, 2, ... n).
  • Cuando las rutas tienen el mismo Order, la ruta más específica coincide primero seguida de rutas menos específicas.
  • Cuando las rutas con el mismo Order y el mismo número de parámetros coinciden con una dirección URL de solicitud, las rutas se procesan en el orden en que se agregan a .PageConventionCollection

Si es posible, evite depender de un orden establecido de procesamiento de rutas. Por lo general, el enrutamiento selecciona la ruta correcta con la coincidencia de direcciones URL. Si debe establecer propiedades de ruta Order para enrutar las solicitudes correctamente, es probable que el esquema de enrutamiento de la aplicación sea confuso para los clientes y frágil para mantener. Busque simplificar el esquema de enrutamiento de la aplicación. La aplicación de ejemplo requiere un orden de procesamiento de rutas explícito para mostrar varios escenarios de enrutamiento mediante una sola aplicación. Sin embargo, debe intentar evitar la práctica de establecer la ruta Order en aplicaciones de producción.

Razor El enrutamiento de páginas y el enrutamiento del controlador MVC comparten una implementación. La información sobre el orden de ruta en los temas de MVC está disponible en Enrutamiento a acciones de controlador: Ordenar rutas de atributo.

Convenciones de modelo

Agregue un delegado para IPageConvention a fin de añadir convenciones de modelo que se aplican a las Razor Páginas.

Adición de una convención de modelo de ruta a todas las páginas

Use Conventions para crear y agregar un IPageRouteModelConvention a la colección de instancias de IPageConvention que se aplican durante la construcción del modelo de ruta de página.

La aplicación de ejemplo agrega una {globalTemplate?} plantilla de ruta a todas las páginas de la aplicación:

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 propiedad de AttributeRouteModel se establece 1en . Esto garantiza el siguiente comportamiento de coincidencia de rutas en la aplicación de ejemplo:

  • Una plantilla de ruta para TheContactPage/{text?} se agrega más adelante en el tema. La ruta de la Página de Contacto tiene un orden predeterminado de null (Order = 0), por lo que coincide antes que la plantilla de ruta {globalTemplate?}.
  • Una plantilla de ruta {aboutTemplate?} se agrega en el tema más adelante. A la {aboutTemplate?} plantilla se le asigna un Order valor de 2. Cuando se solicita la página Acerca de en /About/RouteDataValue, "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["aboutTemplate"] (Order = 2) debido a la configuración de la Order propiedad .
  • Una plantilla de ruta {otherPagesTemplate?} se agrega en el tema más adelante. A la {otherPagesTemplate?} plantilla se le asigna un Order valor de 2. Cuando se solicita cualquier página de la carpeta Pages/OtherPages con un parámetro de ruta (por ejemplo, /OtherPages/Page1/RouteDataValue), "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["otherPagesTemplate"] (Order = 2) debido a la configuración de la Order propiedad .

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Razor Las opciones de páginas, como agregar Conventions, se agregan cuando se agrega MVC a la colección de servicios en Startup.ConfigureServices. Para obtener un ejemplo, consulte la aplicación de ejemplo.

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

Solicite la página Acerca del ejemplo en localhost:5000/About/GlobalRouteValue e inspeccione el resultado:

La página Acerca de se solicita con un segmento de ruta de GlobalRouteValue. La página representada muestra que el valor de los datos de ruta se captura en el método OnGet de la página.

Adición de una convención de modelo de aplicación a todas las páginas

Use Conventions para crear y agregar un IPageApplicationModelConvention a la colección de IPageConvention instancias que se aplican durante la construcción del modelo de la aplicación de página.

Para demostrar esto y otras convenciones más adelante en el tema, la aplicación de ejemplo incluye una AddHeaderAttribute clase . El constructor de clase acepta una name cadena y una values matriz de cadenas. Estos valores se usan en su OnResultExecuting método para establecer un encabezado de respuesta. La clase completa se muestra en la sección Convenciones de acción del modelo de página más adelante en el tema.

La aplicación de ejemplo usa la AddHeaderAttribute clase para agregar un encabezado, GlobalHeader, a todas las páginas de la aplicación:

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());

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se ha añadido el GlobalHeader.

Adición de una convención de modelo de controlador a todas las páginas

Use Conventions para crear y agregar un IPageHandlerModelConvention a la colección de instancias de IPageConvention que se aplican durante la construcción del modelo del controlador de páginas.

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

Startup.cs:

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

Convenciones de acción en rutas de página

El proveedor de modelo de ruta predeterminado que se deriva de IPageRouteModelProvider invoca convenciones diseñadas para ofrecer puntos de extensibilidad para configurar las rutas de página.

Convención del modelo de ruta de carpetas

Use AddFolderRouteModelConvention para crear y agregar un IPageRouteModelConvention que invoque una acción en el PageRouteModel para todas las páginas de la carpeta especificada.

La aplicación de ejemplo usa AddFolderRouteModelConvention para agregar una {otherPagesTemplate?} plantilla de ruta a las páginas de la carpeta 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 propiedad de AttributeRouteModel se establece 2en . Esto garantiza que la plantilla de {globalTemplate?} (establecida anteriormente en el tema en 1) tenga prioridad para la primera posición del valor de datos de ruta cuando se proporciona un único valor de ruta. Si se solicita una página en la carpeta Pages/OtherPages con un valor de parámetro de ruta (por ejemplo, /OtherPages/Page1/RouteDataValue), "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no RouteData.Values["otherPagesTemplate"] (Order = 2) debido a la configuración de la Order propiedad .

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Solicite la página Page1 del ejemplo en localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue e inspeccione el resultado:

Página1 en la carpeta OtherPages se solicita con un segmento de ruta de GlobalRouteValue y OtherPagesRouteValue. La página que se muestra indica que los valores de los datos de ruta se capturan en el método OnGet de la página.

Convención del modelo de ruta de página

Use AddPageRouteModelConvention para crear y agregar un IPageRouteModelConvention que invoque una acción para PageRouteModel la página con el nombre especificado.

La aplicación de ejemplo usa AddPageRouteModelConvention para agregar una {aboutTemplate?} plantilla de ruta a la página 'Acerca de':

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 propiedad de AttributeRouteModel se establece 2en . Esto garantiza que la plantilla de {globalTemplate?} (establecida anteriormente en el tema en 1) tenga prioridad para la primera posición del valor de datos de ruta cuando se proporciona un único valor de ruta. Si se solicita la página acerca de con un valor de parámetro de ruta en /About/RouteDataValue, "RouteDataValue" se carga en RouteData.Values["globalTemplate"] (Order = 1) y no en RouteData.Values["aboutTemplate"] (Order = 2) debido a la propiedad Order establecida.

Siempre que sea posible, no establezca Order, lo que resulta en Order = 0. Confíe en el enrutamiento para seleccionar la ruta correcta.

Solicite la página Acerca del ejemplo en localhost:5000/About/GlobalRouteValue/AboutRouteValue e inspeccione el resultado:

La página 'Acerca de' se solicita utilizando segmentos de ruta para GlobalRouteValue y AboutRouteValue. La página renderizada muestra que los valores de los datos de ruta se capturan en el método OnGet de la página.

Configuración de una ruta de página

Use AddPageRoute para configurar una ruta hacia una página en la ruta especificada de la página. Los vínculos generados a la página usan la ruta especificada. AddPageRoute usa AddPageRouteModelConvention para establecer la ruta.

La aplicación de ejemplo crea una ruta a /TheContactPage para Contact.cshtml:

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

También se puede acceder a la página Contacto a /Contact través de su ruta predeterminada.

La ruta personalizada de la aplicación de ejemplo a la página Contacto permite un segmento de ruta opcional text ({text?}). La página también incluye este segmento opcional en su @page directiva en caso de que el visitante acceda a la página en su /Contact ruta:

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

Tenga en cuenta que la dirección URL generada para el vínculo Contacto en la página representada refleja la ruta actualizada:

Vínculo de contacto de la aplicación de ejemplo en la barra de navegación

Inspeccionar el vínculo Contacto en el HTML representado indica que href está establecido en

Visite la página Contacto en su ruta normal, /Contact, o la ruta personalizada, /TheContactPage. Si proporciona un segmento de ruta adicional text , la página muestra el segmento codificado en HTML que se proporciona:

Ejemplo del explorador Edge de proporcionar un segmento de ruta opcional

Convenciones de acción del modelo de página

El proveedor de modelos de página predeterminado que implementa IPageApplicationModelProvider invoca convenciones diseñadas para proporcionar puntos de extensibilidad para configurar modelos de página. Estas convenciones son útiles al compilar y modificar escenarios de procesamiento y detección de páginas.

Para los ejemplos de esta sección, la aplicación de ejemplo utiliza una clase AddHeaderAttribute, que es un ResultFilterAttribute, que aplica un encabezado de respuesta.

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

Usando convenciones, el ejemplo demuestra cómo aplicar el atributo a todas las páginas de una carpeta y a una página individual.

Convención del modelo de aplicación de carpetas

Use AddFolderApplicationModelConvention para crear y añadir un IPageApplicationModelConvention que invoque una acción en las instancias de PageApplicationModel para todas las páginas de la carpeta especificada.

En el ejemplo se muestra el uso de AddFolderApplicationModelConvention agregando un encabezado, OtherPagesHeader, a las páginas dentro de la carpeta OtherPages de la aplicación:

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

Solicite la página Page1 del ejemplo en localhost:5000/OtherPages/Page1 e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página OtherPages/Page1 muestran que se ha agregado OtherPagesHeader.

Convención de modelo de aplicación de página

Use AddPageApplicationModelConvention para crear y agregar un IPageApplicationModelConvention que invoque una acción para PageApplicationModel la página con el nombre especificado.

En el ejemplo se muestra el uso de AddPageApplicationModelConvention agregando un encabezado , AboutHeadera la página Acerca de:

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

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se ha agregado AboutHeader.

Configuración de un filtro

ConfigureFilter configura el filtro especificado que se va a aplicar. Puede implementar una clase de filtro, pero la aplicación de ejemplo muestra cómo implementar un filtro en una expresión lambda, que se implementa en segundo plano como un generador que devuelve un filtro:

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

El modelo de aplicación de páginas se usa para comprobar la ruta de acceso relativa para los segmentos que conducen a la página Page2 de la carpeta OtherPages. Si la condición se cumple, se agrega un encabezado. Si no es así, se aplica EmptyFilter.

EmptyFilter es un filtro de acción. Dado que los filtros de acción son ignorados por Razor Pages, EmptyFilter no surte el efecto previsto si la ruta no contiene OtherPages/Page2.

Solicite la página Page2 del ejemplo en localhost:5000/OtherPages/Page2 e inspeccione los encabezados para ver el resultado:

OtherPagesPage2Header se agrega a la respuesta de Page2.

Configuración de un generador de filtros

ConfigureFilterconfigura el generador especificado para aplicar filtros a todas las RazorPáginas.

La aplicación de ejemplo proporciona un ejemplo de uso de un generador de filtros agregando un encabezado, FilterFactoryHeader, con dos valores a las páginas de la aplicación:

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

Solicite la página Acerca del ejemplo en localhost:5000/About e inspeccione los encabezados para ver el resultado:

Los encabezados de respuesta de la página Acerca de muestran que se han agregado dos encabezados FilterFactoryHeader.

Filtros MVC y filtro de página (IPageFilter)

Pages omite Razor de MVC, ya que Razor Pages usa métodos de controlador. Hay otros tipos de filtros de MVC disponibles para su uso: Autorización, Excepción, Recurso y Resultado. Para obtener más información, consulte el tema Filtros .

El filtro Página (IPageFilter) es un filtro que se aplica a Razor Pages. Para obtener más información, vea Métodos de filtrado de Razor Pages.

Recursos adicionales

  • Last updated on