ASP.NET Core のルーティングRouting in ASP.NET Core

Ryan NowakSteve SmithRick AndersonBy Ryan Nowak, Steve Smith, and Rick Anderson

このトピックのバージョン 1.1 については、「Routing in ASP.NET Core」 (ASP.NET Core のルーティング) (バージョン 1.1、PDF) をダウンロードしてください。For the 1.1 version of this topic, download Routing in ASP.NET Core (version 1.1, PDF).

ルーティングでは、要求 URI をエンドポイント セレクターにマッピングし、受信要求をエンドポイントに配布します。Routing is responsible for mapping request URIs to endpoint selectors and dispatching incoming requests to endpoints. ルートはアプリに定義され、アプリの起動時に構成されます。Routes are defined in the app and configured when the app starts. ルートは、要求に含まれている URL から値を任意で抽出できます。その値を要求処理に利用できます。A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. ルーティングでは、アプリからのルート情報を利用し、エンドポイント セレクターにマッピングする URL を生成することもできます。Using route information from the app, routing is also able to generate URLs that map to endpoint selectors.

ASP.NET Core 2.2 で最新のルーティング シナリオを使用するには、Startup.ConfigureServices互換性バージョンを MVC サービス登録に指定します。To use the latest routing scenarios in ASP.NET Core 2.2, specify the compatibility version to the MVC services registration in Startup.ConfigureServices:

services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

EnableEndpointRouting オプションでは、ルーティングで内部的にエンドポイント ベースのロジックを使用するか、ASP.NET Core 2.1 以前の IRouter ベースのロジックを使用する必要があるかどうかを決定します。The EnableEndpointRouting option determines if routing should internally use endpoint-based logic or the IRouter-based logic of ASP.NET Core 2.1 or earlier. 互換性バージョンが 2.2 以降に設定されている場合、既定値は true となります。When the compatibility version is set to 2.2 or later, the default value is true. 以前のルーティング ロジックを使用する場合は、値を false に設定します。Set the value to false to use the prior routing logic:

// Use the routing logic of ASP.NET Core 2.1 or earlier:
services.AddMvc(options => options.EnableEndpointRouting = false)
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

IRouter ベースのルーティングの詳細については、このトピックの ASP.NET Core 2.1 バージョンを参照してください。For more information on IRouter-based routing, see the ASP.NET Core 2.1 version of this topic.

ルーティングでは要求 URI をルート ハンドラーにマッピングし、受信要求を配布します。Routing is responsible for mapping request URIs to route handlers and dispatching an incoming requests. ルートはアプリに定義され、アプリの起動時に構成されます。Routes are defined in the app and configured when the app starts. ルートは、要求に含まれている URL から値を任意で抽出できます。その値を要求処理に利用できます。A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. ルーティングでは、アプリからの構成済みルートを使用して、ルート ハンドラーにマッピングする URL を生成できます。Using configured routes from the app, routing is able to generate URLs that map to route handlers.

ASP.NET Core 2.1 で最新のルーティング シナリオを使用するには、Startup.ConfigureServices互換性バージョンを MVC サービス登録に指定します。To use the latest routing scenarios in ASP.NET Core 2.1, specify the compatibility version to the MVC services registration in Startup.ConfigureServices:

services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

重要

本文では、ASP.NET Core ルーティングについて詳しく取り上げます。This document covers low-level ASP.NET Core routing. ASP.NET Core MVC ルーティングの詳細については、「ASP.NET Core でのコントローラー アクションへのルーティング」を参照してください。For information on ASP.NET Core MVC routing, see ASP.NET Core でのコントローラー アクションへのルーティング. Razor Pages のルーティング規則については、「ASP.NET Core での Razor ページのルートとアプリの規則」を参照してください。For information on routing conventions in Razor Pages, see ASP.NET Core での Razor ページのルートとアプリの規則.

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

ルーティングの基本Routing basics

ほとんどのアプリでは、URL を読みやすくてわかりやすいものにするために、基本的なでわかりやすいルーティング スキームを選択する必要があります。Most apps should choose a basic and descriptive routing scheme so that URLs are readable and meaningful. 既定の規則ルート {controller=Home}/{action=Index}/{id?}:The default conventional route {controller=Home}/{action=Index}/{id?}:

  • 基本的でわかりやすいルーティング スキームをサポートしています。Supports a basic and descriptive routing scheme.
  • UI ベースのアプリの便利な開始点となります。Is a useful starting point for UI-based apps.

開発者は一般的に、特殊な状況でのアプリのトラフィックが多い領域 (ブログや E コマース エンドポイントなど) に対しては、属性ルーティングまたは専用規則ルートを使用して簡易ルートをさらに追加します。Developers commonly add additional terse routes to high-traffic areas of an app in specialized situations (for example, blog and ecommerce endpoints) using attribute routing or dedicated conventional routes.

Web API では、属性ルーティングを使用して、HTTP 動詞で操作を表現するリソースのセットとしてアプリの機能をモデル化する必要があります。Web APIs should use attribute routing to model the app's functionality as a set of resources where operations are represented by HTTP verbs. つまり、同じ論理リソース上の多くの操作 (たとえば GET や POST) で、同じ URL を使用します。This means that many operations (for example, GET, POST) on the same logical resource will use the same URL. 属性ルーティングでは、API のパブリック エンドポイント レイアウトを慎重に設計するために必要となるコントロールのレベルが提供されます。Attribute routing provides a level of control that's needed to carefully design an API's public endpoint layout.

Razor Pages アプリでは既定の規則ルーティングを使用して、アプリの Pages フォルダーの名前付きリソースを提供します。Razor Pages apps use default conventional routing to serve named resources in the Pages folder of an app. Razor Pages のルーティング動作をカスタマイズできる追加の規則を使用できます。Additional conventions are available that allow you to customize Razor Pages routing behavior. 詳細については、次のトピックを参照してください。 ASP.NET Core での Razor ページの概要 および ASP.NET Core での Razor ページのルートとアプリの規則.For more information, see ASP.NET Core での Razor ページの概要 and ASP.NET Core での Razor ページのルートとアプリの規則.

URL 生成サポートを使用すると、アプリを相互にリンクする URL をハード コーディングすることなくアプリを開発できます。URL generation support allows the app to be developed without hard-coding URLs to link the app together. このサポートにより、基本的なルーティング構成を使用して作業を開始し、アプリのリソース レイアウトが決まった後でルートを変更することができます。This support allows for starting with a basic routing configuration and modifying the routes after the app's resource layout is determined.

ルーティングではエンドポイント (Endpoint) を使用して、アプリの論理エンドポイントを表します。Routing uses endpoints (Endpoint) to represent logical endpoints in an app.

エンドポイントでは、要求と、任意のメタデータのコレクションを処理するデリゲートが定義されます。An endpoint defines a delegate to process requests and a collection of arbitrary metadata. メタデータは、各エンドポイントにアタッチされている構成とポリシーに基づいて横断的な関心事を実装するために使用されます。The metadata is used implement cross-cutting concerns based on policies and configuration attached to each endpoint.

ルーティング システムには次の特性があります。The routing system has the following characteristics:

  • ルート テンプレート構文は、トークン化されたルート パラメーターでルートを定義するために使用されます。Route template syntax is used to define routes with tokenized route parameters.

  • 規則スタイルおよび属性スタイルのエンドポイント構成が許可されます。Conventional-style and attribute-style endpoint configuration is permitted.

  • IRouteConstraint は、URL パラメーターに特定のエンドポイント制約で有効な値が含まれているかどうかを確認するために使用されます。IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.

  • MVC/Razor Pages などのアプリ モデルでは、ルーティング シナリオの予測可能な実装を持つ、すべてのエンドポイントを登録します。App models, such as MVC/Razor Pages, register all of their endpoints, which have a predictable implementation of routing scenarios.

  • ルーティングの実装では、必要に応じて、ミドルウェア パイプラインでのルーティングに関する決定を行います。The routing implementation makes routing decisions wherever desired in the middleware pipeline.

  • ルーティング ミドルウェアの後に表示されるミドルウェアでは、特定の要求 URI に関するルーティング ミドルウェアのエンドポイント決定の結果を検査できます。Middleware that appears after a Routing Middleware can inspect the result of the Routing Middleware's endpoint decision for a given request URI.

  • ミドルウェア パイプラインの任意の場所でアプリのすべてのエンドポイントを列挙することができます。It's possible to enumerate all of the endpoints in the app anywhere in the middleware pipeline.

  • アプリではルーティングを使用し、エンドポイント情報に基づいて URL (リダイレクトやリンクなど) を生成できます。そのため、URL をハードコーディングする必要がなく、保守管理が容易になります。An app can use routing to generate URLs (for example, for redirection or links) based on endpoint information and thus avoid hard-coded URLs, which helps maintainability.

  • URL の生成は、任意の拡張機能をサポートする、アドレスに基づきます。URL generation is based on addresses, which support arbitrary extensibility:

    • リンク ジェネレーター API (LinkGenerator) は、URI を生成するために依存関係挿入 (DI) を使用して任意の場所で解決できます。The Link Generator API (LinkGenerator) can be resolved anywhere using dependency injection (DI) to generate URLs.
    • リンク ジェネレーター API を DI で使用できない場合、IUrlHelper で URL を構築するためのメソッドが提供されます。Where the Link Generator API isn't available via DI, IUrlHelper offers methods to build URLs.

注意

ASP.NET Core 2.2 のエンドポイント ルーティングのリリースでは、エンドポイント リンクは、MVC/Razor Pages アクションおよびページに制限されます。With the release of endpoint routing in ASP.NET Core 2.2, endpoint linking is limited to MVC/Razor Pages actions and pages. エンドポイント リンク機能の拡張は、今後のリリースで予定されています。The expansions of endpoint-linking capabilities is planned for future releases.

ルーティングにおけるルート (IRouter の実装) の利用目的:Routing uses routes (implementations of IRouter) to:

  • 受信要求をルート ハンドラーにマッピングする。Map incoming requests to route handlers.
  • 応答で使用される URL を生成する。Generate the URLs used in responses.

既定では、アプリにはルート コレクションが 1 つあります。By default, an app has a single collection of routes. 要求が到着すると、コレクション内のルートは、コレクションに存在する順序で処理されます。When a request arrives, the routes in the collection are processed in the order that they exist in the collection. フレームワークでは、コレクション内の各ルートに対して RouteAsync メソッドを呼び出し、受信要求 URL とコレクション内のルートとの照合を試みます。The framework attempts to match an incoming request URL to a route in the collection by calling the RouteAsync method on each route in the collection. 応答ではルーティングを使用し、ルート情報に基づいて URL (リダイレクトやリンクなど) を生成できます。そのため、URL をハードコーディングする必要がなく、保守管理が容易になります。A response can use routing to generate URLs (for example, for redirection or links) based on route information and thus avoid hard-coded URLs, which helps maintainability.

ルーティング システムには次の特性があります。The routing system has the following characteristics:

  • ルート テンプレート構文は、トークン化されたルート パラメーターでルートを定義するために使用されます。Route template syntax is used to define routes with tokenized route parameters.
  • 規則スタイルおよび属性スタイルのエンドポイント構成が許可されます。Conventional-style and attribute-style endpoint configuration is permitted.
  • IRouteConstraint は、URL パラメーターに特定のエンドポイント制約で有効な値が含まれているかどうかを確認するために使用されます。IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.
  • MVC/Razor Pages などのアプリ モデルでは、ルーティング シナリオの予測可能な実装を持つ、すべてのルートを登録します。App models, such as MVC/Razor Pages, register all of their routes, which have a predictable implementation of routing scenarios.
  • 応答ではルーティングを使用し、ルート情報に基づいて URL (リダイレクトやリンクなど) を生成できます。そのため、URL をハードコーディングする必要がなく、保守管理が容易になります。A response can use routing to generate URLs (for example, for redirection or links) based on route information and thus avoid hard-coded URLs, which helps maintainability.
  • URL の生成は、任意の拡張機能をサポートする、ルートに基づきます。URL generation is based on routes, which support arbitrary extensibility. IUrlHelper では、URL を構築するためのメソッドが提供されます。IUrlHelper offers methods to build URLs.

ルーティングは RouterMiddleware クラスによりミドルウェア パイプラインに接続されます。Routing is connected to the middleware pipeline by the RouterMiddleware class. ASP.NET Core MVC では、ミドルウェア パイプラインにその構成の一部としてルーティングが追加され、MVC および Razor Pages アプリでのルーティングが処理されます。ASP.NET Core MVC adds routing to the middleware pipeline as part of its configuration and handles routing in MVC and Razor Pages apps. スタンドアロン コンポーネントとしてルーティングを利用する方法については、「ルーティング ミドルウェアの使用」セクションを参照してください。To learn how to use routing as a standalone component, see the Use Routing Middleware section.

URL 一致URL matching

URL 一致というプロセスでは、ルーティングによって、受信要求がエンドポイントに配布されます。URL matching is the process by which routing dispatches an incoming request to an endpoint. このプロセスは URL パスのデータに基づきますが、要求内のあらゆるデータを考慮することもできます。This process is based on data in the URL path but can be extended to consider any data in the request. アプリの規模を大きくしたり、より複雑にしたりするとき、要求を個別のハンドラーに配布する機能が鍵となります。The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

エンドポイント ルーティングのルーティング システムでは、配布に関するすべての決定が行われます。The routing system in endpoint routing is responsible for all dispatching decisions. ミドルウェアでは選択されたエンドポイントに基づいてポリシーが適用されるため、セキュリティ ポリシーの適用や配布に影響する可能性のある決定は、ルーティング システム内で行うことが重要です。Since the middleware applies policies based on the selected endpoint, it's important that any decision that can affect dispatching or the application of security policies is made inside the routing system.

エンドポイントのデリゲートが実行されると、それまでに実行された要求処理に基づいて、RouteContext.RouteData のプロパティが適切な値に設定されます。When the endpoint delegate is executed, the properties of RouteContext.RouteData are set to appropriate values based on the request processing performed thus far.

URL 一致というプロセスでは、ルーティングによって、受信要求がハンドラーに配布されます。URL matching is the process by which routing dispatches an incoming request to a handler. このプロセスは URL パスのデータに基づきますが、要求内のあらゆるデータを考慮することもできます。This process is based on data in the URL path but can be extended to consider any data in the request. アプリの規模を大きくしたり、より複雑にしたりするとき、要求を個別のハンドラーに配布する機能が鍵となります。The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

受信要求は RouterMiddleware に入ります。これが各ルートで順に RouteAsync メソッドを呼び出します。Incoming requests enter the RouterMiddleware, which calls the RouteAsync method on each route in sequence. IRouter インスタンスでは、RouteContext.Handler を非 null の RequestDelegate に設定することで、要求を処理するかどうかを選択します。The IRouter instance chooses whether to handle the request by setting the RouteContext.Handler to a non-null RequestDelegate. 要求に適したハンドラーがルートに見つかると、ルート処理が停止します。ハンドラーが呼び出され、要求を処理します。If a route sets a handler for the request, route processing stops, and the handler is invoked to process the request. 要求を処理するためのルート ハンドラーが見つからない場合、ミドルウェアによって、要求が要求パイプラインの次のミドルウェアに渡されます。If no route handler is found to process the request, the middleware hands the request off to the next middleware in the request pipeline.

RouteAsync に最初に入力されるのが、現在の要求に関連付けられている RouteContext.HttpContext です。The primary input to RouteAsync is the RouteContext.HttpContext associated with the current request. RouteContext.HandlerRouteContext.RouteData はルートが一致した後に設定される出力です。The RouteContext.Handler and RouteContext.RouteData are outputs set after a route is matched.

また、RouteAsync を呼び出す一致が見つかると、それまでに実行された要求処理に基づいて、RouteContext.RouteData のプロパティが適切な値に設定されます。A match that calls RouteAsync also sets the properties of the RouteContext.RouteData to appropriate values based on the request processing performed thus far.

RouteData.Values は、ルートから生成されたルート値のディクショナリです。RouteData.Values is a dictionary of route values produced from the route. この値は通常、URL のトークン化で決定されます。この値を利用してユーザー入力を受け取ったり、アプリ内で決定をさらに配布したりできます。These values are usually determined by tokenizing the URL and can be used to accept user input or to make further dispatching decisions inside the app.

RouteData.DataTokens は、一致したルートに関連する追加データのプロパティ バッグです。RouteData.DataTokens is a property bag of additional data related to the matched route. 一致したルートに基づいてアプリで決定を行えるように、DataTokens が提供されます。これは状態データと各ルートの関連付けをサポートするためのものです。DataTokens are provided to support associating state data with each route so that the app can make decisions based on which route matched. この値は開発者が定義するものです。ルーティングの動作に影響を与えることはありませんThese values are developer-defined and do not affect the behavior of routing in any way. また、RouteData.DataTokens に格納された値はどのような型でも構いません。一方、RouteData.Values は文字列間で変換できる必要があります。Additionally, values stashed in RouteData.DataTokens can be of any type, in contrast to RouteData.Values, which must be convertible to and from strings.

RouteData.Routers は、過去に要求に一致したルートの一覧です。RouteData.Routers is a list of the routes that took part in successfully matching the request. ルートはルートの中に入れ子にすることができます。Routes can be nested inside of one another. Routers プロパティは、結果的に一致をもたらしたルートの論理ツリーを通るパスを表します。The Routers property reflects the path through the logical tree of routes that resulted in a match. 一般的に、Routers の最初の項目はルート コレクションであり、これは URL 生成に使用するものです。Generally, the first item in Routers is the route collection and should be used for URL generation. Routers の最後の項目は、一致したルート ハンドラーです。The last item in Routers is the route handler that matched.

URL 生成URL generation

URL 生成は、ルーティングにおいて、一連のルート値に基づいて URL パスを作成するプロセスです。URL generation is the process by which routing can create a URL path based on a set of route values. これにより、エンドポイントとそれにアクセスする URL を論理的に分離できます。This allows for a logical separation between your endpoints and the URLs that access them.

エンドポイント ルーティングには、リンク ジェネレーター API (LinkGenerator) が含まれています。Endpoint routing includes the Link Generator API (LinkGenerator). LinkGenerator は、DI から取得できるシングルトン サービスです。LinkGenerator is a singleton service that can be retrieved from DI. API は、実行中の要求のコンテキスト外で使用することができます。The API can be used outside of the context of an executing request. MVC の IUrlHelper と、タグ ヘルパー、HTML ヘルパー、アクション結果など、IUrlHelper に依存するシナリオではリンク ジェネレーターを使用して、リンク生成機能を提供します。MVC's IUrlHelper and scenarios that rely on IUrlHelper, such as Tag Helpers, HTML Helpers, and Action Results, use the link generator to provide link generating capabilities.

リンク ジェネレーターは、アドレスアドレス スキーム の概念に基づいています。The link generator is backed by the concept of an address and address schemes. アドレス スキームは、リンク生成で考慮すべきエンドポイントを決定する方法です。An address scheme is a way of determining the endpoints that should be considered for link generation. たとえば、MVC/Razor Pages からの、多くのユーザーに馴染みのあるルート名やルート値シナリオは、アドレス スキームとして実装されます。For example, the route name and route values scenarios many users are familiar with from MVC/Razor Pages are implemented as an address scheme.

リンク ジェネレーターでは、次の拡張メソッドを使用して、MVC/Razor Pages アクションおよびページにリンクできます。The link generator can link to MVC/Razor Pages actions and pages via the following extension methods:

  • GetPathByAction
  • GetUriByAction
  • GetPathByPage
  • GetUriByPage

これらのメソッドのオーバーロードでは、HttpContext を含む引数が受け入れられます。An overload of these methods accepts arguments that include the HttpContext. これらのメソッドは Url.Action および Url.Page と機能的には同等ですが、柔軟性とオプションがさらに提供されます。These methods are functionally equivalent to Url.Action and Url.Page but offer additional flexibility and options.

GetPath* メソッドは、絶対パスを含む URI を生成するという点で Url.Action および Url.Page に最も似ています。The GetPath* methods are most similar to Url.Action and Url.Page in that they generate a URI containing an absolute path. GetUri* メソッドでは常に、スキームとホストを含む絶対 URI が生成されます。The GetUri* methods always generate an absolute URI containing a scheme and host. HttpContext を受け入れるメソッドでは、実行中の要求のコンテキストで URI が生成されます。The methods that accept an HttpContext generate a URI in the context of the executing request. 実行中の要求からのアンビエント ルート値、URL ベース パス、スキーム、およびホストは、オーバーライドされない限り使用されます。The ambient route values, URL base path, scheme, and host from the executing request are used unless overridden.

LinkGenerator はアドレスと共に呼び出されます。LinkGenerator is called with an address. URI の生成は、次の 2 つの手順で行われます。Generating a URI occurs in two steps:

  1. アドレスは、そのアドレスと一致するエンドポイントのリストにバインドされます。An address is bound to a list of endpoints that match the address.
  2. 各エンドポイントの RoutePattern は、指定された値と一致するルート パターンが見つかるまで評価されます。Each endpoint's RoutePattern is evaluated until a route pattern that matches the supplied values is found. 結果の出力は、リンク ジェネレーターに指定された他の URI 部分と結合され、返されます。The resulting output is combined with the other URI parts supplied to the link generator and returned.

LinkGenerator によって提供されるメソッドでは、すべての種類のアドレスの標準的なリンク生成機能がサポートされます。The methods provided by LinkGenerator support standard link generation capabilities for any type of address. リンク ジェネレーターを使用する最も便利な方法は、特定のアドレスの種類の操作を実行する拡張メソッドを使用することです。The most convenient way to use the link generator is through extension methods that perform operations for a specific address type.

拡張メソッドExtension Method 説明Description
GetPathByAddress 指定された値に基づき、絶対パスを含む URI を生成します。Generates a URI with an absolute path based on the provided values.
GetUriByAddress 指定された値に基づき、絶対 URI を生成します。Generates an absolute URI based on the provided values.

警告

LinkGenerator メソッド呼び出しによる次の影響に注意してください。Pay attention to the following implications of calling LinkGenerator methods:

  • 受信要求の Host ヘッダーが確認されないアプリ構成では、GetUri* 拡張メソッドは注意して使用してください。Use GetUri* extension methods with caution in an app configuration that doesn't validate the Host header of incoming requests. 受信要求の Host ヘッダーが確認されていない場合、信頼されていない要求入力を、ビュー/ページの URI でクライアントに送り返すことができます。If the Host header of incoming requests isn't validated, untrusted request input can be sent back to the client in URIs in a view/page. すべての運用アプリで、Host ヘッダーを既知の有効な値と照らし合わせて確認するようにサーバーを構成することをお勧めします。We recommend that all production apps configure their server to validate the Host header against known valid values.

  • ミドルウェアで Map または MapWhen と組み合わせて、LinkGenerator を使用する場合は注意してください。Use LinkGenerator with caution in middleware in combination with Map or MapWhen. Map* では、実行中の要求の基本パスが変更され、リンク生成の出力に影響します。Map* changes the base path of the executing request, which affects the output of link generation. すべての LinkGenerator API で基本パスを指定することができます。All of the LinkGenerator APIs allow specifying a base path. リンク生成への Map* の影響を元に戻すための空の基本パスを必ず指定してください。Always specify an empty base path to undo Map*'s affect on link generation.

以前のバージョンのルーティングとの相違点Differences from earlier versions of routing

ASP.NET Core 2.2 以降でのエンドポイント ルーティングと、ASP.NET Core での以前のバージョンのルーティングには、次のようないくつかの違いがあります。A few differences exist between endpoint routing in ASP.NET Core 2.2 or later and earlier versions of routing in ASP.NET Core:

  • エンドポイント ルーティング システムでは、Route からの継承を含む、IRouter ベースの拡張機能がサポートされません。The endpoint routing system doesn't support IRouter-based extensibility, including inheriting from Route.

  • エンドポイント ルーティングでは WebApiCompatShim がサポートされません。Endpoint routing doesn't support WebApiCompatShim. 互換性 shim を引き続き使用するには、2.1 の互換性バージョン (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) を使用します。Use the 2.1 compatibility version (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) to continue using the compatibility shim.

  • エンドポイント ルーティングでは、規則ルートを使用する場合に生成される URI の大文字と小文字の指定の動作が異なります。Endpoint Routing has different behavior for the casing of generated URIs when using conventional routes.

    次の既定のルート テンプレートについて考えてみます。Consider the following default route template:

    app.UseMvc(routes =>
    {
        routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
    });
    

    次のルートを使用して、アクションへのリンクを生成するとします。Suppose you generate a link to an action using the following route:

    var link = Url.Action("ReadPost", "blog", new { id = 17, });
    

    IRouter ベースのルーティングでは、このコードで /blog/ReadPost/17 の URI が生成され、指定されたルート値の大文字と小文字の指定が優先されます。With IRouter-based routing, this code generates a URI of /blog/ReadPost/17, which respects the casing of the provided route value. ASP.NET Core 2.2 以降のエンドポイント ルーティングでは、/Blog/ReadPost/17 ("Blog" の先頭は大文字) が生成されます。Endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 ("Blog" is capitalized). エンドポイント ルーティングでは IOutboundParameterTransformer インターフェイスが提供されます。それを使用して、この動作をグローバルにカスタマイズしたり、URL のマッピングで異なる規則を適用したりすることができます。Endpoint routing provides the IOutboundParameterTransformer interface that can be used to customize this behavior globally or to apply different conventions for mapping URLs.

    詳細については、「パラメーター トランスフォーマー参照」セクションを参照してください。For more information, see the Parameter transformer reference section.

  • 存在しないコントローラー/アクションまたはページへのリンクを試みる場合、規則ルートがある MVC/Razor Pages によって使用されるリンク生成の動作は異なります。Link Generation used by MVC/Razor Pages with conventional routes behaves differently when attempting to link to an controller/action or page that doesn't exist.

    次の既定のルート テンプレートについて考えてみます。Consider the following default route template:

    app.UseMvc(routes =>
    {
        routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
    });
    

    次のように既定のテンプレートを使用して、アクションへのリンクを生成するとします。Suppose you generate a link to an action using the default template with the following:

    var link = Url.Action("ReadPost", "Blog", new { id = 17, });
    

    IRouter ベースのルーティングでは、BlogController が存在しない場合や ReadPost アクション メソッドがない場合でも、結果は常に /Blog/ReadPost/17 となります。With IRouter-based routing, the result is always /Blog/ReadPost/17, even if the BlogController doesn't exist or doesn't have a ReadPost action method. 予想どおり、アクション メソッドが存在する場合は、ASP.NET Core 2.2 以降のエンドポイント ルーティングで /Blog/ReadPost/17 が生成されます。As expected, endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 if the action method exists. しかし、アクションが存在しない場合は、エンドポイント ルーティングで空の文字列が生成されます。However, endpoint routing produces an empty string if the action doesn't exist. 概念的には、エンドポイント ルーティングでは、アクションが存在しない場合はエンドポイントが存在するとは見なされません。Conceptually, endpoint routing doesn't assume that the endpoint exists if the action doesn't exist.

  • エンドポイント ルーティングで使用する場合は、リンク生成のアンビエント値の無効化アルゴリズム の動作が異なります。The link generation ambient value invalidation algorithm behaves differently when used with endpoint routing.

    アンビエント値の無効化 は、現在実行中の要求からのルート値 (アンビエント値) のうち、どちらがリンク生成操作で使用できのかを判断するアルゴリズムです。Ambient value invalidation is the algorithm that decides which route values from the currently executing request (the ambient values) can be used in link generation operations. 規則ルーティングでは、異なるアクションへのリンク時に余分なルート値が常に無効化されました。Conventional routing always invalidated extra route values when linking to a different action. 属性ルーティングは、ASP.NET Core 2.2 のリリースより前ではこのように動作しませんでした。Attribute routing didn't have this behavior prior to the release of ASP.NET Core 2.2. 以前のバージョンの ASP.NET Core では、同じルート パラメーター名を使用する別のアクションへのリンクでリンク生成エラーが発生しました。In earlier versions of ASP.NET Core, links to another action that use the same route parameter names resulted in link generation errors. ASP.NET Core 2.2 以降では、両方の形式のルーティングで、別のアクションへのリンク時に値が無効化されます。In ASP.NET Core 2.2 or later, both forms of routing invalidate values when linking to another action.

    ASP.NET Core 2.1 以前での次の例について考えてみます。Consider the following example in ASP.NET Core 2.1 or earlier. 別のアクション (または別のページ) にリンクする場合、好ましくない方法でルート値が再利用される可能性があります。When linking to another action (or another page), route values can be reused in undesirable ways.

    /Pages/Store/Product.cshtml の場合:In /Pages/Store/Product.cshtml:

    @page "{id}"
    @Url.Page("/Login")
    

    /Pages/Login.cshtml の場合:In /Pages/Login.cshtml:

    @page "{id?}"
    

    ASP.NET Core 2.1 以前で URI が /Store/Product/18 である場合、@Url.Page("/Login") によって Store/Info ページに生成されるリンクは /Login/18 となります。If the URI is /Store/Product/18 in ASP.NET Core 2.1 or earlier, the link generated on the Store/Info page by @Url.Page("/Login") is /Login/18. リンク先が完全にアプリの異なる部分であっても、18 という id の値が再利用されます。The id value of 18 is reused, even though the link destination is different part of the app entirely. /Login ページのコンテキスト内の id ルート値は、商品 ID 値ではなく、ユーザー ID 値であると考えられます。The id route value in the context of the /Login page is probably a user ID value, not a store product ID value.

    ASP.NET Core 2.2 以降でのエンドポイント ルーティングでは、結果は /Login となります。In endpoint routing with ASP.NET Core 2.2 or later, the result is /Login. リンク先が異なるアクションやページである場合、アンビエント値は再利用されません。Ambient values aren't reused when the linked destination is a different action or page.

  • ラウンド トリップ ルート パラメーターの構文: 二重アスタリスク (**) キャッチオール パラメーター構文を使用する場合、スラッシュはエンコードされません。Round-tripping route parameter syntax: Forward slashes aren't encoded when using a double-asterisk (**) catch-all parameter syntax.

    リンクの生成中に、ルーティング システムでは、スラッシュを除く二重アスタリスク (**) キャッチオール パラメーター ({**myparametername} など) でキャプチャされた値をエンコードします。During link generation, the routing system encodes the value captured in a double-asterisk (**) catch-all parameter (for example, {**myparametername}) except the forward slashes. 二重アスタリスク キャッチオールは、ASP.NET Core 2.2 以降の IRouter ベース ルーティングでサポートされます。The double-asterisk catch-all is supported with IRouter-based routing in ASP.NET Core 2.2 or later.

    以前のバージョンの ASP.NET Core での単一のアスタリスク キャッチオール パラメーター構文 ({*myparametername}) は引き続きサポートされ、スラッシュはエンコードされます。The single asterisk catch-all parameter syntax in prior versions of ASP.NET Core ({*myparametername}) remains supported, and forward slashes are encoded.

    ルートRoute 以下で生成されるリンクLink generated with
    Url.Action(new { category = "admin/products" })
    /search/{*page} /search/admin%2Fproducts (スラッシュはエンコードされます)/search/admin%2Fproducts (the forward slash is encoded)
    /search/{**page} /search/admin/products

ミドルウェアの例Middleware example

次の例では、ミドルウェアで LinkGenerator API を使用して、商品をリストするアクション メソッドへのリンクを作成します。In the following example, a middleware uses the LinkGenerator API to create link to an action method that lists store products. リンク ジェネレーターは、クラスに挿入し、GenerateLink を呼び出すことで、アプリのどのクラスでも使用できます。Using the link generator by injecting it into a class and calling GenerateLink is available to any class in an app.

public class ProductsLinkMiddleware
{
    private readonly LinkGenerator _linkGenerator;

    public ProductsLinkMiddleware(RequestDelegate next, LinkGenerator linkGenerator)
    {
        _linkGenerator = linkGenerator;
    }

    public async Task InvokeAsync(HttpContext httpContext)
    {
        var url = _linkGenerator.GenerateLink(new { controller = "Store",
                                                    action = "ListProducts" });

        httpContext.Response.ContentType = "text/plain";

        await httpContext.Response.WriteAsync($"Go to {url} to see our products.");
    }
}

URL 生成は、ルーティングにおいて、一連のルート値に基づいて URL パスを作成するプロセスです。URL generation is the process by which routing can create a URL path based on a set of route values. これにより、ルート ハンドラーとそれにアクセスする URL を論理的に分離できます。This allows for a logical separation between route handlers and the URLs that access them.

URL 生成は同様の繰り返しプロセスに従いますが、最初にユーザーまたはフレームワーク コードでルート コレクションの GetVirtualPath メソッドを呼び出します。URL generation follows a similar iterative process, but it starts with user or framework code calling into the GetVirtualPath method of the route collection. 非 null の VirtualPathData が返されるまで、各ルート で順番に GetVirtualPath メソッドが呼び出されます。Each route has its GetVirtualPath method called in sequence until a non-null VirtualPathData is returned.

GetVirtualPath の第一入力:The primary inputs to GetVirtualPath are:

ルートでは ValuesAmbientValues によって指定されるルート値を主に使用し、URL を生成できるかどうかと、どの値を含めるかを判断します。Routes primarily use the route values provided by Values and AmbientValues to decide whether it's possible to generate a URL and what values to include. AmbientValues は、現在の要求を照合することで生成された一連のルート値です。The AmbientValues are the set of route values that were produced from matching the current request. 対照的に、Values は、現在の操作に適した URL の生成方法を指定するルート値です。In contrast, Values are the route values that specify how to generate the desired URL for the current operation. ルートで現在のコンテキストに関連付けられているサービスまたは追加データを取得する必要がある場合、HttpContext が指定されます。The HttpContext is provided in case a route should obtain services or additional data associated with the current context.

ヒント

VirtualPathContext.ValuesVirtualPathContext.AmbientValues のオーバーライド セットであると考えてください。Think of VirtualPathContext.Values as a set of overrides for the VirtualPathContext.AmbientValues. URL 生成では、同じルートまたはルート値を利用することでリンクの URL 生成を生成するために、現在の要求からのルート値の再利用が試行されます。URL generation attempts to reuse route values from the current request to generate URLs for links using the same route or route values.

GetVirtualPath の出力は VirtualPathData です。The output of GetVirtualPath is a VirtualPathData. VirtualPathDataRouteData の並列です。VirtualPathData is a parallel of RouteData. VirtualPathData には出力 URL として VirtualPath が含まれ、ルートで設定する追加プロパティがいくつか含まれます。VirtualPathData contains the VirtualPath for the output URL and some additional properties that should be set by the route.

VirtualPathData.VirtualPath プロパティには、ルートによって生成された仮想パスが含まれます。The VirtualPathData.VirtualPath property contains the virtual path produced by the route. 必要に応じて、パスをさらに処理する必要がある場合があります。Depending on your needs, you may need to process the path further. 生成された URL を HTML で表示するには、アプリの基礎パスを先頭に追加する必要があります。If you want to render the generated URL in HTML, prepend the base path of the app.

VirtualPathData.Router は URL を正常に生成したルートの参照です。The VirtualPathData.Router is a reference to the route that successfully generated the URL.

VirtualPathData.DataTokens プロパティは、URL を生成したルートに関連する追加データのディクショナリです。The VirtualPathData.DataTokens properties is a dictionary of additional data related to the route that generated the URL. これは RouteData.DataTokens の並列です。This is the parallel of RouteData.DataTokens.

ルートを作成するCreate routes

ルーティングにより、IRouter の標準実装として Route クラスが与えられます。Routing provides the Route class as the standard implementation of IRouter. Route ではルート テンプレート 構文を利用して、RouteAsync の呼び出し時に URL パスに対して照合するパターンを定義します。Route uses the route template syntax to define patterns to match against the URL path when RouteAsync is called. Route は同じルート テンプレートを利用し、GetVirtualPath の呼び出し時に URL を生成します。Route uses the same route template to generate a URL when GetVirtualPath is called.

ほとんどのアプリは、MapRoute を呼び出すか、IRouteBuilder で定義されている同様の拡張メソッドの 1 つを呼び出してルートを作成します。Most apps create routes by calling MapRoute or one of the similar extension methods defined on IRouteBuilder. いずれの IRouteBuilder 拡張メソッドでも、Route のインスタンスが作成され、それがルート コレクションに追加されます。Any of the IRouteBuilder extension methods create an instance of Route and add it to the route collection.

MapRoute では、ルート ハンドラー パラメーターは受け入れられません。MapRoute doesn't accept a route handler parameter. MapRoute は、DefaultHandler によって処理されるルートを追加するだけです。MapRoute only adds routes that are handled by the DefaultHandler. MVC でのルーティングの詳細については、「ASP.NET Core でのコントローラー アクションへのルーティング」を参照してください。To learn more about routing in MVC, see ASP.NET Core でのコントローラー アクションへのルーティング.

MapRoute では、ルート ハンドラー パラメーターは受け入れられません。MapRoute doesn't accept a route handler parameter. MapRoute は、DefaultHandler によって処理されるルートを追加するだけです。MapRoute only adds routes that are handled by the DefaultHandler. 既定のハンドラーは IRouter であり、そのハンドラーで要求が処理されない可能性があります。The default handler is an IRouter, and the handler might not handle the request. たとえば、ASP.NET Core MVC は通常、利用できるコントローラーやアクションに一致する要求のみを処理する既定のハンドラーとして構成されます。For example, ASP.NET Core MVC is typically configured as a default handler that only handles requests that match an available controller and action. MVC でのルーティングの詳細については、「ASP.NET Core でのコントローラー アクションへのルーティング」を参照してください。To learn more about routing in MVC, see ASP.NET Core でのコントローラー アクションへのルーティング.

次のコード例は、一般的な ASP.NET Core MVC ルート定義によって使用される MapRoute 呼び出しの例です。The following code example is an example of a MapRoute call used by a typical ASP.NET Core MVC route definition:

routes.MapRoute(
    name: "default",
    template: "{controller=Home}/{action=Index}/{id?}");

このテンプレートでは URL パスが照合され、ルート値が抽出されます。This template matches a URL path and extracts the route values. たとえば、/Products/Details/17 というパスでは、{ controller = Products, action = Details, id = 17 } というルート値が生成されます。For example, the path /Products/Details/17 generates the following route values: { controller = Products, action = Details, id = 17 }.

ルート値は、URL パスをセグメントに分割し、各セグメントと、ルート テンプレートのルート パラメーター 名を照合することで決定されます。Route values are determined by splitting the URL path into segments and matching each segment with the route parameter name in the route template. ルート パラメーターが指定されます。Route parameters are named. パラメーターは、中かっこ { ... } でパラメーター名を囲むことで定義されます。The parameters defined by enclosing the parameter name in braces { ... }.

上のテンプレートでは URL パス / の照合も行い、{ controller = Home, action = Index } という値を生成します。The preceding template could also match the URL path / and produce the values { controller = Home, action = Index }. これは、ルート パラメーターの {controller}{action} に既定値が与えられ、id ルート パラメーターが任意であるためです。This occurs because the {controller} and {action} route parameters have default values and the id route parameter is optional. ルート パラメーター名の後の等号 (=) とそれに続く値により、パラメーターの既定値が定義されます。An equals sign (=) followed by a value after the route parameter name defines a default value for the parameter. ルート パラメーター名の後の疑問符 (?) により、オプションのパラメーターが定義されます。A question mark (?) after the route parameter name defines an optional parameter.

既定値のルート パラメーターはルートが一致するとルート値を常に生成します。Route parameters with a default value always produce a route value when the route matches. オプションのパラメーターは、対応する URL パス セグメントがなかった場合、ルート値を生成しません。Optional parameters don't produce a route value if there was no corresponding URL path segment. ルート テンプレートのシナリオと構文の詳しい説明については、「ルート テンプレート参照」セクションを参照してください。See the Route template reference section for a thorough description of route template scenarios and syntax.

次の例では、ルート パラメーター定義 {id:int} により、id ルート パラメーターのルート制約が定義されます。In the following example, the route parameter definition {id:int} defines a route constraint for the id route parameter:

routes.MapRoute(
    name: "default",
    template: "{controller=Home}/{action=Index}/{id:int}");

このテンプレートは /Products/Details/Apples ではなく、/Products/Details/17 のような URL パスを照合します。This template matches a URL path like /Products/Details/17 but not /Products/Details/Apples. ルート制約は IRouteConstraint を実装し、ルート値を調べて正しいことを確認します。Route constraints implement IRouteConstraint and inspect route values to verify them. この例では、ルート値 id は整数に変換できなければなりません。In this example, the route value id must be convertible to an integer. フレームワークによって提供されるルート制約については、「ルート制約参照」を参照してください。See route-constraint-reference for an explanation of route constraints provided by the framework.

MapRoute の追加オーバーロードは、constraintsdataTokensdefaults の値を受け取ります。Additional overloads of MapRoute accept values for constraints, dataTokens, and defaults. このようなパラメーターは一般的に、匿名型のオブジェクトを渡し、匿名型のプロパティ名がルート パラメーター名と一致するというような使われ方をします。The typical usage of these parameters is to pass an anonymously typed object, where the property names of the anonymous type match route parameter names.

次の MapRoute 例では、同等のルートを作成します。The following MapRoute examples create equivalent routes:

routes.MapRoute(
    name: "default_route",
    template: "{controller}/{action}/{id?}",
    defaults: new { controller = "Home", action = "Index" });

routes.MapRoute(
    name: "default_route",
    template: "{controller=Home}/{action=Index}/{id?}");

ヒント

制約と既定値を定義するインライン構文は単純なルートの場合に便利です。The inline syntax for defining constraints and defaults can be convenient for simple routes. しかし、インライン構文でサポートされていない、データ トークンなどのシナリオがあります。However, there are scenarios, such as data tokens, that aren't supported by inline syntax.

次の例では、その他のいくつかのシナリオを示します。The following example demonstrates a few additional scenarios:

routes.MapRoute(
    name: "blog",
    template: "Blog/{**article}",
    defaults: new { controller = "Blog", action = "ReadArticle" });

上記のテンプレートでは /Blog/All-About-Routing/Introduction のような URL パスを照合し、値 { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction } を抽出します。The preceding template matches a URL path like /Blog/All-About-Routing/Introduction and extracts the values { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction }. controlleraction の既定のルート値は、テンプレートに対応するルート パラメーターがなくても、ルートにより生成されます。The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. 既定値はルート テンプレートで指定できます。Default values can be specified in the route template. article ルート パラメーターは、ルート パラメーター名の前に二重アスタリスク (**) があるときに、キャッチオール として定義されます。The article route parameter is defined as a catch-all by the appearance of an double asterisk (**) before the route parameter name. キャッチオール ルート パラメーターは、URL パスの残りの部分をキャプチャします。空の文字列も照合できます。Catch-all route parameters capture the remainder of the URL path and can also match the empty string.

routes.MapRoute(
    name: "blog",
    template: "Blog/{*article}",
    defaults: new { controller = "Blog", action = "ReadArticle" });

上記のテンプレートでは /Blog/All-About-Routing/Introduction のような URL パスを照合し、値 { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction } を抽出します。The preceding template matches a URL path like /Blog/All-About-Routing/Introduction and extracts the values { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction }. controlleraction の既定のルート値は、テンプレートに対応するルート パラメーターがなくても、ルートにより生成されます。The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. 既定値はルート テンプレートで指定できます。Default values can be specified in the route template. article ルート パラメーターは、ルート パラメーター名の前にアスタリスク (*) があるときに、キャッチオール として定義されます。The article route parameter is defined as a catch-all by the appearance of an asterisk (*) before the route parameter name. キャッチオール ルート パラメーターは、URL パスの残りの部分をキャプチャします。空の文字列も照合できます。Catch-all route parameters capture the remainder of the URL path and can also match the empty string.

次の例では、ルート制約とデータ トークンを追加します。The following example adds route constraints and data tokens:

routes.MapRoute(
    name: "us_english_products",
    template: "en-US/Products/{id}",
    defaults: new { controller = "Products", action = "Details" },
    constraints: new { id = new IntRouteConstraint() },
    dataTokens: new { locale = "en-US" });

上記のテンプレートでは /en-US/Products/5 のような URL パスを照合し、値 { controller = Products, action = Details, id = 5 } とデータ トークン { locale = en-US } を抽出します。The preceding template matches a URL path like /en-US/Products/5 and extracts the values { controller = Products, action = Details, id = 5 } and the data tokens { locale = en-US }.

ローカル変数ウィンドウ トークン

ルート クラス URL の生成Route class URL generation

Route クラスは、一連のルート値をそのルート テンプレートと組み合わせる方法でも URL を生成できます。The Route class can also perform URL generation by combining a set of route values with its route template. 論理的には、URL パスの照合とは逆のプロセスになります。This is logically the reverse process of matching the URL path.

ヒント

URL 生成を理解する方法として、どのような URL を生成したいのかを考えてください。そして、ルート テンプレートがその URL にどのように照合されるのかを考えてください。To better understand URL generation, imagine what URL you want to generate and then think about how a route template would match that URL. どのような値が生成されるでしょうか。What values would be produced? Route クラスにおける URL 生成のしくみと大体同じになります。This is the rough equivalent of how URL generation works in the Route class.

次の例では、一般的な ASP.NET Core MVC の既定のルートを使用します。The following example uses a general ASP.NET Core MVC default route:

routes.MapRoute(
    name: "default",
    template: "{controller=Home}/{action=Index}/{id?}");

ルート値が { controller = Products, action = List } の場合、URL /Products/List が生成されます。With the route values { controller = Products, action = List }, the URL /Products/List is generated. ルート値が対応ルート パラメーターの代替となり、URL パスが作られます。The route values are substituted for the corresponding route parameters to form the URL path. id は任意のルート パラメーターであるため、URL は id の値なしで正常に生成されます。Since id is an optional route parameter, the URL is successfully generated without a value for id.

ルート値が { controller = Home, action = Index } の場合、URL / が生成されます。With the route values { controller = Home, action = Index }, the URL / is generated. 指定されたルート値は既定値と一致し、その既定値に対応するセグメントを省略しても問題は発生しません。The provided route values match the default values, and the segments corresponding to the default values are safely omitted.

生成された両方の URL では、次のルート定義 (/Home/Index/) でラウンドトリップされ、URL の生成に使用された同じルート値が生成されます。Both URLs generated round-trip with the following route definition (/Home/Index and /) produce the same route values that were used to generate the URL.

注意

アプリで ASP.NET Core MVC が使用される場合、ルーティングを直接呼び出す代わりに、UrlHelper を使用して URL を生成する必要があります。An app using ASP.NET Core MVC should use UrlHelper to generate URLs instead of calling into routing directly.

URL 生成の詳細については、「URL 生成参照」セクションを参照してください。For more information on URL generation, see the Url generation reference section.

ルーティング ミドルウェアの使用Use Routing Middleware

アプリのプロジェクト ファイルの Microsoft.AspNetCore.App メタパッケージを参照します。Reference the Microsoft.AspNetCore.App metapackage in the app's project file.

Startup.ConfigureServices でサービス コンテナーにルーティングを追加した例:Add routing to the service container in Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRouting();
}

ルートは Startup.Configure メソッドで設定する必要があります。Routes must be configured in the Startup.Configure method. サンプル アプリでは次の API を使用します。The sample app uses the following APIs:

var trackPackageRouteHandler = new RouteHandler(context =>
{
    var routeValues = context.GetRouteData().Values;
    return context.Response.WriteAsync(
        $"Hello! Route values: {string.Join(", ", routeValues)}");
});

var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);

routeBuilder.MapRoute(
    "Track Package Route",
    "package/{operation:regex(^track|create|detonate$)}/{id:int}");

routeBuilder.MapGet("hello/{name}", context =>
{
    var name = context.GetRouteValue("name");
    // The route handler when HTTP GET "hello/<anything>" matches
    // To match HTTP GET "hello/<anything>/<anything>, 
    // use routeBuilder.MapGet("hello/{*name}"
    return context.Response.WriteAsync($"Hi, {name}!");
});

var routes = routeBuilder.Build();
app.UseRouter(routes);

下の表は、応答と所与の URI をまとめたものです。The following table shows the responses with the given URIs.

URIURI 応答Response
/package/create/3 Hello!Hello! Route values: [operation, create], [id, 3]Route values: [operation, create], [id, 3]
/package/track/-3 Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/-3/ Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/ 要求はフォール スルーし、一致するものはありません。The request falls through, no match.
GET /hello/Joe Hi, Joe!Hi, Joe!
POST /hello/Joe 要求はフォール スルーし、HTTP GET のみが一致します。The request falls through, matches HTTP GET only.
GET /hello/Joe/Smith 要求はフォール スルーし、一致するものはありません。The request falls through, no match.

ルートを 1 つ構成する場合、UseRouter を呼び出し、IRouter インスタンスを渡します。If you're configuring a single route, call UseRouter passing in an IRouter instance. RouteBuilder を使用する必要はありません。You won't need to use RouteBuilder.

このフレームワークでは、ルートを作成するために拡張メソッド セット (RequestDelegateRouteBuilderExtensions) が提供されます。The framework provides a set of extension methods for creating routes (RequestDelegateRouteBuilderExtensions):

  • MapDelete
  • MapGet
  • MapMiddlewareDelete
  • MapMiddlewareGet
  • MapMiddlewarePost
  • MapMiddlewarePut
  • MapMiddlewareRoute
  • MapMiddlewareVerb
  • MapPost
  • MapPut
  • MapRoute
  • MapVerb

MapGet など、リストされているメソッドの一部では、RequestDelegate が必要です。Some of listed methods, such as MapGet, require a RequestDelegate. RequestDelegate は、ルートが一致したとき、ルート ハンドラーとして使用されます。The RequestDelegate is used as the route handler when the route matches. この仲間の他のメソッドでは、ルート ハンドラーとして使用されるミドルウェア パイプラインを構成できます。Other methods in this family allow configuring a middleware pipeline for use as the route handler. Map* メソッドで、MapRoute などのハンドラーを受け入れない場合、DefaultHandler が使用されます。If the Map* method doesn't accept a handler, such as MapRoute, it uses the DefaultHandler.

Map[Verb] メソッドは制約を利用し、メソッド名の HTTP Verb にルートを制限します。The Map[Verb] methods use constraints to limit the route to the HTTP Verb in the method name. たとえば、 MapGetMapVerbを参照してください。For example, see MapGet and MapVerb.

ルート テンプレート参照Route template reference

中括弧 ({ ... }) 内のトークンはルート パラメーターを定義します。ルートが一致した場合、これがバインドされます。Tokens within curly braces ({ ... }) define route parameters that are bound if the route is matched. 1 つのルート セグメントで複数のルート パラメーターを定義できますが、リテラル値で区切る必要があります。You can define more than one route parameter in a route segment, but they must be separated by a literal value. たとえば、{controller=Home}{action=Index} は有効なルートになりません。{controller}{action} の間にリテラル値がないためです。For example, {controller=Home}{action=Index} isn't a valid route, since there's no literal value between {controller} and {action}. このようなルート パラメーターには名前を付ける必要があります。付加的な属性を指定することもあります。These route parameters must have a name and may have additional attributes specified.

ルート パラメーター以外のリテラル テキスト ({id} など) とパス区切り / は URL のテキストに一致する必要があります。Literal text other than route parameters (for example, {id}) and the path separator / must match the text in the URL. テキスト照合は復号された URL パスを基盤とし、大文字と小文字が区別されます。Text matching is case-insensitive and based on the decoded representation of the URLs path. リテラル ルート パラメーターの区切り記号 ({ または }) を照合するには、文字を繰り返して区切り記号をエスケープします ({{ または }})。To match a literal route parameter delimiter ({ or }), escape the delimiter by repeating the character ({{ or }}).

任意のファイル拡張子が付いたファイル名のキャプチャを試行する URL パターンには、追加の考慮事項があります。URL patterns that attempt to capture a file name with an optional file extension have additional considerations. たとえば、テンプレート files/{filename}.{ext?} について考えてみます。For example, consider the template files/{filename}.{ext?}. filenameext の両方の値が存在するときに、両方の値が入力されます。When values for both filename and ext exist, both values are populated. URL に filename の値だけが存在する場合、末尾のピリオド (.) は任意であるため、このルートは一致となります。If only a value for filename exists in the URL, the route matches because the trailing period (.) is optional. 次の URL はこのルートに一致します。The following URLs match this route:

  • /files/myFile.txt
  • /files/myFile

ルート パラメーターのプレフィックスとしてアスタリスク (*) または二重アスタリスク (**) を使用し、URI の残りの部分にバインドできます。You can use an asterisk (*) or double asterisk (**) as a prefix to a route parameter to bind to the rest of the URI. これらは、キャッチオール パラメーターと呼ばれています。These are called a catch-all parameters. たとえば、blog/{**slug} は、/blog で始まり、その後に (slug ルート値に割り当てられる) 任意の値が続くあらゆる URI に一致します。For example, blog/{**slug} matches any URI that starts with /blog and has any value following it, which is assigned to the slug route value. キャッチオール パラメーターは空の文字列に一致することもあります。Catch-all parameters can also match the empty string.

キャッチオール パラメーターでは、パス区切り (/) 文字を含め、URL の生成にルートが使用されるときに適切な文字がエスケープされます。The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. たとえば、ルート値が { path = "my/path" } のルート foo/{*path} では、foo/my%2Fpath が生成されます。For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. エスケープされたスラッシュに注意してください。Note the escaped forward slash. パス区切り文字をラウンドトリップさせるには、** ルート パラメーター プレフィックスを使用します。To round-trip path separator characters, use the ** route parameter prefix. { path = "my/path" } のルート foo/{**path} では、foo/my/path が生成されます。The route foo/{**path} with { path = "my/path" } generates foo/my/path.

ルート パラメーターのプレフィックスとしてアスタリスク (*) を使用し、URI の残りの部分にバインドできます。You can use the asterisk (*) as a prefix to a route parameter to bind to the rest of the URI. これはキャッチオール パラメーターと呼ばれています。This is called a catch-all parameter. たとえば、blog/{*slug} は、/blog で始まり、その後に (slug ルート値に割り当てられる) 任意の値が続くあらゆる URI に一致します。For example, blog/{*slug} matches any URI that starts with /blog and has any value following it, which is assigned to the slug route value. キャッチオール パラメーターは空の文字列に一致することもあります。Catch-all parameters can also match the empty string.

キャッチオール パラメーターでは、パス区切り (/) 文字を含め、URL の生成にルートが使用されるときに適切な文字がエスケープされます。The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. たとえば、ルート値が { path = "my/path" } のルート foo/{*path} では、foo/my%2Fpath が生成されます。For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. エスケープされたスラッシュに注意してください。Note the escaped forward slash.

ルート パラメーターには、既定値 が含まれることがあります。パラメーター名の後に既定値を指定し、等号 (=) で区切ることで指定されます。Route parameters may have default values designated by specifying the default value after the parameter name separated by an equals sign (=). たとえば、{controller=Home} では、controller の既定値として Home が定義されます。For example, {controller=Home} defines Home as the default value for controller. パラメーターの URL に値がない場合、既定値が使用されます。The default value is used if no value is present in the URL for the parameter. ルート パラメーターは、id? のように、パラメーター名の終わりに疑問符 (?) を追加することでオプションとして扱われます。Route parameters are made optional by appending a question mark (?) to the end of the parameter name, as in id?. オプション値と既定ルート パラメーターの違いは、既定値を含むルート パラメーターは常に値を生成するのに対し、オプションのパラメーターには、要求 URL によって値が指定されたときにのみ値が与えられることにあります。The difference between optional values and default route parameters is that a route parameter with a default value always produces a value—an optional parameter has a value only when a value is provided by the request URL.

ルート パラメーターには、URL からバインドされるルート値に一致しなければならないという制約が含まれることがあります。Route parameters may have constraints that must match the route value bound from the URL. コロン (:) と制約名をルート パラメーター名の後に追加すると、ルート パラメーターのインライン制約が指定されます。Adding a colon (:) and constraint name after the route parameter name specifies an inline constraint on a route parameter. その制約で引数が要求される場合、制約名の後にかっこ ((...)) で囲まれます。If the constraint requires arguments, they're enclosed in parentheses ((...)) after the constraint name. 別のコロン (:) と制約名を追加することで、複数のインライン制約を指定できます。Multiple inline constraints can be specified by appending another colon (:) and constraint name.

制約名と引数が IInlineConstraintResolver サービスに渡され、URL 処理で使用する IRouteConstraint のインスタンスが作成されます。The constraint name and arguments are passed to the IInlineConstraintResolver service to create an instance of IRouteConstraint to use in URL processing. たとえば、ルート テンプレート blog/{article:minlength(10)} によって、制約 minlength と引数 10 が指定されます。For example, the route template blog/{article:minlength(10)} specifies a minlength constraint with the argument 10. ルート制約の詳細とこのフレームワークによって指定される制約のリストについては、「ルート制約参照」セクションを参照してください。For more information on route constraints and a list of the constraints provided by the framework, see the Route constraint reference section.

ルート パラメーターには、リンクを生成し、ページおよびアクションを URL と一致させるときにパラメーターの値を変換する、パラメーター トランスフォーマーが含まれている場合もあります。Route parameters may also have parameter transformers, which transform a parameter's value when generating links and matching actions and pages to URLs. 制約と同様に、パラメーター トランスフォーマーをルート パラメーターにインラインで追加することができます。その場合、ルート パラメーター名の後にコロン (:) とトランスフォーマー名を追加します。Like constraints, parameter transformers can be added inline to a route parameter by adding a colon (:) and transformer name after the route parameter name. たとえば、ルート テンプレート blog/{article:slugify} では、slugify トランスフォーマーが指定されます。For example, the route template blog/{article:slugify} specifies a slugify transformer. パラメーター トランスフォーマーの詳細については、「パラメーター トランスフォーマー参照」セクションを参照してください。For more information on parameter transformers, see the Parameter transformer reference section.

次の表は、ルート テンプレートの例とその動作をまとめたものです。The following table demonstrates example route templates and their behavior.

ルート テンプレートRoute Template 一致する URI の例Example Matching URI 要求 URI…The request URI…
hello /hello 単一パス /hello にのみ一致します。Only matches the single path /hello.
{Page=Home} / 一致し、PageHome に設定されます。Matches and sets Page to Home.
{Page=Home} /Contact 一致し、PageContact に設定されます。Matches and sets Page to Contact.
{controller}/{action}/{id?} /Products/List Products コントローラーと List アクションにマッピングされます。Maps to the Products controller and List action.
{controller}/{action}/{id?} /Products/Details/123 Products コントローラーと Details アクションにマッピングされます (id は 123 に設定されます)。Maps to the Products controller and Details action (id set to 123).
{controller=Home}/{action=Index}/{id?}{controller=Home}/{action=Index}/{id?} / Home コントローラーと Index メソッドにマッピングされます (id は無視されます)。Maps to the Home controller and Index method (id is ignored).

一般的に、テンプレートの利用が最も簡単なルーティングの手法となります。Using a template is generally the simplest approach to routing. ルート テンプレート以外では、制約と既定値も指定できます。Constraints and defaults can also be specified outside the route template.

ヒント

ログを有効にすると、Route など、組み込みのルーティング実装で要求を照合するしくみを確認できます。Enable Logging to see how the built-in routing implementations, such as Route, match requests.

ルーティングの予約名Reserved routing names

次のキーワードは予約名であり、ルート名やパラメーターとして使用できません。The following keywords are reserved names and can't be used as route names or parameters:

  • action
  • area
  • controller
  • handler
  • page

ルート制約参照Route constraint reference

ルート制約は、受信 URL と一致し、URL パスがルート値にトークン化されたときに実行されます。Route constraints execute when a match has occurred to the incoming URL and the URL path is tokenized into route values. ルート制約では、通常、ルート テンプレート経由で関連付けられるルート値を調べ、値が許容できるかどうかをはい/いいえで決定します。Route constraints generally inspect the route value associated via the route template and make a yes/no decision about whether or not the value is acceptable. 一部のルート制約では、ルート値以外のデータを使用し、要求をルーティングできるかどうかが考慮されます。Some route constraints use data outside the route value to consider whether the request can be routed. たとえば、HttpMethodRouteConstraint はその HTTP Verb に基づいて要求を承認または却下します。For example, the HttpMethodRouteConstraint can accept or reject a request based on its HTTP verb. 制約は、要求のルーティングとリンクの生成で使用されます。Constraints are used in routing requests and link generation.

警告

入力の検証には制約を使用しないでください。Don't use constraints for input validation. 入力の検証に制約が使用されると、無効な入力の結果、400 - Bad Request と適切なエラー メッセージではなく、404 - Not Found が表示されます。If constraints are used for input validation, invalid input results in a 404 - Not Found response instead of a 400 - Bad Request with an appropriate error message. ルート制約は、特定のルートに対する入力の妥当性を検証するためではなく、似たようなルートの違いを明らかにするために使用されます。Route constraints are used to disambiguate similar routes, not to validate the inputs for a particular route.

次の表は、ルート制約の例とそれに求められる動作をまとめたものです。The following table demonstrates example route constraints and their expected behavior.

制約constraint Example 一致の例Example Matches メモNotes
int {id:int} 123456789-123456789123456789, -123456789 あらゆる整数に一致するMatches any integer
bool {active:bool} trueFALSEtrue, FALSE true または false に一致する (大文字と小文字を区別しません)Matches true or false (case-insensitive)
datetime {dob:datetime} 2016-12-312016-12-31 7:32pm2016-12-31, 2016-12-31 7:32pm 有効な DateTime 値に一致する (インバリアント カルチャで - 警告参照)Matches a valid DateTime value (in the invariant culture - see warning)
decimal {price:decimal} 49.99-1,000.0149.99, -1,000.01 有効な decimal 値に一致する (インバリアント カルチャで - 警告参照)Matches a valid decimal value (in the invariant culture - see warning)
double {weight:double} 1.234-1,001.01e81.234, -1,001.01e8 有効な double 値に一致する (インバリアント カルチャで - 警告参照)Matches a valid double value (in the invariant culture - see warning)
float {weight:float} 1.234-1,001.01e81.234, -1,001.01e8 有効な float 値に一致する (インバリアント カルチャで - 警告参照)Matches a valid float value (in the invariant culture - see warning)
guid {id:guid} CD2C1638-1638-72D5-1638-DEADBEEF1638{CD2C1638-1638-72D5-1638-DEADBEEF1638}CD2C1638-1638-72D5-1638-DEADBEEF1638, {CD2C1638-1638-72D5-1638-DEADBEEF1638} 有効な Guid 値に一致するMatches a valid Guid value
long {ticks:long} 123456789-123456789123456789, -123456789 有効な long 値に一致するMatches a valid long value
minlength(value) {username:minlength(4)} Rick 4 文字以上の文字列であることが必要String must be at least 4 characters
maxlength(value) {filename:maxlength(8)} Richard 8 文字以内の文字列であることが必要String must be no more than 8 characters
length(length) {filename:length(12)} somefile.txt 厳密に 12 文字の文字列であることが必要String must be exactly 12 characters long
length(min,max) {filename:length(8,16)} somefile.txt 8 文字以上、16 文字以内の文字列であることが必要String must be at least 8 and no more than 16 characters long
min(value) {age:min(18)} 19 18 以上の整数値であることが必要Integer value must be at least 18
max(value) {age:max(120)} 91 120 以下の整数値であることが必要Integer value must be no more than 120
range(min,max) {age:range(18,120)} 91 18 以上、120 以下の整数値であることが必要Integer value must be at least 18 but no more than 120
alpha {name:alpha} Rick 1 つまたは複数のアルファベット文字で構成される文字列が必要 (a-z、大文字と小文字を区別)String must consist of one or more alphabetical characters (a-z, case-insensitive)
regex(expression) {ssn:regex(^\\d{{3}}-\\d{{2}}-\\d{{4}}$)} 123-45-6789 正規表現に一致する文字列が必要 (正規表現の定義についてはヒントを参照)String must match the regular expression (see tips about defining a regular expression)
required {name:required} Rick URL 生成中、非パラメーターが提示されるように強制するUsed to enforce that a non-parameter value is present during URL generation

コロンで区切られた複数の制約を単一のパラメーターに適用することができます。Multiple, colon-delimited constraints can be applied to a single parameter. たとえば、次の制約では、パラメーターが 1 以上の整数値に制限されます。For example, the following constraint restricts a parameter to an integer value of 1 or greater:

[Route("users/{id:int:min(1)}")]
public User GetUserById(int id) { }

警告

URL の妥当性を検証し、CLR 型 (intDateTime など) に変換されるルート制約では、常にインバリアント カルチャが使用されます。Route constraints that verify the URL and are converted to a CLR type (such as int or DateTime) always use the invariant culture. これらの制約では、URL がローカライズ不可であることが前提となります。These constraints assume that the URL is non-localizable. フレームワークから提供されるルート制約がルート値に格納されている値を変更することはありません。The framework-provided route constraints don't modify the values stored in route values. URL から解析されたルート値はすべて文字列として格納されます。All route values parsed from the URL are stored as strings. たとえば、float 制約はルート値を浮動小数に変換しますが、変換された値は、浮動小数に変換できることを検証するためにだけ利用されます。For example, the float constraint attempts to convert the route value to a float, but the converted value is used only to verify it can be converted to a float.

正規表現Regular expressions

ASP.NET Core フレームワークでは、正規表現コンストラクターに RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant が追加されます。The ASP.NET Core framework adds RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant to the regular expression constructor. これらのメンバーの詳細については、「RegexOptions」を参照してください。See RegexOptions for a description of these members.

正規表現では、ルーティングや C# 言語で使用されるものに似た区切り記号とトークンが使用されます。Regular expressions use delimiters and tokens similar to those used by Routing and the C# language. 正規表現トークンはエスケープする必要があります。Regular expression tokens must be escaped. ルーティングで正規表現 ^\d{3}-\d{2}-\d{4}$ を使用するには、C# ソース ファイルで \\ (二重円記号) 文字として文字列に \ (単一の円記号) 文字を指定し、文字列エスケープ文字である \ をエスケープする必要があります (逐語的な文字列リテラルを使用しない限り)。To use the regular expression ^\d{3}-\d{2}-\d{4}$ in routing, the expression must have the \ (single backslash) characters provided in the string as \\ (double backslash) characters in the C# source file in order to escape the \ string escape character (unless using verbatim string literals). ルーティング パラメーター区切り記号文字 ({}[]) をエスケープするには、表現の文字を二重にします ({{}[[]])。To escape routing parameter delimiter characters ({, }, [, ]), double the characters in the expression ({{, }, [[, ]]). 次の表に、正規表現とエスケープ適用後のものを示します。The following table shows a regular expression and the escaped version.

正規表現Regular Expression エスケープ適用後の正規表現Escaped Regular Expression
^\d{3}-\d{2}-\d{4}$ ^\\d{{3}}-\\d{{2}}-\\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$

ルーティングで使用される正規表現は、多くの場合、キャレット (^) 文字で始まり、文字列の開始位置と一致します。Regular expressions used in routing often start with the caret (^) character and match starting position of the string. 表現は、多くの場合、ドル記号 ($) で終わり、文字列の末尾と一致します。The expressions often end with the dollar sign ($) character and match end of the string. ^ 文字と $ 文字により、正規表現はルート パラメーター値全体に一致します。The ^ and $ characters ensure that the regular expression match the entire route parameter value. ^ 文字と $ 文字がなければ、正規表現は、文字列内のあらゆる部分文字列に一致します。それは多くの場合、意図に反することです。Without the ^ and $ characters, the regular expression match any substring within the string, which is often undesirable. 下の表では例を示し、それらが一致する、または一致しない理由について説明します。The following table provides examples and explains why they match or fail to match.

正規表現Expression StringString 一致したものMatch コメントComment
[a-z]{2} hellohello [はい]Yes サブ文字列の一致Substring matches
[a-z]{2} 123abc456123abc456 [はい]Yes サブ文字列の一致Substring matches
[a-z]{2} mzmz [はい]Yes 一致する表現Matches expression
[a-z]{2} MZMZ [はい]Yes 大文字と小文字の使い方が違うNot case sensitive
^[a-z]{2}$ hellohello ×No 上の ^$ を参照See ^ and $ above
^[a-z]{2}$ 123abc456123abc456 ×No 上の ^$ を参照See ^ and $ above

正規表現構文の詳細については、.NET Framework 正規表現に関するページを参照してください。For more information on regular expression syntax, see .NET Framework Regular Expressions.

既知の入力可能値の集まりにパラメーターを制限するには、正規表現を使用します。To constrain a parameter to a known set of possible values, use a regular expression. たとえば、{action:regex(^(list|get|create)$)} の場合、action ルート値は listgetcreate とのみ照合されます。For example, {action:regex(^(list|get|create)$)} only matches the action route value to list, get, or create. 制約ディクショナリに渡された場合、文字列 ^(list|get|create)$ で同じものになります。If passed into the constraints dictionary, the string ^(list|get|create)$ is equivalent. (テンプレート内でインラインではなく) 制約ディクショナリに渡された制約が既知の制約に一致しない場合も、正規表現として扱われます。Constraints that are passed in the constraints dictionary (not inline within a template) that don't match one of the known constraints are also treated as regular expressions.

パラメーター トランスフォーマー参照Parameter transformer reference

パラメーター トランスフォーマー:Parameter transformers:

  • Route のリンクの生成時に実行されます。Execute when generating a link for a Route.
  • Microsoft.AspNetCore.Routing.IOutboundParameterTransformerを実装します。Implement Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.
  • ConstraintMap を使用して構成されます。Are configured using ConstraintMap.
  • パラメーターのルート値を取得し、それを新しい文字列値に変換します。Take the parameter's route value and transform it to a new string value.
  • 変換された値は生成されたリンクで使用されるようになります。Result in using the transformed value in the generated link.

たとえば、Url.Action(new { article = "MyTestArticle" }) のルート パターン blog\{article:slugify} のカスタム slugify パラメーター トランスフォーマーでは、blog\my-test-article が生成されます。For example, a custom slugify parameter transformer in route pattern blog\{article:slugify} with Url.Action(new { article = "MyTestArticle" }) generates blog\my-test-article.

パラメーター トランスフォーマーは、エンドポイントが解決される URI を変換するためにフレームワークで使用されます。Parameter transformers are used by the framework to transform the URI where an endpoint resolves. たとえば、ASP.NET Core MVC ではパラメーター トランスフォーマーを使用して、areacontrolleractionpage を照合するために使用されるルート値を変換します。For example, ASP.NET Core MVC uses parameter transformers to transform the route value used to match an area, controller, action, and page.

routes.MapRoute(
    name: "default",
    template: "{controller=Home:slugify}/{action=Index:slugify}/{id?}");

上記のルートでは、アクション SubscriptionManagementController.GetAll() は URI /subscription-management/get-all と一致します。With the preceding route, the action SubscriptionManagementController.GetAll() is matched with the URI /subscription-management/get-all. パラメーター トランスフォーマーでは、リンクを生成するために使用されるルート値は変更されません。A parameter transformer doesn't change the route values used to generate a link. たとえば、Url.Action("GetAll", "SubscriptionManagement") では /subscription-management/get-all が出力されます。For example, Url.Action("GetAll", "SubscriptionManagement") outputs /subscription-management/get-all.

ASP.NET Core では、生成されたルートと共にパラメーター トランスフォーマーを使用するための API 規則が提供されます。ASP.NET Core provides API conventions for using a parameter transformers with generated routes:

  • ASP.NET Core MVC には、Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention API 規則が備わっています。ASP.NET Core MVC has the Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention API convention. この規則では、指定されたパラメーター トランスフォーマーがアプリ内のすべての属性ルートに適用されます。This convention applies a specified parameter transformer to all attribute routes in the app. パラメーター トランスフォーマーでは、置き換えられる属性ルート トークンが変換されます。The parameter transformer transforms attribute route tokens as they are replaced. 詳細については、「パラメーター トランスフォーマーを使用してトークンの置換をカスタマイズする」をご覧ください。For more information, see Use a parameter transformer to customize token replacement.
  • Razor Pages には、Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention API 規則があります。Razor Pages has the Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention API convention. この規則では、指定されたパラメーター トランスフォーマーが自動で検出されたすべての Razor Pages に適用されます。This convention applies a specified parameter transformer to all automatically discovered Razor Pages. パラメーター トランスフォーマーでは、Razor Pages ルートのフォルダーとファイル名のセグメントが変換されます。The parameter transformer transforms the folder and file name segments of Razor Pages routes. 詳細については、パラメーター トランスフォーマーを使用したページ ルートのカスタマイズに関する記事をご覧ください。For more information, see Use a parameter transformer to customize page routes.

URL 生成参照URL generation reference

次の例では、ルートのリンクを生成する方法を確認できます。ルート値のディクショナリと RouteCollection が指定されています。The following example shows how to generate a link to a route given a dictionary of route values and a RouteCollection.

app.Run(async (context) =>
{
    var dictionary = new RouteValueDictionary
    {
        { "operation", "create" },
        { "id", 123}
    };

    var vpc = new VirtualPathContext(context, null, dictionary, 
        "Track Package Route");
    var path = routes.GetVirtualPath(vpc).VirtualPath;

    context.Response.ContentType = "text/html";
    await context.Response.WriteAsync("Menu<hr/>");
    await context.Response.WriteAsync(
        $"<a href='{path}'>Create Package 123</a><br/>");
});

上のサンプルの終わりで生成された VirtualPath/package/create/123 です。The VirtualPath generated at the end of the preceding sample is /package/create/123. ディクショナリにより、"Track Package Route" テンプレート package/{operation}/{id} のルート値 operationid が提供されます。The dictionary supplies the operation and id route values of the "Track Package Route" template, package/{operation}/{id}. 詳細については、「ルーティング ミドルウェアの使用」セクションのサンプル コードまたはサンプル アプリを参照してください。For details, see the sample code in the Use Routing Middleware section or the sample app.

VirtualPathContext コンストラクターの 2 番目のパラメーターはアンビエント値の集合です。The second parameter to the VirtualPathContext constructor is a collection of ambient values. アンビエント値は、開発者が要求コンテキスト内で指定する必要がある値の数が制限されるため、使用すると便利です。Ambient values are convenient to use because they limit the number of values a developer must specify within a request context. 現在の要求の現在のルート値は、リンク生成の場合、アンビエント値として見なされます。The current route values of the current request are considered ambient values for link generation. ASP.NET Core MVC アプリの HomeControllerAbout アクションでは、コントローラー ルート値を指定し、Index アクションにリンクする必要はありません。Home のアンビエント値が使用されます。In an ASP.NET Core MVC app's About action of the HomeController, you don't need to specify the controller route value to link to the Index action—the ambient value of Home is used.

パラメーターに一致しないアンビエント値は無視されます。Ambient values that don't match a parameter are ignored. アンビエント値は、明示的に指定された値でアンビエント値がオーバーライドされる場合にも無視されます。Ambient values are also ignored when an explicitly provided value overrides the ambient value. URL では左から右に照合されます。Matching occurs from left to right in the URL.

明示的に指定されているが、ルートのセグメントと一致しない値は、クエリ文字列に追加されます。Values explicitly provided but that don't match a segment of the route are added to the query string. 次の表は、ルート テンプレート {controller}/{action}/{id?} の使用時の結果をまとめたものです。The following table shows the result when using the route template {controller}/{action}/{id?}.

アンビエント値Ambient Values 明示的な値Explicit Values 結果Result
controller = "Home"controller = "Home" action = "About"action = "About" /Home/About
controller = "Home"controller = "Home" controller = "Order", action = "About"controller = "Order", action = "About" /Order/About
controller = "Home", color = "Red"controller = "Home", color = "Red" action = "About"action = "About" /Home/About
controller = "Home"controller = "Home" action = "About", color = "Red"action = "About", color = "Red" /Home/About?color=Red

パラメーターに対応しない既定値がルートにあり、その値が明示的に指定される場合、それは既定値に一致する必要があります。If a route has a default value that doesn't correspond to a parameter and that value is explicitly provided, it must match the default value:

routes.MapRoute("blog_route", "blog/{*slug}",
    defaults: new { controller = "Blog", action = "ReadPost" });

リンク生成では、controlleraction について一致する値が指定されるときにのみ、このルートのリンクが生成されます。Link generation only generates a link for this route when the matching values for controller and action are provided.