Razor Směrování stránek a konvence aplikací v ASP.NET Core

Naučte se používat konvence směrování stránek a poskytovatelů modelů aplikací k řízení směrování, zjišťování a zpracování stránek v Razor aplikacích Pages.

Chcete-li zadat trasu stránky, přidat segmenty trasy nebo přidat parametry do trasy, použijte direktivu @page stránky. Další informace naleznete v tématu Vlastní trasy.

Jako segmenty tras nebo názvy parametrů nelze použít vyhrazená slova. Další informace naleznete v tématu Směrování: Rezervované názvy směrování.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Scenario	Ukázka ukazuje
Konvence modelů Conventions.Add IPageRouteModelConvention IPageApplicationModelConvention IPageHandlerModelConvention	Přidejte šablonu trasy a záhlaví na stránky aplikace.
Konvence akcí směrování stránky AddFolderRouteModelConvention AddPageRouteModelConvention AddPageRoute	Přidejte šablonu trasy na stránky ve složce a na jednu stránku.
Konvence akcí modelu stránky AddFolderApplicationModelConvention AddPageApplicationModelConvention ConfigureFilter (filtr třídy, výraz lambda nebo objekt pro vytváření filtrů)	Přidejte záhlaví na stránky ve složce, přidejte záhlaví na jednu stránku a nakonfigurujte objekt pro vytváření filtrů pro přidání záhlaví na stránky aplikace.

Razor Konvence stránek se konfigurují pomocí AddRazorPages přetížení, které konfiguruje RazorPagesOptions. Následující příklady konvence jsou vysvětleny dále v tomto tématu:

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

Pořadí tras

Trasy určují Order zpracování (porovnávání tras).

Pořadí tras	Chování
-1	Trasa se zpracuje před zpracováním jiných tras.
0	Pořadí není zadané (výchozí hodnota). Přiřazování Order (Order = null) výchozích hodnot trasy Order ke zpracování 0 (nula)
1, 2, ... n	Určuje pořadí zpracování tras.

Zpracování tras je vytvořeno konvencí:

• Trasy se zpracovávají v sekvenčním pořadí (-1, 0, 1, 2, ... n).
• Pokud trasy mají stejnou Ordertrasu, bude se jako první shodovat nejvýraznější trasa, za kterou následují méně specifické trasy.
• Pokud trasy se stejným Order počtem parametrů odpovídají adrese URL požadavku, trasy se zpracovávají v pořadí, ve kterém se přidají do PageConventionCollection.

Pokud je to možné, vyhněte se v závislosti na stanoveném pořadí zpracování tras. Obecně platí, že směrování vybere správnou trasu s odpovídající adresou URL. Pokud je nutné nastavit vlastnosti trasy Order pro správné směrování požadavků, schéma směrování aplikace je pravděpodobně matoucí pro klienty a křehké udržovat. Snažte se zjednodušit schéma směrování aplikace. Ukázková aplikace vyžaduje explicitní pořadí zpracování tras, které demonstruje několik scénářů směrování pomocí jedné aplikace. Měli byste se však pokusit vyhnout se postupu nastavení trasy Order v produkčních aplikacích.

Razor Směrování stránek a směrování kontroleru MVC sdílejí implementaci. Informace o pořadí tras v tématech MVC jsou k dispozici v akcích směrování pro kontroleru: Trasy atributů řazení.

Modelové konvence

Přidejte delegáta pro IPageConvention přidání konvencí modelu, které platí pro Razor stránky.

Přidání konvence modelu směrování na všechny stránky

Slouží Conventions k vytvoření a přidání IPageRouteModelConvention kolekce IPageConvention instancí, které se použijí při sestavování modelu směrování stránky.

Ukázková aplikace obsahuje GlobalTemplatePageRouteModelConvention třídu pro přidání {globalTemplate?} šablony trasy na všechny stránky aplikace:

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

V předchozím kódu:

• Metoda PageRouteModel se předá Apply .
• PageRouteModel.Selectors získá počet selektorů.
• Přidá se nový SelectorModel , který obsahuje AttributeRouteModel

RazorMožnosti stránek, jako je přidání, se přidají při Razor přidání Conventionsstránek do kolekce služeb. Příklad najdete v ukázkové aplikaci.

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

Vezměte v úvahu GlobalTemplatePageRouteModelConvention třídu:

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

Vlastnost Order je nastavena AttributeRouteModel na 1hodnotu . Tím se zajistí následující chování při párování tras v ukázkové aplikaci:

• Šablona trasy pro TheContactPage/{text?} je přidána později v tomto tématu. Trasa Contact Page má výchozí pořadí null (Order = 0), takže odpovídá před šablonou {globalTemplate?} trasy, která obsahuje Order = 1.

• Šablona {aboutTemplate?} trasy se zobrazí v předchozím kódu. Šablona {aboutTemplate?} má Order 2 Když je stránka About požadována v /About/RouteDataValue, "RouteDataValue" je načten do RouteData.Values["globalTemplate"] (Order = 1) a ne RouteData.Values["aboutTemplate"] (Order = 2) kvůli nastavení Order vlastnosti.

• Šablona {otherPagesTemplate?} trasy se zobrazí v předchozím kódu. Šablona {otherPagesTemplate?} má Order 2 Pokud je požadována libovolná stránka ve složce Pages/OtherPages s parametrem trasy:

• Například /OtherPages/Page1/xyz

• Hodnota směrovacích dat "xyz" se načte do RouteData.Values["globalTemplate"] (Order = 1).

• RouteData.Values["otherPagesTemplate"] with (Order = 2) není načtena Order kvůli vlastnosti 2 s vyšší hodnotou.

Pokud je to možné, nenastavujte Order. Pokud Order není nastavena, použije se Order = 0výchozí hodnota . Při výběru správné trasy místo Order vlastnosti se spoléháte na směrování.

Vyžádejte si stránku localhost:{port}/About/GlobalRouteValue ukázky About a zkontrolujte výsledek:

Ukázková aplikace používá balíček NuGet Rick.Docs.Samples.RouteInfo k zobrazení informací o směrování ve výstupu protokolování. Pomocí localhost:{port}/About/GlobalRouteValuenástroje logger zobrazí požadavek, šablonu Ordera použitou šablonu:

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

Přidání konvence modelu aplikace na všechny stránky

Slouží Conventions k vytvoření a přidání kolekce IPageApplicationModelConvention IPageConvention instancí, které se použijí při vytváření modelu aplikace stránky.

K předvedení této a dalších konvencí dále v tématu obsahuje AddHeaderAttribute ukázková aplikace třídu. Konstruktor třídy přijímá name řetězec a values pole řetězců. Tyto hodnoty se v metodě OnResultExecuting používají k nastavení hlavičky odpovědi. Úplná třída se zobrazí v části Konvence akcí modelu stránky dále v tématu.

Ukázková aplikace používá AddHeaderAttribute třídu k přidání záhlaví GlobalHeaderna všechny stránky v aplikaci:

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

Vyžádejte si stránku Informace o ukázce a localhost:{port}/About zkontrolujte hlavičky a prohlédněte si výsledek:

Přidání konvence modelu obslužné rutiny na všechny stránky

Slouží Conventions k vytvoření a přidání kolekce IPageHandlerModelConvention IPageConvention instancí, které se použijí při vytváření modelu obslužné rutiny stránky.

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

Konvence akcí směrování stránky

Výchozí zprostředkovatel modelu směrování odvozený z IPageRouteModelProvider vyvolání konvencí, které jsou navrženy tak, aby poskytovaly body rozšiřitelnosti pro konfiguraci tras stránek.

Konvence modelu směrování složek

Slouží AddFolderRouteModelConvention k vytvoření a přidání akce IPageRouteModelConvention , která vyvolá akci pro PageRouteModel všechny stránky pod zadanou složkou.

Ukázková aplikace používá AddFolderRouteModelConvention k přidání {otherPagesTemplate?} šablony trasy na stránky ve složce 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?}"),
            }
        });
    }
});

Vlastnost Order je nastavena AttributeRouteModel na 2hodnotu . Tím se zajistí, že šablona pro {globalTemplate?} (nastavenou dříve v tématu na 1) bude při zadání jedné hodnoty trasy nastavena na prioritu pozice první hodnoty dat trasy. Pokud je stránka ve složce Pages/OtherPages požadována s hodnotou parametru trasy (například /OtherPages/Page1/RouteDataValue), "RouteDataValue" se načte do RouteData.Values["globalTemplate"] (Order = 1) a ne RouteData.Values["otherPagesTemplate"] (Order = 2) kvůli nastavení Order vlastnosti.

Pokud je to možné, nenastavujte Order, což má za Order = 0následek . Při výběru správné trasy se spoléháte na směrování.

Vyžádejte si stránku Page1 localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue ukázky a zkontrolujte výsledek:

Konvence modelu směrování stránky

Slouží AddPageRouteModelConvention k vytvoření a přidání akce IPageRouteModelConvention , která vyvolá akci na PageRouteModel stránce se zadaným názvem.

Ukázková aplikace používá AddPageRouteModelConvention k přidání {aboutTemplate?} šablony trasy na stránku O aplikaci:

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

Vlastnost Order je nastavena AttributeRouteModel na 2hodnotu . Tím se zajistí, že šablona pro {globalTemplate?} (nastavenou dříve v tématu na 1) bude při zadání jedné hodnoty trasy nastavena na prioritu pozice první hodnoty dat trasy. Pokud je stránka About požadována s hodnotou parametru trasy v /About/RouteDataValue, "RouteDataValue" je načten do RouteData.Values["globalTemplate"] (Order = 1) a ne RouteData.Values["aboutTemplate"] (Order = 2) kvůli nastavení Order vlastnosti.

Pokud je to možné, nenastavujte Order, což má za Order = 0následek . Při výběru správné trasy se spoléháte na směrování.

Vyžádejte si stránku localhost:{port}/About/GlobalRouteValue/AboutRouteValue Informace o ukázce a zkontrolujte výsledek:

Výstup protokolovacího modulu se zobrazí:

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

Přizpůsobení tras stránek pomocí transformátoru parametrů

Viz transformátory parametrů.

Konfigurace trasy stránky

Slouží AddPageRoute ke konfiguraci trasy na stránku na zadané cestě stránky. Vygenerované odkazy na stránku používají zadanou trasu. AddPageRoute používá AddPageRouteModelConvention k navázání trasy.

Ukázková aplikace vytvoří trasu /TheContactPage ContactRazor pro stránku:

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

Na Contact stránce se dostanete také přes výchozí trasu contact1 /.

Vlastní trasa ukázkové aplikace na Contact stránku umožňuje volitelný text segment trasy ({text?}). Stránka také obsahuje tento volitelný segment ve své @page direktivě pro případ, že návštěvník přistupuje na stránku na své /Contact trase:

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

Všimněte si, že adresa URL vygenerovaná pro odkaz Kontakt na vykreslené stránce odráží aktualizovanou trasu:

Contact Navštivte stránku buď na své běžné trase, /Contactnebo vlastní trasu, /TheContactPage. Pokud zadáte další text segment trasy, zobrazí se na stránce segment kódovaný kódem HTML, který zadáte:

Konvence akcí modelu stránky

Výchozí zprostředkovatel modelu stránky, který implementuje IPageApplicationModelProvider konvence vyvolání, které jsou navržené tak, aby poskytovaly body rozšiřitelnosti pro konfiguraci modelů stránek. Tyto konvence jsou užitečné při vytváření a úpravě scénářů zjišťování a zpracování stránek.

Ukázková aplikace v této části používá AddHeaderAttribute třídu, která ResultFilterAttributepoužívá hlavičku odpovědi:

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

Pomocí konvencí ukázka ukazuje, jak použít atribut na všechny stránky ve složce a na jednu stránku.

Konvence modelu aplikace složek

Slouží AddFolderApplicationModelConvention k vytvoření a přidání akce IPageApplicationModelConvention PageApplicationModel s instancemi pro všechny stránky v zadané složce.

Ukázka demonstruje použití AddFolderApplicationModelConvention přidáním hlavičky , OtherPagesHeaderna stránky uvnitř složky OtherPages aplikace:

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

Vyžádejte si stránku Page1 ukázky a localhost:5000/OtherPages/Page1 prohlédněte si záhlaví a prohlédněte si výsledek:

Konvence modelu aplikace stránky

Slouží AddPageApplicationModelConvention k vytvoření a přidání akce IPageApplicationModelConvention , která vyvolá akci na PageApplicationModel stránce se zadaným názvem.

Ukázka demonstruje použití AddPageApplicationModelConvention přidáním záhlaví , AboutHeaderna stránku O aplikaci:

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

Vyžádejte si stránku Informace o ukázce a localhost:5000/About zkontrolujte hlavičky a prohlédněte si výsledek:

Konfigurace filtru

ConfigureFilter nakonfiguruje zadaný filtr, který se má použít. Třídu filtru můžete implementovat, ale ukázková aplikace ukazuje, jak implementovat filtr ve výrazu lambda, který se implementuje na pozadí jako továrna, která vrací filtr:

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

Model aplikace stránky slouží ke kontrole relativní cesty pro segmenty, které vedou na stránku Page2 ve složce OtherPages . Pokud podmínka projde, přidá se záhlaví. Pokud ne, použije se EmptyFilter .

EmptyFilterje filtr akce. Vzhledem k tomu, že filtry akcí jsou ignorovány stránkami Razor , EmptyFilter nemá žádný efekt, pokud cesta neobsahuje OtherPages/Page2.

Požádejte ukázkovou stránku Page2 na localhost:5000/OtherPages/Page2 stránce stránky a prohlédněte si záhlaví a prohlédněte si výsledek:

Konfigurace objektu pro vytváření filtrů

ConfigureFilter nakonfiguruje zadanou továrnu tak, aby použila filtry na všechny Razor stránky.

Ukázková aplikace poskytuje příklad použití objektu pro vytváření filtrů přidáním záhlaví se FilterFactoryHeaderdvěma hodnotami na stránky aplikace:

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

Vyžádejte si stránku Informace o ukázce a localhost:5000/About zkontrolujte hlavičky a prohlédněte si výsledek:

Filtry MVC a filtr stránky (IPageFilter)

Filtry akcí MVC jsou stránky ignoroványRazor, protože Razor Stránky používají metody obslužné rutiny. K dispozici jsou další typy filtrů MVC, které můžete použít: autorizace, výjimka, prostředek a výsledek. Další informace najdete v tématu Filtry .

Filtr stránky (IPageFilter) je filtr, který se vztahuje na Razor stránky. Další informace naleznete v tématu Metody filtrování pro Razor stránky.

Další prostředky

• Razor Směrování stránek
• Konvence autorizace Razor Pages v ASP.NET Core
• Oblasti v ASP.NET Core