ASP.NET Core での Razor ページのルートとアプリの規則Razor Pages route and app conventions in ASP.NET Core

ページ ルートとアプリ モデル プロバイダーの規則を使用して、Razor ページ アプリでページのルーティング、検出、および処理を制御する方法について説明します。Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

個別のページにカスタムのページ ルートを構成する必要がある場合、このトピックで後述される「AddPageRoute convention」で、ページへのルーティングを構成します。When you need to configure custom page routes for individual pages, configure routing to pages with the AddPageRoute convention described later in this topic.

ページ ルートの指定、ルート セグメントの追加、ルートへのパラメーターの追加を行うには、ページの @page ディレクティブを使用します。To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. 詳しくは、「カスタム ルート」をご覧ください。For more information, see Custom routes.

ルート セグメントやパラメーター名として使用できない予約語がいくつかあります。There are reserved words that can't be used as route segments or parameter names. 詳しくは、ルーティング: ルーティングの予約名に関するページをご覧ください。For more information, see Routing: Reserved routing names.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

シナリオScenario このサンプルでは、次のデモを実行します。The sample demonstrates ...
モデルの規則Model conventions

Conventions.AddConventions.Add
  • IPageRouteModelConventionIPageRouteModelConvention
  • IPageApplicationModelConventionIPageApplicationModelConvention
  • IPageHandlerModelConventionIPageHandlerModelConvention
ルート テンプレートとヘッダーをアプリのページに追加します。Add a route template and header to an app's pages.
ページ ルート アクション規則Page route action conventions
  • AddFolderRouteModelConventionAddFolderRouteModelConvention
  • AddPageRouteModelConventionAddPageRouteModelConvention
  • AddPageRouteAddPageRoute
ルート テンプレートをフォルダー内のページおよび単一ページに追加します。Add a route template to pages in a folder and to a single page.
ページ モデル アクション規則Page model action conventions
  • AddFolderApplicationModelConventionAddFolderApplicationModelConvention
  • AddPageApplicationModelConventionAddPageApplicationModelConvention
  • ConfigureFilter (フィルター クラス、ラムダ式、またはフィルター ファクトリ)ConfigureFilter (filter class, lambda expression, or filter factory)
ヘッダーをフォルダー内のページに追加し、ヘッダーを単一ページに追加し、ヘッダーをアプリのページに追加するようにフィルター ファクトリを構成します。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.

Razor Pages の規則は、Startup.ConfigureServicesRazorPagesOptions を構成する AddRazorPages のオーバーロードを使用して構成されます。Razor Pages conventions are configured using an AddRazorPages overload that configures RazorPagesOptions in Startup.ConfigureServices. 次の規則の例は、このトピックで後述されます。The following convention examples are explained later in this topic:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages(options =>
    {
        options.Conventions.Add( ... );
        options.Conventions.AddFolderRouteModelConvention(
            "/OtherPages", model => { ... });
        options.Conventions.AddPageRouteModelConvention(
            "/About", model => { ... });
        options.Conventions.AddPageRoute(
            "/Contact", "TheContactPage/{text?}");
        options.Conventions.AddFolderApplicationModelConvention(
            "/OtherPages", model => { ... });
        options.Conventions.AddPageApplicationModelConvention(
            "/About", model => { ... });
        options.Conventions.ConfigureFilter(model => { ... });
        options.Conventions.ConfigureFilter( ... );
    });
}

ルートの順番Route order

ルートは、処理 (ルートの照合) に使われる順番 (Order) を指定します。Routes specify an Order for processing (route matching).

順番Order 動作Behavior
-1-1 ルートは、他のルートが処理される前に処理されます。The route is processed before other routes are processed.
00 順番が指定されていません (既定値)。Order isn't specified (default value). Order を割り当てない (Order = null) 場合、処理に使われるルートの Order は既定で 0 (ゼロ) になります。Not assigning Order (Order = null) defaults the route Order to 0 (zero) for processing.
1、2、… n1, 2, … n ルートの処理順序を指定します。Specifies the route processing order.

ルートの処理は、次の規則で定められています。Route processing is established by convention:

  • ルートは並んだ順番に処理されます (-1、0、1、2、… n)。Routes are processed in sequential order (-1, 0, 1, 2, … n).
  • ルートの Order が同じ場合は、最初に最も明確なルートが照合され、続けて次に明確なルートが照合されます。When routes have the same Order, the most specific route is matched first followed by less specific routes.
  • Order とパラメーター数が同じルートが 1 つの要求 URL と一致した場合、ルートは PageConventionCollection に追加された順番で処理されます。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.

可能であれば、定められたルートの処理順序に依存しないようにしてください。If possible, avoid depending on an established route processing order. 通常は、ルーティングによって、URL が一致する正しいルートが選択されます。Generally, routing selects the correct route with URL matching. 要求が正しくルーティングされるようにルートの Order プロパティを設定する必要がある場合、アプリのルーティング方式がクライアントにとって紛らわしいものとなり、保守が脆弱になる可能性があります。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. アプリのルーティング方式を簡略化するよう努めてください。Seek to simplify the app's routing scheme. サンプル アプリでは、1 つのアプリで複数のルーティング シナリオを示すために、ルートの明示的な処理順序が必要です。The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. ただし、運用環境のアプリでルートの Order を設定するやり方は避けるようにしてください。However, you should attempt to avoid the practice of setting route Order in production apps.

Razor Pages ルーティングと MVC コントローラー ルーティングは、実装を共有します。Razor Pages routing and MVC controller routing share an implementation. MVC のトピックに記載されているルートの順番については、コントローラー アクションへのルーティング: 属性ルートの順序の指定に関するページをご覧ください。Information on route order in the MVC topics is available at Routing to controller actions: Ordering attribute routes.

モデルの規則Model conventions

IPageConvention の委任を追加すると、Razor Pages に適用されるモデルの規則を追加できます。Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

すべてのページにルート モデル規則を追加するAdd a route model convention to all pages

Conventions を使用すると、IPageRouteModelConvention を作成して、ページ ルート モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

サンプル アプリでは、{globalTemplate?} ルート テンプレートをアプリ内のすべてのページに追加します。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?}"),
                }
            });
        }
    }
}

AttributeRouteModelOrder プロパティに 1 が設定されます。The Order property for the AttributeRouteModel is set to 1. これにより、サンプル アプリで次のルートの照合動作が保証されます。This ensures the following route matching behavior in the sample app:

  • TheContactPage/{text?} のルート テンプレートは、このトピックの後半で追加されます。A route template for TheContactPage/{text?} is added later in the topic. 連絡先ページのルートには既定の順番 null (Order = 0) が設定されているため、{globalTemplate?} ルート テンプレートの前に一致します。The Contact Page route has a default order of null (Order = 0), so it matches before the {globalTemplate?} route template.
  • {aboutTemplate?} ルート テンプレートは、このトピックの後半で追加されます。An {aboutTemplate?} route template is added later in the topic. {aboutTemplate?} テンプレートの Order には 2 が指定されます。The {aboutTemplate?} template is given an Order of 2. [About] ページが /About/RouteDataValue で要求されると、"RouteDataValue" は RouteData.Values["globalTemplate"] (Order = 1) に読み込まれ、Order プロパティが設定されるため RouteData.Values["aboutTemplate"] (Order = 2) には読み込まれません。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.
  • {otherPagesTemplate?} ルート テンプレートは、このトピックの後半で追加されます。An {otherPagesTemplate?} route template is added later in the topic. {otherPagesTemplate?} テンプレートの Order には 2 が指定されます。The {otherPagesTemplate?} template is given an Order of 2. ルート パラメーター (/OtherPages/Page1/RouteDataValue など) を使用して Pages/OtherPages フォルダー内のいずれかのページが要求されると、Order プロパティが設定されているため、"RouteDataValue" が RouteData.Values["otherPagesTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

Razor Pages のオプション (Conventions の追加など) は、Razor Pages が Startup.ConfigureServices のサービス コレクションに追加されたときに追加されます。Razor Pages options, such as adding Conventions, are added when Razor Pages is added to the service collection in Startup.ConfigureServices. 例については、サンプル アプリを参照してください。For an example, see the sample app.

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

localhost:5000/About/GlobalRouteValue でサンプルの [About] ページを要求し、その結果を調べます。Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:

[About] ページは、GlobalRouteValue のルート セグメントで要求されます。

すべてのページにアプリ モデル規則を追加するAdd an app model convention to all pages

Conventions を使用すると、IPageApplicationModelConvention を作成して、ページ アプリ モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention instances that are applied during page app model construction.

この規則やこのトピックで後述されるその他の規則のデモを実行するには、サンプル アプリに AddHeaderAttribute クラスを含めます。To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class. クラス コンストラクターは、name 文字列と values 文字列配列を受け入れます。The class constructor accepts a name string and a values string array. これらの値は、応答ヘッダーを設定するために、その OnResultExecuting メソッド内で使用されます。These values are used in its OnResultExecuting method to set a response header. 完全クラスは、このトピックで後述される「ページ モデル アクション規則」セクションで示されます。The full class is shown in the Page model action conventions section later in the topic.

サンプル アプリでは、AddHeaderAttribute クラスを使用して、ヘッダー (GlobalHeader) をアプリ内のすべてのページに追加します。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());

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、GlobalHeader が追加されたことを示しています。

すべてのページにハンドラー モデル規則を追加するAdd a handler model convention to all pages

Conventions を使用すると、IPageHandlerModelConvention を作成して、ページ ハンドラー モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。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());

ページ ルート アクション規則Page route action conventions

IPageRouteModelProvider から派生する既定のルート モデル プロバイダーは、ページ ルートを構成するための拡張ポイントを提供するようにデザインされた規則を呼び出します。The default route model provider that derives from IPageRouteModelProvider invokes conventions which are designed to provide extensibility points for configuring page routes.

フォルダー ルート モデル規則Folder route model convention

AddFolderRouteModelConvention を使用すると、指定したフォルダーの下にあるすべてのページを対象に PageRouteModel へのアクションを呼び出す IPageRouteModelConvention を作成して追加できます。Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for all of the pages under the specified folder.

サンプル アプリでは AddFolderRouteModelConvention を使用して、{otherPagesTemplate?} ルート テンプレートを OtherPages フォルダーのページに追加します。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?}"),
            }
        });
    }
});

AttributeRouteModelOrder プロパティに 2 が設定されます。The Order property for the AttributeRouteModel is set to 2. この設定により、1 つのルート値が指定されたときに、(このトピックの前半で 1 に設定した) {globalTemplate?} のテンプレートが優先的に最初のルート データ値の位置に指定されます。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. ルート パラメーター値 (/OtherPages/Page1/RouteDataValue など) を使用して Pages/OtherPages フォルダー内のページが要求されると、Order プロパティが設定されているため、"RouteDataValue" が RouteData.Values["otherPagesTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue でサンプルの Page1 ページを要求し、その結果を調べます。Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and inspect the result:

OtherPages フォルダーの Page1 は、GlobalRouteValue と OtherPagesRouteValue のルート セグメントで要求されます。

ページ ルート モデル規則Page route model convention

AddPageRouteModelConvention を使用すると、指定した名前のページを対象に PageRouteModel へのアクションを呼び出す IPageRouteModelConvention を作成して追加できます。Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for the page with the specified name.

サンプル アプリでは AddPageRouteModelConvention を使用して、{aboutTemplate?} ルート テンプレートを [About] ページに追加します。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?}"),
            }
        });
    }
});

AttributeRouteModelOrder プロパティに 2 が設定されます。The Order property for the AttributeRouteModel is set to 2. この設定により、1 つのルート値が指定されたときに、(このトピックの前半で 1 に設定した) {globalTemplate?} のテンプレートが優先的に最初のルート データ値の位置に指定されます。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. [About] ページが /About/RouteDataValue にあるルート パラメーター値で要求されると、Order プロパティが設定されているため、"RouteDataValue" は RouteData.Values["aboutTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

localhost:5000/About/GlobalRouteValue/AboutRouteValue でサンプルの [About] ページを要求し、その結果を調べます。Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

[About] ページは、GlobalRouteValue と AboutRouteValue のルート セグメントで要求されます。

パラメーター トランスフォーマーを使用してページ ルートをカスタマイズするUse a parameter transformer to customize page routes

ASP.NET Core によって生成されたページ ルートは、パラメーター トランスフォーマーを使用してカスタマイズできます。Page routes generated by ASP.NET Core can be customized using a parameter transformer. パラメーター トランスフォーマーは IOutboundParameterTransformer を実装し、パラメーターの値を変換します。A parameter transformer implements IOutboundParameterTransformer and transforms the value of parameters. たとえば、SlugifyParameterTransformer パラメーター トランスフォーマーでは、SubscriptionManagement のルート値が subscription-management に変更されます。For example, a custom SlugifyParameterTransformer parameter transformer changes the SubscriptionManagement route value to subscription-management.

PageRouteTransformerConvention ページ ルート モデル規則では、アプリで自動的に生成されたページ ルートのフォルダー名とファイル名のセグメントにパラメーター トランスフォーマーを適用します。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. たとえば、 /Pages/SubscriptionManagement/ViewAll.cshtml にある Razor ページ ファイルのルートは /SubscriptionManagement/ViewAll から /subscription-management/view-all に書き換えられます。For example, the Razor Pages file at /Pages/SubscriptionManagement/ViewAll.cshtml would have its route rewritten from /SubscriptionManagement/ViewAll to /subscription-management/view-all.

PageRouteTransformerConvention では、Razor ページのフォルダー名とファイル名に由来する、自動的に生成されたページ ルートのセグメントのみを変換します。PageRouteTransformerConvention only transforms the automatically generated segments of a page route that come from the Razor Pages folder and file name. @page ディレクティブを使用して追加したルート セグメントは変換されません。It doesn't transform route segments added with the @page directive. この規則では、AddPageRoute で追加したルートも変換されません。The convention also doesn't transform routes added by AddPageRoute.

PageRouteTransformerConvention は、Startup.ConfigureServices でオプションとして登録されます。The PageRouteTransformerConvention is registered as an option in Startup.ConfigureServices:

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

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

警告

System.Text.RegularExpressions を使用して信頼できない入力を処理するときは、タイムアウトを渡します。When using System.Text.RegularExpressions to process untrusted input, pass a timeout. 悪意のあるユーザーが RegularExpressions に入力を提供して、サービス拒否攻撃を行う可能性があります。A malicious user can provide input to RegularExpressions causing a Denial-of-Service attack. RegularExpressions を使用する ASP.NET Core フレームワーク API は、タイムアウトを渡します。ASP.NET Core framework APIs that use RegularExpressions pass a timeout.

ページ ルートの構成Configure a page route

AddPageRoute を使用すると、指定したページ パスにあるページへのルートを構成できます。Use AddPageRoute to configure a route to a page at the specified page path. そのページに対して生成されたリンクでは、指定したルートを使用します。Generated links to the page use your specified route. AddPageRoute では、AddPageRouteModelConvention を使用してルートを確立します。AddPageRoute uses AddPageRouteModelConvention to establish the route.

サンプル アプリでは、Contact.cshtml/TheContactPage へのルートを作成します。The sample app creates a route to /TheContactPage for Contact.cshtml:

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

[Contact] ページには、既定のルート経由の /Contact でアクセスすることもできます。The Contact page can also be reached at /Contact via its default route.

サンプル アプリの [Contact] ページに対するカスタム ルートでは、省略可能な text ルート セグメント ({text?}) を許可します。The sample app's custom route to the Contact page allows for an optional text route segment ({text?}). また、訪問者が /Contact ルートでページにアクセスする場合、ページの @page ディレクティブにはこの省略可能なセグメントも含まれます。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>

レンダリングされたページの Contact リンク用に生成された URL には、更新されたルートが反映されることに注意してください。Note that the URL generated for the Contact link in the rendered page reflects the updated route:

ナビゲーション バーのサンプル アプリの [Contact] リンク

レンダリングされた HTML の [Contact] リンクを調べると、href に '/TheContactPage' が設定されています

通常のルート (/Contact) またはカスタム ルート (/TheContactPage) のいずれかで、[Contact] ページにアクセスします。Visit the Contact page at either its ordinary route, /Contact, or the custom route, /TheContactPage. 追加の text ルート セグメントを指定した場合、ページには指定した HTML エンコードのセグメントが示されます。If you supply an additional text route segment, the page shows the HTML-encoded segment that you provide:

URL の 'TextValue' の省略可能な 'text' ルート セグメントを適用する Microsoft Edge ブラウザーの例。

ページ モデル アクション規則Page model action conventions

IPageApplicationModelProvider を実装する既定のページ モデル プロバイダーは、ページ モデルを構成するための拡張ポイントを提供するようにデザインされた規則を呼び出します。The default page model provider that implements IPageApplicationModelProvider invokes conventions which are designed to provide extensibility points for configuring page models. これらの規則は、ページ検出をビルドおよび変更したり、シナリオを処理したりするときに便利です。These conventions are useful when building and modifying page discovery and processing scenarios.

このセクションの例の場合、サンプル アプリでは、応答ヘッダーを適用する ResultFilterAttribute である、AddHeaderAttribute クラスを使用します。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);
    }
}

規則を使用して、このサンプルでは、フォルダー内のすべてのページおよび単一ページに属性を適用する方法のデモを実行します。Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.

フォルダー アプリ モデル規則Folder app model convention

AddFolderApplicationModelConvention を使用すると、指定したフォルダーの下にあるすべてのページを対象に PageApplicationModel インスタンスへのアクションを呼び出す IPageApplicationModelConvention を作成して追加できます。Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on PageApplicationModel instances for all pages under the specified folder.

このサンプルでは、ヘッダー (OtherPagesHeader) をアプリの OtherPages フォルダー内にあるページに追加して、AddFolderApplicationModelConvention を使用するデモを実行します。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" }));
});

localhost:5000/OtherPages/Page1 でサンプルの Page1 ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:

OtherPages/Page1 ページの応答ヘッダーは、OtherPagesHeader が追加されていることを示しています。

ページ アプリ モデル規則Page app model convention

AddPageApplicationModelConvention を使用すると、指定した名前のページを対象に PageApplicationModel へのアクションを呼び出す IPageApplicationModelConvention を作成して追加できます。Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on the PageApplicationModel for the page with the specified name.

サンプルでは、ヘッダー (AboutHeader) を [About] ページに追加して、AddPageApplicationModelConvention を使用するデモを実行します。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" }));
});

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、AboutHeader が追加されたことを示しています。

フィルターの構成Configure a filter

ConfigureFilter では、指定したフィルターを適用するように構成します。ConfigureFilter configures the specified filter to apply. フィルター クラスを実装できますが、サンプル アプリでは、ラムダ式でフィルターを実装する方法を示しています。これは、フィルターを返すファクトリとしてバックグラウンドで実装されます。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();
});

ページ アプリ モデルは、OtherPages フォルダーの Page2 ページにつながるセグメントの相対パスを確認するために使用されます。The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages folder. 条件を満たすと、ヘッダーが追加されます。If the condition passes, a header is added. 満たさない場合は、EmptyFilter が適用されます。If not, the EmptyFilter is applied.

EmptyFilterアクション フィルターです。EmptyFilter is an Action filter. アクション フィルターは Razor Pages によって無視されるため、パスに OtherPages/Page2 が含まれない場合、EmptyFilter には意図されたような効果はありません。Since Action filters are ignored by Razor Pages, the EmptyFilter has no effect as intended if the path doesn't contain OtherPages/Page2.

localhost:5000/OtherPages/Page2 でサンプルの Page2 ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:

OtherPagesPage2Header は、Page2 への応答に追加されます。

フィルター ファクトリの構成Configure a filter factory

ConfigureFilter では、すべての Razor Pages にフィルターを適用するように、指定したファクトリを構成します。ConfigureFilter configures the specified factory to apply filters to all Razor Pages.

サンプル アプリでは、アプリのページに対する 2 つの値と共にヘッダー (FilterFactoryHeader) を追加して、フィルター ファクトリを使用する例を提供します。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;
        }
    }
}

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、FilterFactoryHeader ヘッダーが 2 つ追加されたことを示しています。

MVC フィルターとページ フィルター (IPageFilter)MVC Filters and the Page filter (IPageFilter)

Razor Pages はハンドラー メソッドを使用するため、MVC アクション フィルターは Razor Pages によって無視されます。MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. 使用できるその他の種類の MVC フィルターは次のとおりです。承認例外リソース、および結果Other types of MVC filters are available for you to use: Authorization, Exception, Resource, and Result. 詳細については、「フィルター」トピックを参照してください。For more information, see the Filters topic.

ページ フィルター (IPageFilter) は、Razor Pages に適用されるフィルターの 1 つです。The Page filter (IPageFilter) is a filter that applies to Razor Pages. 詳細については、Razor Pages のフィルター メソッドに関するページを参照してください。For more information, see Filter methods for Razor Pages.

その他の技術情報Additional resources

ページ ルートとアプリ モデル プロバイダーの規則を使用して、Razor ページ アプリでページのルーティング、検出、および処理を制御する方法について説明します。Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

個別のページにカスタムのページ ルートを構成する必要がある場合、このトピックで後述される「AddPageRoute convention」で、ページへのルーティングを構成します。When you need to configure custom page routes for individual pages, configure routing to pages with the AddPageRoute convention described later in this topic.

ページ ルートの指定、ルート セグメントの追加、ルートへのパラメーターの追加を行うには、ページの @page ディレクティブを使用します。To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. 詳しくは、「カスタム ルート」をご覧ください。For more information, see Custom routes.

ルート セグメントやパラメーター名として使用できない予約語がいくつかあります。There are reserved words that can't be used as route segments or parameter names. 詳しくは、ルーティング: ルーティングの予約名に関するページをご覧ください。For more information, see Routing: Reserved routing names.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

シナリオScenario このサンプルでは、次のデモを実行します。The sample demonstrates ...
モデルの規則Model conventions

Conventions.AddConventions.Add
  • IPageRouteModelConventionIPageRouteModelConvention
  • IPageApplicationModelConventionIPageApplicationModelConvention
  • IPageHandlerModelConventionIPageHandlerModelConvention
ルート テンプレートとヘッダーをアプリのページに追加します。Add a route template and header to an app's pages.
ページ ルート アクション規則Page route action conventions
  • AddFolderRouteModelConventionAddFolderRouteModelConvention
  • AddPageRouteModelConventionAddPageRouteModelConvention
  • AddPageRouteAddPageRoute
ルート テンプレートをフォルダー内のページおよび単一ページに追加します。Add a route template to pages in a folder and to a single page.
ページ モデル アクション規則Page model action conventions
  • AddFolderApplicationModelConventionAddFolderApplicationModelConvention
  • AddPageApplicationModelConventionAddPageApplicationModelConvention
  • ConfigureFilter (フィルター クラス、ラムダ式、またはフィルター ファクトリ)ConfigureFilter (filter class, lambda expression, or filter factory)
ヘッダーをフォルダー内のページに追加し、ヘッダーを単一ページに追加し、ヘッダーをアプリのページに追加するようにフィルター ファクトリを構成します。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.

Razor ページの規則を追加および構成するには、Startup クラス内のサービス コレクションの AddMvcAddRazorPagesOptions 拡張メソッドを使用します。Razor Pages conventions are added and configured using the AddRazorPagesOptions extension method to AddMvc on the service collection in the Startup class. 次の規則の例は、このトピックで後述されます。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( ... );
        });
}

ルートの順番Route order

ルートは、処理 (ルートの照合) に使われる順番 (Order) を指定します。Routes specify an Order for processing (route matching).

順番Order 動作Behavior
-1-1 ルートは、他のルートが処理される前に処理されます。The route is processed before other routes are processed.
00 順番が指定されていません (既定値)。Order isn't specified (default value). Order を割り当てない (Order = null) 場合、処理に使われるルートの Order は既定で 0 (ゼロ) になります。Not assigning Order (Order = null) defaults the route Order to 0 (zero) for processing.
1、2、… n1, 2, … n ルートの処理順序を指定します。Specifies the route processing order.

ルートの処理は、次の規則で定められています。Route processing is established by convention:

  • ルートは並んだ順番に処理されます (-1、0、1、2、… n)。Routes are processed in sequential order (-1, 0, 1, 2, … n).
  • ルートの Order が同じ場合は、最初に最も明確なルートが照合され、続けて次に明確なルートが照合されます。When routes have the same Order, the most specific route is matched first followed by less specific routes.
  • Order とパラメーター数が同じルートが 1 つの要求 URL と一致した場合、ルートは PageConventionCollection に追加された順番で処理されます。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.

可能であれば、定められたルートの処理順序に依存しないようにしてください。If possible, avoid depending on an established route processing order. 通常は、ルーティングによって、URL が一致する正しいルートが選択されます。Generally, routing selects the correct route with URL matching. 要求が正しくルーティングされるようにルートの Order プロパティを設定する必要がある場合、アプリのルーティング方式がクライアントにとって紛らわしいものとなり、保守が脆弱になる可能性があります。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. アプリのルーティング方式を簡略化するよう努めてください。Seek to simplify the app's routing scheme. サンプル アプリでは、1 つのアプリで複数のルーティング シナリオを示すために、ルートの明示的な処理順序が必要です。The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. ただし、運用環境のアプリでルートの Order を設定するやり方は避けるようにしてください。However, you should attempt to avoid the practice of setting route Order in production apps.

Razor Pages ルーティングと MVC コントローラー ルーティングは、実装を共有します。Razor Pages routing and MVC controller routing share an implementation. MVC のトピックに記載されているルートの順番については、コントローラー アクションへのルーティング: 属性ルートの順序の指定に関するページをご覧ください。Information on route order in the MVC topics is available at Routing to controller actions: Ordering attribute routes.

モデルの規則Model conventions

IPageConvention の委任を追加すると、Razor Pages に適用されるモデルの規則を追加できます。Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

すべてのページにルート モデル規則を追加するAdd a route model convention to all pages

Conventions を使用すると、IPageRouteModelConvention を作成して、ページ ルート モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

サンプル アプリでは、{globalTemplate?} ルート テンプレートをアプリ内のすべてのページに追加します。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?}"),
                }
            });
        }
    }
}

AttributeRouteModelOrder プロパティに 1 が設定されます。The Order property for the AttributeRouteModel is set to 1. これにより、サンプル アプリで次のルートの照合動作が保証されます。This ensures the following route matching behavior in the sample app:

  • TheContactPage/{text?} のルート テンプレートは、このトピックの後半で追加されます。A route template for TheContactPage/{text?} is added later in the topic. 連絡先ページのルートには既定の順番 null (Order = 0) が設定されているため、{globalTemplate?} ルート テンプレートの前に一致します。The Contact Page route has a default order of null (Order = 0), so it matches before the {globalTemplate?} route template.
  • {aboutTemplate?} ルート テンプレートは、このトピックの後半で追加されます。An {aboutTemplate?} route template is added later in the topic. {aboutTemplate?} テンプレートの Order には 2 が指定されます。The {aboutTemplate?} template is given an Order of 2. [About] ページが /About/RouteDataValue で要求されると、"RouteDataValue" は RouteData.Values["globalTemplate"] (Order = 1) に読み込まれ、Order プロパティが設定されるため RouteData.Values["aboutTemplate"] (Order = 2) には読み込まれません。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.
  • {otherPagesTemplate?} ルート テンプレートは、このトピックの後半で追加されます。An {otherPagesTemplate?} route template is added later in the topic. {otherPagesTemplate?} テンプレートの Order には 2 が指定されます。The {otherPagesTemplate?} template is given an Order of 2. ルート パラメーター (/OtherPages/Page1/RouteDataValue など) を使用して Pages/OtherPages フォルダー内のいずれかのページが要求されると、Order プロパティが設定されているため、"RouteDataValue" が RouteData.Values["otherPagesTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

Razor Pages のオプション (Conventions の追加など) は、MVC が Startup.ConfigureServices のサービス コレクションに追加されたときに追加されます。Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices. 例については、サンプル アプリを参照してください。For an example, see the sample app.

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

localhost:5000/About/GlobalRouteValue でサンプルの [About] ページを要求し、その結果を調べます。Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:

[About] ページは、GlobalRouteValue のルート セグメントで要求されます。

すべてのページにアプリ モデル規則を追加するAdd an app model convention to all pages

Conventions を使用すると、IPageApplicationModelConvention を作成して、ページ アプリ モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention instances that are applied during page app model construction.

この規則やこのトピックで後述されるその他の規則のデモを実行するには、サンプル アプリに AddHeaderAttribute クラスを含めます。To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class. クラス コンストラクターは、name 文字列と values 文字列配列を受け入れます。The class constructor accepts a name string and a values string array. これらの値は、応答ヘッダーを設定するために、その OnResultExecuting メソッド内で使用されます。These values are used in its OnResultExecuting method to set a response header. 完全クラスは、このトピックで後述される「ページ モデル アクション規則」セクションで示されます。The full class is shown in the Page model action conventions section later in the topic.

サンプル アプリでは、AddHeaderAttribute クラスを使用して、ヘッダー (GlobalHeader) をアプリ内のすべてのページに追加します。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());

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、GlobalHeader が追加されたことを示しています。

すべてのページにハンドラー モデル規則を追加するAdd a handler model convention to all pages

Conventions を使用すると、IPageHandlerModelConvention を作成して、ページ ハンドラー モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。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());

ページ ルート アクション規則Page route action conventions

IPageRouteModelProvider から派生する既定のルート モデル プロバイダーは、ページ ルートを構成するための拡張ポイントを提供するようにデザインされた規則を呼び出します。The default route model provider that derives from IPageRouteModelProvider invokes conventions which are designed to provide extensibility points for configuring page routes.

フォルダー ルート モデル規則Folder route model convention

AddFolderRouteModelConvention を使用すると、指定したフォルダーの下にあるすべてのページを対象に PageRouteModel へのアクションを呼び出す IPageRouteModelConvention を作成して追加できます。Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for all of the pages under the specified folder.

サンプル アプリでは AddFolderRouteModelConvention を使用して、{otherPagesTemplate?} ルート テンプレートを OtherPages フォルダーのページに追加します。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?}"),
            }
        });
    }
});

AttributeRouteModelOrder プロパティに 2 が設定されます。The Order property for the AttributeRouteModel is set to 2. この設定により、1 つのルート値が指定されたときに、(このトピックの前半で 1 に設定した) {globalTemplate?} のテンプレートが優先的に最初のルート データ値の位置に指定されます。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. ルート パラメーター値 (/OtherPages/Page1/RouteDataValue など) を使用して Pages/OtherPages フォルダー内のページが要求されると、Order プロパティが設定されているため、"RouteDataValue" が RouteData.Values["otherPagesTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue でサンプルの Page1 ページを要求し、その結果を調べます。Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and inspect the result:

OtherPages フォルダーの Page1 は、GlobalRouteValue と OtherPagesRouteValue のルート セグメントで要求されます。

ページ ルート モデル規則Page route model convention

AddPageRouteModelConvention を使用すると、指定した名前のページを対象に PageRouteModel へのアクションを呼び出す IPageRouteModelConvention を作成して追加できます。Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for the page with the specified name.

サンプル アプリでは AddPageRouteModelConvention を使用して、{aboutTemplate?} ルート テンプレートを [About] ページに追加します。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?}"),
            }
        });
    }
});

AttributeRouteModelOrder プロパティに 2 が設定されます。The Order property for the AttributeRouteModel is set to 2. この設定により、1 つのルート値が指定されたときに、(このトピックの前半で 1 に設定した) {globalTemplate?} のテンプレートが優先的に最初のルート データ値の位置に指定されます。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. [About] ページが /About/RouteDataValue にあるルート パラメーター値で要求されると、Order プロパティが設定されているため、"RouteDataValue" は RouteData.Values["aboutTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

localhost:5000/About/GlobalRouteValue/AboutRouteValue でサンプルの [About] ページを要求し、その結果を調べます。Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

[About] ページは、GlobalRouteValue と AboutRouteValue のルート セグメントで要求されます。

パラメーター トランスフォーマーを使用してページ ルートをカスタマイズするUse a parameter transformer to customize page routes

ASP.NET Core によって生成されたページ ルートは、パラメーター トランスフォーマーを使用してカスタマイズできます。Page routes generated by ASP.NET Core can be customized using a parameter transformer. パラメーター トランスフォーマーは IOutboundParameterTransformer を実装し、パラメーターの値を変換します。A parameter transformer implements IOutboundParameterTransformer and transforms the value of parameters. たとえば、SlugifyParameterTransformer パラメーター トランスフォーマーでは、SubscriptionManagement のルート値が subscription-management に変更されます。For example, a custom SlugifyParameterTransformer parameter transformer changes the SubscriptionManagement route value to subscription-management.

PageRouteTransformerConvention ページ ルート モデル規則では、アプリで自動的に生成されたページ ルートのフォルダー名とファイル名のセグメントにパラメーター トランスフォーマーを適用します。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. たとえば、 /Pages/SubscriptionManagement/ViewAll.cshtml にある Razor ページ ファイルのルートは /SubscriptionManagement/ViewAll から /subscription-management/view-all に書き換えられます。For example, the Razor Pages file at /Pages/SubscriptionManagement/ViewAll.cshtml would have its route rewritten from /SubscriptionManagement/ViewAll to /subscription-management/view-all.

PageRouteTransformerConvention では、Razor ページのフォルダー名とファイル名に由来する、自動的に生成されたページ ルートのセグメントのみを変換します。PageRouteTransformerConvention only transforms the automatically generated segments of a page route that come from the Razor Pages folder and file name. @page ディレクティブを使用して追加したルート セグメントは変換されません。It doesn't transform route segments added with the @page directive. この規則では、AddPageRoute で追加したルートも変換されません。The convention also doesn't transform routes added by AddPageRoute.

PageRouteTransformerConvention は、Startup.ConfigureServices でオプションとして登録されます。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();
    }
}

ページ ルートの構成Configure a page route

AddPageRoute を使用すると、指定したページ パスにあるページへのルートを構成できます。Use AddPageRoute to configure a route to a page at the specified page path. そのページに対して生成されたリンクでは、指定したルートを使用します。Generated links to the page use your specified route. AddPageRoute では、AddPageRouteModelConvention を使用してルートを確立します。AddPageRoute uses AddPageRouteModelConvention to establish the route.

サンプル アプリでは、Contact.cshtml/TheContactPage へのルートを作成します。The sample app creates a route to /TheContactPage for Contact.cshtml:

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

[Contact] ページには、既定のルート経由の /Contact でアクセスすることもできます。The Contact page can also be reached at /Contact via its default route.

サンプル アプリの [Contact] ページに対するカスタム ルートでは、省略可能な text ルート セグメント ({text?}) を許可します。The sample app's custom route to the Contact page allows for an optional text route segment ({text?}). また、訪問者が /Contact ルートでページにアクセスする場合、ページの @page ディレクティブにはこの省略可能なセグメントも含まれます。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>

レンダリングされたページの Contact リンク用に生成された URL には、更新されたルートが反映されることに注意してください。Note that the URL generated for the Contact link in the rendered page reflects the updated route:

ナビゲーション バーのサンプル アプリの [Contact] リンク

レンダリングされた HTML の [Contact] リンクを調べると、href に '/TheContactPage' が設定されています

通常のルート (/Contact) またはカスタム ルート (/TheContactPage) のいずれかで、[Contact] ページにアクセスします。Visit the Contact page at either its ordinary route, /Contact, or the custom route, /TheContactPage. 追加の text ルート セグメントを指定した場合、ページには指定した HTML エンコードのセグメントが示されます。If you supply an additional text route segment, the page shows the HTML-encoded segment that you provide:

URL の 'TextValue' の省略可能な 'text' ルート セグメントを適用する Microsoft Edge ブラウザーの例。

ページ モデル アクション規則Page model action conventions

IPageApplicationModelProvider を実装する既定のページ モデル プロバイダーは、ページ モデルを構成するための拡張ポイントを提供するようにデザインされた規則を呼び出します。The default page model provider that implements IPageApplicationModelProvider invokes conventions which are designed to provide extensibility points for configuring page models. これらの規則は、ページ検出をビルドおよび変更したり、シナリオを処理したりするときに便利です。These conventions are useful when building and modifying page discovery and processing scenarios.

このセクションの例の場合、サンプル アプリでは、応答ヘッダーを適用する ResultFilterAttribute である、AddHeaderAttribute クラスを使用します。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);
    }
}

規則を使用して、このサンプルでは、フォルダー内のすべてのページおよび単一ページに属性を適用する方法のデモを実行します。Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.

フォルダー アプリ モデル規則Folder app model convention

AddFolderApplicationModelConvention を使用すると、指定したフォルダーの下にあるすべてのページを対象に PageApplicationModel インスタンスへのアクションを呼び出す IPageApplicationModelConvention を作成して追加できます。Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on PageApplicationModel instances for all pages under the specified folder.

このサンプルでは、ヘッダー (OtherPagesHeader) をアプリの OtherPages フォルダー内にあるページに追加して、AddFolderApplicationModelConvention を使用するデモを実行します。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" }));
});

localhost:5000/OtherPages/Page1 でサンプルの Page1 ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:

OtherPages/Page1 ページの応答ヘッダーは、OtherPagesHeader が追加されていることを示しています。

ページ アプリ モデル規則Page app model convention

AddPageApplicationModelConvention を使用すると、指定した名前のページを対象に PageApplicationModel へのアクションを呼び出す IPageApplicationModelConvention を作成して追加できます。Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on the PageApplicationModel for the page with the specified name.

サンプルでは、ヘッダー (AboutHeader) を [About] ページに追加して、AddPageApplicationModelConvention を使用するデモを実行します。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" }));
});

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、AboutHeader が追加されたことを示しています。

フィルターの構成Configure a filter

ConfigureFilter では、指定したフィルターを適用するように構成します。ConfigureFilter configures the specified filter to apply. フィルター クラスを実装できますが、サンプル アプリでは、ラムダ式でフィルターを実装する方法を示しています。これは、フィルターを返すファクトリとしてバックグラウンドで実装されます。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();
});

ページ アプリ モデルは、OtherPages フォルダーの Page2 ページにつながるセグメントの相対パスを確認するために使用されます。The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages folder. 条件を満たすと、ヘッダーが追加されます。If the condition passes, a header is added. 満たさない場合は、EmptyFilter が適用されます。If not, the EmptyFilter is applied.

EmptyFilterアクション フィルターです。EmptyFilter is an Action filter. アクション フィルターは Razor Pages によって無視されるため、パスに OtherPages/Page2 が含まれない場合、EmptyFilter には意図されたような効果はありません。Since Action filters are ignored by Razor Pages, the EmptyFilter has no effect as intended if the path doesn't contain OtherPages/Page2.

localhost:5000/OtherPages/Page2 でサンプルの Page2 ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:

OtherPagesPage2Header は、Page2 への応答に追加されます。

フィルター ファクトリの構成Configure a filter factory

ConfigureFilter では、すべての Razor Pages にフィルターを適用するように、指定したファクトリを構成します。ConfigureFilter configures the specified factory to apply filters to all Razor Pages.

サンプル アプリでは、アプリのページに対する 2 つの値と共にヘッダー (FilterFactoryHeader) を追加して、フィルター ファクトリを使用する例を提供します。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;
        }
    }
}

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、FilterFactoryHeader ヘッダーが 2 つ追加されたことを示しています。

MVC フィルターとページ フィルター (IPageFilter)MVC Filters and the Page filter (IPageFilter)

Razor Pages はハンドラー メソッドを使用するため、MVC アクション フィルターは Razor Pages によって無視されます。MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. 使用できるその他の種類の MVC フィルターは次のとおりです。承認例外リソース、および結果Other types of MVC filters are available for you to use: Authorization, Exception, Resource, and Result. 詳細については、「フィルター」トピックを参照してください。For more information, see the Filters topic.

ページ フィルター (IPageFilter) は、Razor Pages に適用されるフィルターの 1 つです。The Page filter (IPageFilter) is a filter that applies to Razor Pages. 詳細については、Razor Pages のフィルター メソッドに関するページを参照してください。For more information, see Filter methods for Razor Pages.

その他の技術情報Additional resources

ページ ルートとアプリ モデル プロバイダーの規則を使用して、Razor ページ アプリでページのルーティング、検出、および処理を制御する方法について説明します。Learn how to use page route and app model provider conventions to control page routing, discovery, and processing in Razor Pages apps.

個別のページにカスタムのページ ルートを構成する必要がある場合、このトピックで後述される「AddPageRoute convention」で、ページへのルーティングを構成します。When you need to configure custom page routes for individual pages, configure routing to pages with the AddPageRoute convention described later in this topic.

ページ ルートの指定、ルート セグメントの追加、ルートへのパラメーターの追加を行うには、ページの @page ディレクティブを使用します。To specify a page route, add route segments, or add parameters to a route, use the page's @page directive. 詳しくは、「カスタム ルート」をご覧ください。For more information, see Custom routes.

ルート セグメントやパラメーター名として使用できない予約語がいくつかあります。There are reserved words that can't be used as route segments or parameter names. 詳しくは、ルーティング: ルーティングの予約名に関するページをご覧ください。For more information, see Routing: Reserved routing names.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

シナリオScenario このサンプルでは、次のデモを実行します。The sample demonstrates ...
モデルの規則Model conventions

Conventions.AddConventions.Add
  • IPageRouteModelConventionIPageRouteModelConvention
  • IPageApplicationModelConventionIPageApplicationModelConvention
  • IPageHandlerModelConventionIPageHandlerModelConvention
ルート テンプレートとヘッダーをアプリのページに追加します。Add a route template and header to an app's pages.
ページ ルート アクション規則Page route action conventions
  • AddFolderRouteModelConventionAddFolderRouteModelConvention
  • AddPageRouteModelConventionAddPageRouteModelConvention
  • AddPageRouteAddPageRoute
ルート テンプレートをフォルダー内のページおよび単一ページに追加します。Add a route template to pages in a folder and to a single page.
ページ モデル アクション規則Page model action conventions
  • AddFolderApplicationModelConventionAddFolderApplicationModelConvention
  • AddPageApplicationModelConventionAddPageApplicationModelConvention
  • ConfigureFilter (フィルター クラス、ラムダ式、またはフィルター ファクトリ)ConfigureFilter (filter class, lambda expression, or filter factory)
ヘッダーをフォルダー内のページに追加し、ヘッダーを単一ページに追加し、ヘッダーをアプリのページに追加するようにフィルター ファクトリを構成します。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.

Razor ページの規則を追加および構成するには、Startup クラス内のサービス コレクションの AddMvcAddRazorPagesOptions 拡張メソッドを使用します。Razor Pages conventions are added and configured using the AddRazorPagesOptions extension method to AddMvc on the service collection in the Startup class. 次の規則の例は、このトピックで後述されます。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( ... );
        });
}

ルートの順番Route order

ルートは、処理 (ルートの照合) に使われる順番 (Order) を指定します。Routes specify an Order for processing (route matching).

順番Order 動作Behavior
-1-1 ルートは、他のルートが処理される前に処理されます。The route is processed before other routes are processed.
00 順番が指定されていません (既定値)。Order isn't specified (default value). Order を割り当てない (Order = null) 場合、処理に使われるルートの Order は既定で 0 (ゼロ) になります。Not assigning Order (Order = null) defaults the route Order to 0 (zero) for processing.
1、2、… n1, 2, … n ルートの処理順序を指定します。Specifies the route processing order.

ルートの処理は、次の規則で定められています。Route processing is established by convention:

  • ルートは並んだ順番に処理されます (-1、0、1、2、… n)。Routes are processed in sequential order (-1, 0, 1, 2, … n).
  • ルートの Order が同じ場合は、最初に最も明確なルートが照合され、続けて次に明確なルートが照合されます。When routes have the same Order, the most specific route is matched first followed by less specific routes.
  • Order とパラメーター数が同じルートが 1 つの要求 URL と一致した場合、ルートは PageConventionCollection に追加された順番で処理されます。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.

可能であれば、定められたルートの処理順序に依存しないようにしてください。If possible, avoid depending on an established route processing order. 通常は、ルーティングによって、URL が一致する正しいルートが選択されます。Generally, routing selects the correct route with URL matching. 要求が正しくルーティングされるようにルートの Order プロパティを設定する必要がある場合、アプリのルーティング方式がクライアントにとって紛らわしいものとなり、保守が脆弱になる可能性があります。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. アプリのルーティング方式を簡略化するよう努めてください。Seek to simplify the app's routing scheme. サンプル アプリでは、1 つのアプリで複数のルーティング シナリオを示すために、ルートの明示的な処理順序が必要です。The sample app requires an explicit route processing order to demonstrate several routing scenarios using a single app. ただし、運用環境のアプリでルートの Order を設定するやり方は避けるようにしてください。However, you should attempt to avoid the practice of setting route Order in production apps.

Razor Pages ルーティングと MVC コントローラー ルーティングは、実装を共有します。Razor Pages routing and MVC controller routing share an implementation. MVC のトピックに記載されているルートの順番については、コントローラー アクションへのルーティング: 属性ルートの順序の指定に関するページをご覧ください。Information on route order in the MVC topics is available at Routing to controller actions: Ordering attribute routes.

モデルの規則Model conventions

IPageConvention の委任を追加すると、Razor Pages に適用されるモデルの規則を追加できます。Add a delegate for IPageConvention to add model conventions that apply to Razor Pages.

すべてのページにルート モデル規則を追加するAdd a route model convention to all pages

Conventions を使用すると、IPageRouteModelConvention を作成して、ページ ルート モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。Use Conventions to create and add an IPageRouteModelConvention to the collection of IPageConvention instances that are applied during page route model construction.

サンプル アプリでは、{globalTemplate?} ルート テンプレートをアプリ内のすべてのページに追加します。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?}"),
                }
            });
        }
    }
}

AttributeRouteModelOrder プロパティに 1 が設定されます。The Order property for the AttributeRouteModel is set to 1. これにより、サンプル アプリで次のルートの照合動作が保証されます。This ensures the following route matching behavior in the sample app:

  • TheContactPage/{text?} のルート テンプレートは、このトピックの後半で追加されます。A route template for TheContactPage/{text?} is added later in the topic. 連絡先ページのルートには既定の順番 null (Order = 0) が設定されているため、{globalTemplate?} ルート テンプレートの前に一致します。The Contact Page route has a default order of null (Order = 0), so it matches before the {globalTemplate?} route template.
  • {aboutTemplate?} ルート テンプレートは、このトピックの後半で追加されます。An {aboutTemplate?} route template is added later in the topic. {aboutTemplate?} テンプレートの Order には 2 が指定されます。The {aboutTemplate?} template is given an Order of 2. [About] ページが /About/RouteDataValue で要求されると、"RouteDataValue" は RouteData.Values["globalTemplate"] (Order = 1) に読み込まれ、Order プロパティが設定されるため RouteData.Values["aboutTemplate"] (Order = 2) には読み込まれません。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.
  • {otherPagesTemplate?} ルート テンプレートは、このトピックの後半で追加されます。An {otherPagesTemplate?} route template is added later in the topic. {otherPagesTemplate?} テンプレートの Order には 2 が指定されます。The {otherPagesTemplate?} template is given an Order of 2. ルート パラメーター (/OtherPages/Page1/RouteDataValue など) を使用して Pages/OtherPages フォルダー内のいずれかのページが要求されると、Order プロパティが設定されているため、"RouteDataValue" が RouteData.Values["otherPagesTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

Razor Pages のオプション (Conventions の追加など) は、MVC が Startup.ConfigureServices のサービス コレクションに追加されたときに追加されます。Razor Pages options, such as adding Conventions, are added when MVC is added to the service collection in Startup.ConfigureServices. 例については、サンプル アプリを参照してください。For an example, see the sample app.

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

localhost:5000/About/GlobalRouteValue でサンプルの [About] ページを要求し、その結果を調べます。Request the sample's About page at localhost:5000/About/GlobalRouteValue and inspect the result:

[About] ページは、GlobalRouteValue のルート セグメントで要求されます。

すべてのページにアプリ モデル規則を追加するAdd an app model convention to all pages

Conventions を使用すると、IPageApplicationModelConvention を作成して、ページ アプリ モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。Use Conventions to create and add an IPageApplicationModelConvention to the collection of IPageConvention instances that are applied during page app model construction.

この規則やこのトピックで後述されるその他の規則のデモを実行するには、サンプル アプリに AddHeaderAttribute クラスを含めます。To demonstrate this and other conventions later in the topic, the sample app includes an AddHeaderAttribute class. クラス コンストラクターは、name 文字列と values 文字列配列を受け入れます。The class constructor accepts a name string and a values string array. これらの値は、応答ヘッダーを設定するために、その OnResultExecuting メソッド内で使用されます。These values are used in its OnResultExecuting method to set a response header. 完全クラスは、このトピックで後述される「ページ モデル アクション規則」セクションで示されます。The full class is shown in the Page model action conventions section later in the topic.

サンプル アプリでは、AddHeaderAttribute クラスを使用して、ヘッダー (GlobalHeader) をアプリ内のすべてのページに追加します。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());

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、GlobalHeader が追加されたことを示しています。

すべてのページにハンドラー モデル規則を追加するAdd a handler model convention to all pages

Conventions を使用すると、IPageHandlerModelConvention を作成して、ページ ハンドラー モデルの構築中に適用される IPageConvention インスタンスのコレクションに追加できます。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());

ページ ルート アクション規則Page route action conventions

IPageRouteModelProvider から派生する既定のルート モデル プロバイダーは、ページ ルートを構成するための拡張ポイントを提供するようにデザインされた規則を呼び出します。The default route model provider that derives from IPageRouteModelProvider invokes conventions which are designed to provide extensibility points for configuring page routes.

フォルダー ルート モデル規則Folder route model convention

AddFolderRouteModelConvention を使用すると、指定したフォルダーの下にあるすべてのページを対象に PageRouteModel へのアクションを呼び出す IPageRouteModelConvention を作成して追加できます。Use AddFolderRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for all of the pages under the specified folder.

サンプル アプリでは AddFolderRouteModelConvention を使用して、{otherPagesTemplate?} ルート テンプレートを OtherPages フォルダーのページに追加します。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?}"),
            }
        });
    }
});

AttributeRouteModelOrder プロパティに 2 が設定されます。The Order property for the AttributeRouteModel is set to 2. この設定により、1 つのルート値が指定されたときに、(このトピックの前半で 1 に設定した) {globalTemplate?} のテンプレートが優先的に最初のルート データ値の位置に指定されます。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. ルート パラメーター値 (/OtherPages/Page1/RouteDataValue など) を使用して Pages/OtherPages フォルダー内のページが要求されると、Order プロパティが設定されているため、"RouteDataValue" が RouteData.Values["otherPagesTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue でサンプルの Page1 ページを要求し、その結果を調べます。Request the sample's Page1 page at localhost:5000/OtherPages/Page1/GlobalRouteValue/OtherPagesRouteValue and inspect the result:

OtherPages フォルダーの Page1 は、GlobalRouteValue と OtherPagesRouteValue のルート セグメントで要求されます。

ページ ルート モデル規則Page route model convention

AddPageRouteModelConvention を使用すると、指定した名前のページを対象に PageRouteModel へのアクションを呼び出す IPageRouteModelConvention を作成して追加できます。Use AddPageRouteModelConvention to create and add an IPageRouteModelConvention that invokes an action on the PageRouteModel for the page with the specified name.

サンプル アプリでは AddPageRouteModelConvention を使用して、{aboutTemplate?} ルート テンプレートを [About] ページに追加します。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?}"),
            }
        });
    }
});

AttributeRouteModelOrder プロパティに 2 が設定されます。The Order property for the AttributeRouteModel is set to 2. この設定により、1 つのルート値が指定されたときに、(このトピックの前半で 1 に設定した) {globalTemplate?} のテンプレートが優先的に最初のルート データ値の位置に指定されます。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. [About] ページが /About/RouteDataValue にあるルート パラメーター値で要求されると、Order プロパティが設定されているため、"RouteDataValue" は RouteData.Values["aboutTemplate"] (Order = 2) ではなく RouteData.Values["globalTemplate"] (Order = 1) に読み込まれます。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.

可能な限り、Order を設定しないでください。これにより、Order = 0 が生じます。Wherever possible, don't set the Order, which results in Order = 0. 正しいルートの選択には、ルーティングを使用してください。Rely on routing to select the correct route.

localhost:5000/About/GlobalRouteValue/AboutRouteValue でサンプルの [About] ページを要求し、その結果を調べます。Request the sample's About page at localhost:5000/About/GlobalRouteValue/AboutRouteValue and inspect the result:

[About] ページは、GlobalRouteValue と AboutRouteValue のルート セグメントで要求されます。

ページ ルートの構成Configure a page route

AddPageRoute を使用すると、指定したページ パスにあるページへのルートを構成できます。Use AddPageRoute to configure a route to a page at the specified page path. そのページに対して生成されたリンクでは、指定したルートを使用します。Generated links to the page use your specified route. AddPageRoute では、AddPageRouteModelConvention を使用してルートを確立します。AddPageRoute uses AddPageRouteModelConvention to establish the route.

サンプル アプリでは、Contact.cshtml/TheContactPage へのルートを作成します。The sample app creates a route to /TheContactPage for Contact.cshtml:

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

[Contact] ページには、既定のルート経由の /Contact でアクセスすることもできます。The Contact page can also be reached at /Contact via its default route.

サンプル アプリの [Contact] ページに対するカスタム ルートでは、省略可能な text ルート セグメント ({text?}) を許可します。The sample app's custom route to the Contact page allows for an optional text route segment ({text?}). また、訪問者が /Contact ルートでページにアクセスする場合、ページの @page ディレクティブにはこの省略可能なセグメントも含まれます。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>

レンダリングされたページの Contact リンク用に生成された URL には、更新されたルートが反映されることに注意してください。Note that the URL generated for the Contact link in the rendered page reflects the updated route:

ナビゲーション バーのサンプル アプリの [Contact] リンク

レンダリングされた HTML の [Contact] リンクを調べると、href に '/TheContactPage' が設定されています

通常のルート (/Contact) またはカスタム ルート (/TheContactPage) のいずれかで、[Contact] ページにアクセスします。Visit the Contact page at either its ordinary route, /Contact, or the custom route, /TheContactPage. 追加の text ルート セグメントを指定した場合、ページには指定した HTML エンコードのセグメントが示されます。If you supply an additional text route segment, the page shows the HTML-encoded segment that you provide:

URL の 'TextValue' の省略可能な 'text' ルート セグメントを適用する Microsoft Edge ブラウザーの例。

ページ モデル アクション規則Page model action conventions

IPageApplicationModelProvider を実装する既定のページ モデル プロバイダーは、ページ モデルを構成するための拡張ポイントを提供するようにデザインされた規則を呼び出します。The default page model provider that implements IPageApplicationModelProvider invokes conventions which are designed to provide extensibility points for configuring page models. これらの規則は、ページ検出をビルドおよび変更したり、シナリオを処理したりするときに便利です。These conventions are useful when building and modifying page discovery and processing scenarios.

このセクションの例の場合、サンプル アプリでは、応答ヘッダーを適用する ResultFilterAttribute である、AddHeaderAttribute クラスを使用します。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);
    }
}

規則を使用して、このサンプルでは、フォルダー内のすべてのページおよび単一ページに属性を適用する方法のデモを実行します。Using conventions, the sample demonstrates how to apply the attribute to all of the pages in a folder and to a single page.

フォルダー アプリ モデル規則Folder app model convention

AddFolderApplicationModelConvention を使用すると、指定したフォルダーの下にあるすべてのページを対象に PageApplicationModel インスタンスへのアクションを呼び出す IPageApplicationModelConvention を作成して追加できます。Use AddFolderApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on PageApplicationModel instances for all pages under the specified folder.

このサンプルでは、ヘッダー (OtherPagesHeader) をアプリの OtherPages フォルダー内にあるページに追加して、AddFolderApplicationModelConvention を使用するデモを実行します。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" }));
});

localhost:5000/OtherPages/Page1 でサンプルの Page1 ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's Page1 page at localhost:5000/OtherPages/Page1 and inspect the headers to view the result:

OtherPages/Page1 ページの応答ヘッダーは、OtherPagesHeader が追加されていることを示しています。

ページ アプリ モデル規則Page app model convention

AddPageApplicationModelConvention を使用すると、指定した名前のページを対象に PageApplicationModel へのアクションを呼び出す IPageApplicationModelConvention を作成して追加できます。Use AddPageApplicationModelConvention to create and add an IPageApplicationModelConvention that invokes an action on the PageApplicationModel for the page with the specified name.

サンプルでは、ヘッダー (AboutHeader) を [About] ページに追加して、AddPageApplicationModelConvention を使用するデモを実行します。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" }));
});

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、AboutHeader が追加されたことを示しています。

フィルターの構成Configure a filter

ConfigureFilter では、指定したフィルターを適用するように構成します。ConfigureFilter configures the specified filter to apply. フィルター クラスを実装できますが、サンプル アプリでは、ラムダ式でフィルターを実装する方法を示しています。これは、フィルターを返すファクトリとしてバックグラウンドで実装されます。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();
});

ページ アプリ モデルは、OtherPages フォルダーの Page2 ページにつながるセグメントの相対パスを確認するために使用されます。The page app model is used to check the relative path for segments that lead to the Page2 page in the OtherPages folder. 条件を満たすと、ヘッダーが追加されます。If the condition passes, a header is added. 満たさない場合は、EmptyFilter が適用されます。If not, the EmptyFilter is applied.

EmptyFilterアクション フィルターです。EmptyFilter is an Action filter. アクション フィルターは Razor Pages によって無視されるため、パスに OtherPages/Page2 が含まれない場合、EmptyFilter には意図されたような効果はありません。Since Action filters are ignored by Razor Pages, the EmptyFilter has no effect as intended if the path doesn't contain OtherPages/Page2.

localhost:5000/OtherPages/Page2 でサンプルの Page2 ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's Page2 page at localhost:5000/OtherPages/Page2 and inspect the headers to view the result:

OtherPagesPage2Header は、Page2 への応答に追加されます。

フィルター ファクトリの構成Configure a filter factory

ConfigureFilter では、すべての Razor Pages にフィルターを適用するように、指定したファクトリを構成します。ConfigureFilter configures the specified factory to apply filters to all Razor Pages.

サンプル アプリでは、アプリのページに対する 2 つの値と共にヘッダー (FilterFactoryHeader) を追加して、フィルター ファクトリを使用する例を提供します。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;
        }
    }
}

localhost:5000/About でサンプルの [About] ページを要求し、そのヘッダーを調べて結果を確認します。Request the sample's About page at localhost:5000/About and inspect the headers to view the result:

[About] ページの応答ヘッダーは、FilterFactoryHeader ヘッダーが 2 つ追加されたことを示しています。

MVC フィルターとページ フィルター (IPageFilter)MVC Filters and the Page filter (IPageFilter)

Razor Pages はハンドラー メソッドを使用するため、MVC アクション フィルターは Razor Pages によって無視されます。MVC Action filters are ignored by Razor Pages, since Razor Pages use handler methods. 使用できるその他の種類の MVC フィルターは次のとおりです。承認例外リソース、および結果Other types of MVC filters are available for you to use: Authorization, Exception, Resource, and Result. 詳細については、「フィルター」トピックを参照してください。For more information, see the Filters topic.

ページ フィルター (IPageFilter) は、Razor Pages に適用されるフィルターの 1 つです。The Page filter (IPageFilter) is a filter that applies to Razor Pages. 詳細については、Razor Pages のフィルター メソッドに関するページを参照してください。For more information, see Filter methods for Razor Pages.

その他の技術情報Additional resources