Razor Pages: Routen- und App-Konventionen in ASP.NET Core Pages route and app conventions in ASP.NET Core

Erfahren Sie, wie Sie in Apps für Razor Pages mithilfe von Konventionen für Seitenrouten und App-Modellanbieter das Seitenrouting, die Ermittlung und die Verarbeitung steuern können.Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

Wenn Sie für einzelne Seiten benutzerdefinierte Seitenrouten konfigurieren müssen, sollten Sie das Routing zu den Seiten mithilfe der AddPageRoute-Konvention konfigurieren, die weiter unten in diesem Artikel beschrieben wird.When you need to configure custom page routes for individual pages, configure routing to pages with the AddPageRoute convention described later in this topic.

Um eine Seitenroute anzugeben oder einer Route Segmente oder Parameter hinzuzufügen, verwenden Sie die Anweisung @page der Seite.To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. Weitere Informationen finden Sie unter Benutzerdefinierte Routen.For more information, see Custom routes.

Es gibt reservierte Wörter, die nicht als Routensegmente oder Parameternamen verwendet werden können.There are reserved words that can't be used as route segments or parameter names. Weitere Informationen finden Sie unter Routing: Reservierte Routingnamen.For more information, see Routing: Reserved routing names.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

SzenarioScenario Dieses Beispiel veranschaulicht Folgendes:The sample demonstrates ...
Model conventions (Modellkonventionen)Model conventions

Conventions.AddConventions.Add
  • IPageRouteModelConventionIPageRouteModelConvention
  • IPageApplicationModelConventionIPageApplicationModelConvention
  • IPageHandlerModelConventionIPageHandlerModelConvention
Das Hinzufügen einer Routenvorlage und eines Headers zu den Seiten einer AppAdd a route template and header to an app's pages.
Konventionen für SeitenroutenaktionenPage route action conventions
  • AddFolderRouteModelConventionAddFolderRouteModelConvention
  • AddPageRouteModelConventionAddPageRouteModelConvention
  • AddPageRouteAddPageRoute
Das Hinzufügen einer Routenvorlage zu Seiten in einem Ordner und zu einer EinzelseiteAdd a route template to pages in a folder and to a single page.
Konventionen für SeitenmodellaktionenPage model action conventions
  • AddFolderApplicationModelConventionAddFolderApplicationModelConvention
  • AddPageApplicationModelConventionAddPageApplicationModelConvention
  • ConfigureFilter (Filterklasse, Lambdaausdruck oder Filterzuordnungsinstanz)ConfigureFilter (filter class, lambda expression, or filter factory)
Das Hinzufügen eines Headers zu Seiten in einem Ordner, das Hinzufügen eines Headers zu einer einzelnen Seite und das Konfigurieren einer Filter-Factoy zum Hinzufügen eines Headers zu den Seiten einer App.Add a header to pages in a folder, add a header to a single page, and configure a filter factory to add a header to an app's pages.

Konventionen für Razor Pages werden mithilfe der Erweiterungsmethode AddRazorPagesOptions für AddMvc unter der Dienstsammlung in der Klasse Startup hinzugefügt und konfiguriert.Razor Pages conventions are added and configured using the AddRazorPagesOptions extension method to AddMvc on the service collection in the Startup class. Die folgenden Beispiele der Konvention werden später in diesem Thema erläutert:The following convention examples are explained later in this topic:

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

RoutenreihenfolgeRoute order

Routen geben eine Order für die Verarbeitung an (Routenabgleich).Routes specify an Order for processing (route matching).

AuftragOrder VerhaltenBehavior
-1-1 Die Route wird vor anderen Routen verarbeitet.The route is processed before other routes are processed.
00 Die Reihenfolge wurde nicht angegeben (Standardwert).Order isn't specified (default value). Wenn Sie Order (Order = null) nicht zuweisen, wird für die Verarbeitung der Route Order standardmäßig auf 0 (null) gesetzt.Not assigning Order (Order = null) defaults the route Order to 0 (zero) for processing.
1, 2, … n1, 2, … n Gibt die Verarbeitungsreihenfolge für die Route an.Specifies the route processing order.

Die Routenverarbeitung wird gemäß der Konvention eingerichtet:Route processing is established by convention:

  • Routen werden in sequenzieller Reihenfolge verarbeitet (-1, 0, 1, 2, … n).Routes are processed in sequential order (-1, 0, 1, 2, … n).
  • Wenn Routen dieselbe Order aufweisen, wird zuerst die spezifischste Route abgeglichen, danach folgen die weniger spezifischen Routen.When routes have the same Order, the most specific route is matched first followed by less specific routes.
  • Wenn Routen mit derselben Order und derselben Anzahl Parameter mit einer Anforderungs-URL übereinstimmen, werden Routen in der Reihenfolge verarbeitet, in der sie der PageConventionCollection hinzugefügt wurden.When routes with the same Order and the same number of parameters match a request URL, routes are processed in the order that they're added to the PageConventionCollection.

Vermeiden Sie nach Möglichkeit die Abhängigkeit von einer festgelegten Verarbeitungsreihenfolge für Routen.If possible, avoid depending on an established route processing order. Im Allgemeinen wird beim Routing die richtige Route mittels URL-Zuordnung ausgewählt.Generally, routing selects the correct route with URL matching. Wenn Sie zum ordnungsgemäßen Weiterleiten von Anforderungen für die Route Order-Eigenschaften festlegen müssen, ist das Routingschema der App für Clients wahrscheinlich irreführend und in Bezug auf die Verwaltung störanfälliger.If you must set route Order properties to route requests correctly, the app's routing scheme is probably confusing to clients and fragile to maintain. Versuchen Sie daher, das Routingschema der App zu vereinfachen.Seek to simplify the app's routing scheme. Bei der Beispiel-App ist eine explizite Verarbeitungsreihenfolge für Routen erforderlich, um mit einer einzigen App verschiedene Routingszenarios veranschaulichen zu können.The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. In Produktions-Apps sollten Sie jedoch nach Möglichkeit eine Festlegung von Order für Routen vermeiden.However, you should attempt to avoid the practice of setting route Order in production apps.

Razor Pages-Routing und MVC Controller-Routing verwenden eine gemeinsame Implementierung. Pages routing and MVC controller routing share an implementation. Informationen zur Reihenfolge von Routen in den MVC-Themen finden Sie unter Routing zu Controlleraktionen: Ordnen der Attributrouten.Information on route order in the MVC topics is available at Routing to controller actions: Ordering attribute routes.

ModellkonventionenModel conventions

Fügen Sie einen Delegaten für IPageConvention hinzu, um Modellkonventionen hinzuzufügen, die auf Razor Pages anwendbar sind.Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

Hinzufügen einer Routenmodellkonvention zu allen SeitenAdd a route model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageRouteModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenroutenmodellen eingesetzt werden.Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

Die Beispielanwendung fügt dann zu allen Seiten der App eine {globalTemplate?}-Routenvorlage hinzu:The sample app adds a {globalTemplate?} route template to all of the pages in the app:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 1 festgelegt.The Order property for the AttributeRouteModel is set to 1. Dadurch wird das folgende Routenabgleichsverhalten in der Beispiel-App sichergestellt:This ensures the following route matching behavior in the sample app:

  • Eine Routenvorlage für TheContactPage/{text?} wird später in diesem Thema hinzugefügt.A route template for TheContactPage/{text?} is added later in the topic. Die Standardreihenfolge der Route für die Kontaktseite lautet null (Order = 0). Somit wird sie vor der Routenvorlage {globalTemplate?} abgeglichen.The Contact Page route has a default order of null (Order = 0), so it matches before the {globalTemplate?} route template.
  • Eine Routenvorlage für {aboutTemplate?} wird später in diesem Thema hinzugefügt.An {aboutTemplate?} route template is added later in the topic. Die Vorlage {aboutTemplate?} erhält den Order von 2.The {aboutTemplate?} template is given an Order of 2. Wenn die Seite „Info“ unter /About/RouteDataValue angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["aboutTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.When the About page is requested at /About/RouteDataValue, "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["aboutTemplate"] (Order = 2) due to setting the Order property.
  • Eine Routenvorlage für {otherPagesTemplate?} wird später in diesem Thema hinzugefügt.An {otherPagesTemplate?} route template is added later in the topic. Die Vorlage {otherPagesTemplate?} erhält den Order von 2.The {otherPagesTemplate?} template is given an Order of 2. Wenn eine Seite im Ordner Pages/OtherPages mit einem Routenparameter (z. B. /OtherPages/Page1/RouteDataValue) angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["otherPagesTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.When any page in the Pages/OtherPages folder is requested with a route parameter (for example, /OtherPages/Page1/RouteDataValue), "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["otherPagesTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Optionen für Razor Pages, z. B. das Hinzufügen von Conventions, werden hinzugefügt, wenn MVC der Dienstauflistung in Startup.ConfigureServices hinzugefügt wird.Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices. In der Beispiel-App finden Sie ein Beispiel hierfür.For an example, see the sample app.

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About/GlobalRouteValue an, und prüfen Sie das Ergebnis:Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:

Die Seite „Info“ wird mit einem Routensegment von GlobalRouteValue angefordert.

Hinzufügen einer App-Modellkonvention zu allen SeitenAdd an app model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageApplicationModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenanwendungsmodellen eingesetzt werden.Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention instances that are applied during page app model construction.

Die Beispielanwendung enthält eine AddHeaderAttribute-Klasse, damit das Verwenden dieser und anderer Konventionen weiter unten in diesem Thema gezeigt werden kann.To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class. Der Klassenkonstruktor akzeptiert eine name-Zeichenfolge und ein values-Zeichenfolgenarray.The class constructor accepts a name string and a values string array. Diese Werte werden in seiner OnResultExecuting-Methode verwendet, um einen Antwortheader einzurichten.These values are used in its OnResultExecuting method to set a response header. Die Klasse wird im Abschnitt Seitenmodellaktionskonventionen weiter unten in diesem Artikel erläutert.The full class is shown in the Page model action conventions section later in the topic.

Die Beispielanwendung verwendet die Klasse AddHeaderAttribute, um den Header GlobalHeader zu allen Seiten der Anwendung hinzuzufügen:The sample app uses the AddHeaderAttribute class to add a header, GlobalHeader, to all of the pages in the app:

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

Startup.cs:Startup.cs:

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Antwortheader der Seite „Info“ zeigen an, dass „GlobalHeader“ hinzugefügt wurde.

Hinzufügen einer Handlermodellkonvention zu allen SeitenAdd a handler model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageHandlerModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenhandlermodellen eingesetzt werden.Use Conventions to create and add an IPageHandlerModelConvention to the collection of IPageConvention instances that are applied during page handler model construction.

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

Startup.cs:Startup.cs:

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

Konventionen für SeitenroutenaktionenPage route action conventions

Der Standardanbieter für Routenmodelle, der von IPageRouteModelProvider abgeleitet wird, ruft Konventionen auf, die entwickelt wurden, um Erweiterungspunkte zum Konfigurieren von Seitenrouten bereitzustellen.The default route model provider that derives from IPageRouteModelProvider invokes conventions which are designed to provide extensibility points for configuring page routes.

OrdnerroutenmodellkonventionFolder route model convention

Verwenden Sie AddFolderRouteModelConvention zum Erstellen und Hinzuzufügen einer IPageRouteModelConvention, die eine Aktion für PageRouteModel für alle Seiten im angegebenen Ordner aufruft.Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for all of the pages under the specified folder.

Die Beispielanwendung verwendet AddFolderRouteModelConvention, um eine {otherPagesTemplate?}-Routenvorlage zu den Seiten im Ordner OtherPages hinzuzufügen:The sample app uses AddFolderRouteModelConvention to add an {otherPagesTemplate?} route template to the pages in the OtherPages folder:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 2 festgelegt.The Order property for the AttributeRouteModel is set to 2. Dadurch wird sichergestellt, dass die Vorlage für {globalTemplate?}, die weiter oben in diesem Thema für 1 festgelegt wurde, in Bezug auf die erste Position für einen Routendatenwert vorgezogen wird, wenn nur ein einziger Routenwert angegeben wurde.This ensures that the template for {globalTemplate?} (set earlier in the topic to 1) is given priority for the first route data value position when a single route value is provided. Wenn eine Seite im Ordner Pages/OtherPages mit einem Routenparameterwert (z. B. /OtherPages/Page1/RouteDataValue) angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["otherPagesTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.If a page in the Pages/OtherPages folder is requested with a route parameter value (for example, /OtherPages/Page1/RouteDataValue), "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["otherPagesTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Fordern Sie die Seite „Seite1“ der Beispielanwendung unter localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue an, und prüfen Sie das Ergebnis:Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and inspect the result:

Seite1 aus dem Ordner „OtherPages“ wird mit einem Routensegment von GlobalRouteValue und OtherPagesRouteValue angefordert.

SeitenroutenmodellkonventionPage route model convention

Verwenden Sie AddPageRouteModelConvention zum Erstellen und Hinzuzufügen einer IPageRouteModelConvention, die eine Aktion für das PageRouteModel für die Seite mit dem angegebenen Namen aufruft.Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for the page with the specified name.

Die Beispielanwendung verwendet AddPageRouteModelConvention, um eine {aboutTemplate?}-Routenvorlage zu der Seite „Info“ hinzuzufügen:The sample app uses AddPageRouteModelConvention to add an {aboutTemplate?} route template to the About page:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 2 festgelegt.The Order property for the AttributeRouteModel is set to 2. Dadurch wird sichergestellt, dass die Vorlage für {globalTemplate?}, die weiter oben in diesem Thema für 1 festgelegt wurde, in Bezug auf die erste Position für einen Routendatenwert vorgezogen wird, wenn nur ein einziger Routenwert angegeben wurde.This ensures that the template for {globalTemplate?} (set earlier in the topic to 1) is given priority for the first route data value position when a single route value is provided. Wenn die Seite „Info“ mit einem Routenparameterwert unter /About/RouteDataValue angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["aboutTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.If the About page is requested with a route parameter value at /About/RouteDataValue, "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["aboutTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About/GlobalRouteValue/AboutRouteValue an, und prüfen Sie das Ergebnis:Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

Die Seite „Info“ wird mit Routensegmenten für GlobalRouteValue und AboutRouteValue angefordert.

Verwenden eines Parametertransformators zum Anpassen von SeitenroutenUse a parameter transformer to customize page routes

Von ASP.NET Core generierte Seitenrouten können mit einem Parametertransformator angepasst werden.Page routes generated by ASP.NET Core can be customized using a parameter transformer. Ein Parametertransformator implementiert IOutboundParameterTransformer und wandelt den Wert der Parameter um.A parameter transformer implements IOutboundParameterTransformer and transforms the value of parameters. Beispielsweise ändert ein benutzerdefinierter SlugifyParameterTransformer-Parametertransformator den Routenwert SubscriptionManagement in subscription-management.For example, a custom SlugifyParameterTransformer parameter transformer changes the SubscriptionManagement route value to subscription-management.

Mit der Seitenroutenmodellkonvention PageRouteTransformerConvention wird ein Parametertransformator auf die Ordner- und Dateinamenssegmente von automatisch generierten Seitenrouten in einer App angewendet.The PageRouteTransformerConvention page route model convention applies a parameter transformer to the folder and file name segments of automatically generated page routes in an app. Für die Razor Pages-Datei unter /Pages/SubscriptionManagement/ViewAll.cshtml wird die Route beispielsweise von /SubscriptionManagement/ViewAll in /subscription-management/view-all umgeschrieben.For example, the Razor Pages file at /Pages/SubscriptionManagement/ViewAll.cshtml would have its route rewritten from /SubscriptionManagement/ViewAll to /subscription-management/view-all.

Mit PageRouteTransformerConvention werden nur die automatisch generierten Segmente einer Seitenroute transformiert, die aus dem Ordner- und Dateinamen von Razor Pages stammen.PageRouteTransformerConvention only transforms the automatically generated segments of a page route that come from the Razor Pages folder and file name. Mit der @page-Anweisung hinzugefügte Routensegmente werden nicht transformiert.It doesn't transform route segments added with the @page directive. Auch durch AddPageRoute hinzugefügte Routen werden mit dieser Konvention nicht transformiert.The convention also doesn't transform routes added by AddPageRoute.

Die PageRouteTransformerConvention wird als Option in Startup.ConfigureServices registriert:The PageRouteTransformerConvention is registered as an option in Startup.ConfigureServices:

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

Warnung

Übergeben Sie ein Timeout, wenn Sie System.Text.RegularExpressions zum Verarbeiten nicht vertrauenswürdiger Eingaben verwenden.When using System.Text.RegularExpressions to process untrusted input, pass a timeout. Ein böswilliger Benutzer kann Eingaben für RegularExpressions angeben, um einen Denial-of-Service-Angriff durchzuführen.A malicious user can provide input to RegularExpressions causing a Denial-of-Service attack. ASP.NET Core-Framework-APIs, die RegularExpressions verwenden, übergeben ein Timeout.ASP.NET Core framework APIs that use RegularExpressions pass a timeout.

Konfigurieren einer SeitenrouteConfigure a page route

Konfigurieren Sie mithilfe von AddPageRoute eine Route zu einer Seite am angegebenen Seitenpfad.Use AddPageRoute to configure a route to a page at the specified page path. Generierte Links, die auf die Seite verweisen, verwenden die von Ihnen angegebene Route.Generated links to the page use your specified route. AddPageRoute verwendet die AddPageRouteModelConvention zum Aufbauen der Route.AddPageRoute uses AddPageRouteModelConvention to establish the route.

Die Beispielanwendung erstellt für Contact.cshtml eine Route zur Seite /TheContactPage:The sample app creates a route to /TheContactPage for Contact.cshtml:

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

Die Seite „Kontakt“ kann auch unter /Contact über ihre Standardroute erreicht werden.The Contact page can also be reached at /Contact via its default route.

Die benutzerdefinierte Route der Beispielanwendung, die zur Seite „Kontakt“ führt, ermöglicht das Verwenden eines optionalen text-Routensegments ({text?}).The sample app's custom route to the Contact page allows for an optional text route segment ({text?}). Die Seite enthält dieses optionale Segment auch in ihrer @page-Anweisung, für den Fall, dass der Besucher über die /Contact-Route auf die Seite zugreift:The page also includes this optional segment in its @page directive in case the visitor accesses the page at its /Contact route:

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

Beachten Sie, dass die URL, die für den Link Kontakt in der gerenderten Seite generiert wurde, die aktualisierte Route widerspiegelt:Note that the URL generated for the Contact link in the rendered page reflects the updated route:

Kontaktlink der Beispielanwendung in der Navigationsleiste

Beim Überprüfen des Kontaktlinks in der gerenderten HTML zeigt sich, dass das HREF-Attribut auf „/TheContactPage“ festgelegt wurde.

Sie können die Kontaktseite entweder über deren übliche Route, /Contact, oder über die benutzerdefinierte Route, /TheContactPage, besuchen.Visit the Contact page at either its ordinary route, /Contact, or the custom route, /TheContactPage. Wenn Sie ein zusätzliches text-Routensegment bereitstellen, wird dieses HTML-codierte Segment auf der Seite angezeigt:If you supply an additional text route segment, the page shows the HTML-encoded segment that you provide:

Beispiel für das Bereitstellen eines optionalen „Text“-Routensegments mit „TextValue“ in der URL in der Ansicht des Microsoft Edge-Browsers

Konventionen für SeitenmodellaktionenPage model action conventions

Der Standardanbieter für Seitenmodelle, der IPageApplicationModelProvider implementiert, ruft Konventionen auf, die entwickelt wurden, um Erweiterungspunkte zum Konfigurieren von Seitenmodellen bereitzustellen.The default page model provider that implements IPageApplicationModelProvider invokes conventions which are designed to provide extensibility points for configuring page models. Diese Konventionen sind beim Erstellen und Ändern von Seitenermittlungs- und Verarbeitungsszenarios hilfreich.These conventions are useful when building and modifying page discovery and processing scenarios.

In den Beispielen in diesem Abschnitt verwendet die Beispielanwendung eine AddHeaderAttribute-Klasse, also ein ResultFilterAttribute, das einen Antwortheader verwendet:For the examples in this section, the sample app uses an AddHeaderAttribute class, which is a ResultFilterAttribute, that applies a response header:

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

Das Beispiel veranschaulicht mithilfe von Konventionen, wie das Attribut auf alle Seiten in einem Ordner und auf eine Einzelseite angewendet werden kann.Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.

Ordner-App-ModellkonventionFolder app model convention

Verwenden Sie AddFolderApplicationModelConvention zum Erstellen und Hinzuzufügen einer IPageApplicationModelConvention, die eine Aktion für PageApplicationModel-Instanzen für alle Seiten im angegebenen Ordner aufruft.Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on PageApplicationModel instances for all pages under the specified folder.

Im Beispiel wird die Verwendung der AddFolderApplicationModelConvention durch Hinzufügen eines Headers, OtherPagesHeader, zu den Seiten im Ordner OtherPages der Anwendung veranschaulicht:The sample demonstrates the use of AddFolderApplicationModelConvention by adding a header, OtherPagesHeader, to the pages inside the OtherPages folder of the app:

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

Fordern Sie die Seite „Seite1“ der Beispielanwendung unter localhost:5000/OtherPages/Page1 an, und prüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:

Antwortheader der Seite „OtherPages/Seite1“ zeigt, dass der OtherPagesHeader hinzugefügt wurde.

Seiten-App-ModellkonventionPage app model convention

Verwenden Sie AddPageApplicationModelConvention zum Erstellen und Hinzuzufügen einer IPageApplicationModelConvention, die eine Aktion für das PageApplicationModel für die Seite mit dem angegebenen Namen aufruft.Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on the PageApplicationModel for the page with the specified name.

Im Beispiel wird das Verwenden von AddPageApplicationModelConvention durch Hinzufügen eines Headers, AboutHeader, auf der Seite „Info“ veranschaulicht:The sample demonstrates the use of AddPageApplicationModelConvention by adding a header, AboutHeader, to the About page:

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Antwortheader der Seite „Info“ zeigen, dass AboutHeader hinzugefügt wurde.

Konfigurieren eines FiltersConfigure a filter

Der angegebene Filter, der angewendet werden soll, wird mit ConfigureFilter konfiguriert.ConfigureFilter configures the specified filter to apply. Sie können Filterklassen selbst implementieren. In der Beispielanwendung wird jedoch gezeigt, wie Sie einen Filter in einen Lambdaausdruck implementieren. Dieser wird dann im Hintergrund als Zuordnungsinstanz implementiert, die einen Filter zurückgibt:You can implement a filter class, but the sample app shows how to implement a filter in a lambda expression, which is implemented behind-the-scenes as a factory that returns a filter:

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

Das Seiten-App-Modell wird verwendet, um den relativen Pfad für Segmente zu überprüfen, die zur Seite „Seite2“ im Ordner OtherPages führen.The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages folder. Wenn die Bedingung erfüllt ist, wird ein Header hinzugefügt.If the condition passes, a header is added. Wenn dies nicht der Fall ist, wird der EmptyFilter angewendet.If not, the EmptyFilter is applied.

EmptyFilter ist ein Aktionsfilter.EmptyFilter is an Action filter. Wenn der Pfad OtherPages/Page2 nicht enthält, hat der EmptyFilter, wie vorgesehen, keine Auswirkung, da Aktionsfilter von Razor Pages ignoriert werden.Since Action filters are ignored by Razor Pages, the EmptyFilter has no effect as intended if the path doesn't contain OtherPages/Page2.

Fordern Sie die Seite „Seite2“ der Beispielanwendung unter localhost:5000/OtherPages/Page2 an, und prüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:

Der Header „OtherPagesPage2Header“ wird zur Antwort für „Seite2“ hinzugefügt.

Konfigurieren einer FilterzuordnungsinstanzConfigure a filter factory

Mit ConfigureFilter wird die angegebene Zuordnungsinstanz so konfiguriert, dass sie Filter auf alle Razor Pages anwendet.ConfigureFilter configures the specified factory to apply filters to all Razor Pages.

Die Beispielanwendung bietet Ihnen die Möglichkeit des beispielhaften Verwendens einer Filterzuordnungsinstanz durch Hinzufügen des Headers FilterFactoryHeader zu den Seiten der Anwendung, der zwei Werte besitzt:The sample app provides an example of using a filter factory by adding a header, FilterFactoryHeader, with two values to the app's pages:

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

AddHeaderWithFactory.cs: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;
        }
    }
}

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Die Antwortheader der Seite „Info“ zeigen, dass zwei Header des Typs „FilterFactoryHeader“ hinzugefügt wurden.

Die MVC-Filter und der Seitenfilter (IPageFilter)MVC Filters and the Page filter (IPageFilter)

MVC-Aktionsfilter werden von Razor Pages ignoriert, da Razor Pages Handlermethoden verwenden.MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. Darüber hinaus stehen die folgenden MVC-Filtertypen zur Verfügung: Autorisierung, Ausnahme, Ressource und Ergebnis.Other types of MVC filters are available for you to use: Authorization, Exception, Resource, and Result. Weitere Informationen finden Sie im Thema Filter.For more information, see the Filters topic.

Der Seitenfilter (IPageFilter) ist ein Filter, der auf Razor Pages anwendbar ist.The Page filter (IPageFilter) is a filter that applies to Razor Pages. Weitere Informationen finden Sie unter Filtermethoden für Razor Pages.For more information, see Filter methods for Razor Pages.

Zusätzliche RessourcenAdditional resources

Erfahren Sie, wie Sie in Apps für Razor Pages mithilfe von Konventionen für Seitenrouten und App-Modellanbieter das Seitenrouting, die Ermittlung und die Verarbeitung steuern können.Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

Wenn Sie für einzelne Seiten benutzerdefinierte Seitenrouten konfigurieren müssen, sollten Sie das Routing zu den Seiten mithilfe der AddPageRoute-Konvention konfigurieren, die weiter unten in diesem Artikel beschrieben wird.When you need to configure custom page routes for individual pages, configure routing to pages with the AddPageRoute convention described later in this topic.

Um eine Seitenroute anzugeben oder einer Route Segmente oder Parameter hinzuzufügen, verwenden Sie die Anweisung @page der Seite.To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. Weitere Informationen finden Sie unter Benutzerdefinierte Routen.For more information, see Custom routes.

Es gibt reservierte Wörter, die nicht als Routensegmente oder Parameternamen verwendet werden können.There are reserved words that can't be used as route segments or parameter names. Weitere Informationen finden Sie unter Routing: Reservierte Routingnamen.For more information, see Routing: Reserved routing names.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

SzenarioScenario Dieses Beispiel veranschaulicht Folgendes:The sample demonstrates ...
Model conventions (Modellkonventionen)Model conventions

Conventions.AddConventions.Add
  • IPageRouteModelConventionIPageRouteModelConvention
  • IPageApplicationModelConventionIPageApplicationModelConvention
  • IPageHandlerModelConventionIPageHandlerModelConvention
Das Hinzufügen einer Routenvorlage und eines Headers zu den Seiten einer AppAdd a route template and header to an app's pages.
Konventionen für SeitenroutenaktionenPage route action conventions
  • AddFolderRouteModelConventionAddFolderRouteModelConvention
  • AddPageRouteModelConventionAddPageRouteModelConvention
  • AddPageRouteAddPageRoute
Das Hinzufügen einer Routenvorlage zu Seiten in einem Ordner und zu einer EinzelseiteAdd a route template to pages in a folder and to a single page.
Konventionen für SeitenmodellaktionenPage model action conventions
  • AddFolderApplicationModelConventionAddFolderApplicationModelConvention
  • AddPageApplicationModelConventionAddPageApplicationModelConvention
  • ConfigureFilter (Filterklasse, Lambdaausdruck oder Filterzuordnungsinstanz)ConfigureFilter (filter class, lambda expression, or filter factory)
Das Hinzufügen eines Headers zu Seiten in einem Ordner, das Hinzufügen eines Headers zu einer einzelnen Seite und das Konfigurieren einer Filter-Factoy zum Hinzufügen eines Headers zu den Seiten einer App.Add a header to pages in a folder, add a header to a single page, and configure a filter factory to add a header to an app's pages.

Konventionen für Razor Pages werden AddMvc mithilfe der Erweiterungsmethode AddRazorPagesOptions unter der Dienstklasse in der Klasse Startup hinzugefügt.Razor Pages conventions are added and configured using the AddRazorPagesOptions extension method to AddMvc on the service collection in the Startup class. Die folgenden Beispiele der Konvention werden später in diesem Thema erläutert:The following convention examples are explained later in this topic:

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

RoutenreihenfolgeRoute order

Routen geben eine Order für die Verarbeitung an (Routenabgleich).Routes specify an Order for processing (route matching).

AuftragOrder VerhaltenBehavior
-1-1 Die Route wird vor anderen Routen verarbeitet.The route is processed before other routes are processed.
00 Die Reihenfolge wurde nicht angegeben (Standardwert).Order isn't specified (default value). Wenn Sie Order (Order = null) nicht zuweisen, wird für die Verarbeitung der Route Order standardmäßig auf 0 (null) gesetzt.Not assigning Order (Order = null) defaults the route Order to 0 (zero) for processing.
1, 2, … n1, 2, … n Gibt die Verarbeitungsreihenfolge für die Route an.Specifies the route processing order.

Die Routenverarbeitung wird gemäß der Konvention eingerichtet:Route processing is established by convention:

  • Routen werden in sequenzieller Reihenfolge verarbeitet (-1, 0, 1, 2, … n).Routes are processed in sequential order (-1, 0, 1, 2, … n).
  • Wenn Routen dieselbe Order aufweisen, wird zuerst die spezifischste Route abgeglichen, danach folgen die weniger spezifischen Routen.When routes have the same Order, the most specific route is matched first followed by less specific routes.
  • Wenn Routen mit derselben Order und derselben Anzahl Parameter mit einer Anforderungs-URL übereinstimmen, werden Routen in der Reihenfolge verarbeitet, in der sie der PageConventionCollection hinzugefügt wurden.When routes with the same Order and the same number of parameters match a request URL, routes are processed in the order that they're added to the PageConventionCollection.

Vermeiden Sie nach Möglichkeit die Abhängigkeit von einer festgelegten Verarbeitungsreihenfolge für Routen.If possible, avoid depending on an established route processing order. Im Allgemeinen wird beim Routing die richtige Route mittels URL-Zuordnung ausgewählt.Generally, routing selects the correct route with URL matching. Wenn Sie zum ordnungsgemäßen Weiterleiten von Anforderungen für die Route Order-Eigenschaften festlegen müssen, ist das Routingschema der App für Clients wahrscheinlich irreführend und in Bezug auf die Verwaltung störanfälliger.If you must set route Order properties to route requests correctly, the app's routing scheme is probably confusing to clients and fragile to maintain. Versuchen Sie daher, das Routingschema der App zu vereinfachen.Seek to simplify the app's routing scheme. Bei der Beispiel-App ist eine explizite Verarbeitungsreihenfolge für Routen erforderlich, um mit einer einzigen App verschiedene Routingszenarios veranschaulichen zu können.The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. In Produktions-Apps sollten Sie jedoch nach Möglichkeit eine Festlegung von Order für Routen vermeiden.However, you should attempt to avoid the practice of setting route Order in production apps.

Razor Pages-Routing und MVC Controller-Routing verwenden eine gemeinsame Implementierung. Pages routing and MVC controller routing share an implementation. Informationen zur Reihenfolge von Routen in den MVC-Themen finden Sie unter Routing zu Controlleraktionen: Ordnen der Attributrouten.Information on route order in the MVC topics is available at Routing to controller actions: Ordering attribute routes.

ModellkonventionenModel conventions

Fügen Sie einen Delegaten für IPageConvention hinzu, um Modellkonventionen hinzuzufügen, die auf Razor Pages anwendbar sind.Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

Hinzufügen einer Routenmodellkonvention zu allen SeitenAdd a route model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageRouteModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenroutenmodellen eingesetzt werden.Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

Die Beispielanwendung fügt dann zu allen Seiten der App eine {globalTemplate?}-Routenvorlage hinzu:The sample app adds a {globalTemplate?} route template to all of the pages in the app:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 1 festgelegt.The Order property for the AttributeRouteModel is set to 1. Dadurch wird das folgende Routenabgleichsverhalten in der Beispiel-App sichergestellt:This ensures the following route matching behavior in the sample app:

  • Eine Routenvorlage für TheContactPage/{text?} wird später in diesem Thema hinzugefügt.A route template for TheContactPage/{text?} is added later in the topic. Die Standardreihenfolge der Route für die Kontaktseite lautet null (Order = 0). Somit wird sie vor der Routenvorlage {globalTemplate?} abgeglichen.The Contact Page route has a default order of null (Order = 0), so it matches before the {globalTemplate?} route template.
  • Eine Routenvorlage für {aboutTemplate?} wird später in diesem Thema hinzugefügt.An {aboutTemplate?} route template is added later in the topic. Die Vorlage {aboutTemplate?} erhält den Order von 2.The {aboutTemplate?} template is given an Order of 2. Wenn die Seite „Info“ unter /About/RouteDataValue angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["aboutTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.When the About page is requested at /About/RouteDataValue, "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["aboutTemplate"] (Order = 2) due to setting the Order property.
  • Eine Routenvorlage für {otherPagesTemplate?} wird später in diesem Thema hinzugefügt.An {otherPagesTemplate?} route template is added later in the topic. Die Vorlage {otherPagesTemplate?} erhält den Order von 2.The {otherPagesTemplate?} template is given an Order of 2. Wenn eine Seite im Ordner Pages/OtherPages mit einem Routenparameter (z. B. /OtherPages/Page1/RouteDataValue) angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["otherPagesTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.When any page in the Pages/OtherPages folder is requested with a route parameter (for example, /OtherPages/Page1/RouteDataValue), "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["otherPagesTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Optionen für Razor Pages, z. B. das Hinzufügen von Conventions, werden hinzugefügt, wenn MVC der Dienstauflistung in Startup.ConfigureServices hinzugefügt wird.Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices. In der Beispiel-App finden Sie ein Beispiel hierfür.For an example, see the sample app.

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About/GlobalRouteValue an, und prüfen Sie das Ergebnis:Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:

Die Seite „Info“ wird mit einem Routensegment von GlobalRouteValue angefordert.

Hinzufügen einer App-Modellkonvention zu allen SeitenAdd an app model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageApplicationModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenanwendungsmodellen eingesetzt werden.Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention instances that are applied during page app model construction.

Die Beispielanwendung enthält eine AddHeaderAttribute-Klasse, damit das Verwenden dieser und anderer Konventionen weiter unten in diesem Thema gezeigt werden kann.To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class. Der Klassenkonstruktor akzeptiert eine name-Zeichenfolge und ein values-Zeichenfolgenarray.The class constructor accepts a name string and a values string array. Diese Werte werden in seiner OnResultExecuting-Methode verwendet, um einen Antwortheader einzurichten.These values are used in its OnResultExecuting method to set a response header. Die Klasse wird im Abschnitt Seitenmodellaktionskonventionen weiter unten in diesem Artikel erläutert.The full class is shown in the Page model action conventions section later in the topic.

Die Beispielanwendung verwendet die Klasse AddHeaderAttribute, um den Header GlobalHeader zu allen Seiten der Anwendung hinzuzufügen:The sample app uses the AddHeaderAttribute class to add a header, GlobalHeader, to all of the pages in the app:

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

Startup.cs:Startup.cs:

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Antwortheader der Seite „Info“ zeigen an, dass „GlobalHeader“ hinzugefügt wurde.

Hinzufügen einer Handlermodellkonvention zu allen SeitenAdd a handler model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageHandlerModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenhandlermodellen eingesetzt werden.Use Conventions to create and add an IPageHandlerModelConvention to the collection of IPageConvention instances that are applied during page handler model construction.

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

Startup.cs:Startup.cs:

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

Konventionen für SeitenroutenaktionenPage route action conventions

Der Standardanbieter für Routenmodelle, der von IPageRouteModelProvider abgeleitet wird, ruft Konventionen auf, die entwickelt wurden, um Erweiterungspunkte zum Konfigurieren von Seitenrouten bereitzustellen.The default route model provider that derives from IPageRouteModelProvider invokes conventions which are designed to provide extensibility points for configuring page routes.

OrdnerroutenmodellkonventionFolder route model convention

Verwenden Sie AddFolderRouteModelConvention zum Erstellen und Hinzuzufügen einer IPageRouteModelConvention, die eine Aktion für PageRouteModel für alle Seiten im angegebenen Ordner aufruft.Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for all of the pages under the specified folder.

Die Beispielanwendung verwendet AddFolderRouteModelConvention, um eine {otherPagesTemplate?}-Routenvorlage zu den Seiten im Ordner OtherPages hinzuzufügen:The sample app uses AddFolderRouteModelConvention to add an {otherPagesTemplate?} route template to the pages in the OtherPages folder:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 2 festgelegt.The Order property for the AttributeRouteModel is set to 2. Dadurch wird sichergestellt, dass die Vorlage für {globalTemplate?}, die weiter oben in diesem Thema für 1 festgelegt wurde, in Bezug auf die erste Position für einen Routendatenwert vorgezogen wird, wenn nur ein einziger Routenwert angegeben wurde.This ensures that the template for {globalTemplate?} (set earlier in the topic to 1) is given priority for the first route data value position when a single route value is provided. Wenn eine Seite im Ordner Pages/OtherPages mit einem Routenparameterwert (z. B. /OtherPages/Page1/RouteDataValue) angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["otherPagesTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.If a page in the Pages/OtherPages folder is requested with a route parameter value (for example, /OtherPages/Page1/RouteDataValue), "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["otherPagesTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Fordern Sie die Seite „Seite1“ der Beispielanwendung unter localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue an, und prüfen Sie das Ergebnis:Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and inspect the result:

Seite1 aus dem Ordner „OtherPages“ wird mit einem Routensegment von GlobalRouteValue und OtherPagesRouteValue angefordert.

SeitenroutenmodellkonventionPage route model convention

Verwenden Sie AddPageRouteModelConvention zum Erstellen und Hinzuzufügen einer IPageRouteModelConvention, die eine Aktion für das PageRouteModel für die Seite mit dem angegebenen Namen aufruft.Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for the page with the specified name.

Die Beispielanwendung verwendet AddPageRouteModelConvention, um eine {aboutTemplate?}-Routenvorlage zu der Seite „Info“ hinzuzufügen:The sample app uses AddPageRouteModelConvention to add an {aboutTemplate?} route template to the About page:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 2 festgelegt.The Order property for the AttributeRouteModel is set to 2. Dadurch wird sichergestellt, dass die Vorlage für {globalTemplate?}, die weiter oben in diesem Thema für 1 festgelegt wurde, in Bezug auf die erste Position für einen Routendatenwert vorgezogen wird, wenn nur ein einziger Routenwert angegeben wurde.This ensures that the template for {globalTemplate?} (set earlier in the topic to 1) is given priority for the first route data value position when a single route value is provided. Wenn die Seite „Info“ mit einem Routenparameterwert unter /About/RouteDataValue angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["aboutTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.If the About page is requested with a route parameter value at /About/RouteDataValue, "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["aboutTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About/GlobalRouteValue/AboutRouteValue an, und prüfen Sie das Ergebnis:Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

Die Seite „Info“ wird mit Routensegmenten für GlobalRouteValue und AboutRouteValue angefordert.

Verwenden eines Parametertransformators zum Anpassen von SeitenroutenUse a parameter transformer to customize page routes

Von ASP.NET Core generierte Seitenrouten können mit einem Parametertransformator angepasst werden.Page routes generated by ASP.NET Core can be customized using a parameter transformer. Ein Parametertransformator implementiert IOutboundParameterTransformer und wandelt den Wert der Parameter um.A parameter transformer implements IOutboundParameterTransformer and transforms the value of parameters. Beispielsweise ändert ein benutzerdefinierter SlugifyParameterTransformer-Parametertransformator den Routenwert SubscriptionManagement in subscription-management.For example, a custom SlugifyParameterTransformer parameter transformer changes the SubscriptionManagement route value to subscription-management.

Mit der Seitenroutenmodellkonvention PageRouteTransformerConvention wird ein Parametertransformator auf die Ordner- und Dateinamenssegmente von automatisch generierten Seitenrouten in einer App angewendet.The PageRouteTransformerConvention page route model convention applies a parameter transformer to the folder and file name segments of automatically generated page routes in an app. Für die Razor Pages-Datei unter /Pages/SubscriptionManagement/ViewAll.cshtml wird die Route beispielsweise von /SubscriptionManagement/ViewAll in /subscription-management/view-all umgeschrieben.For example, the Razor Pages file at /Pages/SubscriptionManagement/ViewAll.cshtml would have its route rewritten from /SubscriptionManagement/ViewAll to /subscription-management/view-all.

Mit PageRouteTransformerConvention werden nur die automatisch generierten Segmente einer Seitenroute transformiert, die aus dem Ordner- und Dateinamen von Razor Pages stammen.PageRouteTransformerConvention only transforms the automatically generated segments of a page route that come from the Razor Pages folder and file name. Mit der @page-Anweisung hinzugefügte Routensegmente werden nicht transformiert.It doesn't transform route segments added with the @page directive. Auch durch AddPageRoute hinzugefügte Routen werden mit dieser Konvention nicht transformiert.The convention also doesn't transform routes added by AddPageRoute.

Die PageRouteTransformerConvention wird als Option in Startup.ConfigureServices registriert:The PageRouteTransformerConvention is registered as an option in Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddRazorPagesOptions(options =>
        {
            options.Conventions.Add(
                new PageRouteTransformerConvention(
                    new SlugifyParameterTransformer()));
        });
}

public class SlugifyParameterTransformer : IOutboundParameterTransformer
{
    public string TransformOutbound(object value)
    {
        if (value == null) { return null; }

        // Slugify value
        return Regex.Replace(value.ToString(), "([a-z])([A-Z])", "$1-$2").ToLower();
    }
}

Konfigurieren einer SeitenrouteConfigure a page route

Konfigurieren Sie mithilfe von AddPageRoute eine Route zu einer Seite am angegebenen Seitenpfad.Use AddPageRoute to configure a route to a page at the specified page path. Generierte Links, die auf die Seite verweisen, verwenden die von Ihnen angegebene Route.Generated links to the page use your specified route. AddPageRoute verwendet die AddPageRouteModelConvention zum Aufbauen der Route.AddPageRoute uses AddPageRouteModelConvention to establish the route.

Die Beispielanwendung erstellt für Contact.cshtml eine Route zur Seite /TheContactPage:The sample app creates a route to /TheContactPage for Contact.cshtml:

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

Die Seite „Kontakt“ kann auch unter /Contact über ihre Standardroute erreicht werden.The Contact page can also be reached at /Contact via its default route.

Die benutzerdefinierte Route der Beispielanwendung, die zur Seite „Kontakt“ führt, ermöglicht das Verwenden eines optionalen text-Routensegments ({text?}).The sample app's custom route to the Contact page allows for an optional text route segment ({text?}). Die Seite enthält dieses optionale Segment auch in ihrer @page-Anweisung, für den Fall, dass der Besucher über die /Contact-Route auf die Seite zugreift:The page also includes this optional segment in its @page directive in case the visitor accesses the page at its /Contact route:

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

Beachten Sie, dass die URL, die für den Link Kontakt in der gerenderten Seite generiert wurde, die aktualisierte Route widerspiegelt:Note that the URL generated for the Contact link in the rendered page reflects the updated route:

Kontaktlink der Beispielanwendung in der Navigationsleiste

Beim Überprüfen des Kontaktlinks in der gerenderten HTML zeigt sich, dass das HREF-Attribut auf „/TheContactPage“ festgelegt wurde.

Sie können die Kontaktseite entweder über deren übliche Route, /Contact, oder über die benutzerdefinierte Route, /TheContactPage, besuchen.Visit the Contact page at either its ordinary route, /Contact, or the custom route, /TheContactPage. Wenn Sie ein zusätzliches text-Routensegment bereitstellen, wird dieses HTML-codierte Segment auf der Seite angezeigt:If you supply an additional text route segment, the page shows the HTML-encoded segment that you provide:

Beispiel für das Bereitstellen eines optionalen „Text“-Routensegments mit „TextValue“ in der URL in der Ansicht des Microsoft Edge-Browsers

Konventionen für SeitenmodellaktionenPage model action conventions

Der Standardanbieter für Seitenmodelle, der IPageApplicationModelProvider implementiert, ruft Konventionen auf, die entwickelt wurden, um Erweiterungspunkte zum Konfigurieren von Seitenmodellen bereitzustellen.The default page model provider that implements IPageApplicationModelProvider invokes conventions which are designed to provide extensibility points for configuring page models. Diese Konventionen sind beim Erstellen und Ändern von Seitenermittlungs- und Verarbeitungsszenarios hilfreich.These conventions are useful when building and modifying page discovery and processing scenarios.

In den Beispielen in diesem Abschnitt verwendet die Beispielanwendung eine AddHeaderAttribute-Klasse, also ein ResultFilterAttribute, das einen Antwortheader verwendet:For the examples in this section, the sample app uses an AddHeaderAttribute class, which is a ResultFilterAttribute, that applies a response header:

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

Das Beispiel veranschaulicht mithilfe von Konventionen, wie das Attribut auf alle Seiten in einem Ordner und auf eine Einzelseite angewendet werden kann.Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.

Ordner-App-ModellkonventionFolder app model convention

Verwenden Sie AddFolderApplicationModelConvention zum Erstellen und Hinzuzufügen einer IPageApplicationModelConvention, die eine Aktion für PageApplicationModel-Instanzen für alle Seiten im angegebenen Ordner aufruft.Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on PageApplicationModel instances for all pages under the specified folder.

Im Beispiel wird die Verwendung der AddFolderApplicationModelConvention durch Hinzufügen eines Headers, OtherPagesHeader, zu den Seiten im Ordner OtherPages der Anwendung veranschaulicht:The sample demonstrates the use of AddFolderApplicationModelConvention by adding a header, OtherPagesHeader, to the pages inside the OtherPages folder of the app:

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

Fordern Sie die Seite „Seite1“ der Beispielanwendung unter localhost:5000/OtherPages/Page1 an, und prüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:

Antwortheader der Seite „OtherPages/Seite1“ zeigt, dass der OtherPagesHeader hinzugefügt wurde.

Seiten-App-ModellkonventionPage app model convention

Verwenden Sie AddPageApplicationModelConvention zum Erstellen und Hinzuzufügen einer IPageApplicationModelConvention, die eine Aktion für das PageApplicationModel für die Seite mit dem angegebenen Namen aufruft.Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on the PageApplicationModel for the page with the specified name.

Im Beispiel wird das Verwenden von AddPageApplicationModelConvention durch Hinzufügen eines Headers, AboutHeader, auf der Seite „Info“ veranschaulicht:The sample demonstrates the use of AddPageApplicationModelConvention by adding a header, AboutHeader, to the About page:

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Antwortheader der Seite „Info“ zeigen, dass AboutHeader hinzugefügt wurde.

Konfigurieren eines FiltersConfigure a filter

Der angegebene Filter, der angewendet werden soll, wird mit ConfigureFilter konfiguriert.ConfigureFilter configures the specified filter to apply. Sie können Filterklassen selbst implementieren. In der Beispielanwendung wird jedoch gezeigt, wie Sie einen Filter in einen Lambdaausdruck implementieren. Dieser wird dann im Hintergrund als Zuordnungsinstanz implementiert, die einen Filter zurückgibt:You can implement a filter class, but the sample app shows how to implement a filter in a lambda expression, which is implemented behind-the-scenes as a factory that returns a filter:

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

Das Seiten-App-Modell wird verwendet, um den relativen Pfad für Segmente zu überprüfen, die zur Seite „Seite2“ im Ordner OtherPages führen.The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages folder. Wenn die Bedingung erfüllt ist, wird ein Header hinzugefügt.If the condition passes, a header is added. Wenn dies nicht der Fall ist, wird der EmptyFilter angewendet.If not, the EmptyFilter is applied.

EmptyFilter ist ein Aktionsfilter.EmptyFilter is an Action filter. Wenn der Pfad OtherPages/Page2 nicht enthält, hat der EmptyFilter, wie vorgesehen, keine Auswirkung, da Aktionsfilter von Razor Pages ignoriert werden.Since Action filters are ignored by Razor Pages, the EmptyFilter has no effect as intended if the path doesn't contain OtherPages/Page2.

Fordern Sie die Seite „Seite2“ der Beispielanwendung unter localhost:5000/OtherPages/Page2 an, und prüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:

Der Header „OtherPagesPage2Header“ wird zur Antwort für „Seite2“ hinzugefügt.

Konfigurieren einer FilterzuordnungsinstanzConfigure a filter factory

Mit ConfigureFilter wird die angegebene Zuordnungsinstanz so konfiguriert, dass sie Filter auf alle Razor Pages anwendet.ConfigureFilter configures the specified factory to apply filters to all Razor Pages.

Die Beispielanwendung bietet Ihnen die Möglichkeit des beispielhaften Verwendens einer Filterzuordnungsinstanz durch Hinzufügen des Headers FilterFactoryHeader zu den Seiten der Anwendung, der zwei Werte besitzt:The sample app provides an example of using a filter factory by adding a header, FilterFactoryHeader, with two values to the app's pages:

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

AddHeaderWithFactory.cs: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;
        }
    }
}

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Die Antwortheader der Seite „Info“ zeigen, dass zwei Header des Typs „FilterFactoryHeader“ hinzugefügt wurden.

Die MVC-Filter und der Seitenfilter (IPageFilter)MVC Filters and the Page filter (IPageFilter)

MVC-Aktionsfilter werden von Razor Pages ignoriert, da Razor Pages Handlermethoden verwenden.MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. Darüber hinaus stehen die folgenden MVC-Filtertypen zur Verfügung: Autorisierung, Ausnahme, Ressource und Ergebnis.Other types of MVC filters are available for you to use: Authorization, Exception, Resource, and Result. Weitere Informationen finden Sie im Thema Filter.For more information, see the Filters topic.

Der Seitenfilter (IPageFilter) ist ein Filter, der auf Razor Pages anwendbar ist.The Page filter (IPageFilter) is a filter that applies to Razor Pages. Weitere Informationen finden Sie unter Filtermethoden für Razor Pages.For more information, see Filter methods for Razor Pages.

Zusätzliche RessourcenAdditional resources

Erfahren Sie, wie Sie in Apps für Razor Pages mithilfe von Konventionen für Seitenrouten und App-Modellanbieter das Seitenrouting, die Ermittlung und die Verarbeitung steuern können.Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

Wenn Sie für einzelne Seiten benutzerdefinierte Seitenrouten konfigurieren müssen, sollten Sie das Routing zu den Seiten mithilfe der AddPageRoute-Konvention konfigurieren, die weiter unten in diesem Artikel beschrieben wird.When you need to configure custom page routes for individual pages, configure routing to pages with the AddPageRoute convention described later in this topic.

Um eine Seitenroute anzugeben oder einer Route Segmente oder Parameter hinzuzufügen, verwenden Sie die Anweisung @page der Seite.To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. Weitere Informationen finden Sie unter Benutzerdefinierte Routen.For more information, see Custom routes.

Es gibt reservierte Wörter, die nicht als Routensegmente oder Parameternamen verwendet werden können.There are reserved words that can't be used as route segments or parameter names. Weitere Informationen finden Sie unter Routing: Reservierte Routingnamen.For more information, see Routing: Reserved routing names.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

SzenarioScenario Dieses Beispiel veranschaulicht Folgendes:The sample demonstrates ...
Model conventions (Modellkonventionen)Model conventions

Conventions.AddConventions.Add
  • IPageRouteModelConventionIPageRouteModelConvention
  • IPageApplicationModelConventionIPageApplicationModelConvention
  • IPageHandlerModelConventionIPageHandlerModelConvention
Das Hinzufügen einer Routenvorlage und eines Headers zu den Seiten einer AppAdd a route template and header to an app's pages.
Konventionen für SeitenroutenaktionenPage route action conventions
  • AddFolderRouteModelConventionAddFolderRouteModelConvention
  • AddPageRouteModelConventionAddPageRouteModelConvention
  • AddPageRouteAddPageRoute
Das Hinzufügen einer Routenvorlage zu Seiten in einem Ordner und zu einer EinzelseiteAdd a route template to pages in a folder and to a single page.
Konventionen für SeitenmodellaktionenPage model action conventions
  • AddFolderApplicationModelConventionAddFolderApplicationModelConvention
  • AddPageApplicationModelConventionAddPageApplicationModelConvention
  • ConfigureFilter (Filterklasse, Lambdaausdruck oder Filterzuordnungsinstanz)ConfigureFilter (filter class, lambda expression, or filter factory)
Das Hinzufügen eines Headers zu Seiten in einem Ordner, das Hinzufügen eines Headers zu einer einzelnen Seite und das Konfigurieren einer Filter-Factoy zum Hinzufügen eines Headers zu den Seiten einer App.Add a header to pages in a folder, add a header to a single page, and configure a filter factory to add a header to an app's pages.

Konventionen für Razor Pages werden AddMvc mithilfe der Erweiterungsmethode AddRazorPagesOptions unter der Dienstklasse in der Klasse Startup hinzugefügt.Razor Pages conventions are added and configured using the AddRazorPagesOptions extension method to AddMvc on the service collection in the Startup class. Die folgenden Beispiele der Konvention werden später in diesem Thema erläutert:The following convention examples are explained later in this topic:

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

RoutenreihenfolgeRoute order

Routen geben eine Order für die Verarbeitung an (Routenabgleich).Routes specify an Order for processing (route matching).

AuftragOrder VerhaltenBehavior
-1-1 Die Route wird vor anderen Routen verarbeitet.The route is processed before other routes are processed.
00 Die Reihenfolge wurde nicht angegeben (Standardwert).Order isn't specified (default value). Wenn Sie Order (Order = null) nicht zuweisen, wird für die Verarbeitung der Route Order standardmäßig auf 0 (null) gesetzt.Not assigning Order (Order = null) defaults the route Order to 0 (zero) for processing.
1, 2, … n1, 2, … n Gibt die Verarbeitungsreihenfolge für die Route an.Specifies the route processing order.

Die Routenverarbeitung wird gemäß der Konvention eingerichtet:Route processing is established by convention:

  • Routen werden in sequenzieller Reihenfolge verarbeitet (-1, 0, 1, 2, … n).Routes are processed in sequential order (-1, 0, 1, 2, … n).
  • Wenn Routen dieselbe Order aufweisen, wird zuerst die spezifischste Route abgeglichen, danach folgen die weniger spezifischen Routen.When routes have the same Order, the most specific route is matched first followed by less specific routes.
  • Wenn Routen mit derselben Order und derselben Anzahl Parameter mit einer Anforderungs-URL übereinstimmen, werden Routen in der Reihenfolge verarbeitet, in der sie der PageConventionCollection hinzugefügt wurden.When routes with the same Order and the same number of parameters match a request URL, routes are processed in the order that they're added to the PageConventionCollection.

Vermeiden Sie nach Möglichkeit die Abhängigkeit von einer festgelegten Verarbeitungsreihenfolge für Routen.If possible, avoid depending on an established route processing order. Im Allgemeinen wird beim Routing die richtige Route mittels URL-Zuordnung ausgewählt.Generally, routing selects the correct route with URL matching. Wenn Sie zum ordnungsgemäßen Weiterleiten von Anforderungen für die Route Order-Eigenschaften festlegen müssen, ist das Routingschema der App für Clients wahrscheinlich irreführend und in Bezug auf die Verwaltung störanfälliger.If you must set route Order properties to route requests correctly, the app's routing scheme is probably confusing to clients and fragile to maintain. Versuchen Sie daher, das Routingschema der App zu vereinfachen.Seek to simplify the app's routing scheme. Bei der Beispiel-App ist eine explizite Verarbeitungsreihenfolge für Routen erforderlich, um mit einer einzigen App verschiedene Routingszenarios veranschaulichen zu können.The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. In Produktions-Apps sollten Sie jedoch nach Möglichkeit eine Festlegung von Order für Routen vermeiden.However, you should attempt to avoid the practice of setting route Order in production apps.

Razor Pages-Routing und MVC Controller-Routing verwenden eine gemeinsame Implementierung. Pages routing and MVC controller routing share an implementation. Informationen zur Reihenfolge von Routen in den MVC-Themen finden Sie unter Routing zu Controlleraktionen: Ordnen der Attributrouten.Information on route order in the MVC topics is available at Routing to controller actions: Ordering attribute routes.

ModellkonventionenModel conventions

Fügen Sie einen Delegaten für IPageConvention hinzu, um Modellkonventionen hinzuzufügen, die auf Razor Pages anwendbar sind.Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

Hinzufügen einer Routenmodellkonvention zu allen SeitenAdd a route model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageRouteModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenroutenmodellen eingesetzt werden.Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

Die Beispielanwendung fügt dann zu allen Seiten der App eine {globalTemplate?}-Routenvorlage hinzu:The sample app adds a {globalTemplate?} route template to all of the pages in the app:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 1 festgelegt.The Order property for the AttributeRouteModel is set to 1. Dadurch wird das folgende Routenabgleichsverhalten in der Beispiel-App sichergestellt:This ensures the following route matching behavior in the sample app:

  • Eine Routenvorlage für TheContactPage/{text?} wird später in diesem Thema hinzugefügt.A route template for TheContactPage/{text?} is added later in the topic. Die Standardreihenfolge der Route für die Kontaktseite lautet null (Order = 0). Somit wird sie vor der Routenvorlage {globalTemplate?} abgeglichen.The Contact Page route has a default order of null (Order = 0), so it matches before the {globalTemplate?} route template.
  • Eine Routenvorlage für {aboutTemplate?} wird später in diesem Thema hinzugefügt.An {aboutTemplate?} route template is added later in the topic. Die Vorlage {aboutTemplate?} erhält den Order von 2.The {aboutTemplate?} template is given an Order of 2. Wenn die Seite „Info“ unter /About/RouteDataValue angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["aboutTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.When the About page is requested at /About/RouteDataValue, "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["aboutTemplate"] (Order = 2) due to setting the Order property.
  • Eine Routenvorlage für {otherPagesTemplate?} wird später in diesem Thema hinzugefügt.An {otherPagesTemplate?} route template is added later in the topic. Die Vorlage {otherPagesTemplate?} erhält den Order von 2.The {otherPagesTemplate?} template is given an Order of 2. Wenn eine Seite im Ordner Pages/OtherPages mit einem Routenparameter (z. B. /OtherPages/Page1/RouteDataValue) angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["otherPagesTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.When any page in the Pages/OtherPages folder is requested with a route parameter (for example, /OtherPages/Page1/RouteDataValue), "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["otherPagesTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Optionen für Razor Pages, z. B. das Hinzufügen von Conventions, werden hinzugefügt, wenn MVC der Dienstauflistung in Startup.ConfigureServices hinzugefügt wird.Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices. In der Beispiel-App finden Sie ein Beispiel hierfür.For an example, see the sample app.

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About/GlobalRouteValue an, und prüfen Sie das Ergebnis:Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:

Die Seite „Info“ wird mit einem Routensegment von GlobalRouteValue angefordert.

Hinzufügen einer App-Modellkonvention zu allen SeitenAdd an app model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageApplicationModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenanwendungsmodellen eingesetzt werden.Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention instances that are applied during page app model construction.

Die Beispielanwendung enthält eine AddHeaderAttribute-Klasse, damit das Verwenden dieser und anderer Konventionen weiter unten in diesem Thema gezeigt werden kann.To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class. Der Klassenkonstruktor akzeptiert eine name-Zeichenfolge und ein values-Zeichenfolgenarray.The class constructor accepts a name string and a values string array. Diese Werte werden in seiner OnResultExecuting-Methode verwendet, um einen Antwortheader einzurichten.These values are used in its OnResultExecuting method to set a response header. Die Klasse wird im Abschnitt Seitenmodellaktionskonventionen weiter unten in diesem Artikel erläutert.The full class is shown in the Page model action conventions section later in the topic.

Die Beispielanwendung verwendet die Klasse AddHeaderAttribute, um den Header GlobalHeader zu allen Seiten der Anwendung hinzuzufügen:The sample app uses the AddHeaderAttribute class to add a header, GlobalHeader, to all of the pages in the app:

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

Startup.cs:Startup.cs:

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Antwortheader der Seite „Info“ zeigen an, dass „GlobalHeader“ hinzugefügt wurde.

Hinzufügen einer Handlermodellkonvention zu allen SeitenAdd a handler model convention to all pages

Verwenden Sie Conventions zum Erstellen und Hinzufügen einer IPageHandlerModelConvention zur Auflistung der Instanzen von IPageConvention, die während der Erstellung von Seitenhandlermodellen eingesetzt werden.Use Conventions to create and add an IPageHandlerModelConvention to the collection of IPageConvention instances that are applied during page handler model construction.

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

Startup.cs:Startup.cs:

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

Konventionen für SeitenroutenaktionenPage route action conventions

Der Standardanbieter für Routenmodelle, der von IPageRouteModelProvider abgeleitet wird, ruft Konventionen auf, die entwickelt wurden, um Erweiterungspunkte zum Konfigurieren von Seitenrouten bereitzustellen.The default route model provider that derives from IPageRouteModelProvider invokes conventions which are designed to provide extensibility points for configuring page routes.

OrdnerroutenmodellkonventionFolder route model convention

Verwenden Sie AddFolderRouteModelConvention zum Erstellen und Hinzuzufügen einer IPageRouteModelConvention, die eine Aktion für PageRouteModel für alle Seiten im angegebenen Ordner aufruft.Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for all of the pages under the specified folder.

Die Beispielanwendung verwendet AddFolderRouteModelConvention, um eine {otherPagesTemplate?}-Routenvorlage zu den Seiten im Ordner OtherPages hinzuzufügen:The sample app uses AddFolderRouteModelConvention to add an {otherPagesTemplate?} route template to the pages in the OtherPages folder:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 2 festgelegt.The Order property for the AttributeRouteModel is set to 2. Dadurch wird sichergestellt, dass die Vorlage für {globalTemplate?}, die weiter oben in diesem Thema für 1 festgelegt wurde, in Bezug auf die erste Position für einen Routendatenwert vorgezogen wird, wenn nur ein einziger Routenwert angegeben wurde.This ensures that the template for {globalTemplate?} (set earlier in the topic to 1) is given priority for the first route data value position when a single route value is provided. Wenn eine Seite im Ordner Pages/OtherPages mit einem Routenparameterwert (z. B. /OtherPages/Page1/RouteDataValue) angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["otherPagesTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.If a page in the Pages/OtherPages folder is requested with a route parameter value (for example, /OtherPages/Page1/RouteDataValue), "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["otherPagesTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Fordern Sie die Seite „Seite1“ der Beispielanwendung unter localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue an, und prüfen Sie das Ergebnis:Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and inspect the result:

Seite1 aus dem Ordner „OtherPages“ wird mit einem Routensegment von GlobalRouteValue und OtherPagesRouteValue angefordert.

SeitenroutenmodellkonventionPage route model convention

Verwenden Sie AddPageRouteModelConvention zum Erstellen und Hinzuzufügen einer IPageRouteModelConvention, die eine Aktion für das PageRouteModel für die Seite mit dem angegebenen Namen aufruft.Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for the page with the specified name.

Die Beispielanwendung verwendet AddPageRouteModelConvention, um eine {aboutTemplate?}-Routenvorlage zu der Seite „Info“ hinzuzufügen:The sample app uses AddPageRouteModelConvention to add an {aboutTemplate?} route template to the About page:

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

Die Eigenschaft Order ist für das AttributeRouteModel auf 2 festgelegt.The Order property for the AttributeRouteModel is set to 2. Dadurch wird sichergestellt, dass die Vorlage für {globalTemplate?}, die weiter oben in diesem Thema für 1 festgelegt wurde, in Bezug auf die erste Position für einen Routendatenwert vorgezogen wird, wenn nur ein einziger Routenwert angegeben wurde.This ensures that the template for {globalTemplate?} (set earlier in the topic to 1) is given priority for the first route data value position when a single route value is provided. Wenn die Seite „Info“ mit einem Routenparameterwert unter /About/RouteDataValue angefordert wird, wird „RouteDataValue“ in die Vorlage RouteData.Values["globalTemplate"] geladen (Order = 1) und nicht in RouteData.Values["aboutTemplate"] (Order = 2), da die Eigenschaft Order auf null festgelegt wurde.If the About page is requested with a route parameter value at /About/RouteDataValue, "RouteDataValue" is loaded into RouteData.Values["globalTemplate"] (Order = 1) and not RouteData.Values["aboutTemplate"] (Order = 2) due to setting the Order property.

Legen Sie die Order möglichst nicht fest, sodass Order = 0 gilt.Wherever possible, don't set the Order, which results in Order = 0. Verlassen Sie sich bei der Auswahl der richtigen Route auf die Routenplanung.Rely on routing to select the correct route.

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About/GlobalRouteValue/AboutRouteValue an, und prüfen Sie das Ergebnis:Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

Die Seite „Info“ wird mit Routensegmenten für GlobalRouteValue und AboutRouteValue angefordert.

Konfigurieren einer SeitenrouteConfigure a page route

Konfigurieren Sie mithilfe von AddPageRoute eine Route zu einer Seite am angegebenen Seitenpfad.Use AddPageRoute to configure a route to a page at the specified page path. Generierte Links, die auf die Seite verweisen, verwenden die von Ihnen angegebene Route.Generated links to the page use your specified route. AddPageRoute verwendet die AddPageRouteModelConvention zum Aufbauen der Route.AddPageRoute uses AddPageRouteModelConvention to establish the route.

Die Beispielanwendung erstellt für Contact.cshtml eine Route zur Seite /TheContactPage:The sample app creates a route to /TheContactPage for Contact.cshtml:

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

Die Seite „Kontakt“ kann auch unter /Contact über ihre Standardroute erreicht werden.The Contact page can also be reached at /Contact via its default route.

Die benutzerdefinierte Route der Beispielanwendung, die zur Seite „Kontakt“ führt, ermöglicht das Verwenden eines optionalen text-Routensegments ({text?}).The sample app's custom route to the Contact page allows for an optional text route segment ({text?}). Die Seite enthält dieses optionale Segment auch in ihrer @page-Anweisung, für den Fall, dass der Besucher über die /Contact-Route auf die Seite zugreift:The page also includes this optional segment in its @page directive in case the visitor accesses the page at its /Contact route:

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

Beachten Sie, dass die URL, die für den Link Kontakt in der gerenderten Seite generiert wurde, die aktualisierte Route widerspiegelt:Note that the URL generated for the Contact link in the rendered page reflects the updated route:

Kontaktlink der Beispielanwendung in der Navigationsleiste

Beim Überprüfen des Kontaktlinks in der gerenderten HTML zeigt sich, dass das HREF-Attribut auf „/TheContactPage“ festgelegt wurde.

Sie können die Kontaktseite entweder über deren übliche Route, /Contact, oder über die benutzerdefinierte Route, /TheContactPage, besuchen.Visit the Contact page at either its ordinary route, /Contact, or the custom route, /TheContactPage. Wenn Sie ein zusätzliches text-Routensegment bereitstellen, wird dieses HTML-codierte Segment auf der Seite angezeigt:If you supply an additional text route segment, the page shows the HTML-encoded segment that you provide:

Beispiel für das Bereitstellen eines optionalen „Text“-Routensegments mit „TextValue“ in der URL in der Ansicht des Microsoft Edge-Browsers

Konventionen für SeitenmodellaktionenPage model action conventions

Der Standardanbieter für Seitenmodelle, der IPageApplicationModelProvider implementiert, ruft Konventionen auf, die entwickelt wurden, um Erweiterungspunkte zum Konfigurieren von Seitenmodellen bereitzustellen.The default page model provider that implements IPageApplicationModelProvider invokes conventions which are designed to provide extensibility points for configuring page models. Diese Konventionen sind beim Erstellen und Ändern von Seitenermittlungs- und Verarbeitungsszenarios hilfreich.These conventions are useful when building and modifying page discovery and processing scenarios.

In den Beispielen in diesem Abschnitt verwendet die Beispielanwendung eine AddHeaderAttribute-Klasse, also ein ResultFilterAttribute, das einen Antwortheader verwendet:For the examples in this section, the sample app uses an AddHeaderAttribute class, which is a ResultFilterAttribute, that applies a response header:

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

Das Beispiel veranschaulicht mithilfe von Konventionen, wie das Attribut auf alle Seiten in einem Ordner und auf eine Einzelseite angewendet werden kann.Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.

Ordner-App-ModellkonventionFolder app model convention

Verwenden Sie AddFolderApplicationModelConvention zum Erstellen und Hinzuzufügen einer IPageApplicationModelConvention, die eine Aktion für PageApplicationModel-Instanzen für alle Seiten im angegebenen Ordner aufruft.Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on PageApplicationModel instances for all pages under the specified folder.

Im Beispiel wird die Verwendung der AddFolderApplicationModelConvention durch Hinzufügen eines Headers, OtherPagesHeader, zu den Seiten im Ordner OtherPages der Anwendung veranschaulicht:The sample demonstrates the use of AddFolderApplicationModelConvention by adding a header, OtherPagesHeader, to the pages inside the OtherPages folder of the app:

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

Fordern Sie die Seite „Seite1“ der Beispielanwendung unter localhost:5000/OtherPages/Page1 an, und prüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:

Antwortheader der Seite „OtherPages/Seite1“ zeigt, dass der OtherPagesHeader hinzugefügt wurde.

Seiten-App-ModellkonventionPage app model convention

Verwenden Sie AddPageApplicationModelConvention zum Erstellen und Hinzuzufügen einer IPageApplicationModelConvention, die eine Aktion für das PageApplicationModel für die Seite mit dem angegebenen Namen aufruft.Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on the PageApplicationModel for the page with the specified name.

Im Beispiel wird das Verwenden von AddPageApplicationModelConvention durch Hinzufügen eines Headers, AboutHeader, auf der Seite „Info“ veranschaulicht:The sample demonstrates the use of AddPageApplicationModelConvention by adding a header, AboutHeader, to the About page:

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

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Antwortheader der Seite „Info“ zeigen, dass AboutHeader hinzugefügt wurde.

Konfigurieren eines FiltersConfigure a filter

Der angegebene Filter, der angewendet werden soll, wird mit ConfigureFilter konfiguriert.ConfigureFilter configures the specified filter to apply. Sie können Filterklassen selbst implementieren. In der Beispielanwendung wird jedoch gezeigt, wie Sie einen Filter in einen Lambdaausdruck implementieren. Dieser wird dann im Hintergrund als Zuordnungsinstanz implementiert, die einen Filter zurückgibt:You can implement a filter class, but the sample app shows how to implement a filter in a lambda expression, which is implemented behind-the-scenes as a factory that returns a filter:

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

Das Seiten-App-Modell wird verwendet, um den relativen Pfad für Segmente zu überprüfen, die zur Seite „Seite2“ im Ordner OtherPages führen.The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages folder. Wenn die Bedingung erfüllt ist, wird ein Header hinzugefügt.If the condition passes, a header is added. Wenn dies nicht der Fall ist, wird der EmptyFilter angewendet.If not, the EmptyFilter is applied.

EmptyFilter ist ein Aktionsfilter.EmptyFilter is an Action filter. Wenn der Pfad OtherPages/Page2 nicht enthält, hat der EmptyFilter, wie vorgesehen, keine Auswirkung, da Aktionsfilter von Razor Pages ignoriert werden.Since Action filters are ignored by Razor Pages, the EmptyFilter has no effect as intended if the path doesn't contain OtherPages/Page2.

Fordern Sie die Seite „Seite2“ der Beispielanwendung unter localhost:5000/OtherPages/Page2 an, und prüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:

Der Header „OtherPagesPage2Header“ wird zur Antwort für „Seite2“ hinzugefügt.

Konfigurieren einer FilterzuordnungsinstanzConfigure a filter factory

Mit ConfigureFilter wird die angegebene Zuordnungsinstanz so konfiguriert, dass sie Filter auf alle Razor Pages anwendet.ConfigureFilter configures the specified factory to apply filters to all Razor Pages.

Die Beispielanwendung bietet Ihnen die Möglichkeit des beispielhaften Verwendens einer Filterzuordnungsinstanz durch Hinzufügen des Headers FilterFactoryHeader zu den Seiten der Anwendung, der zwei Werte besitzt:The sample app provides an example of using a filter factory by adding a header, FilterFactoryHeader, with two values to the app's pages:

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

AddHeaderWithFactory.cs: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;
        }
    }
}

Fordern Sie die Seite „Info“ der Beispielanwendung unter localhost:5000/About an, und überprüfen Sie die Header, um das Ergebnis zu sehen:Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

Die Antwortheader der Seite „Info“ zeigen, dass zwei Header des Typs „FilterFactoryHeader“ hinzugefügt wurden.

Die MVC-Filter und der Seitenfilter (IPageFilter)MVC Filters and the Page filter (IPageFilter)

MVC-Aktionsfilter werden von Razor Pages ignoriert, da Razor Pages Handlermethoden verwenden.MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. Darüber hinaus stehen die folgenden MVC-Filtertypen zur Verfügung: Autorisierung, Ausnahme, Ressource und Ergebnis.Other types of MVC filters are available for you to use: Authorization, Exception, Resource, and Result. Weitere Informationen finden Sie im Thema Filter.For more information, see the Filters topic.

Der Seitenfilter (IPageFilter) ist ein Filter, der auf Razor Pages anwendbar ist.The Page filter (IPageFilter) is a filter that applies to Razor Pages. Weitere Informationen finden Sie unter Filtermethoden für Razor Pages.For more information, see Filter methods for Razor Pages.

Zusätzliche RessourcenAdditional resources