ASP.NET Core에서 라우팅Routing in ASP.NET Core

작성자: Ryan Nowak, Steve SmithRick AndersonBy Ryan Nowak, Steve Smith, and Rick Anderson

라우팅은 요청 URI를 엔드포인트에 매핑하고 들어오는 요청을 이러한 엔드포인트로 디스패치합니다.Routing is responsible for mapping request URIs to endpoints and dispatching incoming requests to those 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 endpoints.

중요

이 문서에서는 낮은 수준의 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.

일반적으로 개발자는 특성 라우팅 또는 전용 기존 경로를 사용하여 특수한 상황에서 앱의 트래픽이 높은 영역(예: 블로그 및 전자 상거래 엔드포인트)에 간결한 추가 경로를 추가합니다.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. 메타데이터는 각 엔드포인트에 연결된 정책과 구성에 따라 횡단 관심사(Cross-Cutting Concerns)를 구현하는 데 사용됩니다.The metadata is used to 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)는 DI(종속성 주입)를 사용하여 URL을 생성하기 위해 어디서나 확인할 수 있습니다.The Link Generator API (LinkGenerator) can be resolved anywhere using dependency injection (DI) to generate URLs.
    • DI를 통해 링크 생성기 API를 사용할 수 없는 경우 IUrlHelper에서 URL을 작성하는 메서드를 제공합니다.Where the Link Generator API isn't available via DI, IUrlHelper offers methods to build URLs.

참고

엔드포인트 연결은 MVC/Razor Pages 작업 및 페이지로 제한됩니다.Endpoint linking is limited to MVC/Razor Pages actions and pages. 이후 릴리스에서는 엔드포인트 연결 기능이 확장될 예정입니다.The expansions of endpoint-linking capabilities is planned for future releases.

라우팅은 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.

라우팅 미들웨어가 실행되면 엔드포인트(Endpoint) 및 경로 값을 HttpContext의 기능으로 설정합니다.When a Routing Middleware executes, it sets an endpoint (Endpoint) and route values to a feature on the HttpContext. 현재 요청의 경우 다음과 같이 동작합니다.For the current request:

  • HttpContext.GetEndpoint를 호출하면 엔드포인트를 가져옵니다.Calling HttpContext.GetEndpoint gets the endpoint.
  • HttpRequest.RouteValues는 경로 값의 컬렉션을 가져옵니다.HttpRequest.RouteValues gets the collection of route values.

라우팅 미들웨어 뒤에 실행되는 미들웨어는 엔드포인트를 보고, 작업을 수행할 수 있습니다.Middleware running after the Routing Middleware can see the endpoint and take action. 예를 들어 권한 부여 미들웨어는 엔드포인트의 메타데이터 컬렉션에서 권한 부여 정책에 대한 정보를 얻을 수 있습니다.For example, an Authorization Middleware can interrogate the endpoint's metadata collection for an authorization policy. 요청 처리 파이프라인의 모든 미들웨어가 실행된 후에 선택한 엔드포인트의 대리자가 호출됩니다.After all of the middleware in the request processing pipeline is executed, the selected endpoint's delegate is invoked.

엔드포인트 라우팅의 라우팅 시스템은 모든 디스패치를 결정합니다.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.

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에 안전하게 배치되는(stashed) 값은 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.

LinkGenerator를 사용한 URL 생성URL generation with LinkGenerator

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의 IUrlHelperIUrlHelper를 사용하는 시나리오(예: 태그 도우미, HTML 도우미 및 작업 결과)는 링크 생성기를 사용하여 링크 생성 기능을 제공합니다.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:

이러한 메서드의 오버로드에는 HttpContext를 포함한 인수가 허용됩니다.An overload of these methods accepts arguments that include the HttpContext. 이러한 메서드는 기능적으로 Url.ActionUrl.Page와 동일하지만, 추가적인 유연성과 옵션을 제공합니다.These methods are functionally equivalent to Url.Action and Url.Page but offer additional flexibility and options.

GetPath* 메서드는 절대 경로가 포함된 URI를 생성한다는 점에서 Url.ActionUrl.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 생성은 다음 두 단계로 수행됩니다.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:

  • 들어오는 요청의 GetUri* 헤더의 유효성을 검사하지 않는 앱 구성에서는 Host 확장 메서드를 신중하게 사용하세요.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.

  • 미들웨어에서 MapWhen 또는 LinkGenerator과 함께 Map를 사용할 때는 신중하게 사용하세요.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 이전 버전의 라우팅 간에는 다음과 같은 몇 가지 차이점이 있습니다.A few differences exist between endpoint routing and versions of routing earlier than in ASP.NET Core 2.2:

  • 엔드포인트 라우팅 시스템은 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). 엔드포인트 라우팅은 이 동작을 전역으로 사용자 지정하거나 URL 매핑에 대해 다른 규칙을 적용하는 데 사용할 수 있는 IOutboundParameterTransformer 인터페이스를 제공합니다.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인 경우 Store/Info 페이지에서 @Url.Page("/Login")로 생성된 링크는 /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.

  • 라운드트립 경로 매개 변수 구문: 이중 별표(**) 범용(catch-all) 매개 변수 구문을 사용하는 경우 슬래시는 인코딩되지 않습니다.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.

using Microsoft.AspNetCore.Routing;

public class ProductsLinkMiddleware
{
    private readonly LinkGenerator _linkGenerator;

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

    public async Task InvokeAsync(HttpContext httpContext)
    {
        var url = _linkGenerator.GetPathByAction("ListProducts", "Store");

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

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

경로 만들기Create routes

대부분의 앱은 MapRoute 또는 IRouteBuilder에 정의된 유사한 확장 메서드 중 하나를 호출하여 경로를 만듭니다.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. MapRouteDefaultHandler에 의해 처리되는 경로만 추가합니다.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의 컨트롤러 작업에 라우팅.

다음 코드 예제는 일반적인 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의 추가 오버로드는 constraints, dataTokensdefaults에 대한 값을 허용합니다.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.

다음 예제에서는 경로 제약 조건 및 데이터 토큰을 추가합니다.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 }.

지역 Windows 토큰

Route 클래스 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? 이는 URL 생성이 Route 클래스에서 작동하는 방식과 대략적으로 동일합니다.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 } 경로 값을 사용하면 /Products/List URL이 생성됩니다.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는 선택적 경로 매개 변수이므로 id에 대한 값 없이 URL이 성공적으로 생성됩니다.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.

뒤이어 언급된 경로 정의(/Home/Index/)를 사용하는 URL 생성 왕복 모두에서는 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$)}/{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.

프레임워크는 경로를 만드는 확장 메서드 모음(RequestDelegateRouteBuilderExtensions)을 제공합니다.The framework provides a set of extension methods for creating routes (RequestDelegateRouteBuilderExtensions):

Map[Verb] 메서드는 제약 조건을 사용하여 메서드 이름에 지정된 HTTP 동사에 대한 경로로 제한합니다.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. 경로 세그먼트에 둘 이상의 경로 매개 변수를 정의할 수 있지만 리터럴 값으로 분리되어 있어야 합니다.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.

catch-all 매개 변수는 경로 구분 기호(/) 문자를 포함하여 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.

경로 매개 변수에는 등호(=)로 구분된 매개 변수 이름 뒤에 기본값을 지정하여 지정된 기본값이 있을 수 있습니다.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.

제약 조건 이름 및 인수는 IRouteConstraint의 인스턴스를 만드는 IInlineConstraintResolver 서비스로 전달되어 URL 처리에서 사용합니다.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)}는 인수 10으로 minlength 제약 조건을 지정합니다.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?} / 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 동사에 따라 요청을 허용하거나 거부할 수 있습니다.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 - 잘못된 요청 대신 404 - 찾을 수 없음 응답이 발생합니다.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} 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 문자열은 하나 이상의 알파벳 문자(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) { }

경고

CLR 형식(예: int 또는 DateTime)으로 변환되는 URL을 확인하는 경로 제약 조건은 항상 고정 문화권을 사용합니다.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 문자열String 일치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 경로 값을 list, get 또는 create으로만 일치시킵니다.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.

사용자 지정 경로 제약 조건Custom Route Constraints

기본 제공 경로 제약 조건 외에도 IRouteConstraint 인터페이스를 구현하여 사용자 지정 경로 제약 조건을 만들 수 있습니다.In addition to the built-in route constraints, custom route constraints can be created by implementing the IRouteConstraint interface. IRouteConstraint 인터페이스에는 제약 조건이 충족되는 경우 true를 반환하고 그렇지 않은 경우 false를 반환하는 Match 단일 메서드가 포함됩니다.The IRouteConstraint interface contains a single method, Match, which returns true if the constraint is satisfied and false otherwise.

사용자 지정 IRouteConstraint를 사용하려면 앱의 서비스 컨테이너에 있는 앱의 ConstraintMap에 경로 제약 조건 형식을 등록해야 합니다.To use a custom IRouteConstraint, the route constraint type must be registered with the app's ConstraintMap in the app's service container. ConstraintMap은 경로 제약 조건 키를 해당 제약 조건의 유효성을 검사하는 IRouteConstraint 구현과 매핑하는 사전입니다.A ConstraintMap is a dictionary that maps route constraint keys to IRouteConstraint implementations that validate those constraints. Startup.ConfigureServices에서 services.AddRouting 호출의 일부로 또는 services.Configure<RouteOptions>를 사용하여 직접 RouteOptions를 구성하여 앱의 ConstraintMap을 수정할 수 있습니다.An app's ConstraintMap can be updated in Startup.ConfigureServices either as part of a services.AddRouting call or by configuring RouteOptions directly with services.Configure<RouteOptions>. 예:For example:

services.AddRouting(options =>
{
    options.ConstraintMap.Add("customName", typeof(MyCustomConstraint));
});

이제 제약 조건 형식을 등록할 때 지정한 이름을 사용하여 일반적인 방식으로 제약 조건을 경로에 적용할 수 있습니다.The constraint can then be applied to routes in the usual manner, using the name specified when registering the constraint type. 예:For example:

[HttpGet("{id:customName}")]
public ActionResult<string> Get(string id)

매개 변수 변환기 참조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.

경로 패턴에서 매개 변수 변환기를 사용하려면 먼저 Startup.ConfigureServicesConstraintMap을 사용하여 구성합니다.To use a parameter transformer in a route pattern, configure it first using ConstraintMap in Startup.ConfigureServices:

services.AddRouting(options =>
{
    // Replace the type and the name used to refer to it with your own
    // IOutboundParameterTransformer implementation
    options.ConstraintMap["slugify"] = typeof(SlugifyParameterTransformer);
});

매개 변수 변환기는 프레임워크에 의해 사용되어 엔드포인트가 해결되는 URI를 변환합니다.Parameter transformers are used by the framework to transform the URI where an endpoint resolves. 예를 들어 ASP.NET Core MVC는 매개 변수 변환기를 사용하여 area , controller , actionpage와 일치하도록 사용되는 경로 값을 변환합니다.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:slugify=Home}/{action:slugify=Index}/{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 생성자에 대한 두 번째 매개 변수는 앰비언트 값의 컬렉션입니다.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 앱의 HomeController에 대한 About 작업에서는 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.

복잡한 세그먼트Complex segments

복잡한 세그먼트(예: [Route("/x{token}y")])는 non-greedy 방식으로 오른쪽에서 왼쪽으로 리터럴을 매칭하여 처리됩니다.Complex segments (for example [Route("/x{token}y")]) are processed by matching up literals from right to left in a non-greedy way. 복잡한 세그먼트 일치 방법에 대한 자세한 설명은 이 코드를 참조하세요.See this code for a detailed explanation of how complex segments are matched. 코드 샘플은 ASP.NET Core에서 사용되지 않지만 복잡한 세그먼트에 대한 적절한 설명을 제공합니다.The code sample is not used by ASP.NET Core, but it provides a good explanation of complex segments.

라우팅은 요청 URI를 엔드포인트에 매핑하고 들어오는 요청을 이러한 엔드포인트로 디스패치합니다.Routing is responsible for mapping request URIs to endpoints and dispatching incoming requests to those 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 endpoints.

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.

중요

이 문서에서는 낮은 수준의 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.

일반적으로 개발자는 특성 라우팅 또는 전용 기존 경로를 사용하여 특수한 상황에서 앱의 트래픽이 높은 영역(예: 블로그 및 전자 상거래 엔드포인트)에 간결한 추가 경로를 추가합니다.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. 메타데이터는 각 엔드포인트에 연결된 정책과 구성에 따라 횡단 관심사(Cross-Cutting Concerns)를 구현하는 데 사용됩니다.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)는 DI(종속성 주입)를 사용하여 URL을 생성하기 위해 어디서나 확인할 수 있습니다.The Link Generator API (LinkGenerator) can be resolved anywhere using dependency injection (DI) to generate URLs.
    • DI를 통해 링크 생성기 API를 사용할 수 없는 경우 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.

라우팅은 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.

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에 안전하게 배치되는(stashed) 값은 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.

LinkGenerator를 사용한 URL 생성URL generation with LinkGenerator

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의 IUrlHelperIUrlHelper를 사용하는 시나리오(예: 태그 도우미, HTML 도우미 및 작업 결과)는 링크 생성기를 사용하여 링크 생성 기능을 제공합니다.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:

이러한 메서드의 오버로드에는 HttpContext를 포함한 인수가 허용됩니다.An overload of these methods accepts arguments that include the HttpContext. 이러한 메서드는 기능적으로 Url.ActionUrl.Page와 동일하지만, 추가적인 유연성과 옵션을 제공합니다.These methods are functionally equivalent to Url.Action and Url.Page but offer additional flexibility and options.

GetPath* 메서드는 절대 경로가 포함된 URI를 생성한다는 점에서 Url.ActionUrl.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 생성은 다음 두 단계로 수행됩니다.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:

  • 들어오는 요청의 GetUri* 헤더의 유효성을 검사하지 않는 앱 구성에서는 Host 확장 메서드를 신중하게 사용하세요.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.

  • 미들웨어에서 MapWhen 또는 LinkGenerator과 함께 Map를 사용할 때는 신중하게 사용하세요.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). 엔드포인트 라우팅은 이 동작을 전역으로 사용자 지정하거나 URL 매핑에 대해 다른 규칙을 적용하는 데 사용할 수 있는 IOutboundParameterTransformer 인터페이스를 제공합니다.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인 경우 Store/Info 페이지에서 @Url.Page("/Login")로 생성된 링크는 /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.

  • 라운드트립 경로 매개 변수 구문: 이중 별표(**) 범용(catch-all) 매개 변수 구문을 사용하는 경우 슬래시는 인코딩되지 않습니다.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.

using Microsoft.AspNetCore.Routing;

public class ProductsLinkMiddleware
{
    private readonly LinkGenerator _linkGenerator;

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

    public async Task InvokeAsync(HttpContext httpContext)
    {
        var url = _linkGenerator.GetPathByAction("ListProducts", "Store");

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

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

경로 만들기Create routes

대부분의 앱은 MapRoute 또는 IRouteBuilder에 정의된 유사한 확장 메서드 중 하나를 호출하여 경로를 만듭니다.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. MapRouteDefaultHandler에 의해 처리되는 경로만 추가합니다.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의 컨트롤러 작업에 라우팅.

다음 코드 예제는 일반적인 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의 추가 오버로드는 constraints, dataTokensdefaults에 대한 값을 허용합니다.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.

다음 예제에서는 경로 제약 조건 및 데이터 토큰을 추가합니다.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 }.

지역 Windows 토큰

Route 클래스 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? 이는 URL 생성이 Route 클래스에서 작동하는 방식과 대략적으로 동일합니다.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 } 경로 값을 사용하면 /Products/List URL이 생성됩니다.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는 선택적 경로 매개 변수이므로 id에 대한 값 없이 URL이 성공적으로 생성됩니다.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.

뒤이어 언급된 경로 정의(/Home/Index/)를 사용하는 URL 생성 왕복 모두에서는 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$)}/{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.

프레임워크는 경로를 만드는 확장 메서드 모음(RequestDelegateRouteBuilderExtensions)을 제공합니다.The framework provides a set of extension methods for creating routes (RequestDelegateRouteBuilderExtensions):

Map[Verb] 메서드는 제약 조건을 사용하여 메서드 이름에 지정된 HTTP 동사에 대한 경로로 제한합니다.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. 경로 세그먼트에 둘 이상의 경로 매개 변수를 정의할 수 있지만 리터럴 값으로 분리되어 있어야 합니다.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.

catch-all 매개 변수는 경로 구분 기호(/) 문자를 포함하여 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.

경로 매개 변수에는 등호(=)로 구분된 매개 변수 이름 뒤에 기본값을 지정하여 지정된 기본값이 있을 수 있습니다.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.

제약 조건 이름 및 인수는 IRouteConstraint의 인스턴스를 만드는 IInlineConstraintResolver 서비스로 전달되어 URL 처리에서 사용합니다.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)}는 인수 10으로 minlength 제약 조건을 지정합니다.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?} / 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 동사에 따라 요청을 허용하거나 거부할 수 있습니다.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 - 잘못된 요청 대신 404 - 찾을 수 없음 응답이 발생합니다.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} 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 문자열은 하나 이상의 알파벳 문자(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) { }

경고

CLR 형식(예: int 또는 DateTime)으로 변환되는 URL을 확인하는 경로 제약 조건은 항상 고정 문화권을 사용합니다.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 문자열String 일치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 경로 값을 list, get 또는 create으로만 일치시킵니다.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.

사용자 지정 경로 제약 조건Custom Route Constraints

기본 제공 경로 제약 조건 외에도 IRouteConstraint 인터페이스를 구현하여 사용자 지정 경로 제약 조건을 만들 수 있습니다.In addition to the built-in route constraints, custom route constraints can be created by implementing the IRouteConstraint interface. IRouteConstraint 인터페이스에는 제약 조건이 충족되는 경우 true를 반환하고 그렇지 않은 경우 false를 반환하는 Match 단일 메서드가 포함됩니다.The IRouteConstraint interface contains a single method, Match, which returns true if the constraint is satisfied and false otherwise.

사용자 지정 IRouteConstraint를 사용하려면 앱의 서비스 컨테이너에 있는 앱의 ConstraintMap에 경로 제약 조건 형식을 등록해야 합니다.To use a custom IRouteConstraint, the route constraint type must be registered with the app's ConstraintMap in the app's service container. ConstraintMap은 경로 제약 조건 키를 해당 제약 조건의 유효성을 검사하는 IRouteConstraint 구현과 매핑하는 사전입니다.A ConstraintMap is a dictionary that maps route constraint keys to IRouteConstraint implementations that validate those constraints. Startup.ConfigureServices에서 services.AddRouting 호출의 일부로 또는 services.Configure<RouteOptions>를 사용하여 직접 RouteOptions를 구성하여 앱의 ConstraintMap을 수정할 수 있습니다.An app's ConstraintMap can be updated in Startup.ConfigureServices either as part of a services.AddRouting call or by configuring RouteOptions directly with services.Configure<RouteOptions>. 예:For example:

services.AddRouting(options =>
{
    options.ConstraintMap.Add("customName", typeof(MyCustomConstraint));
});

이제 제약 조건 형식을 등록할 때 지정한 이름을 사용하여 일반적인 방식으로 제약 조건을 경로에 적용할 수 있습니다.The constraint can then be applied to routes in the usual manner, using the name specified when registering the constraint type. 예:For example:

[HttpGet("{id:customName}")]
public ActionResult<string> Get(string id)

매개 변수 변환기 참조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.

경로 패턴에서 매개 변수 변환기를 사용하려면 먼저 Startup.ConfigureServicesConstraintMap을 사용하여 구성합니다.To use a parameter transformer in a route pattern, configure it first using ConstraintMap in Startup.ConfigureServices:

services.AddRouting(options =>
{
    // Replace the type and the name used to refer to it with your own
    // IOutboundParameterTransformer implementation
    options.ConstraintMap["slugify"] = typeof(SlugifyParameterTransformer);
});

매개 변수 변환기는 프레임워크에 의해 사용되어 엔드포인트가 해결되는 URI를 변환합니다.Parameter transformers are used by the framework to transform the URI where an endpoint resolves. 예를 들어 ASP.NET Core MVC는 매개 변수 변환기를 사용하여 area , controller , actionpage와 일치하도록 사용되는 경로 값을 변환합니다.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:slugify=Home}/{action:slugify=Index}/{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 생성자에 대한 두 번째 매개 변수는 앰비언트 값의 컬렉션입니다.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 앱의 HomeController에 대한 About 작업에서는 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.

복잡한 세그먼트Complex segments

복잡한 세그먼트(예: [Route("/x{token}y")])는 non-greedy 방식으로 오른쪽에서 왼쪽으로 리터럴을 매칭하여 처리됩니다.Complex segments (for example [Route("/x{token}y")]) are processed by matching up literals from right to left in a non-greedy way. 복잡한 세그먼트 일치 방법에 대한 자세한 설명은 이 코드를 참조하세요.See this code for a detailed explanation of how complex segments are matched. 코드 샘플은 ASP.NET Core에서 사용되지 않지만 복잡한 세그먼트에 대한 적절한 설명을 제공합니다.The code sample is not used by ASP.NET Core, but it provides a good explanation of complex segments.

라우팅은 요청 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.

일반적으로 개발자는 특성 라우팅 또는 전용 기존 경로를 사용하여 특수한 상황에서 앱의 트래픽이 높은 영역(예: 블로그 및 전자 상거래 엔드포인트)에 간결한 추가 경로를 추가합니다.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.

라우팅은 경로(IRouter의 구현)를 사용하여 다음 작업을 수행합니다.Routing uses routes (implementations of IRouter) to:

  • 들어오는 요청을 경로 처리기에 매핑합니다.Map incoming requests to route handlers.
  • 응답에 사용되는 URL을 생성합니다.Generate the URLs used in responses.

기본적으로 앱에는 단일 경로 컬렉션이 있습니다.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 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에 안전하게 배치되는(stashed) 값은 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 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. HTML에서 생성된 URL을 렌더링하려는 경우 앱의 기본 경로를 추가합니다.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에 정의된 유사한 확장 메서드 중 하나를 호출하여 경로를 만듭니다.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. MapRouteDefaultHandler에 의해 처리되는 경로만 추가합니다.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의 추가 오버로드는 constraints, dataTokensdefaults에 대한 값을 허용합니다.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 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 }.

지역 Windows 토큰

Route 클래스 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? 이는 URL 생성이 Route 클래스에서 작동하는 방식과 대략적으로 동일합니다.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 } 경로 값을 사용하면 /Products/List URL이 생성됩니다.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는 선택적 경로 매개 변수이므로 id에 대한 값 없이 URL이 성공적으로 생성됩니다.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.

뒤이어 언급된 경로 정의(/Home/Index/)를 사용하는 URL 생성 왕복 모두에서는 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$)}/{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.

단일 경로를 구성하는 경우 IRouter 인스턴스를 전달하는 UseRouter를 호출합니다.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):

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 동사에 대한 경로로 제한합니다.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. 경로 세그먼트에 둘 이상의 경로 매개 변수를 정의할 수 있지만 리터럴 값으로 분리되어 있어야 합니다.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 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.

catch-all 매개 변수는 경로 구분 기호(/) 문자를 포함하여 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.

제약 조건 이름 및 인수는 IRouteConstraint의 인스턴스를 만드는 IInlineConstraintResolver 서비스로 전달되어 URL 처리에서 사용합니다.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)}는 인수 10으로 minlength 제약 조건을 지정합니다.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.

다음 표에서는 경로 템플릿 예제 및 해당 동작을 보여 줍니다.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?} / 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 동사에 따라 요청을 허용하거나 거부할 수 있습니다.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 - 잘못된 요청 대신 404 - 찾을 수 없음 응답이 발생합니다.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} 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 문자열은 하나 이상의 알파벳 문자(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) { }

경고

CLR 형식(예: int 또는 DateTime)으로 변환되는 URL을 확인하는 경로 제약 조건은 항상 고정 문화권을 사용합니다.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 문자열String 일치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 경로 값을 list, get 또는 create으로만 일치시킵니다.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.

사용자 지정 경로 제약 조건Custom Route Constraints

기본 제공 경로 제약 조건 외에도 IRouteConstraint 인터페이스를 구현하여 사용자 지정 경로 제약 조건을 만들 수 있습니다.In addition to the built-in route constraints, custom route constraints can be created by implementing the IRouteConstraint interface. IRouteConstraint 인터페이스에는 제약 조건이 충족되는 경우 true를 반환하고 그렇지 않은 경우 false를 반환하는 Match 단일 메서드가 포함됩니다.The IRouteConstraint interface contains a single method, Match, which returns true if the constraint is satisfied and false otherwise.

사용자 지정 IRouteConstraint를 사용하려면 앱의 서비스 컨테이너에 있는 앱의 ConstraintMap에 경로 제약 조건 형식을 등록해야 합니다.To use a custom IRouteConstraint, the route constraint type must be registered with the app's ConstraintMap in the app's service container. ConstraintMap은 경로 제약 조건 키를 해당 제약 조건의 유효성을 검사하는 IRouteConstraint 구현과 매핑하는 사전입니다.A ConstraintMap is a dictionary that maps route constraint keys to IRouteConstraint implementations that validate those constraints. Startup.ConfigureServices에서 services.AddRouting 호출의 일부로 또는 services.Configure<RouteOptions>를 사용하여 직접 RouteOptions를 구성하여 앱의 ConstraintMap을 수정할 수 있습니다.An app's ConstraintMap can be updated in Startup.ConfigureServices either as part of a services.AddRouting call or by configuring RouteOptions directly with services.Configure<RouteOptions>. 예:For example:

services.AddRouting(options =>
{
    options.ConstraintMap.Add("customName", typeof(MyCustomConstraint));
});

이제 제약 조건 형식을 등록할 때 지정한 이름을 사용하여 일반적인 방식으로 제약 조건을 경로에 적용할 수 있습니다.The constraint can then be applied to routes in the usual manner, using the name specified when registering the constraint type. 예:For example:

[HttpGet("{id:customName}")]
public ActionResult<string> Get(string id)

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 생성자에 대한 두 번째 매개 변수는 앰비언트 값의 컬렉션입니다.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 앱의 HomeController에 대한 About 작업에서는 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.

복잡한 세그먼트Complex segments

복잡한 세그먼트(예: [Route("/x{token}y")])는 non-greedy 방식으로 오른쪽에서 왼쪽으로 리터럴을 매칭하여 처리됩니다.Complex segments (for example [Route("/x{token}y")]) are processed by matching up literals from right to left in a non-greedy way. 복잡한 세그먼트 일치 방법에 대한 자세한 설명은 이 코드를 참조하세요.See this code for a detailed explanation of how complex segments are matched. 코드 샘플은 ASP.NET Core에서 사용되지 않지만 복잡한 세그먼트에 대한 적절한 설명을 제공합니다.The code sample is not used by ASP.NET Core, but it provides a good explanation of complex segments.