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

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

ルーティング機能は受信要求をルート ハンドラーにマッピングします。Routing functionality is responsible for mapping an incoming request to a route handler. ルートは ASP.NET アプリに定義され、アプリの起動時に構成されます。Routes are defined in the ASP.NET app and configured when the app starts up. ルートは、要求に含まれている URL から値を任意で抽出できます。その値を要求処理に利用できます。A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. ルーティング機能は、ASP.NET アプリからのルート情報を利用し、ルート ハンドラーにマッピングする URL を生成することもできます。Using route information from the ASP.NET app, the routing functionality is also able to generate URLs that map to route handlers. そのため、ルーティングでは URL に基づいて、つまり、ルート ハンドラー情報によって指定されるルート ハンドラーに対応する URL に基づいてルート ハンドラーを見つけることができます。Therefore, routing can find a route handler based on a URL, or the URL corresponding to a given route handler based on route handler information.

重要

本文では、ASP.NET Core ルーティングについて詳しく取り上げます。This document covers the low level ASP.NET Core routing. ASP.NET Core MVC ルーティングについては、コントローラー アクションへのルーティングに関するページを参照してください。For ASP.NET Core MVC routing, see Route to controller actions

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

ルーティングの基本Routing basics

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

  • 受信要求をルート ハンドラーにマッピングするmap incoming requests to route handlers

  • 応答で使用される URL を生成するgenerate URLs used in responses

一般的に、アプリにはルート コレクションが 1 つ与えられます。Generally, an app has a single collection of routes. 要求が届くと、そのルート コレクションが順を追って処理されます。When a request arrives, the route collection is processed in order. 受信要求は、ルート コレクションのルートごとに RouteAsync メソッドを呼び出し、要求 URL に一致するルートを探します。The incoming request looks for a route that matches the request URL by calling the RouteAsync method on each available route in the route collection. それに対し、応答はルーティングを利用し、ルート情報に基づいて URL (リダイレクションやリンクの URL など) を生成できます。そのため、URL をハードコーディングする必要がなく、保守管理が楽になります。By contrast, a response can use routing to generate URLs (for example, for redirection or links) based on route information, and thus avoid having to hard-code URLs, which helps maintainability.

ルーティングは RouterMiddleware クラスによりミドルウェア パイプラインに接続されます。Routing is connected to the middleware pipeline by the RouterMiddleware class. ASP.NET Core MVC は、ミドルウェア パイプラインにその構成の一部としてルーティングを追加します。ASP.NET Core MVC adds routing to the middleware pipeline as part of its configuration. スタンドアロン コンポーネントとしてルーティングを利用する方法については、「ルーティング ミドルウェアの使用」を参照してください。To learn about using routing as a standalone component, see Using routing middleware.

URL 一致URL matching

URL 一致というプロセスでは、ルーティングによって、受信要求がハンドラーに配布されます。URL matching is the process by which routing dispatches an incoming request to a handler. このプロセスは通常、URL パスのデータに基づきますが、要求内のあらゆるデータを考慮することもできます。This process is generally 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 application.

受信要求は 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 will be invoked to process the request. すべてのルートが試され、要求に適したハンドラーが見つからなかった場合、ミドルウェアはを呼び出し、要求パイプラインの次のミドルウェアが呼び出されます。If all routes are tried and no handler is found for the request, the middleware calls next and the next middleware in the request pipeline is invoked.

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 that will be set after a route matches.

また、RouteAsync で一致が見つかると、それまでに完了した要求処理に基づき、RouteContext.RouteData のプロパティが適切な値に設定されます。A match during RouteAsync will also set the properties of the RouteContext.RouteData to appropriate values based on the request processing done so far. ルートが要求に一致すると、RouteContext.RouteData結果に関する重要なステータス情報が追加されます。If a route matches a request, the RouteContext.RouteData will contain important state information about the result.

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 application.

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 the application can make decisions later based on which route matched. この値は開発者が定義するものです。ルーティングの動作に影響を与えることはありませんThese values are developer-defined and do not affect the behavior of routing in any way. また、データ トークンに格納された値はどのような種類でも構いません。一方、ルート値は文字列に簡単に変換できる種類でなければなりません。Additionally, values stashed in data tokens can be of any type, in contrast to route values, which must be easily convertible to and from strings.

RouteData.Routers は、過去に要求に一致したルートの一覧です。RouteData.Routers is a list of the routes that took part in successfully matching the request. ルートはルートの中に入れ子にすることができます。Routers プロパティは、結果的に一致をもたらしたルートの論理ツリーを通るパスを表します。Routes can be nested inside one another, and 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 handlers and the URLs that access them.

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

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

  • VirtualPathContext.HttpContext

  • VirtualPathContext.Values

  • VirtualPathContext.AmbientValues

ルートは ValuesAmbientValues が与えるルート値を第一に利用し、どこで URL を生成できるか、どの値を含めるかを決定します。Routes primarily use the route values provided by the Values and AmbientValues to decide where 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 with the routing system. 対照的に、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 needs to get services or additional data associated with the current context.

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

GetVirtualPath の出力は VirtualPathData です。The output of GetVirtualPath is a VirtualPathData. VirtualPathDataRouteData の並列です。これには出力 URL として VirtualPath が含まれ、ルートで設定する追加プロパティがいくつか含まれます。VirtualPathData is a parallel of RouteData; it 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 で表示するには、アプリケーションの基礎パスを先頭に追加する必要があります。For instance, if you want to render the generated URL in HTML you need to prepend the base path of the application.

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.

ルートの作成Creating 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 that will match against the URL path when RouteAsync is called. Route は同じルート テンプレートを利用し、GetVirtualPath の呼び出し時に URL を生成します。Route will use the same route template to generate a URL when GetVirtualPath is called.

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

注: MapRoute はルート ハンドラー パラメーターを受け取りません。DefaultHandler によって処理されるルートを追加するだけです。Note: MapRoute doesn't take a route handler parameter - it only adds routes that will be handled by the DefaultHandler. 既定のハンドラーは IRouter であるため、要求を処理しないように決定されることがあります。Since the default handler is an IRouter, it may decide not to handle the request. たとえば、ASP.NET MVC は通常、利用できるコントローラーやアクションに一致する要求のみを処理する既定のハンドラーとして構成されます。For example, ASP.NET MVC is typically configured as a default handler that only handles requests that match an available controller and action. MVC にルーティングする方法については、コントローラー アクションへのルーティングに関するページを参照してください。To learn more about routing to MVC, see Route to controller actions.

一般的な ASP.NET MVC ルート定義によって使用される MapRoute 呼び出しの例:This is an example of a MapRoute call used by a typical ASP.NET MVC route definition:

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

このテンプレートは /Products/Details/17 のような URL パスを照合し、ルート値 { controller = Products, action = Details, id = 17 } を抽出します。This template will match a URL path like /Products/Details/17 and extract the route values { controller = Products, action = Details, id = 17 }. ルート値は、URL パスをセグメントに分割し、各セグメントとルート テンプレートのルート パラメーターを照合することで決定されます。The 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. 括弧 { } でパラメーターを囲むことで定義されます。They're defined by enclosing the parameter name in braces { }.

上のテンプレートは URL パス / を照合し、値 { controller = Home, action = Index } を生成します。The template above could also match the URL path / and would produce the values { controller = Home, action = Index }. これは、ルート パラメーターの {controller}{action} に既定値が与えられ、id ルート パラメーターが任意であるためです。This happens 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 the parameter as optional. 既定値のルート パラメーターはルートが一致すると、ルート値を常に生成します。オプションのパラメーターは、対応する URL パス セグメントがなかった場合、ルート値を生成しません。Route parameters with a default value always produce a route value when the route matches - optional parameters won't produce a route value if there was no corresponding URL path segment.

ルート テンプレートの機能と構文については、「route-template-reference」(ルート テンプレート参照) に詳しい説明があります。See route-template-reference for a thorough description of route template features and syntax.

ルート制約が含まれる例:This example includes a route constraint:

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

このテンプレートは /Products/Details/Apples ではなく、/Products/Details/17 のような URL パスを照合します。This template will match a URL path like /Products/Details/17, but not /Products/Details/Apples. ルート パラメーター定義 {id:int} により、id ルート パラメーターのルート制約が定義されます。The route parameter definition {id:int} defines a route constraint for the id route parameter. ルート制約は 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 a more detailed explanation of route constraints that are provided by the framework.

MapRoute の追加オーバーロードは、constraintsdataTokensdefaults の値を受け取ります。Additional overloads of MapRoute accept values for constraints, dataTokens, and defaults. MapRoute のこのような追加パラメーターは object 型として定義されます。These additional parameters of MapRoute are defined as type object. このようなパラメーターは一般的に、匿名型のオブジェクトを渡し、匿名型のプロパティ名がルート パラメーター名と一致するというような使われ方をします。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.

同等のルートを作成する 2 つの例:The following two 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?}");

ヒント: 制約と既定値を定義するインライン構文は単純なルートの場合に便利です。Tip: The inline syntax for defining constraints and defaults can be more convenient for simple routes. ただし、インライン構文でサポートされないデータ トークンなどの機能があります。However, there are features such as data tokens which are not supported by inline syntax.

その他の機能を示す例:This example demonstrates a few more features:

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 } を抽出します。This template will match a URL path like /Blog/All-About-Routing/Introduction and will extract 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.

ルート制約とデータ トークンを追加する例:This 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 } を抽出します。This 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 生成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 にどのように照合されるのか考えてください。Tip: 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 MVC スタイルのルートの使用例:This example uses a basic ASP.NET MVC style 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 }, this route will generate the URL /Products/List. ルート値が対応ルート パラメーターの代替となり、URL パスが作られます。The route values are substituted for the corresponding route parameters to form the URL path. id は任意のルート パラメーターであるため、値がなくても問題ありません。Since id is an optional route parameter, it's no problem that it doesn't have a value.

ルート値が { controller = Home, action = Index } のとき、このルートは URL / を生成します。With the route values { controller = Home, action = Index }, this route will generate the URL /. 与えられたルート値が既定値に一致することで、その値に対応するセグメントを省略しても問題が発生しません。The route values that were provided match the default values so the segments corresponding to those values can be safely omitted. 生成されたいずれの URL もこのルート定義でラウンドトリップし、URL の生成に利用された同じルート値を生成することに注意してください。Note that both URLs generated would round-trip with this route definition and produce the same route values that were used to generate the URL.

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

URL 生成処理の詳細については、「URL 生成参照」を参照してください。For more details about the URL generation process, see url-generation-reference.

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

NuGet パッケージ "Microsoft.AspNetCore.Routing" を追加します。Add the NuGet package "Microsoft.AspNetCore.Routing".

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

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

ルートは Startup クラスの Configure メソッドに設定する必要があります。Routes must be configured in the Configure method in the Startup class. 下のサンプルで使用されている API:The sample below uses these APIs:

  • RouteBuilder
  • Build
  • MapGet HTTP GET 要求のみを照合MapGet Matches only HTTP GET requests
  • UseRouter
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    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");
        // This is 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 table below shows the responses with the given URIs.

URIURI 応答Response
/package/create/3/package/create/3 Hello!Hello! Route values: [operation, create], [id, 3]Route values: [operation, create], [id, 3]
/package/track/-3/package/track/-3 Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/-3//package/track/-3/ Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track//package/track/ <Fall through, no match><Fall through, no match>
GET /hello/JoeGET /hello/Joe Hi, Joe!Hi, Joe!
POST /hello/JoePOST /hello/Joe <Fall through, matches HTTP GET only><Fall through, matches HTTP GET only>
GET /hello/Joe/SmithGET /hello/Joe/Smith <Fall through, no match><Fall through, no match>

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

このフレームワークは、ルートを作成するために次のような拡張メソッドを提供します。The framework provides a set of extension methods for creating routes such as:

  • MapRoute
  • MapGet
  • MapPost
  • MapPut
  • MapDelete
  • MapVerb

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

Map[Verb] メソッドは制約を利用し、メソッド名の HTTP Verb にルートを制限します。The Map[Verb] methods use constraints to limit the route to the HTTP Verb in the method name. 例が必要な場合、「MapGet」や「MapVerb」をご覧ください。For example, see MapGet and MapVerb.

ルート テンプレート参照Route Template Reference

中括弧 ({ }) 内のトークンはルート パラメーターを定義します。ルートが一致した場合、これがバインドされます。Tokens within curly braces ({ }) define route parameters which will be 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} wouldn't be 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 the literal route parameter delimiter { or }, escape it by repeating the character ({{ or }}).

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

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

ルート パラメーターのプレフィックスとして * 文字を使用し、URI の残りの部分にバインドできます。これはキャッチオール パラメーターと呼ばれています。You can use the * character 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} would match any URI that started with /blog and had any value following it (which would be assigned to the slug route value). キャッチオール パラメーターは空の文字列に一致することもあります。Catch-all parameters can also match the empty string.

ルート パラメーターには、既定値が含まれることがあります。パラメーター名の後に既定値を指定し、= で区切ることで指名されます。Route parameters may have default values, designated by specifying the default after the parameter name, separated by an =. たとえば、{controller=Home} では、controller の既定値として Home が定義されます。For example, {controller=Home} would define 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? のように、パラメーター名の終わりに ? を追加して指定します)。In addition to default values, route parameters may be optional (specified by appending a ? to the end of the parameter name, as in id?). オプションと "既定値がある" ことの違いは、既定値を含むルート パラメーターは常に値を生成するのに対し、オプションのパラメーターには値が指定されたときにのみ値が与えられることにあります。The difference between optional and "has default" is that a route parameter with a default value always produces a value; an optional parameter has a value only when one is provided.

ルート パラメーターには、URL からバインドされるルート値に一致しなければならないという制約も含まれることがあります。Route parameters may also have constraints, which 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 those are provided 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 is 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 the minlength constraint with the argument 10. ルート制約の詳細とこのフレームワークで与えられる制約の一覧については、「ルート制約参照」を参照してください。For more description route constraints, and a listing of the constraints provided by the framework, see route-constraint-reference.

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

ルート テンプレートRoute Template 一致する URL の例Example Matching URL メモNotes
hellohello /hello/hello パス /hello にのみ一致Only matches the single path /hello
{Page=Home}{Page=Home} / 一致し、PageHome に設定されるMatches and sets Page to Home
{Page=Home}{Page=Home} /Contact/Contact 一致し、PageContact に設定されるMatches and sets Page to Contact
{controller}/{action}/{id?}{controller}/{action}/{id?} /Products/List/Products/List コントローラー Products とアクション List にマッピングされるMaps to Products controller and List action
{controller}/{action}/{id?}{controller}/{action}/{id?} /Products/Details/123/Products/Details/123 コントローラー Products とアクション Details にマッピングされ、Maps to Products controller and Details action. id が 123 に設定されるid set to 123
{controller=Home}/{action=Index}/{id?}{controller=Home}/{action=Index}/{id?} / コントローラー Home とメソッド Index にマッピングされ、id が無視されるMaps to 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 など、組み込みのルーティング実装が要求を照合するしくみを確認できます。Tip: 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

ルート制約は、Route が入ってきた URL の構文に一致し、URL パスをルート値にトークン化したときに実行されます。Route constraints execute when a Route has matched the syntax of the incoming URL and tokenized the URL path into route values. ルート制約では、通常、ルート テンプレート経由で関連付けらるルート値を調べ、値が許容できるかどうかを単純な「はい/いいえ」で決定します。Route constraints generally inspect the route value associated via the route template and make a simple 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.

警告

入力検証には制約を使用しないでください。無効な入力に起因し、400 と適切なエラー メッセージではなく、404 (Not Found) が表示されます。Avoid using constraints for input validation, because doing so means that invalid input will result in a 404 (Not Found) instead of a 400 with an appropriate error message. ルート制約は、特定のルートに対する入力の妥当性を検証するためではなく、似たようなルートの違いを明らかにするために使用してください。Route constraints should be used to disambiguate between similar routes, not to validate the inputs for a particular route.

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

制約constraint Example 一致の例Example Matches メモNotes
int {id:int} 123456789, -123456789123456789, -123456789 あらゆる整数に一致するMatches any integer
bool {active:bool} true, FALSEtrue, FALSE true または false に一致する (大文字と小文字が区別されます)Matches true or false (case-insensitive)
datetime {dob:datetime} 2016-12-31, 2016-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 など) に変換できます。常にインバリアント カルチャを使用してください。URL がローカライズ不可であると見なされます。Route constraints that verify the URL can be converted to a CLR type (such as int or DateTime) always use the invariant culture - they assume 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 will be stored as strings. たとえば、浮動小数ルート制約はルート値を浮動小数に変換しますが、変換された値は、浮動小数に変換できることを検証するためにだけ利用されます。For example, the Float route constraint will attempt 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 Enumeration」(RegexOptions 列挙) を参照してください。See RegexOptions Enumeration 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# ソース ファイルで \ 文字を \\ のように入力し、文字列エスケープ文字である \ をエスケープする必要があります (逐語的な文字列リテラルを使用しない限り)。For example, to use the regular expression ^\d{3}-\d{2}-\d{4}$ in Routing, it needs to have the \ characters typed in as \\ in the C# source file to escape the \ string escape character (unless using verbatim string literals. {}、'['、']' 文字は、二回入力することでエスケープし、ルーティング パラメーター区切り文字をエスケープする必要があります。The { , } , '[' and ']' characters need to be escaped by doubling them to escape the Routing parameter delimiter characters. 次の表は、正規表現とエスケープ適用後の表示をまとめたものです。The table below shows a regular expression and the escaped version.

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

ルーティングで使用される正規表現は、多くの場合、^ 文字で始まり (文字列の開始位置に一致)、$ 文字で終わります (文字列の終了文字に一致)。Regular expressions used in routing will often start with the ^ character (match starting position of the string) and end with the $ character (match ending position of the string). ^ 文字と $ 文字により、正規表現はルート パラメーター値全体に一致します。The ^ and $ characters ensure that the regular expression match the entire route parameter value. ^ 文字と $ 文字がなければ、正規表現は、意図に反して文字列内のあらゆる部分文字列に一致します。Without the ^ and $ characters the regular expression will match any substring within the string, which is often not what you want. 下の表では例をいくつか挙げ、それが一致する/一致しない理由をまとめています。The table below shows some 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 正規表現」を参照してください。Refer to .NET Framework Regular Expressions for more information on regular expression syntax.

既知の入力可能値の集まりにパラメーターを制限するには、正規表現を使用します。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)$" would be 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.

URL 生成参照URL Generation Reference

下の例では、ルートのリンクを生成する方法を確認できます。ルート値のディクショナリと RouteCollection が指定されています。The example below 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 sample above is /package/create/123.

VirtualPathContext コンストラクターの 2 番目のパラメーターはアンビエント値の集合です。The second parameter to the VirtualPathContext constructor is a collection of ambient values. アンビエント値は、開発者が特定の文脈で要求における値を指定しなければならないよう、値の数を制限するので便利です。Ambient values provide convenience by limiting the number of values a developer must specify within a certain request context. 現在の要求の現在のルート値は、リンク生成の場合、アンビエント値として見なされます。The current route values of the current request are considered ambient values for link generation. たとえば、ASP.NET MVC アプリで HomeControllerAbout アクション中、コントローラー ルート値を指定し、Index アクションにリンクする必要はありません (Home のアンビエント値が使用されます)。For example, in an ASP.NET MVC app if you are in the 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 will be used).

パラメーターに一致しないアンビエント値は無視されます。明示的に指定された値によりオーバーライドされるときもアンビエント値は無視されます (URL の左から右へ)。Ambient values that don't match a parameter are ignored, and ambient values are also ignored when an explicitly-provided value overrides it, going from left to right in the URL.

明示的に指定されているが何も一致しない値はクエリ文字列に追加されます。Values that are explicitly provided but which don't match anything 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. 例:For example:

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

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