Enrutamiento en ASP.NET CoreRouting in ASP.NET Core

Por Ryan Nowak, Steve Smith y Rick AndersonBy Ryan Nowak, Steve Smith, and Rick Anderson

Para obtener la versión 1.1 de este tema, descargue Routing in ASP.NET Core (version 1.1, PDF) [Enrutamiento en ASP.NET Core (versión 1.1, PDF)].For the 1.1 version of this topic, download Routing in ASP.NET Core (version 1.1, PDF).

El enrutamiento es responsable de asignar URI de solicitud a los selectores de punto de conexión y de distribuir las solicitudes entrantes a los puntos de conexión.Routing is responsible for mapping request URIs to endpoint selectors and dispatching incoming requests to endpoints. Las rutas se definen en la aplicación y se configuran cuando se inicia la aplicación.Routes are defined in the app and configured when the app starts. Una ruta puede extraer opcionalmente valores de la dirección URL contenida en la solicitud, que se pueden usar para procesar las solicitudes.A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. Con la información de ruta de la aplicación, el enrutamiento también puede generar direcciones URL que se asignan a selectores de punto de conexión.Using route information from the app, routing is also able to generate URLs that map to endpoint selectors.

Para usar los escenarios de enrutamiento más recientes de ASP.NET Core 2.2, especifique la versión de compatibilidad en el registro de servicios de MVC en Startup.ConfigureServices: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);

La opción EnableEndpointRouting determina si el enrutamiento debe usar de forma interna la lógica basada en el punto de conexión o la lógica basada en IRouter de ASP.NET Core 2.1 o una versión anterior.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. Cuando la versión de compatibilidad se establece en 2.2 o una versión posterior, el valor predeterminado es true.When the compatibility version is set to 2.2 or later, the default value is true. Establezca el valor en false para usar la lógica de enrutamiento anterior: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);

Para obtener más información sobre el enrutamiento basado en IRouter, vea la versión para ASP.NET Core 2.1 de este tema.For more information on IRouter-based routing, see the ASP.NET Core 2.1 version of this topic.

El enrutamiento es responsable de asignar los URI de solicitud a los controladores de ruta y de distribuir las solicitudes entrantes.Routing is responsible for mapping request URIs to route handlers and dispatching an incoming requests. Las rutas se definen en la aplicación y se configuran cuando se inicia la aplicación.Routes are defined in the app and configured when the app starts. Una ruta puede extraer opcionalmente valores de la dirección URL contenida en la solicitud, que se pueden usar para procesar las solicitudes.A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. Mediante las rutas configuradas de la aplicación, el enrutamiento puede generar direcciones URL que se asignan a los controladores de ruta.Using configured routes from the app, routing is able to generate URLs that map to route handlers.

Para usar los escenarios de enrutamiento más recientes de ASP.NET Core 2.1, especifique la versión de compatibilidad en el registro de servicios de MVC en Startup.ConfigureServices: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);

Importante

En este documento se describe el enrutamiento de ASP.NET Core de bajo nivel.This document covers low-level ASP.NET Core routing. Para obtener información sobre el enrutamiento de ASP.NET Core MVC, vea Enrutar a acciones de controlador de ASP.NET Core.For information on ASP.NET Core MVC routing, see Enrutar a acciones de controlador de ASP.NET Core. Para obtener más información sobre las convenciones de enrutamiento en Razor Pages, consulte Convenciones de aplicación y de ruta de páginas de Razor en ASP.NET Core.For information on routing conventions in Razor Pages, see Convenciones de aplicación y de ruta de páginas de Razor en ASP.NET Core.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Fundamentos del enrutamientoRouting basics

La mayoría de las aplicaciones deben elegir un esquema de enrutamiento básico y descriptivo para que las direcciones URL sean legibles y significativas.Most apps should choose a basic and descriptive routing scheme so that URLs are readable and meaningful. La ruta convencional predeterminada {controller=Home}/{action=Index}/{id?}:The default conventional route {controller=Home}/{action=Index}/{id?}:

  • Admite un esquema de enrutamiento básico y descriptivo.Supports a basic and descriptive routing scheme.
  • Se trata de un punto de partida útil para las aplicaciones basadas en la interfaz de usuario.Is a useful starting point for UI-based apps.

Los desarrolladores suelen agregar rutas breves adicionales a áreas de mucho tráfico de una aplicación en situaciones especializadas (por ejemplo, puntos de conexión de blog y comercio electrónico) con el enrutamiento mediante atributos o rutas convencionales dedicadas.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.

Las API web deben usar el enrutamiento mediante atributos para modelar la funcionalidad de la aplicación como un conjunto de recursos donde las operaciones se representan mediante verbos 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. Esto significa que muchas operaciones (por ejemplo, GET y POST) del mismo recurso lógico usarán la misma dirección URL.This means that many operations (for example, GET, POST) on the same logical resource will use the same URL. El enrutamiento mediante atributos proporciona un nivel de control que es necesario para diseñar cuidadosamente un diseño de puntos de conexión públicos de la API.Attribute routing provides a level of control that's needed to carefully design an API's public endpoint layout.

En las aplicaciones de Razor Pages se usa el enrutamiento convencional predeterminado para proporcionar recursos con nombre en la carpeta Páginas de una aplicación.Razor Pages apps use default conventional routing to serve named resources in the Pages folder of an app. Existen convenciones adicionales que permiten personalizar el comportamiento de enrutamiento de Razor Pages.Additional conventions are available that allow you to customize Razor Pages routing behavior. Para obtener más información, vea Introducción a las páginas de Razor en ASP.NET Core y Convenciones de aplicación y de ruta de páginas de Razor en ASP.NET Core.For more information, see Introducción a las páginas de Razor en ASP.NET Core and Convenciones de aplicación y de ruta de páginas de Razor en ASP.NET Core.

La compatibilidad de la generación de direcciones URL permite desarrollar la aplicación sin codificar de forma rígida las direcciones URL para vincular la aplicación.URL generation support allows the app to be developed without hard-coding URLs to link the app together. Esta compatibilidad permite empezar con una configuración de enrutamiento básica y modificar las rutas una vez determinado el diseño de los recursos de la aplicación.This support allows for starting with a basic routing configuration and modifying the routes after the app's resource layout is determined.

El enrutamiento usa puntos de conexión (Endpoint) para representar los puntos de conexión lógicos en una aplicación.Routing uses endpoints (Endpoint) to represent logical endpoints in an app.

Un punto de conexión define un delegado para procesar las solicitudes y una colección de metadatos arbitrarios.An endpoint defines a delegate to process requests and a collection of arbitrary metadata. Los metadatos se usan para implementar cuestiones transversales según las directivas y la configuración asociada a cada punto de conexión.The metadata is used implement cross-cutting concerns based on policies and configuration attached to each endpoint.

El sistema de enrutamiento tiene las características siguientes:The routing system has the following characteristics:

  • La sintaxis de plantilla de ruta se usa para definir las rutas con parámetros de ruta con tokens.Route template syntax is used to define routes with tokenized route parameters.

  • Se permite la configuración de puntos de conexión de estilo convencional y de estilo de atributo.Conventional-style and attribute-style endpoint configuration is permitted.

  • Se usa IRouteConstraint para determinar si un parámetro de dirección URL contiene un valor válido para una restricción de punto de conexión determinada.IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.

  • Los modelos de aplicación, como MVC y Razor Pages, registran todos sus puntos de conexión, que presentan una implementación predecible de los escenarios de enrutamiento.App models, such as MVC/Razor Pages, register all of their endpoints, which have a predictable implementation of routing scenarios.

  • La implementación de enrutamiento toma decisiones relativas al enrutamiento siempre que sea lo deseado en la canalización de middleware.The routing implementation makes routing decisions wherever desired in the middleware pipeline.

  • El middleware que aparece después de un middleware de enrutamiento puede inspeccionar el resultado de la decisión del punto de conexión del middleware de enrutamiento para un URI de solicitud determinado.Middleware that appears after a Routing Middleware can inspect the result of the Routing Middleware's endpoint decision for a given request URI.

  • Se pueden enumerar todos los puntos de conexión de la aplicación en cualquier parte de la canalización de middleware.It's possible to enumerate all of the endpoints in the app anywhere in the middleware pipeline.

  • Una aplicación puede usar el enrutamiento para generar direcciones URL (por ejemplo, para el redireccionamiento o los vínculos) en función de la información del punto de conexión. De este modo, se evita codificar de forma rígida las direcciones URL, lo que facilita el mantenimiento.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.

  • La generación de direcciones URL se basa en direcciones, que admiten la extensibilidad arbitraria:URL generation is based on addresses, which support arbitrary extensibility:

    • La API del generador de vínculos (LinkGenerator) se puede resolver en cualquier lugar mediante la inserción de dependencias (DI) para generar direcciones URL.The Link Generator API (LinkGenerator) can be resolved anywhere using dependency injection (DI) to generate URLs.
    • Cuando la API del generador de vínculos no está disponible a través de DI, IUrlHelper ofrece métodos para generar direcciones URL.Where the Link Generator API isn't available via DI, IUrlHelper offers methods to build URLs.

Nota

Con el lanzamiento del enrutamiento de punto de conexión en ASP.NET Core 2.2, la vinculación de punto de conexión se limita a acciones y páginas de Razor Pages y MVC.With the release of endpoint routing in ASP.NET Core 2.2, endpoint linking is limited to MVC/Razor Pages actions and pages. Las expansiones de las funciones de vinculación de punto de conexión están previstas para próximas versiones.The expansions of endpoint-linking capabilities is planned for future releases.

El enrutamiento usa rutas (implementaciones de IRouter) para:Routing uses routes (implementations of IRouter) to:

  • Asignar las solicitudes entrantes a controladores de ruta.Map incoming requests to route handlers.
  • Generar las direcciones URL que se usan en las respuestas.Generate the URLs used in responses.

De forma predeterminada, una aplicación tiene una sola colección de rutas.By default, an app has a single collection of routes. Cuando llega una solicitud, las rutas de la colección se procesan en el orden en el que se encuentran en la colección.When a request arrives, the routes in the collection are processed in the order that they exist in the collection. El marco de trabajo intenta hacer coincidir una dirección URL de solicitud entrante con una ruta de la colección mediante una llamada al método RouteAsync en cada ruta de la colección.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. Una respuesta puede usar el enrutamiento para generar direcciones URL (por ejemplo, para el redireccionamiento o los vínculos) en función de la información de ruta. De este modo, se evita codificar de forma rígida las direcciones URL, lo que facilita el mantenimiento.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.

El sistema de enrutamiento tiene las características siguientes:The routing system has the following characteristics:

  • La sintaxis de plantilla de ruta se usa para definir las rutas con parámetros de ruta con tokens.Route template syntax is used to define routes with tokenized route parameters.
  • Se permite la configuración de puntos de conexión de estilo convencional y de estilo de atributo.Conventional-style and attribute-style endpoint configuration is permitted.
  • Se usa IRouteConstraint para determinar si un parámetro de dirección URL contiene un valor válido para una restricción de punto de conexión determinada.IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.
  • Los modelos de aplicación, como MVC y Razor Pages, registran todas sus rutas, que tienen una implementación predecible de los escenarios de enrutamiento.App models, such as MVC/Razor Pages, register all of their routes, which have a predictable implementation of routing scenarios.
  • Una respuesta puede usar el enrutamiento para generar direcciones URL (por ejemplo, para el redireccionamiento o los vínculos) en función de la información de ruta. De este modo, se evita codificar de forma rígida las direcciones URL, lo que facilita el mantenimiento.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.
  • La generación de direcciones URL se basa en rutas, que admiten la extensibilidad arbitraria.URL generation is based on routes, which support arbitrary extensibility. IUrlHelper ofrece métodos para generar direcciones URL.IUrlHelper offers methods to build URLs.

La clase RouterMiddleware conecta el enrutamiento a la canalización de software intermedio.Routing is connected to the middleware pipeline by the RouterMiddleware class. ASP.NET Core MVC agrega enrutamiento a la canalización de middleware como parte de su configuración y controla el enrutamiento en las aplicaciones de MVC y 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. Para obtener información sobre cómo usar el enrutamiento como componente independiente, vea la sección Uso de software intermedio de enrutamiento.To learn how to use routing as a standalone component, see the Use Routing Middleware section.

Coincidencia de dirección URLURL matching

La coincidencia de dirección URL es el proceso por el cual el enrutamiento envía una solicitud entrante a un punto de conexión.URL matching is the process by which routing dispatches an incoming request to an endpoint. Este proceso se basa en datos de la ruta de dirección URL, pero se puede ampliar para tener en cuenta cualquier dato de la solicitud.This process is based on data in the URL path but can be extended to consider any data in the request. La capacidad de enviar solicitudes a controladores independientes es clave para escalar el tamaño y la complejidad de una aplicación.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

El sistema de enrutamiento en el enrutamiento de punto de conexión es responsable de todas las decisiones relativas al envío.The routing system in endpoint routing is responsible for all dispatching decisions. Como el middleware aplica las directivas en función del punto de conexión seleccionado, es importante que cualquier decisión que pueda afectar a la distribución o la aplicación de directivas de seguridad se realice dentro del sistema de enrutamiento.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.

Cuando se ejecuta el delegado del punto de conexión, las propiedades de RouteContext.RouteData se establecen en los valores adecuados en función del procesamiento de solicitudes realizado hasta el momento.When the endpoint delegate is executed, the properties of RouteContext.RouteData are set to appropriate values based on the request processing performed thus far.

La coincidencia de dirección URL es el proceso por el cual el enrutamiento envía una solicitud entrante a un controlador.URL matching is the process by which routing dispatches an incoming request to a handler. Este proceso se basa en datos de la ruta de dirección URL, pero se puede ampliar para tener en cuenta cualquier dato de la solicitud.This process is based on data in the URL path but can be extended to consider any data in the request. La capacidad de enviar solicitudes a controladores independientes es clave para escalar el tamaño y la complejidad de una aplicación.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

Las solicitudes entrantes especifican la clase RouterMiddleware, que llama al método RouteAsync en cada ruta de la secuencia.Incoming requests enter the RouterMiddleware, which calls the RouteAsync method on each route in sequence. La instancia de IRouter decide si controla la solicitud mediante el establecimiento de RouteContext.Handler en un RequestDelegate que no sea NULL.The IRouter instance chooses whether to handle the request by setting the RouteContext.Handler to a non-null RequestDelegate. Si una ruta establece un controlador para la solicitud, el procesamiento de rutas se detiene y se invoca el controlador para procesar la solicitud.If a route sets a handler for the request, route processing stops, and the handler is invoked to process the request. Si no se encuentra ningún controlador de ruta para procesar la solicitud, el middleware entrega la solicitud al siguiente middleware en la canalización de solicitudes.If no route handler is found to process the request, the middleware hands the request off to the next middleware in the request pipeline.

La entrada principal para RouteAsync es el RouteContext.HttpContext asociado a la solicitud actual.The primary input to RouteAsync is the RouteContext.HttpContext associated with the current request. RouteContext.Handler y RouteContext.RouteData son salidas que se establecen después de que una ruta coincida.The RouteContext.Handler and RouteContext.RouteData are outputs set after a route is matched.

Una coincidencia que llama a RouteAsync también establece las propiedades de RouteContext.RouteData en los valores adecuados en función del procesamiento de solicitudes realizado hasta el momento.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 es un diccionario de los valores de ruta generados desde la ruta.RouteData.Values is a dictionary of route values produced from the route. Estos valores se suelen determinar mediante la conversión en tokens de la dirección URL, y se pueden usar para aceptar la entrada del usuario o para tomar otras decisiones sobre el envío dentro de la aplicación.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 es un contenedor de propiedades de datos adicionales relacionados con la ruta coincidente.RouteData.DataTokens is a property bag of additional data related to the matched route. Se proporcionan DataTokens para permitir la asociación de datos de estado con cada ruta, de modo que la aplicación pueda tomar decisiones en función de las rutas que han coincidido.DataTokens are provided to support associating state data with each route so that the app can make decisions based on which route matched. Estos valores los define el desarrollador y no afectan de ninguna manera al comportamiento del enrutamiento.These values are developer-defined and do not affect the behavior of routing in any way. Además, los valores que se guardan provisionalmente en RouteData.DataTokens pueden ser de cualquier tipo, a diferencia de RouteData.Values, que deben poder convertirse en cadenas y a partir de estas.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 es una lista de las rutas que han participado en encontrar una coincidencia correcta con la solicitud.RouteData.Routers is a list of the routes that took part in successfully matching the request. Las rutas se pueden anidar unas dentro de otras.Routes can be nested inside of one another. La propiedad Routers refleja la ruta de acceso del árbol lógico de rutas que han tenido como resultado una coincidencia.The Routers property reflects the path through the logical tree of routes that resulted in a match. Por lo general, el primer elemento de Routers es la colección de rutas y se debe usar para la generación de direcciones URL.Generally, the first item in Routers is the route collection and should be used for URL generation. El último elemento de Routers es el controlador de ruta que ha coincidido.The last item in Routers is the route handler that matched.

Generación de dirección URLURL generation

La generación de dirección URL es el proceso por el cual el enrutamiento puede crear una ruta de dirección URL basada en un conjunto de valores de ruta.URL generation is the process by which routing can create a URL path based on a set of route values. Esto permite una separación lógica entre los puntos de conexión y las direcciones URL que tienen acceso a ellos.This allows for a logical separation between your endpoints and the URLs that access them.

El enrutamiento de punto de conexión incluye la API del generador de vínculos (LinkGenerator).Endpoint routing includes the Link Generator API (LinkGenerator). LinkGenerator es un servicio singleton que se puede recuperar a partir de la DI.LinkGenerator is a singleton service that can be retrieved from DI. La API se puede usar fuera del contexto de una solicitud en ejecución.The API can be used outside of the context of an executing request. IUrlHelper de MVC y los escenarios que dependen de IUrlHelper, como los asistentes de etiquetas, los de HTML y los resultados de acción, usan el generador de vínculos para proporcionar funciones de generación de vínculos.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.

El generador de vínculos está respaldado por el concepto de una dirección y esquemas de direcciones.The link generator is backed by the concept of an address and address schemes. Un esquema de direcciones es una manera de determinar los puntos de conexión que se deben tener en cuenta para la generación de vínculos.An address scheme is a way of determining the endpoints that should be considered for link generation. Por ejemplo, los escenarios de nombre y valores de ruta de Razor Pages y MVC con los que muchos usuarios están familiarizados se implementan como un esquema de direcciones.For example, the route name and route values scenarios many users are familiar with from MVC/Razor Pages are implemented as an address scheme.

El generador de vínculos puede vincular a acciones y páginas de Razor Pages y MVC a través de los métodos de extensión siguientes:The link generator can link to MVC/Razor Pages actions and pages via the following extension methods:

  • GetPathByAction
  • GetUriByAction
  • GetPathByPage
  • GetUriByPage

Una sobrecarga de estos métodos acepta argumentos que incluyan HttpContext.An overload of these methods accepts arguments that include the HttpContext. Estos métodos son equivalentes funcionalmente a Url.Action y Url.Page, pero ofrecen flexibilidad y opciones adicionales.These methods are functionally equivalent to Url.Action and Url.Page but offer additional flexibility and options.

Los métodos GetPath* son más similares a Url.Action y Url.Page, dado que generan un URI que contiene una ruta de acceso absoluta.The GetPath* methods are most similar to Url.Action and Url.Page in that they generate a URI containing an absolute path. Los métodos GetUri* siempre generan un URI absoluto que contiene un esquema y un host.The GetUri* methods always generate an absolute URI containing a scheme and host. Los métodos que aceptan HttpContext generan un URI en el contexto de la solicitud que se ejecuta.The methods that accept an HttpContext generate a URI in the context of the executing request. A menos que se reemplacen, se usan los valores de ruta de ambiente, la ruta de acceso base de la dirección URL, el esquema y el host de la solicitud que se ejecuta.The ambient route values, URL base path, scheme, and host from the executing request are used unless overridden.

Se llama a LinkGenerator con una dirección.LinkGenerator is called with an address. La generación de un URI se produce en dos pasos:Generating a URI occurs in two steps:

  1. Se enlaza una dirección a una lista de puntos de conexión que coincidan con la dirección.An address is bound to a list of endpoints that match the address.
  2. Se evalúa el elemento RoutePattern de cada punto de conexión hasta que se encuentra un patrón de ruta que coincida con los valores proporcionados.Each endpoint's RoutePattern is evaluated until a route pattern that matches the supplied values is found. La salida resultante se combina con otras partes del URI proporcionadas al generador de vínculos y devueltas.The resulting output is combined with the other URI parts supplied to the link generator and returned.

Los métodos proporcionados por LinkGenerator admiten funciones estándar de generación de vínculos para cualquier tipo de dirección.The methods provided by LinkGenerator support standard link generation capabilities for any type of address. La forma más útil de usar el generador de vínculos es a través de métodos de extensión que realicen operaciones para un tipo de dirección específica.The most convenient way to use the link generator is through extension methods that perform operations for a specific address type.

Método de extensiónExtension Method DescripciónDescription
GetPathByAddress Genera un URI con una ruta de acceso absoluta en función de los valores proporcionados.Generates a URI with an absolute path based on the provided values.
GetUriByAddress Genera un URI absoluto en función de los valores proporcionados.Generates an absolute URI based on the provided values.

Advertencia

Preste atención a las consecuencias siguientes de llamar a los métodos LinkGenerator:Pay attention to the following implications of calling LinkGenerator methods:

  • Use los métodos de extensión GetUri* con precaución en una configuración de aplicación en la que no se valide el encabezado Host de las solicitudes entrantes.Use GetUri* extension methods with caution in an app configuration that doesn't validate the Host header of incoming requests. Si no se valida el encabezado Host de las solicitudes entrantes, la entrada de la solicitud que no sea de confianza se puede devolver al cliente en los URI de una página o vista.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. Se recomienda que todas las aplicaciones de producción configuren su servidor para validar el encabezado Host en función de valores válidos conocidos.We recommend that all production apps configure their server to validate the Host header against known valid values.

  • Use LinkGenerator con precaución en el middleware junto con Map o MapWhen.Use LinkGenerator with caution in middleware in combination with Map or MapWhen. Map* cambia la ruta de acceso base de la solicitud que se ejecuta, lo que afecta a la salida de la generación de vínculos.Map* changes the base path of the executing request, which affects the output of link generation. Todas las API de LinkGenerator permiten especificar una ruta de acceso base.All of the LinkGenerator APIs allow specifying a base path. Especifique siempre una ruta de acceso base vacía para deshacer el efecto de Map* en la generación de vínculos.Always specify an empty base path to undo Map*'s affect on link generation.

Diferencias con respecto a versiones anteriores del enrutamientoDifferences from earlier versions of routing

Existen algunas diferencias entre el enrutamiento de punto de conexión de ASP.NET Core 2.2 o posterior, y las versiones anteriores del enrutamiento en 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:

  • El sistema de enrutamiento de punto de conexión no es compatible con la extensibilidad basada en IRouter, incluida la herencia de Route.The endpoint routing system doesn't support IRouter-based extensibility, including inheriting from Route.

  • El enrutamiento de punto de conexión no es compatible con WebApiCompatShim.Endpoint routing doesn't support WebApiCompatShim. Utilice la versión compatibilidad 2.1 (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) para seguir usando la corrección de compatibilidad.Use the 2.1 compatibility version (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) to continue using the compatibility shim.

  • El enrutamiento de punto de conexión tiene un comportamiento diferente para el uso de mayúsculas y minúsculas en los URI generados al usar rutas convencionales.Endpoint Routing has different behavior for the casing of generated URIs when using conventional routes.

    Tenga en cuenta la plantilla de ruta predeterminada siguiente:Consider the following default route template:

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

    Supongamos que genera un vínculo a una acción mediante la ruta siguiente:Suppose you generate a link to an action using the following route:

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

    Con el enrutamiento basado en IRouter, este código genera un URI de /blog/ReadPost/17, que respeta las mayúsculas y minúsculas del valor de ruta proporcionado.With IRouter-based routing, this code generates a URI of /blog/ReadPost/17, which respects the casing of the provided route value. El enrutamiento de punto de conexión de ASP.NET Core 2.2 o versiones posteriores genera /Blog/ReadPost/17 ("Blog" se pone mayúscula).Endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 ("Blog" is capitalized). El enrutamiento de punto de conexión proporciona la interfaz IOutboundParameterTransformer, que se puede usar para personalizar este comportamiento de forma global, o bien para aplicar otras convenciones para la asignación de direcciones URL.Endpoint routing provides the IOutboundParameterTransformer interface that can be used to customize this behavior globally or to apply different conventions for mapping URLs.

    Para obtener más información, vea la sección Referencia de transformadores de parámetros.For more information, see the Parameter transformer reference section.

  • La generación de vínculos que se usa en Razor Pages y MVC con las rutas convencionales tiene un comportamiento diferente al intentar vincularlo a un controlador o una acción, o a una página que no existe.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.

    Tenga en cuenta la plantilla de ruta predeterminada siguiente:Consider the following default route template:

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

    Supongamos que genera un vínculo a una acción mediante la plantilla predeterminada con lo siguiente:Suppose you generate a link to an action using the default template with the following:

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

    Con el enrutamiento basado en IRouter, el resultado siempre es /Blog/ReadPost/17, incluso aunque BlogController no exista o no tenga un método de acción ReadPost.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. Como se esperaba, si el método de acción existe, el enrutamiento de punto de conexión de ASP.NET Core 2.2 o versiones posteriores genera /Blog/ReadPost/17.As expected, endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 if the action method exists. Sin embargo, si la acción no existe, el enrutamiento de punto de conexión genera una cadena vacía.However, endpoint routing produces an empty string if the action doesn't exist. Conceptualmente, el enrutamiento de punto de conexión no supone que, si la acción no existe, sí que exista el punto de conexión.Conceptually, endpoint routing doesn't assume that the endpoint exists if the action doesn't exist.

  • El algoritmo de invalidación del valor de ambiente de la generación de vínculos tiene otro comportamiento al usarlo con el enrutamiento de punto de conexión.The link generation ambient value invalidation algorithm behaves differently when used with endpoint routing.

    La invalidación del valor de ambiente es el algoritmo que decide qué valores de ruta de la solicitud que se ejecuta actualmente (los valores de ambiente) se pueden usar en las operaciones de generación de vínculos.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. El enrutamiento convencional siempre invalida los valores de ruta adicionales al vincular a otra acción.Conventional routing always invalidated extra route values when linking to a different action. El enrutamiento mediante atributos no tenía este comportamiento antes del lanzamiento de ASP.NET Core 2.2.Attribute routing didn't have this behavior prior to the release of ASP.NET Core 2.2. En versiones anteriores de ASP.NET Core, los vínculos a otra acción que usara los mismos nombres de parámetro de ruta producían errores de generación de vínculo.In earlier versions of ASP.NET Core, links to another action that use the same route parameter names resulted in link generation errors. En ASP.NET Core 2.2 o versiones posteriores, las dos formas de enrutamiento invalidan los valores cuando se vincula a otra acción.In ASP.NET Core 2.2 or later, both forms of routing invalidate values when linking to another action.

    Considere el ejemplo siguiente de ASP.NET Core 2.1 o una versión anterior.Consider the following example in ASP.NET Core 2.1 or earlier. Al vincular a otra acción (o a otra página), los valores de ruta se pueden reutilizar de formas no deseadas.When linking to another action (or another page), route values can be reused in undesirable ways.

    En /Pages/Store/Product.cshtml:In /Pages/Store/Product.cshtml:

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

    En /Pages/Login.cshtml:In /Pages/Login.cshtml:

    @page "{id?}"
    

    Si el URI es /Store/Product/18 en ASP.NET Core 2.1 o versiones anteriores, el vínculo que genera @Url.Page("/Login") en la página Store/Info es /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. Se reutiliza el valor id de 18, aunque el destino del vínculo sea otro elemento totalmente distinto de la aplicación.The id value of 18 is reused, even though the link destination is different part of the app entirely. El valor de ruta id en el contexto de la página /Login probablemente sea un valor de id. de usuario, no un valor de id. de producto de tienda.The id route value in the context of the /Login page is probably a user ID value, not a store product ID value.

    En el enrutamiento de punto de conexión con ASP.NET Core 2.2 o versiones posteriores, el resultado es /Login.In endpoint routing with ASP.NET Core 2.2 or later, the result is /Login. Los valores de ambiente no se reutilizan cuando el destino vinculado es otra acción o página.Ambient values aren't reused when the linked destination is a different action or page.

  • Sintaxis de parámetro de ruta de ida y vuelta: las barras diagonales no se codifican cuando se usa una sintaxis de parámetro comodín de doble asterisco (**).Round-tripping route parameter syntax: Forward slashes aren't encoded when using a double-asterisk (**) catch-all parameter syntax.

    Durante la generación de vínculos, el sistema de enrutamiento codifica el valor capturado en un parámetro comodín de doble asterisco (**; por ejemplo, {**myparametername}), excepto las barras diagonales.During link generation, the routing system encodes the value captured in a double-asterisk (**) catch-all parameter (for example, {**myparametername}) except the forward slashes. El comodín de doble asterisco es compatible con el enrutamiento basado en IRouter en ASP.NET Core 2.2 o versiones posteriores.The double-asterisk catch-all is supported with IRouter-based routing in ASP.NET Core 2.2 or later.

    La sintaxis de parámetro comodín de un único asterisco en versiones anteriores de ASP.NET Core ({*myparametername}) sigue siendo compatible y las barras diagonales se codifican.The single asterisk catch-all parameter syntax in prior versions of ASP.NET Core ({*myparametername}) remains supported, and forward slashes are encoded.

    RutaRoute Vínculo generado conLink generated with
    Url.Action(new { category = "admin/products" })
    /search/{*page} /search/admin%2Fproducts (la barra diagonal se codifica)/search/admin%2Fproducts (the forward slash is encoded)
    /search/{**page} /search/admin/products

Ejemplo de middlewareMiddleware example

En el ejemplo siguiente, un middleware usa la API LinkGenerator para crear el vínculo a un método de acción que enumera los productos de la tienda.In the following example, a middleware uses the LinkGenerator API to create link to an action method that lists store products. El uso del generador de vínculos mediante su inserción en una clase y la llamada a GenerateLink está disponible para cualquier clase de una aplicación.Using the link generator by injecting it into a class and calling GenerateLink is available to any class in an app.

public class ProductsLinkMiddleware
{
    private readonly LinkGenerator _linkGenerator;

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

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

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

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

La generación de dirección URL es el proceso por el cual el enrutamiento puede crear una ruta de dirección URL basada en un conjunto de valores de ruta.URL generation is the process by which routing can create a URL path based on a set of route values. Esto permite una separación lógica entre los controladores de ruta y las direcciones URL que tienen acceso a ellos.This allows for a logical separation between route handlers and the URLs that access them.

La generación de direcciones URL sigue un proceso iterativo similar, pero se inicia cuando el código de usuario o de marco de trabajo llama al método GetVirtualPath de la colección de rutas.URL generation follows a similar iterative process, but it starts with user or framework code calling into the GetVirtualPath method of the route collection. Se llama en secuencia al método GetVirtualPath de cada ruta hasta que se devuelva un valor VirtualPathData distinto de NULL.Each route has its GetVirtualPath method called in sequence until a non-null VirtualPathData is returned.

La principal entradas de GetVirtualPath son:The primary inputs to GetVirtualPath are:

Las rutas usan principalmente los valores de ruta proporcionados por Values y AmbientValues para decidir si es posible generar una dirección URL y qué valores se van a incluir.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 son el conjunto de valores de ruta producidos a partir de la coincidencia con la solicitud actual.The AmbientValues are the set of route values that were produced from matching the current request. En cambio, Values son los valores de ruta que especifican cómo se genera la dirección URL deseada para la operación actual.In contrast, Values are the route values that specify how to generate the desired URL for the current operation. Se proporciona HttpContext por si una ruta debe obtener servicios o datos adicionales asociados con el contexto actual.The HttpContext is provided in case a route should obtain services or additional data associated with the current context.

Sugerencia

Piense en VirtualPathContext.Values como un conjunto de invalidaciones para VirtualPathContext.AmbientValues.Think of VirtualPathContext.Values as a set of overrides for the VirtualPathContext.AmbientValues. La generación de direcciones URL intenta reutilizar los valores de ruta de la solicitud actual para generar direcciones URL para los vínculos con la misma ruta o valores de ruta.URL generation attempts to reuse route values from the current request to generate URLs for links using the same route or route values.

La salida de GetVirtualPath es VirtualPathData.The output of GetVirtualPath is a VirtualPathData. VirtualPathData es un valor paralelo de RouteData.VirtualPathData is a parallel of RouteData. VirtualPathData contiene el valor VirtualPath de la dirección URL de salida y algunas propiedades más que la ruta debe establecer.VirtualPathData contains the VirtualPath for the output URL and some additional properties that should be set by the route.

La propiedad VirtualPathData.VirtualPath contiene la ruta de acceso virtual generada por la ruta.The VirtualPathData.VirtualPath property contains the virtual path produced by the route. Es posible que deba procesar aún más la ruta de acceso, según sus necesidades.Depending on your needs, you may need to process the path further. Si quiere representar la dirección URL generada en HTML, anteponga la ruta de acceso base de la aplicación.If you want to render the generated URL in HTML, prepend the base path of the app.

VirtualPathData.Router es una referencia a la ruta que ha generado correctamente la dirección URL.The VirtualPathData.Router is a reference to the route that successfully generated the URL.

La propiedad VirtualPathData.DataTokens es un diccionario de datos adicionales relacionados con la ruta que ha generado la dirección URL.The VirtualPathData.DataTokens properties is a dictionary of additional data related to the route that generated the URL. Se trata del valor paralelo de RouteData.DataTokens.This is the parallel of RouteData.DataTokens.

Creación de rutasCreate routes

El enrutamiento proporciona la clase Route como implementación estándar de IRouter.Routing provides the Route class as the standard implementation of IRouter. Route usa la sintaxis de plantilla de ruta para definir patrones que se hacen coincidir con la ruta de dirección URL cuando se llama a RouteAsync.Route uses the route template syntax to define patterns to match against the URL path when RouteAsync is called. Route usa la misma plantilla de ruta para generar una dirección URL cuando se llama a GetVirtualPath.Route uses the same route template to generate a URL when GetVirtualPath is called.

La mayoría de las aplicaciones crea rutas mediante una llamada a MapRoute o a uno de los métodos de extensión similares definidos en IRouteBuilder.Most apps create routes by calling MapRoute or one of the similar extension methods defined on IRouteBuilder. Todos los métodos de extensión IRouteBuilder crean una instancia de Route y la agregan a la colección de rutas.Any of the IRouteBuilder extension methods create an instance of Route and add it to the route collection.

MapRoute no acepta un parámetro de controlador de ruta.MapRoute doesn't accept a route handler parameter. MapRoute solo agrega las rutas que se controlan mediante DefaultHandler.MapRoute only adds routes that are handled by the DefaultHandler. Para obtener más información sobre el enrutamiento en MVC, vea Enrutar a acciones de controlador de ASP.NET Core.To learn more about routing in MVC, see Enrutar a acciones de controlador de ASP.NET Core.

MapRoute no acepta un parámetro de controlador de ruta.MapRoute doesn't accept a route handler parameter. MapRoute solo agrega las rutas que se controlan mediante DefaultHandler.MapRoute only adds routes that are handled by the DefaultHandler. El controlador predeterminado es un elemento IRouter, y es posible que el controlador no pueda atender la solicitud.The default handler is an IRouter, and the handler might not handle the request. Por ejemplo, ASP.NET Core MVC se suele configurar como un controlador predeterminado que solo controla las solicitudes que coinciden con un controlador y una acción disponibles.For example, ASP.NET Core MVC is typically configured as a default handler that only handles requests that match an available controller and action. Para obtener más información sobre el enrutamiento en MVC, vea Enrutar a acciones de controlador de ASP.NET Core.To learn more about routing in MVC, see Enrutar a acciones de controlador de ASP.NET Core.

El código siguiente es un ejemplo de una llamada a MapRoute usada por una definición de ruta típica de ASP.NET Core MVC: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?}");

Esta plantilla coincide con una ruta de dirección URL y extrae los valores de ruta.This template matches a URL path and extracts the route values. Por ejemplo, la ruta de acceso /Products/Details/17 genera los valores de ruta siguientes: { controller = Products, action = Details, id = 17 }.For example, the path /Products/Details/17 generates the following route values: { controller = Products, action = Details, id = 17 }.

Los valores de ruta se determinan al dividir la ruta de dirección URL en segmentos y hacer coincidir cada segmento con el nombre del parámetro de ruta en la plantilla de ruta.Route values are determined by splitting the URL path into segments and matching each segment with the route parameter name in the route template. Los parámetros de ruta tienen un nombre asignado.Route parameters are named. Para definir los parámetros, el nombre del parámetro se incluye entre llaves { ... }.The parameters defined by enclosing the parameter name in braces { ... }.

La plantilla anterior también podría coincidir con la ruta de dirección URL / y generar los valores { controller = Home, action = Index }.The preceding template could also match the URL path / and produce the values { controller = Home, action = Index }. Esto se debe a que los parámetros de ruta {controller} y {action} tienen valores predeterminados y el parámetro de ruta id es opcional.This occurs because the {controller} and {action} route parameters have default values and the id route parameter is optional. Un signo igual (=) seguido de un valor después del nombre del parámetro de ruta define un valor predeterminado para el parámetro.An equals sign (=) followed by a value after the route parameter name defines a default value for the parameter. Un signo de interrogación (?) después del nombre del parámetro de ruta define un parámetro opcional.A question mark (?) after the route parameter name defines an optional parameter.

Los parámetros de ruta con un valor predeterminado siempre generan un valor de ruta cuando la ruta coincide.Route parameters with a default value always produce a route value when the route matches. Los parámetros opcionales no generan un valor de ruta si no existió el segmento de ruta de dirección URL correspondiente.Optional parameters don't produce a route value if there was no corresponding URL path segment. Vea la sección Referencia de plantilla de ruta para obtener una descripción detallada de los escenarios y la sintaxis de la plantilla de ruta.See the Route template reference section for a thorough description of route template scenarios and syntax.

En el ejemplo siguiente, la definición de parámetro de ruta {id:int} define una restricción de ruta para el parámetro de ruta 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}");

Esta plantilla coincide con una ruta de dirección URL como /Products/Details/17, pero no con /Products/Details/Apples.This template matches a URL path like /Products/Details/17 but not /Products/Details/Apples. Las restricciones de ruta implementan IRouteConstraint e inspeccionan los valores de ruta para comprobarlos.Route constraints implement IRouteConstraint and inspect route values to verify them. En este ejemplo, el valor de ruta id debe poder convertirse en un entero.In this example, the route value id must be convertible to an integer. Vea la Referencia de restricción de ruta para obtener una explicación de las restricciones de ruta proporcionadas por el marco de trabajo.See route-constraint-reference for an explanation of route constraints provided by the framework.

Las sobrecargas adicionales de MapRoute aceptan valores para constraints, dataTokens y defaults.Additional overloads of MapRoute accept values for constraints, dataTokens, and defaults. Estos parámetros suelen usarse para pasar un objeto de tipo anónimo, donde los nombres de propiedad del tipo anónimo coinciden con los nombres de los parámetros de ruta.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.

En los ejemplos MapRoute siguientes se crean rutas equivalentes: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?}");

Sugerencia

La sintaxis insertada para definir las restricciones y los valores predeterminados puede ser conveniente para las rutas simples.The inline syntax for defining constraints and defaults can be convenient for simple routes. Pero hay algunos escenarios, como los tokens de datos, que no son compatibles con la sintaxis insertada.However, there are scenarios, such as data tokens, that aren't supported by inline syntax.

En el ejemplo siguiente se muestran algunos escenarios más:The following example demonstrates a few additional scenarios:

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

La plantilla anterior coincide con una ruta de dirección URL como /Blog/All-About-Routing/Introduction y extrae los valores { 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 }. La ruta genera los valores de ruta predeterminados para controller y action, incluso si no hay parámetros de ruta correspondientes en la plantilla.The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. Los valores predeterminados pueden especificarse en la plantilla de ruta.Default values can be specified in the route template. El parámetro de ruta article se define como un comodín por la aparición de un asterisco doble (**) antes del nombre del parámetro de ruta.The article route parameter is defined as a catch-all by the appearance of an double asterisk (**) before the route parameter name. Los parámetros de ruta comodín capturan el resto de la ruta de dirección URL y también pueden coincidir con la cadena vacía.Catch-all route parameters capture the remainder of the URL path and can also match the empty string.

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

La plantilla anterior coincide con una ruta de dirección URL como /Blog/All-About-Routing/Introduction y extrae los valores { 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 }. La ruta genera los valores de ruta predeterminados para controller y action, incluso si no hay parámetros de ruta correspondientes en la plantilla.The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. Los valores predeterminados pueden especificarse en la plantilla de ruta.Default values can be specified in the route template. El parámetro de ruta article se define como un comodín por la aparición de un asterisco (*) antes del nombre del parámetro de ruta.The article route parameter is defined as a catch-all by the appearance of an asterisk (*) before the route parameter name. Los parámetros de ruta comodín capturan el resto de la ruta de dirección URL y también pueden coincidir con la cadena vacía.Catch-all route parameters capture the remainder of the URL path and can also match the empty string.

En el ejemplo siguiente se agregan restricciones de ruta y tokens de datos: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" });

La plantilla anterior coincide con una ruta de dirección URL como /en-US/Products/5 y extrae los valores { controller = Products, action = Details, id = 5 } y los tokens de datos { 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 }.

Tokens de Windows de variables locales

Generación de direcciones URL de clase de rutaRoute class URL generation

La clase Route también puede llevar a cabo la generación de dirección URL mediante la combinación de un conjunto de valores de ruta con su plantilla de ruta.The Route class can also perform URL generation by combining a set of route values with its route template. Se trata lógicamente del proceso inverso de hacer coincidir la ruta de dirección URL.This is logically the reverse process of matching the URL path.

Sugerencia

Para entender mejor la generación de direcciones URL, imagine qué dirección URL quiere generar y, después, piense cómo coincidiría una plantilla de ruta con esa dirección 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. ¿Qué valores se generarían?What values would be produced? Este es un equivalente aproximado de cómo funciona la generación de dirección URL en la clase Route.This is the rough equivalent of how URL generation works in the Route class.

En el ejemplo siguiente se usa una ruta predeterminada de ASP.NET Core MVC general:The following example uses a general ASP.NET Core MVC default route:

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

Con los valores de ruta { controller = Products, action = List }, se genera la dirección URL /Products/List.With the route values { controller = Products, action = List }, the URL /Products/List is generated. Los valores de ruta se sustituyen por los parámetros de ruta correspondientes para formar la ruta de dirección URL.The route values are substituted for the corresponding route parameters to form the URL path. Como id es un parámetro de ruta opcional, la dirección URL se ha generado correctamente sin ningún valor para id.Since id is an optional route parameter, the URL is successfully generated without a value for id.

Con los valores de ruta { controller = Home, action = Index }, se genera la dirección URL /.With the route values { controller = Home, action = Index }, the URL / is generated. Los valores de ruta proporcionados coinciden con los valores predeterminados, y los segmentos correspondientes a los valores predeterminados se omiten sin ningún riesgo.The provided route values match the default values, and the segments corresponding to the default values are safely omitted.

Ambas direcciones URL generadas realizan un recorrido de ida y vuelta con la definición de ruta siguiente (/Home/Index y /) y generan los mismos valores de ruta que se usaron para generar la dirección 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.

Nota

Las aplicaciones con ASP.NET Core MVC deben usar UrlHelper para generar direcciones URL en lugar de llamar directamente al enrutamiento.An app using ASP.NET Core MVC should use UrlHelper to generate URLs instead of calling into routing directly.

Para obtener más información sobre la generación de direcciones URL, vea la sección Referencia de generación de direcciones URL.For more information on URL generation, see the Url generation reference section.

Uso de software intermedio de enrutamientoUse Routing Middleware

Haga referencia al metapaquete Microsoft.AspNetCore.App en el archivo de proyecto de la aplicación.Reference the Microsoft.AspNetCore.App metapackage in the app's project file.

Agregue enrutamiento al contenedor de servicios en Startup.ConfigureServices:Add routing to the service container in Startup.ConfigureServices:

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

Las rutas se deben configurar en el método Startup.Configure.Routes must be configured in the Startup.Configure method. En la aplicación de ejemplo se usan las API siguientes:The sample app uses the following APIs:

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

var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);

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

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

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

En la tabla siguiente se muestran las respuestas con los URI especificados.The following table shows the responses with the given URIs.

Identificador URIURI RespuestaResponse
/package/create/3 Hello!Hello! Valores de ruta: [operation, create], [id, 3]Route values: [operation, create], [id, 3]
/package/track/-3 Hello!Hello! Valores de ruta: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/-3/ Hello!Hello! Valores de ruta: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/ La solicitud pasa; no hay ninguna coincidencia.The request falls through, no match.
GET /hello/Joe Hi, Joe!Hi, Joe!
POST /hello/Joe La solicitud pasa; solo coincide con HTTP GET.The request falls through, matches HTTP GET only.
GET /hello/Joe/Smith La solicitud pasa; no hay ninguna coincidencia.The request falls through, no match.

Si va a configurar una única ruta, pase una instancia de IRouter para llamar a UseRouter.If you're configuring a single route, call UseRouter passing in an IRouter instance. No tendrá que usar RouteBuilder.You won't need to use RouteBuilder.

El marco de trabajo proporciona un conjunto de métodos de extensión para crear rutas (RequestDelegateRouteBuilderExtensions):The framework provides a set of extension methods for creating routes (RequestDelegateRouteBuilderExtensions):

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

Algunos de los métodos enumerados, como MapGet, requieren un RequestDelegate.Some of listed methods, such as MapGet, require a RequestDelegate. El valor RequestDelegate se usa como controlador de ruta cuando la ruta coincida.The RequestDelegate is used as the route handler when the route matches. Otros métodos de esta familia permiten configurar una canalización de software intermedio para usarla como controlador de ruta.Other methods in this family allow configuring a middleware pipeline for use as the route handler. Si el método Map* no acepta un controlador, como MapRoute, usa DefaultHandler.If the Map* method doesn't accept a handler, such as MapRoute, it uses the DefaultHandler.

Los métodos Map[Verb] usan restricciones para limitar la ruta al verbo HTTP en el nombre del método.The Map[Verb] methods use constraints to limit the route to the HTTP Verb in the method name. Por ejemplo, vea MapGet y MapVerb.For example, see MapGet and MapVerb.

Referencia de plantilla de rutaRoute template reference

Los tokens entre llaves ({ ... }) definen parámetros de ruta que se enlazan si se encuentran coincidencias con la ruta.Tokens within curly braces ({ ... }) define route parameters that are bound if the route is matched. Puede definir más de un parámetro de ruta en un segmento de ruta, pero deben estar separados por un valor literal.You can define more than one route parameter in a route segment, but they must be separated by a literal value. Por ejemplo, {controller=Home}{action=Index} no es una ruta válida, ya que no hay ningún valor literal entre {controller} y {action}.For example, {controller=Home}{action=Index} isn't a valid route, since there's no literal value between {controller} and {action}. Estos parámetros de ruta deben tener un nombre y, opcionalmente, atributos adicionales especificados.These route parameters must have a name and may have additional attributes specified.

El texto literal diferente de los parámetros de ruta (por ejemplo, {id}) y el separador de ruta / deben coincidir con el texto de la dirección URL.Literal text other than route parameters (for example, {id}) and the path separator / must match the text in the URL. La coincidencia de texto no distingue mayúsculas de minúsculas y se basa en la representación descodificada de la ruta de las direcciones URL.Text matching is case-insensitive and based on the decoded representation of the URLs path. Para que el delimitador de parámetro de ruta literal coincida ({ o }), repita el carácter ({{ o }}) para usarlo como secuencia de escape.To match a literal route parameter delimiter ({ or }), escape the delimiter by repeating the character ({{ or }}).

Los patrones de dirección URL que intentan capturar un nombre de archivo con una extensión de archivo opcional tienen consideraciones adicionales.URL patterns that attempt to capture a file name with an optional file extension have additional considerations. Por ejemplo, considere la plantilla files/{filename}.{ext?}.For example, consider the template files/{filename}.{ext?}. Cuando existen valores para filename y ext, los dos valores se rellenan.When values for both filename and ext exist, both values are populated. Si solo existe un valor para filename en la dirección URL, la ruta coincide porque el punto final (.) es opcional.If only a value for filename exists in the URL, the route matches because the trailing period (.) is optional. Las direcciones URL siguientes coinciden con esta ruta:The following URLs match this route:

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

Se puede usar un asterisco (*) o un asterisco doble (**) como prefijo de un parámetro de ruta para enlazar con el resto del URI.You can use an asterisk (*) or double asterisk (**) as a prefix to a route parameter to bind to the rest of the URI. Se denominan parámetros comodín.These are called a catch-all parameters. Por ejemplo, blog/{**slug} coincide con cualquier URI que empiece por /blog y que vaya seguido de cualquier valor, que se asigna al valor de ruta slug.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. Los parámetros comodín también pueden coincidir con una cadena vacía.Catch-all parameters can also match the empty string.

El parámetro catch-all inserta los caracteres de escape correspondientes cuando se usa la ruta para generar una dirección URL, incluidos caracteres de separación de ruta de acceso (/).The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. Por ejemplo, la ruta foo/{*path} con valores de ruta { path = "my/path" } genera foo/my%2Fpath.For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. Tenga en cuenta la barra diagonal de escape.Note the escaped forward slash. Para los caracteres separadores de ruta de acceso de ida y vuelta, use el prefijo de parámetro de ruta **.To round-trip path separator characters, use the ** route parameter prefix. La ruta foo/{**path} con { path = "my/path" } genera foo/my/path.The route foo/{**path} with { path = "my/path" } generates foo/my/path.

Se puede usar el asterisco (*) como prefijo de un parámetro de ruta para enlazar con el resto del URI.You can use the asterisk (*) as a prefix to a route parameter to bind to the rest of the URI. Es lo que se denomina un parámetro comodín.This is called a catch-all parameter. Por ejemplo, blog/{*slug} coincide con cualquier URI que empiece por /blog y que vaya seguido de cualquier valor, que se asigna al valor de ruta slug.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. Los parámetros comodín también pueden coincidir con una cadena vacía.Catch-all parameters can also match the empty string.

El parámetro catch-all inserta los caracteres de escape correspondientes cuando se usa la ruta para generar una dirección URL, incluidos caracteres de separación de ruta de acceso (/).The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. Por ejemplo, la ruta foo/{*path} con valores de ruta { path = "my/path" } genera foo/my%2Fpath.For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. Tenga en cuenta la barra diagonal de escape.Note the escaped forward slash.

Los parámetros de ruta pueden tener valores predeterminados designados mediante la especificación del valor predeterminado después del nombre de parámetro, separado por un signo igual (=).Route parameters may have default values designated by specifying the default value after the parameter name separated by an equals sign (=). Por ejemplo, {controller=Home} define Home como el valor predeterminado de controller.For example, {controller=Home} defines Home as the default value for controller. El valor predeterminado se usa si no hay ningún valor en la dirección URL para el parámetro.The default value is used if no value is present in the URL for the parameter. Los parámetros de ruta se pueden convertir en opcionales si se anexa un signo de interrogación (?) al final del nombre del parámetro, como en id?.Route parameters are made optional by appending a question mark (?) to the end of the parameter name, as in id?. La diferencia entre los valores opcionales y los parámetros de ruta predeterminados es que un parámetro de ruta con un valor predeterminado siempre genera un valor, mientras que un parámetro opcional tiene un valor solo cuando la dirección URL de solicitud lo proporciona.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.

Los parámetros de ruta pueden tener restricciones que deben coincidir con el valor de ruta enlazado desde la dirección URL.Route parameters may have constraints that must match the route value bound from the URL. Si se agrega un carácter de dos puntos (:) y un nombre de restricción después del nombre del parámetro de ruta, se especifica una restricción insertada en un parámetro de ruta.Adding a colon (:) and constraint name after the route parameter name specifies an inline constraint on a route parameter. Si la restricción requiere argumentos, se incluyen entre paréntesis ((...)) después del nombre de restricción.If the constraint requires arguments, they're enclosed in parentheses ((...)) after the constraint name. Se pueden especificar varias restricciones insertadas si se anexa otro carácter de dos puntos (:) y un nombre de restricción.Multiple inline constraints can be specified by appending another colon (:) and constraint name.

El nombre de restricción y los argumentos se pasan al servicio IInlineConstraintResolver para crear una instancia de IRouteConstraint para su uso en el procesamiento de direcciones URL.The constraint name and arguments are passed to the IInlineConstraintResolver service to create an instance of IRouteConstraint to use in URL processing. Por ejemplo, la plantilla de ruta blog/{article:minlength(10)} especifica una restricción minlength con el argumento 10.For example, the route template blog/{article:minlength(10)} specifies a minlength constraint with the argument 10. Para obtener más información sobre las restricciones de ruta y una lista de las restricciones proporcionadas por el marco de trabajo, vea la sección Referencia de restricciones de ruta.For more information on route constraints and a list of the constraints provided by the framework, see the Route constraint reference section.

Los parámetros de ruta también pueden tener transformadores de parámetros, que transforman el valor de un parámetro al generar vínculos y acciones y páginas coincidentes para las direcciones URL.Route parameters may also have parameter transformers, which transform a parameter's value when generating links and matching actions and pages to URLs. Al igual que las restricciones, los transformadores de parámetros se pueden agregar en línea a un parámetro de ruta al incorporar un carácter de dos puntos (:) y un nombre de transformador después del nombre del parámetro de ruta.Like constraints, parameter transformers can be added inline to a route parameter by adding a colon (:) and transformer name after the route parameter name. Por ejemplo, la plantilla de ruta blog/{article:slugify} especifica un transformador slugify.For example, the route template blog/{article:slugify} specifies a slugify transformer. Para obtener más información sobre los transformadores de parámetros, vea la sección Referencia de transformadores de parámetros.For more information on parameter transformers, see the Parameter transformer reference section.

En la tabla siguiente se muestran algunas plantillas de ruta de ejemplo y su comportamiento.The following table demonstrates example route templates and their behavior.

Plantilla de rutaRoute Template URI coincidente de ejemploExample Matching URI El URI de la solicitud…The request URI…
hello /hello Solo coincide con la ruta de acceso única /hello.Only matches the single path /hello.
{Page=Home} / Coincide y establece Page en Home.Matches and sets Page to Home.
{Page=Home} /Contact Coincide y establece Page en Contact.Matches and sets Page to Contact.
{controller}/{action}/{id?} /Products/List Se asigna al controlador Products y la acción List.Maps to the Products controller and List action.
{controller}/{action}/{id?} /Products/Details/123 Se asigna al controlador Products y la acción Details (id se establece en 123).Maps to the Products controller and Details action (id set to 123).
{controller=Home}/{action=Index}/{id?}{controller=Home}/{action=Index}/{id?} / Se asigna al controlador Home y al método Index (id se omite).Maps to the Home controller and Index method (id is ignored).

El uso de una plantilla suele ser el método de enrutamiento más sencillo.Using a template is generally the simplest approach to routing. Las restricciones y los valores predeterminados también se pueden especificar fuera de la plantilla de ruta.Constraints and defaults can also be specified outside the route template.

Sugerencia

Habilite el registro para ver de qué forma las implementaciones de enrutamiento integradas, como Route, coinciden con las solicitudes.Enable Logging to see how the built-in routing implementations, such as Route, match requests.

Nombres de enrutamientos reservadosReserved routing names

Las siguientes palabras clave son nombres reservados y no se pueden usar como nombres de ruta o parámetros:The following keywords are reserved names and can't be used as route names or parameters:

  • action
  • area
  • controller
  • handler
  • page

Referencia de restricción de rutaRoute constraint reference

Las restricciones de ruta se ejecutan cuando se ha producido una coincidencia con la dirección URL entrante y la ruta de dirección URL se convierte en tokens en valores de ruta.Route constraints execute when a match has occurred to the incoming URL and the URL path is tokenized into route values. En general, las restricciones de ruta inspeccionan el valor de ruta asociado a través de la plantilla de ruta y deciden si el valor es aceptable o no.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. Algunas restricciones de ruta usan datos ajenos al valor de ruta para decidir si la solicitud se puede enrutar.Some route constraints use data outside the route value to consider whether the request can be routed. Por ejemplo, HttpMethodRouteConstraint puede aceptar o rechazar una solicitud basada en su verbo HTTP.For example, the HttpMethodRouteConstraint can accept or reject a request based on its HTTP verb. Las restricciones se usan en las solicitudes de enrutamiento y la generación de vínculos.Constraints are used in routing requests and link generation.

Advertencia

No use las restricciones para las validación de entrada.Don't use constraints for input validation. Si las restricciones se usan para la validación de entrada, los resultados de entrada no válidos producirán un error 404 - No encontrado en lugar de un error 400 - Solicitud incorrecta con un mensaje de error adecuado.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. Las restricciones de ruta se usan para eliminar la ambigüedad entre rutas similares, no para validar las entradas de una ruta determinada.Route constraints are used to disambiguate similar routes, not to validate the inputs for a particular route.

En la tabla siguiente se muestran algunas restricciones de ruta de ejemplo y su comportamiento esperado.The following table demonstrates example route constraints and their expected behavior.

restricciónconstraint EjemploExample Coincidencias de ejemploExample Matches NotasNotes
int {id:int} 123456789, -123456789123456789, -123456789 Coincide con cualquier enteroMatches any integer
bool {active:bool} true, FALSEtrue, FALSE Coincide con true o false (no distingue mayúsculas de minúsculas)Matches true or false (case-insensitive)
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm2016-12-31, 2016-12-31 7:32pm Coincide con un valor DateTime válido (en la referencia cultural invariable; vea la advertencia)Matches a valid DateTime value (in the invariant culture - see warning)
decimal {price:decimal} 49.99, -1,000.0149.99, -1,000.01 Coincide con un valor decimal válido (en la referencia cultural invariable; vea la advertencia)Matches a valid decimal value (in the invariant culture - see warning)
double {weight:double} 1.234, -1,001.01e81.234, -1,001.01e8 Coincide con un valor double válido (en la referencia cultural invariable; vea la advertencia)Matches a valid double value (in the invariant culture - see warning)
float {weight:float} 1.234, -1,001.01e81.234, -1,001.01e8 Coincide con un valor float válido (en la referencia cultural invariable; vea la advertencia)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} Coincide con un valor Guid válidoMatches a valid Guid value
long {ticks:long} 123456789, -123456789123456789, -123456789 Coincide con un valor long válidoMatches a valid long value
minlength(value) {username:minlength(4)} Rick La cadena debe tener al menos cuatro caracteresString must be at least 4 characters
maxlength(value) {filename:maxlength(8)} Richard La cadena no debe tener más de ocho caracteresString must be no more than 8 characters
length(length) {filename:length(12)} somefile.txt La cadena debe tener una longitud de exactamente 12 caracteresString must be exactly 12 characters long
length(min,max) {filename:length(8,16)} somefile.txt La cadena debe tener una longitud como mínimo de ocho caracteres y como máximo de 16String must be at least 8 and no more than 16 characters long
min(value) {age:min(18)} 19 El valor entero debe ser como mínimo 18Integer value must be at least 18
max(value) {age:max(120)} 91 El valor entero debe ser como máximo 120Integer value must be no more than 120
range(min,max) {age:range(18,120)} 91 El valor entero debe ser como mínimo 18 y máximo 120Integer value must be at least 18 but no more than 120
alpha {name:alpha} Rick La cadena debe constar de uno o más caracteres alfabéticos (a-z, no distingue mayúsculas de minúsculas)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 La cadena debe coincidir con la expresión regular (vea las sugerencias sobre cómo definir una expresión regular)String must match the regular expression (see tips about defining a regular expression)
required {name:required} Rick Se usa para exigir que un valor que no es de parámetro esté presente durante la generación de dirección URLUsed to enforce that a non-parameter value is present during URL generation

Es posible aplicar varias restricciones delimitadas por dos puntos a un único parámetro.Multiple, colon-delimited constraints can be applied to a single parameter. Por ejemplo, la siguiente restricción permite limitar un parámetro a un valor entero de 1 o superior: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) { }

Advertencia

Las restricciones de ruta que comprueban la dirección URL y que se convierten en un tipo CLR (como int o DateTime) usan siempre la referencia cultural invariable.Route constraints that verify the URL and are converted to a CLR type (such as int or DateTime) always use the invariant culture. Estas restricciones dan por supuesto que la dirección URL no es localizable.These constraints assume that the URL is non-localizable. Las restricciones de ruta proporcionadas por el marco de trabajo no modifican los valores almacenados en los valores de ruta.The framework-provided route constraints don't modify the values stored in route values. Todos los valores de ruta analizados desde la dirección URL se almacenan como cadenas.All route values parsed from the URL are stored as strings. Por ejemplo, la restricción float intenta convertir el valor de ruta en un valor Float, pero el valor convertido se usa exclusivamente para comprobar que se puede convertir en 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.

Expresiones regularesRegular expressions

El marco de trabajo de ASP.NET Core agrega RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant al constructor de expresiones regulares.The ASP.NET Core framework adds RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant to the regular expression constructor. Vea RegexOptions para obtener una descripción de estos miembros.See RegexOptions for a description of these members.

Las expresiones regulares usan delimitadores y tokens similares a los que usan el enrutamiento y el lenguaje C#.Regular expressions use delimiters and tokens similar to those used by Routing and the C# language. Es necesario usar secuencias de escape con los tokens de expresiones regulares.Regular expression tokens must be escaped. Para usar la expresión regular ^\d{3}-\d{2}-\d{4}$ en el enrutamiento, los caracteres \ (una barra diagonal inversa) de la cadena se deben proporcionar como caracteres \\ (barra diagonal inversa doble) en el archivo de código fuente de C# para que el carácter de escape de cadena \ tenga una secuencia de escape (a menos que se usen literales de cadena textuales).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). Para aplicar secuencias de escape a los caracteres delimitadores de parámetro de enrutamiento ({, }, [ y ]), duplique los caracteres en la expresión ({{, }, [[ y ]]).To escape routing parameter delimiter characters ({, }, [, ]), double the characters in the expression ({{, }, [[, ]]). En la tabla siguiente se muestra una expresión regular y la versión con la secuencia de escape.The following table shows a regular expression and the escaped version.

Expresión regularRegular Expression Expresión regular con secuencia de escapeEscaped Regular Expression
^\d{3}-\d{2}-\d{4}$ ^\\d{{3}}-\\d{{2}}-\\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$

Las expresiones regulares que se usan en el enrutamiento suelen empezar con el carácter de acento circunflejo (^) y coinciden con la posición inicial de la cadena.Regular expressions used in routing often start with the caret (^) character and match starting position of the string. Las expresiones suelen terminar con el carácter del signo de dólar ($) y coincidir con el final de la cadena.The expressions often end with the dollar sign ($) character and match end of the string. Los caracteres ^ y $ garantizan que la expresión regular coincide con el valor completo del parámetro de ruta.The ^ and $ characters ensure that the regular expression match the entire route parameter value. Sin los caracteres ^ y $, la expresión regular coincide con cualquier subcadena de la cadena, algo que normalmente no es deseable.Without the ^ and $ characters, the regular expression match any substring within the string, which is often undesirable. En la tabla siguiente se proporcionan ejemplos y se explica por qué coinciden o no.The following table provides examples and explains why they match or fail to match.

ExpresiónExpression StringString Coincidir conMatch ComentarioComment
[a-z]{2} hellohello Yes Coincidencias de subcadenasSubstring matches
[a-z]{2} 123abc456123abc456 Yes Coincidencias de subcadenasSubstring matches
[a-z]{2} mzmz Yes Coincide con la expresiónMatches expression
[a-z]{2} MZMZ Yes No distingue mayúsculas de minúsculasNot case sensitive
^[a-z]{2}$ hellohello NoNo Vea ^ y $ más arribaSee ^ and $ above
^[a-z]{2}$ 123abc456123abc456 NoNo Vea ^ y $ más arribaSee ^ and $ above

Para obtener más información sobre la sintaxis de expresiones regulares, vea Expresiones regulares de .NET Framework.For more information on regular expression syntax, see .NET Framework Regular Expressions.

Para restringir un parámetro a un conjunto conocido de valores posibles, use una expresión regular.To constrain a parameter to a known set of possible values, use a regular expression. Por ejemplo, {action:regex(^(list|get|create)$)} solo hace coincidir el valor de ruta action con list, get o create.For example, {action:regex(^(list|get|create)$)} only matches the action route value to list, get, or create. Si se pasa al diccionario de restricciones, la cadena ^(list|get|create)$ es equivalente.If passed into the constraints dictionary, the string ^(list|get|create)$ is equivalent. Las restricciones que se pasan al diccionario de restricciones (no insertado en una plantilla) que no coinciden con una de las restricciones conocidas también se tratan como expresiones regulares.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.

Referencia de transformadores de parámetrosParameter transformer reference

Transformadores de parámetros:Parameter transformers:

  • Se ejecutan al generar un vínculo para Route.Execute when generating a link for a Route.
  • Implemente Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.Implement Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.
  • Se configuran con ConstraintMap.Are configured using ConstraintMap.
  • Toman el valor de ruta del parámetro y lo transforman en un nuevo valor de cadena.Take the parameter's route value and transform it to a new string value.
  • Como resultado, el valor transformado se usa en el vínculo generado.Result in using the transformed value in the generated link.

Por ejemplo, un transformador de parámetros personalizado slugify en el patrón de ruta blog\{article:slugify} con Url.Action(new { article = "MyTestArticle" }) genera 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.

El marco usa los transformadores de parámetros para transformar el URI en el que se resuelve un punto de conexión.Parameter transformers are used by the framework to transform the URI where an endpoint resolves. Por ejemplo, ASP.NET Core MVC usa transformadores de parámetros para transformar el valor de ruta usado para hacer coincidir elementos area, controller, action y page.For example, ASP.NET Core MVC uses parameter transformers to transform the route value used to match an area, controller, action, and page.

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

Con la ruta anterior, la acción SubscriptionManagementController.GetAll() coincide con el URI /subscription-management/get-all.With the preceding route, the action SubscriptionManagementController.GetAll() is matched with the URI /subscription-management/get-all. Un transformador de parámetros no cambia los valores de ruta usados para generar un vínculo.A parameter transformer doesn't change the route values used to generate a link. Por ejemplo, Url.Action("GetAll", "SubscriptionManagement") genera /subscription-management/get-all.For example, Url.Action("GetAll", "SubscriptionManagement") outputs /subscription-management/get-all.

ASP.NET Core proporciona las convenciones de API para usar transformadores de parámetros con rutas generadas:ASP.NET Core provides API conventions for using a parameter transformers with generated routes:

  • ASP.NET Core MVC tiene la convención de API Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention.ASP.NET Core MVC has the Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention API convention. Esta convención aplica un transformador de parámetro especificado a todas las rutas de atributo de la aplicación.This convention applies a specified parameter transformer to all attribute routes in the app. El transformador de parámetro transforma los tokens de rutas de atributo a medida que se reemplazan.The parameter transformer transforms attribute route tokens as they are replaced. Para más información, consulte Usar un transformador de parámetro para personalizar el reemplazo de tokens.For more information, see Use a parameter transformer to customize token replacement.
  • Razor Pages tiene la convención de API Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention.Razor Pages has the Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention API convention. Esta convención aplica un transformador de parámetros especificado a todas las instancias de Razor Pages detectadas de forma automática.This convention applies a specified parameter transformer to all automatically discovered Razor Pages. El transformador de parámetros transforma los segmentos de nombre de archivo y carpeta de las rutas de Razor Pages.The parameter transformer transforms the folder and file name segments of Razor Pages routes. Para más información, consulte el artículo sobre cómo usar un transformador de parámetro para personalizar rutas de Razor Pages.For more information, see Use a parameter transformer to customize page routes.

Referencia de generación de direcciones URLURL generation reference

En el ejemplo siguiente se muestra cómo se genera un vínculo a una ruta, dado un diccionario de valores de ruta y un valor 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/>");
});

El valor VirtualPath generado al final del ejemplo anterior es /package/create/123.The VirtualPath generated at the end of the preceding sample is /package/create/123. El diccionario proporciona los valores de ruta operation e id de la plantilla "Ruta de paquete de seguimiento", package/{operation}/{id}.The dictionary supplies the operation and id route values of the "Track Package Route" template, package/{operation}/{id}. Para obtener más información, vea el código de ejemplo de la sección Uso de software intermedio de enrutamiento o la aplicación de ejemplo.For details, see the sample code in the Use Routing Middleware section or the sample app.

El segundo parámetro del constructor VirtualPathContext es una colección de valores de ambiente.The second parameter to the VirtualPathContext constructor is a collection of ambient values. Los valores de ambiente son adecuados porque limitan el número de valores que el desarrollador debe especificar dentro de un contexto de solicitud.Ambient values are convenient to use because they limit the number of values a developer must specify within a request context. Los valores de ruta actuales de la solicitud actual se consideran valores de ambiente para la generación de vínculos.The current route values of the current request are considered ambient values for link generation. En la acción About de HomeController de una aplicación ASP.NET Core MVC, no es necesario especificar el valor de ruta de controlador para vincular a la acción Index (se usará el valor de ambiente 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.

Los valores de ambiente que no coincidan con un parámetro se omiten.Ambient values that don't match a parameter are ignored. También se omiten los valores de ambiente cuando un valor proporcionado de forma explícita invalida el valor de ambiente.Ambient values are also ignored when an explicitly provided value overrides the ambient value. La coincidencia se produce de izquierda a derecha en la dirección URL.Matching occurs from left to right in the URL.

Los valores que se proporcionan de forma explícita pero que no coinciden con un segmento de la ruta se agregan a la cadena de consulta.Values explicitly provided but that don't match a segment of the route are added to the query string. En la tabla siguiente se muestra el resultado cuando se usa la plantilla de ruta {controller}/{action}/{id?}.The following table shows the result when using the route template {controller}/{action}/{id?}.

Valores de ambienteAmbient Values Valores explícitosExplicit Values ResultadoResult
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

Si una ruta tiene un valor predeterminado que no se corresponde con un parámetro y ese valor se proporciona de forma explícita, debe coincidir con el valor predeterminado: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" });

La generación de vínculos solo genera un vínculo para esta ruta si se proporcionan los valores coincidentes para controller y action.Link generation only generates a link for this route when the matching values for controller and action are provided.