Routage dans ASP.NET CoreRouting in ASP.NET Core

Par Ryan Nowak, Steve Smith et Rick AndersonBy Ryan Nowak, Steve Smith, and Rick Anderson

Pour obtenir la version 1.1 de cette rubrique, téléchargez Routing in ASP.NET Core (version 1.1, PDF).For the 1.1 version of this topic, download Routing in ASP.NET Core (version 1.1, PDF).

Le routage est responsable du mappage des URI des requêtes aux sélecteurs de point de terminaison et de la distribution des requêtes entrantes entre les points de terminaison.Routing is responsible for mapping request URIs to endpoint selectors and dispatching incoming requests to endpoints. Les routes sont définies dans l’application et configurées au démarrage de l’application.Routes are defined in the app and configured when the app starts. Une route peut éventuellement extraire des valeurs de l’URL contenue dans la requête, et ces valeurs peuvent ensuite être utilisées pour le traitement de la requête.A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. Avec les informations de routage fournies par l’application, le routage peut également générer des URL qui mappent à des sélecteurs de point de terminaison.Using route information from the app, routing is also able to generate URLs that map to endpoint selectors.

Pour utiliser les scénarios de routage les plus récents dans ASP.NET Core 2.2, spécifiez la version de compatibilité à l’inscription des services MVC dans 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);

L’option EnableEndpointRouting détermine si le routage doit utiliser en interne une logique basée sur les points de terminaison ou la logique basée sur IRouter d’ASP.NET Core 2.1 ou antérieur.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. Quand la version de compatibilité est définie sur 2.2 ou ultérieur, la valeur par défaut est true.When the compatibility version is set to 2.2 or later, the default value is true. Définissez la valeur sur false pour utiliser la logique de routage antérieure :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);

Pour plus d’informations sur le routage basé sur IRouter, consultez la version ASP.NET Core 2.1 de cette rubrique.For more information on IRouter-based routing, see the ASP.NET Core 2.1 version of this topic.

Le routage est responsable du mappage des URI des requêtes aux gestionnaires de routage et de la distribution des requêtes entrantes.Routing is responsible for mapping request URIs to route handlers and dispatching an incoming requests. Les routes sont définies dans l’application et configurées au démarrage de l’application.Routes are defined in the app and configured when the app starts. Une route peut éventuellement extraire des valeurs de l’URL contenue dans la requête, et ces valeurs peuvent ensuite être utilisées pour le traitement de la requête.A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. En utilisant des routes configurées à partir de l’application, le routage est en mesure de générer des URL qui mappent à des gestionnaires de routage.Using configured routes from the app, routing is able to generate URLs that map to route handlers.

Pour utiliser les scénarios de routage les plus récents dans ASP.NET Core 2.1, spécifiez la version de compatibilité à l’inscription des services MVC dans 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);

Important

Ce document traite du routage ASP.NET Core de bas niveau.This document covers low-level ASP.NET Core routing. Pour plus d’informations sur le routage ASP.NET Core MVC, consultez Routage vers les actions du contrôleur dans ASP.NET Core.For information on ASP.NET Core MVC routing, see Routage vers les actions du contrôleur dans ASP.NET Core. Pour plus d’informations sur les conventions de routage dans Razor Pages, consultez Conventions de routes et d’applications pour les pages Razor dans ASP.NET Core.For information on routing conventions in Razor Pages, see Conventions de routes et d’applications pour les pages Razor dans ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Concepts de base du routageRouting basics

La plupart des applications doivent choisir un schéma de routage de base et descriptif pour que les URL soient lisibles et explicites.Most apps should choose a basic and descriptive routing scheme so that URLs are readable and meaningful. La route conventionnelle par défaut {controller=Home}/{action=Index}/{id?} :The default conventional route {controller=Home}/{action=Index}/{id?}:

  • Prend en charge un schéma de routage de base et descriptif.Supports a basic and descriptive routing scheme.
  • Est un point de départ pratique pour les applications basées sur une interface utilisateur.Is a useful starting point for UI-based apps.

Les développeurs ajoutent fréquemment des routes laconiques supplémentaires aux zones à trafic élevé de l’application dans des situations particulières (par exemple des points de terminaison de blog ou d’e-commerce) en utilisant le routage d’attributs ou des routes conventionnelles dédiées.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.

Les API web doivent utiliser le routage d’attributs pour modéliser les fonctionnalités de l’application sous la forme d’un ensemble de ressources dans lequel les opérations sont représentées par des verbes 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. Cela signifie que plusieurs opérations (comme GET et POST) sur la même ressource logique utilisent la même URL.This means that many operations (for example, GET, POST) on the same logical resource will use the same URL. Le routage d’attributs fournit le niveau de contrôle nécessaire pour concevoir avec soin la disposition des points de terminaison publics d’une API.Attribute routing provides a level of control that's needed to carefully design an API's public endpoint layout.

Les applications Razor Pages utilisent le routage conventionnel par défaut pour délivrer des ressources nommées dans le dossier Pages d’une application.Razor Pages apps use default conventional routing to serve named resources in the Pages folder of an app. Des conventions supplémentaires sont disponibles : elles vous permettent de personnaliser le comportement de routage de Razor Pages.Additional conventions are available that allow you to customize Razor Pages routing behavior. Pour plus d’informations, consultez Présentation des pages Razor dans ASP.NET Core et Conventions de routes et d’applications pour les pages Razor dans ASP.NET Core.For more information, see Présentation des pages Razor dans ASP.NET Core and Conventions de routes et d’applications pour les pages Razor dans ASP.NET Core.

La prise en charge de la génération d’URL permet de développer l’application sans coder en dur les URL pour lier l’application.URL generation support allows the app to be developed without hard-coding URLs to link the app together. Cette prise en charge permet de commencer avec une configuration de routage de base, puis de modifier les routes une fois que la disposition des ressources de l’application est déterminée.This support allows for starting with a basic routing configuration and modifying the routes after the app's resource layout is determined.

Le routage utilise des points de terminaison (Endpoint) pour représenter les points de terminaison logiques dans une application.Routing uses endpoints (Endpoint) to represent logical endpoints in an app.

Un point de terminaison définit un délégué pour traiter les requêtes et une collection de métadonnées arbitraires.An endpoint defines a delegate to process requests and a collection of arbitrary metadata. Les métadonnées sont utilisées pour implémenter des problèmes transversaux basés sur des stratégies et une configuration attachées à chaque point de terminaison.The metadata is used implement cross-cutting concerns based on policies and configuration attached to each endpoint.

Le système de routage a les caractéristiques suivantes :The routing system has the following characteristics:

  • Une syntaxe des modèles de route est utilisée pour définir des routes avec des paramètres de route tokenisés.Route template syntax is used to define routes with tokenized route parameters.

  • La configuration de points de terminaison de style conventionnel et de style « attribut » est autorisée.Conventional-style and attribute-style endpoint configuration is permitted.

  • IRouteConstraint est utilisé pour déterminer si un paramètre d’URL contient une valeur valide pour une contrainte de point de terminaison donné.IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.

  • Les modèles d’application, comme MVC/Razor Pages, inscrivent tous leurs points de terminaison, qui ont une implémentation prévisible de scénarios de routage.App models, such as MVC/Razor Pages, register all of their endpoints, which have a predictable implementation of routing scenarios.

  • L’implémentation du routage prend des décisions de routage partout où vous le souhaitez dans le pipeline de middleware (intergiciel).The routing implementation makes routing decisions wherever desired in the middleware pipeline.

  • Le middleware qui apparaît après un middleware de routage peut inspecter le résultat de la décision du middleware de routage quant au point de terminaison d’un URI de requête donné.Middleware that appears after a Routing Middleware can inspect the result of the Routing Middleware's endpoint decision for a given request URI.

  • Il est possible d’énumérer tous les points de terminaison dans l’application n’importe où dans le pipeline de middleware.It's possible to enumerate all of the endpoints in the app anywhere in the middleware pipeline.

  • Une application peut utiliser le routage pour générer des URL (par exemple pour la redirection ou pour des liens) en fonction des informations des points de terminaison et éviter ainsi les URL codées en dur, ce qui facilite la maintenance.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 génération d’URL est basée sur des adresses, qui prennent en charge l’extensibilité arbitraire :URL generation is based on addresses, which support arbitrary extensibility:

Notes

Avec la publication du routage des points de terminaison dans ASP.NET Core 2.2, la liaison de point de terminaison est limitée aux actions et aux pages MVC/Razor Pages.With the release of endpoint routing in ASP.NET Core 2.2, endpoint linking is limited to MVC/Razor Pages actions and pages. Les expansions des fonctionnalités de liaison de point de terminaison sont prévues pour les versions futures.The expansions of endpoint-linking capabilities is planned for future releases.

Le routage utilise des routes (implémentations de IRouter) pour :Routing uses routes (implementations of IRouter) to:

  • Mapper les requêtes entrantes à des gestionnaires de routage.Map incoming requests to route handlers.
  • Générer les URL utilisées dans les réponses.Generate the URLs used in responses.

Par défaut, une application a une seule collection de routes.By default, an app has a single collection of routes. Quand une requête arrive, les routes de la collection sont traitées dans l’ordre où elles se trouvent dans la collection.When a request arrives, the routes in the collection are processed in the order that they exist in the collection. Le framework tente de mettre en correspondance l’URL d’une requête entrante avec une route de la collection en appelant la méthode RouteAsync sur chaque route de la collection.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. Une réponse peut utiliser le routage pour générer des URL (par exemple pour la redirection ou pour des liens) en fonction des informations des routes et éviter ainsi les URL codées en dur, ce qui facilite la maintenance.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.

Le système de routage a les caractéristiques suivantes :The routing system has the following characteristics:

  • Une syntaxe des modèles de route est utilisée pour définir des routes avec des paramètres de route tokenisés.Route template syntax is used to define routes with tokenized route parameters.
  • La configuration de points de terminaison de style conventionnel et de style « attribut » est autorisée.Conventional-style and attribute-style endpoint configuration is permitted.
  • IRouteConstraint est utilisé pour déterminer si un paramètre d’URL contient une valeur valide pour une contrainte de point de terminaison donné.IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.
  • Les modèles d’application, comme MVC/Razor Pages, inscrivent toutes leurs routes, qui ont une implémentation prévisible de scénarios de routage.App models, such as MVC/Razor Pages, register all of their routes, which have a predictable implementation of routing scenarios.
  • Une réponse peut utiliser le routage pour générer des URL (par exemple pour la redirection ou pour des liens) en fonction des informations des routes et éviter ainsi les URL codées en dur, ce qui facilite la maintenance.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 génération d’URL est basée sur des routes, qui prennent en charge l’extensibilité arbitraire.URL generation is based on routes, which support arbitrary extensibility. IUrlHelper offre des méthodes pour générer des URL.IUrlHelper offers methods to build URLs.

Le routage est connecté au pipeline de l’intergiciel (middleware) par la classe RouterMiddleware.Routing is connected to the middleware pipeline by the RouterMiddleware class. ASP.NET Core MVC ajoute le routage au pipeline de middleware dans le cadre de sa configuration, et gère le routage dans les applications MVC et 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. Pour découvrir comment utiliser le routage en tant que composant autonome, consultez la section Utiliser le middleware de routage.To learn how to use routing as a standalone component, see the Use Routing Middleware section.

Correspondance d’URLURL matching

La correspondance d’URL est le processus par lequel le routage distribue une requête entrante à un point de terminaison.URL matching is the process by which routing dispatches an incoming request to an endpoint. Ce processus est basé sur des données présentes dans le chemin de l’URL, mais il peut être étendu pour prendre en compte toutes les données de la requête.This process is based on data in the URL path but can be extended to consider any data in the request. La possibilité de distribuer des requêtes à des gestionnaires distincts est essentielle pour adapter la taille et la complexité d’une application.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

Le système de routage dans le routage de point de terminaison est responsable de toutes les décisions de distribution.The routing system in endpoint routing is responsible for all dispatching decisions. Comme le middleware applique des stratégies basées sur le point de terminaison sélectionné, il est important que les décisions susceptibles d’affecter la distribution ou l’application des stratégies de sécurité soient prises au sein du système de routage.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.

Quand le délégué du point de terminaison est exécuté, les propriétés de RouteContext.RouteData sont définies sur des valeurs appropriées en fonction du traitement des requêtes effectué jusqu’à présent.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 correspondance d’URL est le processus par lequel le routage distribue une requête entrante à un gestionnaire.URL matching is the process by which routing dispatches an incoming request to a handler. Ce processus est basé sur des données présentes dans le chemin de l’URL, mais il peut être étendu pour prendre en compte toutes les données de la requête.This process is based on data in the URL path but can be extended to consider any data in the request. La possibilité de distribuer des requêtes à des gestionnaires distincts est essentielle pour adapter la taille et la complexité d’une application.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

Les requêtes entrantes entrent dans RouterMiddleware, qui appelle la méthode RouteAsync sur chaque route dans l’ordre.Incoming requests enter the RouterMiddleware, which calls the RouteAsync method on each route in sequence. L’instance IRouter détermine s’il faut gérer la requête en affectant à RouteContext.Handler un RequestDelegate non null.The IRouter instance chooses whether to handle the request by setting the RouteContext.Handler to a non-null RequestDelegate. Si une route définit un gestionnaire pour la requête, le traitement de la route s’arrête et le gestionnaire est appelé pour traiter la requête.If a route sets a handler for the request, route processing stops, and the handler is invoked to process the request. Si aucun gestionnaire de routage n’est trouvé pour traiter la requête, le middleware passe la requête au middleware suivant dans le pipeline de requête.If no route handler is found to process the request, the middleware hands the request off to the next middleware in the request pipeline.

L’entrée principale de RouteAsync est le RouteContext.HttpContext associé à la requête actuelle.The primary input to RouteAsync is the RouteContext.HttpContext associated with the current request. RouteContext.Handler et RouteContext.RouteData sont des sorties définies après la mise en correspondance d’une route.The RouteContext.Handler and RouteContext.RouteData are outputs set after a route is matched.

Une correspondance qui appelle RouteAsync définit également les propriétés de RouteContext.RouteData sur des valeurs appropriées en fonction du traitement des requêtes effectué jusqu’à présent.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 est un dictionnaire de valeurs de route produites à partir de la route.RouteData.Values is a dictionary of route values produced from the route. Ces valeurs sont généralement déterminées en décomposant l’URL en jetons. Elles peuvent être utilisées pour accepter l’entrée d’utilisateur ou pour prendre d’autres décisions relatives à la distribution à l’intérieur de l’application.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 est un conteneur de propriétés des données supplémentaires associées à la route mise en correspondance.RouteData.DataTokens is a property bag of additional data related to the matched route. Les DataTokens sont fournis pour prendre en charge l’association de données d’état à chaque route, de façon que l’application puisse prendre des décisions en fonction de la route avec laquelle la correspondance a été établie.DataTokens are provided to support associating state data with each route so that the app can make decisions based on which route matched. Ces valeurs sont définies par le développeur et n’affectent pas le comportement du routage de quelque manière que ce soit.These values are developer-defined and do not affect the behavior of routing in any way. De plus, les valeurs dissimulées dans RouteData.DataTokens peuvent être de n’importe quel type, contrairement aux valeurs RouteData.Values, qui doivent être convertibles en chaînes et à partir de chaînes.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 est une liste des routes qui ont participé à la mise en correspondance correcte de la requête.RouteData.Routers is a list of the routes that took part in successfully matching the request. Les routes peuvent être imbriquées les unes dans les autres.Routes can be nested inside of one another. La propriété Routers reflète le chemin à travers l’arborescence logique des routes qui ont généré une correspondance.The Routers property reflects the path through the logical tree of routes that resulted in a match. En général le premier élément de Routers est la collection de routes et il doit être utilisé pour la génération d’URL.Generally, the first item in Routers is the route collection and should be used for URL generation. Le dernier élément de Routers est le gestionnaire de routage avec lequel la correspondance a été établie.The last item in Routers is the route handler that matched.

Génération d’URLURL generation

La génération d’URL est le processus par lequel le routage peut créer un chemin d’URL basé sur un ensemble de valeurs de route.URL generation is the process by which routing can create a URL path based on a set of route values. Ceci permet une séparation logique entre vos points de terminaison et les URL qui y accèdent.This allows for a logical separation between your endpoints and the URLs that access them.

Le routage des points de terminaison inclut l’API de générateur de liens (LinkGenerator).Endpoint routing includes the Link Generator API (LinkGenerator). LinkGenerator est un service singleton qui peut être récupéré à partir de l’injection de dépendances.LinkGenerator is a singleton service that can be retrieved from DI. L’API peut être utilisée en dehors du contexte d’une requête en cours d’exécution.The API can be used outside of the context of an executing request. Le IUrlHelper de MVC et les scénarios qui s’appuient sur IUrlHelper, comme les Tag Helpers, les helpers HTML et les résultats d’action, utilisent le générateur de liens pour fournir les fonctionnalités de création de liens.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.

Le générateur de liens est basé sur le concept d’une adresse et de schémas d’adresse.The link generator is backed by the concept of an address and address schemes. Un schéma d’adresse est un moyen de déterminer les points de terminaison à prendre en compte pour la génération de liens.An address scheme is a way of determining the endpoints that should be considered for link generation. Par exemple, les scénarios de nom de route et de valeurs de route que connaissent bien nombre d’utilisateurs dans les MVC/Razor Pages sont implémentés en tant que schémas d’adresse.For example, the route name and route values scenarios many users are familiar with from MVC/Razor Pages are implemented as an address scheme.

Le générateur de liens peut lier à des actions et à des pages MVC/Razor Pages via les méthodes d’extension suivantes :The link generator can link to MVC/Razor Pages actions and pages via the following extension methods:

Une surcharge de ces méthodes accepte des arguments qui incluent le HttpContext.An overload of these methods accepts arguments that include the HttpContext. Ces méthodes sont fonctionnellement équivalentes à Url.Action et à Url.Page, mais elles offrent davantage de flexibilité et d’options.These methods are functionally equivalent to Url.Action and Url.Page but offer additional flexibility and options.

Les méthodes GetPath* sont les plus proches de Url.Action et de Url.Page en ce qu’elles génèrent un URI contenant un chemin absolu.The GetPath* methods are most similar to Url.Action and Url.Page in that they generate a URI containing an absolute path. Les méthodes GetUri* génèrent toujours un URI absolu contenant un schéma et un hôte.The GetUri* methods always generate an absolute URI containing a scheme and host. Les méthodes qui acceptent un HttpContext génèrent un URI dans le contexte de la requête en cours d’exécution.The methods that accept an HttpContext generate a URI in the context of the executing request. Les valeurs de route ambiante, le chemin de base d’URL, le schéma et l’hôte de la requête en cours d’exécution sont utilisés, sauf s’ils sont remplacés.The ambient route values, URL base path, scheme, and host from the executing request are used unless overridden.

LinkGenerator est appelé avec une adresse.LinkGenerator is called with an address. La génération d’un URI se fait en deux étapes :Generating a URI occurs in two steps:

  1. Une adresse est liée à une liste de points de terminaison qui correspondent à l’adresse.An address is bound to a list of endpoints that match the address.
  2. Le RoutePattern de chaque point de terminaison est évalué jusqu’à ce qu’un modèle de route correspondant aux valeurs fournies soit trouvé.Each endpoint's RoutePattern is evaluated until a route pattern that matches the supplied values is found. Le résultat obtenu est combiné avec d’autres parties de l’URI fournies par le générateur de liens, puis il est retourné.The resulting output is combined with the other URI parts supplied to the link generator and returned.

Les méthodes fournies par LinkGenerator prennent en charge des fonctionnalités de génération de liens standard pour n’importe quel type d’adresse.The methods provided by LinkGenerator support standard link generation capabilities for any type of address. La façon la plus pratique d’utiliser le générateur de liens est de le faire via des méthodes d’extension qui effectuent des opérations pour un type d’adresse spécifique.The most convenient way to use the link generator is through extension methods that perform operations for a specific address type.

Méthode d'extensionExtension Method DescriptionDescription
GetPathByAddress Génère un URI avec un chemin absolu basé sur les valeurs fournies.Generates a URI with an absolute path based on the provided values.
GetUriByAddress Génère un URI absolu basé sur les valeurs fournies.Generates an absolute URI based on the provided values.

Avertissement

Faites attention aux implications suivantes de l’appel de méthodes LinkGenerator :Pay attention to the following implications of calling LinkGenerator methods:

  • Utilisez les méthodes d’extension GetUri* avec précaution dans une configuration d’application qui ne valide pas l’en-tête Host des requêtes entrantes.Use GetUri* extension methods with caution in an app configuration that doesn't validate the Host header of incoming requests. Si l’en-tête Host des requêtes entrantes n’est pas validé, l’entrée de requête non approuvée peut être renvoyée au client dans les URI d’une page/vue.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. Nous recommandons que toutes les applications de production configurent leur serveur pour qu’il valide l’en-tête Host par rapport à des valeurs valides connues.We recommend that all production apps configure their server to validate the Host header against known valid values.

  • Utilisez LinkGenerator avec précaution dans le middleware en combinaison avec Map ou MapWhen.Use LinkGenerator with caution in middleware in combination with Map or MapWhen. Map* modifie le chemin de base de la requête en cours d’exécution, ce qui affecte la sortie de la génération de liens.Map* changes the base path of the executing request, which affects the output of link generation. Toutes les API LinkGenerator permettent la spécification d’un chemin de base.All of the LinkGenerator APIs allow specifying a base path. Spécifiez toujours un chemin de base vide pour annuler l’effet de Map* sur la génération de liens.Always specify an empty base path to undo Map*'s affect on link generation.

Différences par rapport aux versions précédentes du routageDifferences from earlier versions of routing

Il existe quelques différences entre le routage de points de terminaison d’ASP.NET Core 2.2 ou ultérieur et celui des versions antérieures d’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:

  • Le système de routage de points de terminaison ne prend pas en charge l’extensibilité basée sur IRouter, notamment l’héritage de Route.The endpoint routing system doesn't support IRouter-based extensibility, including inheriting from Route.

  • Le routage de points de terminaison ne prend pas en charge WebApiCompatShim.Endpoint routing doesn't support WebApiCompatShim. Utilisez la version de compatibilité 2.1 (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) pour continuer à utiliser le shim de compatibilité.Use the 2.1 compatibility version (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) to continue using the compatibility shim.

  • Le routage de points de terminaison a un comportement différent pour la casse des URI générés lors de l’utilisation de routes conventionnelles.Endpoint Routing has different behavior for the casing of generated URIs when using conventional routes.

    Considérez le modèle de route par défaut suivant :Consider the following default route template:

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

    Supposez que vous générez un lien vers une action avec la route suivante :Suppose you generate a link to an action using the following route:

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

    Avec le routage basé sur IRouter, ce code génère un URI /blog/ReadPost/17, qui respecte la casse de la valeur de la route fournie.With IRouter-based routing, this code generates a URI of /blog/ReadPost/17, which respects the casing of the provided route value. Le routage de points de terminaison dans ASP.NET Core 2.2 ou ultérieur produit /Blog/ReadPost/17 (« Blog » commence par une majuscule).Endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 ("Blog" is capitalized). Le routage de points de terminaison fournit l’interface IOutboundParameterTransformer, qui peut être utilisée pour personnaliser ce comportement de façon globale ou pour appliquer des conventions différentes pour le mappage d’URL.Endpoint routing provides the IOutboundParameterTransformer interface that can be used to customize this behavior globally or to apply different conventions for mapping URLs.

    Pour plus d’informations, consultez la section Informations de référence sur les transformateurs de paramètre.For more information, see the Parameter transformer reference section.

  • La génération de liens utilisée par MVC/Razor Pages avec des routes conventionnelles se comporte différemment quand vous tentez de lier à un contrôleur/action ou à une page qui n’existe pas.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.

    Considérez le modèle de route par défaut suivant :Consider the following default route template:

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

    Supposez que vous générez un lien vers une action en utilisant le modèle par défaut avec ce qui suit :Suppose you generate a link to an action using the default template with the following:

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

    Avec le routage basé sur IRouter, le résultat est toujours /Blog/ReadPost/17, même si le BlogController n’existe pas ou n’a pas de méthode d’action 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. Comme prévu, le routage de points de terminaison dans ASP.NET Core 2.2 ou ultérieur produit /Blog/ReadPost/17 si la méthode d’action existe.As expected, endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 if the action method exists. Cependant, le routage de points de terminaison produit une chaîne vide si l’action n’existe pas.However, endpoint routing produces an empty string if the action doesn't exist. Sur le plan conceptuel, le routage de points de terminaison ne fait pas l’hypothèse que le point de terminaison existe si l’action n’existe pas.Conceptually, endpoint routing doesn't assume that the endpoint exists if the action doesn't exist.

  • L’algorithme d’invalidation de valeur ambiante de la génération de liens se comporte différemment quand il est utilisé avec le routage de points de terminaison.The link generation ambient value invalidation algorithm behaves differently when used with endpoint routing.

    L’invalidation de valeur ambiante est l’algorithme qui décide quelles valeurs de route provenant de la requête en cours d’exécution (les valeurs ambiantes) peuvent être utilisées dans les opérations de génération de liens.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. Le routage conventionnel a toujours invalidé les valeurs de route supplémentaires lors de la liaison à une action différente.Conventional routing always invalidated extra route values when linking to a different action. Le routage d’attributs n’a pas ce comportement avant la publication d’ASP.NET Core 2.2.Attribute routing didn't have this behavior prior to the release of ASP.NET Core 2.2. Dans les versions antérieures d’ASP.NET Core, les liens vers une autre action utilisant les mêmes noms de paramètre de route provoquaient des erreurs de génération de liens.In earlier versions of ASP.NET Core, links to another action that use the same route parameter names resulted in link generation errors. Dans ASP.NET Core 2.2 ou ultérieur, les deux formes de routage invalident les valeurs lors de la liaison vers une autre action.In ASP.NET Core 2.2 or later, both forms of routing invalidate values when linking to another action.

    Considérez l’exemple suivant dans ASP.NET Core 2.1 ou antérieur.Consider the following example in ASP.NET Core 2.1 or earlier. Lors de la liaison à une autre action (ou une autre page), les valeurs de route peuvent être réutilisées de façon non souhaitée.When linking to another action (or another page), route values can be reused in undesirable ways.

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

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

    Dans /Pages/Login.cshtml :In /Pages/Login.cshtml:

    @page "{id?}"
    

    Si l’URI est /Store/Product/18 dans ASP.NET Core 2.1 ou antérieur, le lien généré sur la page Store/Info par @Url.Page("/Login") est /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. La valeur 18 pour id est réutilisée, même si la destination du lien est une partie entièrement différente de l’application.The id value of 18 is reused, even though the link destination is different part of the app entirely. La valeur de route pour id dans le contexte de la page /Login est probablement une valeur d’ID utilisateur, et non pas une valeur d’ID de produit de magasin.The id route value in the context of the /Login page is probably a user ID value, not a store product ID value.

    Dans le routage de points de terminaison avec ASP.NET Core 2.2 ou ultérieur, le résultat est /Login.In endpoint routing with ASP.NET Core 2.2 or later, the result is /Login. Les valeurs ambiantes ne sont pas réutilisées quand la destination liée est une action ou une page différente.Ambient values aren't reused when the linked destination is a different action or page.

  • Syntaxe des paramètres de route avec aller-retour : les barres obliques ne sont pas encodées lors de l’utilisation d’une syntaxe de paramètre passe-partout avec double astérisque (**).Round-tripping route parameter syntax: Forward slashes aren't encoded when using a double-asterisk (**) catch-all parameter syntax.

    Pendant la génération de liens, le système de routage encode la valeur capturée dans un paramètre passe-partout avec double astérisque (**) (par exemple {**myparametername}) sans les barres obliques.During link generation, the routing system encodes the value captured in a double-asterisk (**) catch-all parameter (for example, {**myparametername}) except the forward slashes. Le passe-partout avec double astérisque est pris en charge avec le routage basé sur IRouter dans ASP.NET Core 2.2 ou ultérieur.The double-asterisk catch-all is supported with IRouter-based routing in ASP.NET Core 2.2 or later.

    La syntaxe de paramètre passe-partout avec un seul astérisque dans les versions antérieures d’ASP.NET Core ({*myparametername}) reste prise en charge, et les barres obliques sont encodées.The single asterisk catch-all parameter syntax in prior versions of ASP.NET Core ({*myparametername}) remains supported, and forward slashes are encoded.

    RouteRoute Lien généré avecLink generated with
    Url.Action(new { category = "admin/products" })
    /search/{*page} /search/admin%2Fproducts (la barre oblique est encodée)/search/admin%2Fproducts (the forward slash is encoded)
    /search/{**page} /search/admin/products

Exemple de middlewareMiddleware example

Dans l’exemple suivant, un middleware utilise l’API LinkGenerator pour créer un lien vers une méthode d’action qui liste les produits d’un magasin.In the following example, a middleware uses the LinkGenerator API to create link to an action method that lists store products. L’utilisation du générateur de liens en l’injectant dans une classe et en appelant GenerateLink est disponible pour n’importe quelle classe dans une application.Using the link generator by injecting it into a class and calling GenerateLink is available to any class in an app.

using Microsoft.AspNetCore.Routing;

public class ProductsLinkMiddleware
{
    private readonly LinkGenerator _linkGenerator;

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

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

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

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

La génération d’URL est le processus par lequel le routage peut créer un chemin d’URL basé sur un ensemble de valeurs de route.URL generation is the process by which routing can create a URL path based on a set of route values. Ceci permet une séparation logique entre les gestionnaires de routes et les URL qui y accèdent.This allows for a logical separation between route handlers and the URLs that access them.

La génération d’URL suit un processus itératif similaire, mais elle commence par un appel du code utilisateur ou de framework à la méthode GetVirtualPath de la collection de routes.URL generation follows a similar iterative process, but it starts with user or framework code calling into the GetVirtualPath method of the route collection. La méthode GetVirtualPath de chaque route est appelée en séquence jusqu’à ce qu’un VirtualPathData non null soit retourné.Each route has its GetVirtualPath method called in sequence until a non-null VirtualPathData is returned.

Les entrées principales dans GetVirtualPath sont les suivantes :The primary inputs to GetVirtualPath are:

Les routes utilisent principalement les valeurs de routage fournies par Values et par AmbientValues pour décider où il est possible de générer une URL et quelles sont les valeurs à inclure.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. Les AmbientValues sont l’ensemble des valeurs de route produites à partir de la mise en correspondance de la requête actuelle.The AmbientValues are the set of route values that were produced from matching the current request. En revanche, les Values sont les valeurs de route qui spécifient la façon de générer l’URL souhaitée pour l’opération actuelle.In contrast, Values are the route values that specify how to generate the desired URL for the current operation. HttpContext est fourni au cas où une route aurait besoin d’obtenir des services ou des données supplémentaires associés au contexte actuel.The HttpContext is provided in case a route should obtain services or additional data associated with the current context.

Conseil

Considérez VirtualPathContext.Values comme un ensemble de remplacements pour VirtualPathContext.AmbientValues.Think of VirtualPathContext.Values as a set of overrides for the VirtualPathContext.AmbientValues. La génération d’URL tente de réutiliser des valeurs de route de la requête actuelle afin de générer les URL pour des liens utilisant la même route ou les mêmes valeurs de route.URL generation attempts to reuse route values from the current request to generate URLs for links using the same route or route values.

La sortie de GetVirtualPath est un VirtualPathData.The output of GetVirtualPath is a VirtualPathData. VirtualPathData est l’équivalent de RouteData.VirtualPathData is a parallel of RouteData. VirtualPathData contient le VirtualPath de l’URL de sortie et des propriétés supplémentaires qui doivent être définies par la route.VirtualPathData contains the VirtualPath for the output URL and some additional properties that should be set by the route.

La propriété VirtualPathData.VirtualPath contient le chemin virtuel produit par la route.The VirtualPathData.VirtualPath property contains the virtual path produced by the route. Selon vos besoins, vous devrez peut-être traiter plus avant le chemin.Depending on your needs, you may need to process the path further. Si vous souhaitez afficher l’URL générée au format HTML, ajoutez un préfixe au chemin de base de l’application.If you want to render the generated URL in HTML, prepend the base path of the app.

VirtualPathData.Router est une référence à la route qui a généré avec succès l’URL.The VirtualPathData.Router is a reference to the route that successfully generated the URL.

La propriété VirtualPathData.DataTokens est un dictionnaire de données supplémentaires relatives à la route qui a généré l’URL.The VirtualPathData.DataTokens properties is a dictionary of additional data related to the route that generated the URL. Il s’agit de l’équivalent de RouteData.DataTokens.This is the parallel of RouteData.DataTokens.

Créer des routesCreate routes

Le routage fournit la classe Route comme implémentation standard d’IRouter.Routing provides the Route class as the standard implementation of IRouter. Route utilise la syntaxe des modèles de routage pour définir des modèles à mettre en correspondance avec le chemin d’URL quand RouteAsync est appelé.Route uses the route template syntax to define patterns to match against the URL path when RouteAsync is called. Route utilise le même modèle de routage pour générer une URL quand GetVirtualPath est appelé.Route uses the same route template to generate a URL when GetVirtualPath is called.

La plupart des applications créent des routes en appelant MapRoute ou l’une des méthodes d’extension similaires définies sur IRouteBuilder.Most apps create routes by calling MapRoute or one of the similar extension methods defined on IRouteBuilder. Toutes les méthodes d’extension de IRouteBuilder créent une instance de Route et l’ajoutent à la collection de routes.Any of the IRouteBuilder extension methods create an instance of Route and add it to the route collection.

MapRoute n’accepte pas de paramètre de gestionnaire de routage.MapRoute doesn't accept a route handler parameter. MapRoute ajoute uniquement des routes gérées par DefaultHandler.MapRoute only adds routes that are handled by the DefaultHandler. Pour plus d’informations sur le routage dans MVC, consultez Routage vers les actions du contrôleur dans ASP.NET Core.To learn more about routing in MVC, see Routage vers les actions du contrôleur dans ASP.NET Core.

MapRoute n’accepte pas de paramètre de gestionnaire de routage.MapRoute doesn't accept a route handler parameter. MapRoute ajoute uniquement des routes gérées par DefaultHandler.MapRoute only adds routes that are handled by the DefaultHandler. Le gestionnaire par défaut est un IRouter, et le gestionnaire est susceptible de ne pas traiter la requête.The default handler is an IRouter, and the handler might not handle the request. Par exemple, ASP.NET Core MVC est généralement configuré comme gestionnaire par défaut qui gère uniquement les requêtes correspondant à un contrôleur et une action 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. Pour plus d’informations sur le routage dans MVC, consultez Routage vers les actions du contrôleur dans ASP.NET Core.To learn more about routing in MVC, see Routage vers les actions du contrôleur dans ASP.NET Core.

L’exemple de code suivant est un exemple d’appel à MapRoute utilisé par une définition de route ASP.NET Core MVC classique :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?}");

Ce modèle établit une correspondance avec un chemin d’URL et extrait les valeurs de route .This template matches a URL path and extracts the route values. Par exemple, le chemin /Products/Details/17 génère les valeurs de route suivantes : { controller = Products, action = Details, id = 17 }.For example, the path /Products/Details/17 generates the following route values: { controller = Products, action = Details, id = 17 }.

Les valeurs de route sont déterminées en divisant le chemin d’URL en segments et en mettant en correspondance chaque segment avec le nom des paramètres de routage dans le modèle de routage.Route values are determined by splitting the URL path into segments and matching each segment with the route parameter name in the route template. Les paramètres de routage sont nommés.Route parameters are named. Vous définissez des paramètres en plaçant leur nom entre des accolades { ... }.The parameters defined by enclosing the parameter name in braces { ... }.

Le modèle précédent peut également mettre en correspondance le chemin d’URL / et produire les valeurs { controller = Home, action = Index }.The preceding template could also match the URL path / and produce the values { controller = Home, action = Index }. Cela s’explique par le fait que les paramètres de routage {controller} et {action} ont des valeurs par défaut et que le paramètre de routage id est facultatif.This occurs because the {controller} and {action} route parameters have default values and the id route parameter is optional. Un signe égal (=) suivi d’une valeur après le nom du paramètre de routage définit une valeur par défaut pour le paramètre.An equals sign (=) followed by a value after the route parameter name defines a default value for the parameter. Un point d’interrogation (?) après le nom du paramètre de routage définit un paramètre facultatif.A question mark (?) after the route parameter name defines an optional parameter.

Les paramètres de routage ayant une valeur par défaut produisent toujours une valeur de routage quand la route correspond.Route parameters with a default value always produce a route value when the route matches. Les paramètres facultatifs ne produisent pas de valeur de routage si aucun segment de chemin d’URL ne correspondait.Optional parameters don't produce a route value if there was no corresponding URL path segment. Pour obtenir une description complète des scénarios et de la syntaxe des modèles de routage, consultez la section Informations de référence sur les modèles de routage.See the Route template reference section for a thorough description of route template scenarios and syntax.

Dans l’exemple suivant, la définition du paramètre de route {id:int} définit une contrainte de route pour le paramètre de route 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}");

Ce modèle établit une correspondance avec un chemin d’URL comme /Products/Details/17, mais pas /Products/Details/Apples.This template matches a URL path like /Products/Details/17 but not /Products/Details/Apples. Les contraintes de routage implémentent IRouteConstraint et inspectent les valeurs de route pour les vérifier.Route constraints implement IRouteConstraint and inspect route values to verify them. Dans cet exemple, la valeur de route id doit être convertible en entier.In this example, the route value id must be convertible to an integer. Pour obtenir une explication des contraintes de route fournies par le framework, consultez Informations de référence sur les contraintes de route.See route-constraint-reference for an explanation of route constraints provided by the framework.

Des surcharges supplémentaires de MapRoute acceptent des values pour constraints, dataTokens et defaults.Additional overloads of MapRoute accept values for constraints, dataTokens, and defaults. L’utilisation classique de ces paramètres consiste à passer un objet typé anonymement, où les noms des propriétés du type anonyme correspondent aux noms de paramètre de routage.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.

Les exemples de MapRoute suivants créent des routes équivalentes :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?}");

Conseil

La syntaxe inline pour la définition des contraintes et des valeurs par défaut peut être pratique pour les routes simples.The inline syntax for defining constraints and defaults can be convenient for simple routes. Cependant, certains scénarios, comme les jetons de données, ne sont pas pris en charge par la syntaxe inline.However, there are scenarios, such as data tokens, that aren't supported by inline syntax.

L’exemple suivant montre quelques autres scénarios :The following example demonstrates a few additional scenarios:

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

Le modèle précédent établit une correspondance avec un chemin d’URL comme /Blog/All-About-Routing/Introduction et extrait les valeurs { 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 }. Les valeurs de route par défaut pour controller et action sont produites par la route, même s’il n’existe aucun paramètre de routage correspondant dans le modèle.The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. Il est possible de spécifier des valeurs par défaut dans le modèle de route.Default values can be specified in the route template. Le paramètre de route article est défini comme passe-partout par la présence d’un double astérisque (**) avant le nom du paramètre de route.The article route parameter is defined as a catch-all by the appearance of an double asterisk (**) before the route parameter name. Les paramètres de routage fourre-tout capturent le reste du chemin d’URL et peuvent également établir une correspondance avec la chaîne vide.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" });

Le modèle précédent établit une correspondance avec un chemin d’URL comme /Blog/All-About-Routing/Introduction et extrait les valeurs { 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 }. Les valeurs de route par défaut pour controller et action sont produites par la route, même s’il n’existe aucun paramètre de routage correspondant dans le modèle.The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. Il est possible de spécifier des valeurs par défaut dans le modèle de route.Default values can be specified in the route template. Le paramètre de route article est défini comme passe-partout par la présence d’un astérisque (*) avant le nom du paramètre de route.The article route parameter is defined as a catch-all by the appearance of an asterisk (*) before the route parameter name. Les paramètres de routage fourre-tout capturent le reste du chemin d’URL et peuvent également établir une correspondance avec la chaîne vide.Catch-all route parameters capture the remainder of the URL path and can also match the empty string.

L’exemple suivant ajoute des contraintes de route et des jetons de données :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" });

Le modèle précédent établit une correspondance avec un chemin d’URL comme /en-US/Products/5, et extrait les valeurs { controller = Products, action = Details, id = 5 } et les jetons de données { 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 }.

Jetons Windows de variables locales

Génération d’URL de classe de routeRoute class URL generation

La classe Route peut également effectuer une génération d’URL en combinant un ensemble de valeurs de route et son modèle de routage.The Route class can also perform URL generation by combining a set of route values with its route template. Il s’agit logiquement du processus inverse de la mise en correspondance du chemin d’URL.This is logically the reverse process of matching the URL path.

Conseil

Pour mieux comprendre la génération d’URL, imaginez l’URL que vous voulez générer, puis pensez à la façon dont un modèle de routage établirait une correspondance avec cette 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. Quelles valeurs seraient produites ?What values would be produced? Cela équivaut approximativement à la façon dont la génération d’URL fonctionne dans la classe Route.This is the rough equivalent of how URL generation works in the Route class.

L’exemple suivant utilise une route par défaut ASP.NET Core MVC générale :The following example uses a general ASP.NET Core MVC default route:

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

Avec les valeurs de route { controller = Products, action = List }, l’URL /Products/List est générée.With the route values { controller = Products, action = List }, the URL /Products/List is generated. Les valeurs de route remplacent les paramètres de routage correspondant pour former le chemin d’URL.The route values are substituted for the corresponding route parameters to form the URL path. Dans la mesure où id est un paramètre de route facultatif, l’URL est générée correctement sans valeur pour id.Since id is an optional route parameter, the URL is successfully generated without a value for id.

Avec les valeurs de route { controller = Home, action = Index }, l’URL / est générée.With the route values { controller = Home, action = Index }, the URL / is generated. Les valeurs de route fournies correspondent aux valeurs par défaut, et les segments correspondant aux valeurs par défaut peuvent être omis sans risque.The provided route values match the default values, and the segments corresponding to the default values are safely omitted.

Les deux URL générées effectuent un aller-retour avec la définition de route suivante (/Home/Index et /), et produisent les mêmes valeurs de route que celles utilisées pour générer l’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.

Notes

Pour générer des URL, une application utilisant ASP.NET Core MVC doit utiliser UrlHelper au lieu d’effectuer un appel directement dans le routage.An app using ASP.NET Core MVC should use UrlHelper to generate URLs instead of calling into routing directly.

Pour plus d’informations sur la génération d’URL, consultez la section Informations de référence sur la génération d’URL.For more information on URL generation, see the Url generation reference section.

Utilisation du middleware de routageUse Routing Middleware

Référencez le métapackage Microsoft.AspNetCore.App dans le fichier projet de l’application.Reference the Microsoft.AspNetCore.App metapackage in the app's project file.

Ajoutez le routage au conteneur de service dans Startup.ConfigureServices :Add routing to the service container in Startup.ConfigureServices:

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

Les routes doivent être configurées dans la méthode Startup.Configure.Routes must be configured in the Startup.Configure method. L’exemple d’application utilise les API suivantes :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);

Le tableau suivant montre les réponses avec les URI donnés.The following table shows the responses with the given URIs.

URIURI RéponseResponse
/package/create/3 Hello!Hello! Valeurs de route : [operation, create], [id, 3]Route values: [operation, create], [id, 3]
/package/track/-3 Hello!Hello! Valeurs de route : [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/-3/ Hello!Hello! Valeurs de route : [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/ La requête passe à travers ceci, aucune correspondance.The request falls through, no match.
GET /hello/Joe Hi, Joe!Hi, Joe!
POST /hello/Joe La requête passe à travers ceci, correspondance seulement avec HTTP GET.The request falls through, matches HTTP GET only.
GET /hello/Joe/Smith La requête passe à travers ceci, aucune correspondance.The request falls through, no match.

Si vous configurez une seule route, appelez UseRouter en passant une instance IRouter.If you're configuring a single route, call UseRouter passing in an IRouter instance. Vous n’avez pas besoin d’utiliser RouteBuilder.You won't need to use RouteBuilder.

Le framework fournit un ensemble de méthodes d’extension pour la création de routes (RequestDelegateRouteBuilderExtensions) :The framework provides a set of extension methods for creating routes (RequestDelegateRouteBuilderExtensions):

Certaines des méthodes listées, comme MapGet, nécessitent un RequestDelegate.Some of listed methods, such as MapGet, require a RequestDelegate. RequestDelegate est utilisé comme gestionnaire de routage quand une correspondance est trouvée pour la route.The RequestDelegate is used as the route handler when the route matches. D’autres méthodes de cette famille permettent de configurer un pipeline de middleware utilisé comme gestionnaire de routage.Other methods in this family allow configuring a middleware pipeline for use as the route handler. Si la méthode Map* n’accepte pas de gestionnaire, comme MapRoute, elle utilise le DefaultHandler.If the Map* method doesn't accept a handler, such as MapRoute, it uses the DefaultHandler.

Les méthodes Map[Verb] utilisent des contraintes pour limiter la route au verbe HTTP dans le nom de la méthode.The Map[Verb] methods use constraints to limit the route to the HTTP Verb in the method name. Par exemple, consultez MapGet et MapVerb.For example, see MapGet and MapVerb.

Informations de référence sur les modèles de routageRoute template reference

Les jetons placés entre accolades ({ ... }) définissent des paramètres de routage qui sont liés si une correspondance est trouvée pour la route.Tokens within curly braces ({ ... }) define route parameters that are bound if the route is matched. Vous pouvez définir plusieurs paramètres de routage dans un segment de route, mais ils doivent être séparés par une valeur littérale.You can define more than one route parameter in a route segment, but they must be separated by a literal value. Par exemple {controller=Home}{action=Index} n’est pas une route valide, car il n’y a aucune valeur littérale entre {controller} et {action}.For example, {controller=Home}{action=Index} isn't a valid route, since there's no literal value between {controller} and {action}. Ces paramètres de routage doivent avoir un nom, et ils autorisent la spécification d’attributs supplémentaires.These route parameters must have a name and may have additional attributes specified.

Un texte littéral autre que les paramètres de routage (par exemple, {id}) et le séparateur de chemin / doit correspondre au texte présent dans l’URL.Literal text other than route parameters (for example, {id}) and the path separator / must match the text in the URL. La correspondance de texte ne respecte pas la casse et est basée sur la représentation décodée du chemin des URL.Text matching is case-insensitive and based on the decoded representation of the URLs path. Pour mettre en correspondance un délimiteur de paramètre de route littéral ({ ou }), placez-le dans une séquence d’échappement en répétant le caractère ({{ ou }}).To match a literal route parameter delimiter ({ or }), escape the delimiter by repeating the character ({{ or }}).

Les modèles d’URL qui tentent de capturer un nom de fichier avec une extension de fichier facultative doivent faire l’objet de considérations supplémentaires.URL patterns that attempt to capture a file name with an optional file extension have additional considerations. Prenez par exemple le modèle files/{filename}.{ext?}.For example, consider the template files/{filename}.{ext?}. Quand des valeurs existent à la fois pour filename et pour ext, les deux valeurs sont renseignées.When values for both filename and ext exist, both values are populated. Si seule une valeur existe pour filename dans l’URL, une correspondance est trouvée pour la route, car le point final (.) est facultatif.If only a value for filename exists in the URL, the route matches because the trailing period (.) is optional. Les URL suivantes correspondent à cette route :The following URLs match this route:

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

Vous pouvez utiliser un astérisque (*) ou un double astérisque (**) comme préfixe d’un paramètre de route à lier au reste de l’URI.You can use an asterisk (*) or double asterisk (**) as a prefix to a route parameter to bind to the rest of the URI. Ils sont appelés des paramètres passe-partout.These are called a catch-all parameters. Par exemple, blog/{**slug} établit une correspondance avec n’importe quel URI commençant par /blog et suivi de n’importe quelle valeur, qui est affectée à la valeur de route 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. Les paramètres fourre-tout peuvent également établir une correspondance avec la chaîne vide.Catch-all parameters can also match the empty string.

Le paramètre fourre-tout place les caractères appropriés dans une séquence d’échappement lorsque la route est utilisée pour générer une URL, y compris les caractères de séparation de chemin (/).The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. Par exemple, la route foo/{*path} avec les valeurs de route { path = "my/path" } génère foo/my%2Fpath.For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. Notez la barre oblique d’échappement.Note the escaped forward slash. Pour les séparateurs de chemin aller-retour, utilisez le préfixe de paramètre de routage **.To round-trip path separator characters, use the ** route parameter prefix. La route foo/{**path} avec { path = "my/path" } génère foo/my/path.The route foo/{**path} with { path = "my/path" } generates foo/my/path.

Vous pouvez utiliser l’astérisque (*) comme préfixe d’un paramètre de route à lier au reste de l’URI.You can use the asterisk (*) as a prefix to a route parameter to bind to the rest of the URI. Cela s’appelle un paramètre fourre-tout.This is called a catch-all parameter. Par exemple, blog/{*slug} établit une correspondance avec n’importe quel URI commençant par /blog et suivi de n’importe quelle valeur, qui est affectée à la valeur de route 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. Les paramètres fourre-tout peuvent également établir une correspondance avec la chaîne vide.Catch-all parameters can also match the empty string.

Le paramètre fourre-tout place les caractères appropriés dans une séquence d’échappement lorsque la route est utilisée pour générer une URL, y compris les caractères de séparation de chemin (/).The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. Par exemple, la route foo/{*path} avec les valeurs de route { path = "my/path" } génère foo/my%2Fpath.For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. Notez la barre oblique d’échappement.Note the escaped forward slash.

Les paramètres de route peuvent avoir des valeurs par défaut, désignées en spécifiant la valeur par défaut après le nom du paramètre, séparée par un signe égal (=).Route parameters may have default values designated by specifying the default value after the parameter name separated by an equals sign (=). Par exemple, {controller=Home} définit Home comme valeur par défaut de controller.For example, {controller=Home} defines Home as the default value for controller. La valeur par défaut est utilisée si aucune valeur n’est présente dans l’URL pour le paramètre.The default value is used if no value is present in the URL for the parameter. Vous pouvez rendre facultatifs les paramètres de route en ajoutant un point d’interrogation (?) à la fin du nom du paramètre, comme dans id?.Route parameters are made optional by appending a question mark (?) to the end of the parameter name, as in id?. La différence entre les valeurs facultatives et les paramètres de route par défaut est qu’un paramètre de route ayant une valeur par défaut produit toujours une valeur, tandis qu’un paramètre facultatif a une valeur seulement quand celle-ci est fournie par l’URL de requête.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.

Les paramètres de route peuvent avoir des contraintes, qui doivent correspondre à la valeur de route liée à partir de l’URL.Route parameters may have constraints that must match the route value bound from the URL. L’ajout d’un signe deux-points (:) et d’un nom de contrainte après le nom du paramètre de routage spécifie une contrainte inline sur un paramètre de routage.Adding a colon (:) and constraint name after the route parameter name specifies an inline constraint on a route parameter. Si la contrainte nécessite des arguments, ils sont fournis entre parenthèses ((...)) après le nom de la contrainte.If the constraint requires arguments, they're enclosed in parentheses ((...)) after the constraint name. Il est possible de spécifier plusieurs contraintes inline en ajoutant un autre signe deux-points (:) et le nom d’une autre contrainte.Multiple inline constraints can be specified by appending another colon (:) and constraint name.

Le nom de la contrainte et les arguments sont passés au service IInlineConstraintResolver pour créer une instance de IRouteConstraint à utiliser dans le traitement des URL.The constraint name and arguments are passed to the IInlineConstraintResolver service to create an instance of IRouteConstraint to use in URL processing. Par exemple, le modèle de routage blog/{article:minlength(10)} spécifie une contrainte minlength avec l’argument 10.For example, the route template blog/{article:minlength(10)} specifies a minlength constraint with the argument 10. Pour plus d’informations sur les contraintes de route et pour obtenir la liste des contraintes fournies par le framework, consultez la section Informations de référence sur les contraintes de route.For more information on route constraints and a list of the constraints provided by the framework, see the Route constraint reference section.

Les paramètres de route peuvent également contenir des transformateurs de paramètre, qui transforment une valeur de paramètre lors de la génération des liens et de la mise en correspondance des actions et des pages avec les URL.Route parameters may also have parameter transformers, which transform a parameter's value when generating links and matching actions and pages to URLs. À l’instar des contraintes, les transformateurs de paramètre peuvent être ajoutés inline à un paramètre de routage en ajoutant un signe deux-points (:) et le nom du transformateur après le nom du paramètre de routage.Like constraints, parameter transformers can be added inline to a route parameter by adding a colon (:) and transformer name after the route parameter name. Par exemple, le modèle de routage blog/{article:slugify} spécifie un transformateur slugify.For example, the route template blog/{article:slugify} specifies a slugify transformer. Pour plus d’informations sur les transformateurs de paramètre, consultez la section Informations de référence sur les transformateurs de paramètre.For more information on parameter transformers, see the Parameter transformer reference section.

Le tableau suivant montre des exemples de modèles de route et leur comportement.The following table demonstrates example route templates and their behavior.

Modèle de routageRoute Template Exemple d’URI en correspondanceExample Matching URI URI de la requête…The request URI…
hello /hello Correspond seulement au chemin unique /hello.Only matches the single path /hello.
{Page=Home} / Correspond à Page et le définit sur Home.Matches and sets Page to Home.
{Page=Home} /Contact Correspond à Page et le définit sur Contact.Matches and sets Page to Contact.
{controller}/{action}/{id?} /Products/List Mappe au contrôleur Products et à l’action List.Maps to the Products controller and List action.
{controller}/{action}/{id?} /Products/Details/123 Mappe au contrôleur Products et à l’action Details (id défini sur 123).Maps to the Products controller and Details action (id set to 123).
{controller=Home}/{action=Index}/{id?} / Mappe au contrôleur Home et à la méthode Index (id est ignoré).Maps to the Home controller and Index method (id is ignored).

L’utilisation d’un modèle est généralement l’approche la plus simple pour le routage.Using a template is generally the simplest approach to routing. Il est également possible de spécifier des contraintes et des valeurs par défaut hors du modèle de routage.Constraints and defaults can also be specified outside the route template.

Conseil

Activez la journalisation pour voir comment les implémentations de routage intégrées, comme Route, établissent des correspondances avec les requêtes.Enable Logging to see how the built-in routing implementations, such as Route, match requests.

Noms de routage réservésReserved routing names

Les mots clés suivants sont des noms réservés qui ne peuvent pas être utilisés comme paramètres ou noms de routage :The following keywords are reserved names and can't be used as route names or parameters:

  • action
  • area
  • controller
  • handler
  • page

Informations de référence sur les contraintes de routageRoute constraint reference

Les contraintes de route s’exécutent quand une correspondance s’est produite pour l’URL entrante, et le chemin de l’URL est tokenisé en valeurs de route.Route constraints execute when a match has occurred to the incoming URL and the URL path is tokenized into route values. En général, les contraintes de routage inspectent la valeur de route associée par le biais du modèle de routage, et créent une décision oui/non indiquant si la valeur est, ou non, acceptable.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. Certaines contraintes de routage utilisent des données hors de la valeur de route pour déterminer si la requête peut être routée.Some route constraints use data outside the route value to consider whether the request can be routed. Par exemple, HttpMethodRouteConstraint peut accepter ou rejeter une requête en fonction de son verbe HTTP.For example, the HttpMethodRouteConstraint can accept or reject a request based on its HTTP verb. Les contraintes sont utilisées dans le routage des requêtes et la génération des liens.Constraints are used in routing requests and link generation.

Avertissement

N’utilisez pas de contraintes pour la validation des entrées.Don't use constraints for input validation. Si des contraintes sont utilisées pour la validation des entrées, une entrée non valide génère une réponse 404 - Introuvable au lieu d’une réponse 400 - Requête incorrecte avec un message d’erreur approprié.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. Les contraintes de route sont utilisées pour lever l’ambiguïté entre des routes similaires, et non pas pour valider les entrées d’une route particulière.Route constraints are used to disambiguate similar routes, not to validate the inputs for a particular route.

Le tableau suivant montre des exemples de contrainte de route et leur comportement attendu.The following table demonstrates example route constraints and their expected behavior.

contrainteconstraint ExempleExample Exemples de correspondancesExample Matches NotesNotes
int {id:int} 123456789, -123456789123456789, -123456789 Correspond à n’importe quel entierMatches any integer
bool {active:bool} true, FALSEtrue, FALSE Correspond à true ou à false (non-respect de la casse)Matches true or false (case-insensitive)
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm2016-12-31, 2016-12-31 7:32pm Correspond à une valeur DateTime valide (dans la culture invariante ; voir l’avertissement)Matches a valid DateTime value (in the invariant culture - see warning)
decimal {price:decimal} 49.99, -1,000.0149.99, -1,000.01 Correspond à une valeur decimal valide (dans la culture invariante ; voir l’avertissement)Matches a valid decimal value (in the invariant culture - see warning)
double {weight:double} 1.234, -1,001.01e81.234, -1,001.01e8 Correspond à une valeur double valide (dans la culture invariante ; voir l’avertissement)Matches a valid double value (in the invariant culture - see warning)
float {weight:float} 1.234, -1,001.01e81.234, -1,001.01e8 Correspond à une valeur float valide (dans la culture invariante ; voir l’avertissement)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} Correspond à une valeur Guid valideMatches a valid Guid value
long {ticks:long} 123456789, -123456789123456789, -123456789 Correspond à une valeur long valideMatches a valid long value
minlength(value) {username:minlength(4)} Rick La chaîne doit comporter au moins 4 caractèresString must be at least 4 characters
maxlength(value) {filename:maxlength(8)} Richard La chaîne ne doit pas comporter plus de 8 caractèresString must be no more than 8 characters
length(length) {filename:length(12)} somefile.txt La chaîne doit comporter exactement 12 caractèresString must be exactly 12 characters long
length(min,max) {filename:length(8,16)} somefile.txt La chaîne doit comporter au moins 8 caractères et pas plus de 16 caractèresString must be at least 8 and no more than 16 characters long
min(value) {age:min(18)} 19 La valeur entière doit être au moins égale à 18Integer value must be at least 18
max(value) {age:max(120)} 91 La valeur entière ne doit pas être supérieure à 120Integer value must be no more than 120
range(min,max) {age:range(18,120)} 91 La valeur entière doit être au moins égale à 18 mais ne doit pas être supérieure à 120Integer value must be at least 18 but no more than 120
alpha {name:alpha} Rick La chaîne doit se composer d’un ou de plusieurs caractères alphabétiques (a-z, non-respect de la casse)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 chaîne doit correspondre à l’expression régulière (voir les conseils relatifs à la définition d’une expression régulière)String must match the regular expression (see tips about defining a regular expression)
required {name:required} Rick Utilisé pour garantir qu’une valeur autre qu’un paramètre est présente pendant la génération de l’URLUsed to enforce that a non-parameter value is present during URL generation

Il est possible d’appliquer plusieurs contraintes séparées par un point-virgule à un même paramètre.Multiple, colon-delimited constraints can be applied to a single parameter. Par exemple, la contrainte suivante limite un paramètre à une valeur entière supérieure ou égale à 1 :For example, the following constraint restricts a parameter to an integer value of 1 or greater:

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

Avertissement

Les contraintes de routage qui vérifient que l’URL peut être convertie en type CLR (comme int ou DateTime) utilisent toujours la culture invariant.Route constraints that verify the URL and are converted to a CLR type (such as int or DateTime) always use the invariant culture. ces contraintes partent du principe que l’URL n’est pas localisable.These constraints assume that the URL is non-localizable. Les contraintes de routage fournies par le framework ne modifient pas les valeurs stockées dans les valeurs de route.The framework-provided route constraints don't modify the values stored in route values. Toutes les valeurs de route analysées à partir de l’URL sont stockées sous forme de chaînes.All route values parsed from the URL are stored as strings. Par exemple, la contrainte float tente de convertir la valeur de route en valeur float, mais la valeur convertie est utilisée uniquement pour vérifier qu’elle peut être convertie en valeur 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.

Expressions régulièresRegular expressions

Le framework ASP.NET Core ajoute RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant au constructeur d’expression régulière.The ASP.NET Core framework adds RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant to the regular expression constructor. Pour obtenir une description de ces membres, consultez RegexOptions.See RegexOptions for a description of these members.

Les expressions régulières utilisent les délimiteurs et des jetons semblables à ceux utilisés par le service de routage et le langage C#.Regular expressions use delimiters and tokens similar to those used by Routing and the C# language. Les jetons d’expression régulière doivent être placés dans une séquence d’échappement.Regular expression tokens must be escaped. Pour que l’expression régulière ^\d{3}-\d{2}-\d{4}$ puisse être utilisée dans le routage, il faut que les caractères \ (une seule barre oblique inverse) soit fournis dans la chaîne sous la forme \\ (double barre oblique inverse) dans le fichier source C#, pour placer en échappement le caractère d’échappement de chaîne \ (sauf en cas d’utilisation de littéraux de chaîne textuelle).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). Pour placer en échappement les caractères de délimiteur de paramètre de route ({, }, [, ]), doublez les caractères dans l’expression ({{, }, [[, ]]).To escape routing parameter delimiter characters ({, }, [, ]), double the characters in the expression ({{, }, [[, ]]). Le tableau suivant montre une expression régulière et la version placée en échappement.The following table shows a regular expression and the escaped version.

Expression régulièreRegular Expression Expression régulière en échappementEscaped Regular Expression
^\d{3}-\d{2}-\d{4}$ ^\\d{{3}}-\\d{{2}}-\\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$

Les expressions régulières utilisées dans le routage commencent souvent par un caret (^) et correspondent à la position de début de la chaîne.Regular expressions used in routing often start with the caret (^) character and match starting position of the string. Les expressions se terminent souvent par le signe dollar ($) de caractère et correspondent à la fin de la chaîne.The expressions often end with the dollar sign ($) character and match end of the string. Les caractères ^ et $ garantissent que l’expression régulière établit une correspondance avec la totalité de la valeur du paramètre de route.The ^ and $ characters ensure that the regular expression match the entire route parameter value. Sans les caractères ^ et $, l’expression régulière peut correspondre à n’importe quelle sous-chaîne dans la chaîne, ce qui est souvent indésirable.Without the ^ and $ characters, the regular expression match any substring within the string, which is often undesirable. Le tableau suivant contient des exemples et explique pourquoi ils établissent ou non une correspondance.The following table provides examples and explains why they match or fail to match.

ExpressionExpression ChaîneString Faire correspondre àMatch CommentaireComment
[a-z]{2} hellohello OuiYes Correspondances de sous-chaînesSubstring matches
[a-z]{2} 123abc456123abc456 OuiYes Correspondances de sous-chaînesSubstring matches
[a-z]{2} mzmz OuiYes Correspondance avec l’expressionMatches expression
[a-z]{2} MZMZ OuiYes Non-respect de la casseNot case sensitive
^[a-z]{2}$ hellohello NonNo Voir ^ et $ ci-dessusSee ^ and $ above
^[a-z]{2}$ 123abc456123abc456 NonNo Voir ^ et $ ci-dessusSee ^ and $ above

Pour plus d’informations sur la syntaxe des expressions régulières, consultez Expressions régulières du .NET Framework.For more information on regular expression syntax, see .NET Framework Regular Expressions.

Pour contraindre un paramètre à un ensemble connu de valeurs possibles, utilisez une expression régulière.To constrain a parameter to a known set of possible values, use a regular expression. Par exemple, {action:regex(^(list|get|create)$)} établit une correspondance avec la valeur de route action uniquement pour list, get ou create.For example, {action:regex(^(list|get|create)$)} only matches the action route value to list, get, or create. Si elle est passée dans le dictionnaire de contraintes, la chaîne ^(list|get|create)$ est équivalente.If passed into the constraints dictionary, the string ^(list|get|create)$ is equivalent. Les contraintes passées dans le dictionnaire de contraintes (c’est-à-dire qui ne sont pas inline dans un modèle) qui ne correspondent pas à l’une des contraintes connues sont également traitées comme des expressions régulières.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.

Contraintes d’itinéraire personnaliséCustom Route Constraints

Outre les contraintes d’itinéraire intégré, les contraintes d’itinéraire personnalisé peuvent être créées en implémentant l’interface IRouteConstraint.In addition to the built-in route constraints, custom route constraints can be created by implementing the IRouteConstraint interface. L’interface IRouteConstraint contient une méthode unique, Match, qui retourne true si la contrainte est satisfaite et false dans le cas contraire.The IRouteConstraint interface contains a single method, Match, which returns true if the constraint is satisfied and false otherwise.

Pour utiliser un IRouteConstraint personnalisé, le type de contrainte d’itinéraire doit être inscrit avec le ConstraintMap de l’application dans le conteneur de service de l’application.To use a custom IRouteConstraint, the route constraint type must be registered with the app's ConstraintMap in the app's service container. Un ConstraintMap est un dictionnaire qui mappe les clés de contrainte d’itinéraire aux implémentations IRouteConstraint qui valident ces contraintes.A ConstraintMap is a dictionary that maps route constraint keys to IRouteConstraint implementations that validate those constraints. Le ConstraintMap d’une application peut être mis à jour dans Startup.ConfigureServices dans le cadre d’un appel services.AddRouting ou en configurant RouteOptions directement avec services.Configure<RouteOptions>.An app's ConstraintMap can be updated in Startup.ConfigureServices either as part of a services.AddRouting call or by configuring RouteOptions directly with services.Configure<RouteOptions>. Par exemple :For example:

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

La contrainte peut ensuite être appliquée aux itinéraires de la manière habituelle, en utilisant le nom spécifié lors de l’inscription du type de contrainte.The constraint can then be applied to routes in the usual manner, using the name specified when registering the constraint type. Par exemple :For example:

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

Informations de référence sur le transformateur de paramètreParameter transformer reference

Transformateurs de paramètre :Parameter transformers:

  • Sont exécutés lors de la génération d’un lien pour un Route.Execute when generating a link for a Route.
  • Implémentez Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.Implement Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.
  • Sont configurés à l’aide de ConstraintMap.Are configured using ConstraintMap.
  • Prennent la valeur de routage du paramètre et la convertissent en une nouvelle valeur de chaîne.Take the parameter's route value and transform it to a new string value.
  • Aboutissent à l’utilisation de la valeur transformée dans le lien généré.Result in using the transformed value in the generated link.

Par exemple, un transformateur de paramètre slugify personnalisé dans le modèle d’itinéraire blog\{article:slugify} avec Url.Action(new { article = "MyTestArticle" }) génère 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.

Pour utiliser un transformateur de paramètre dans un modèle d’itinéraire, configurez-le d’abord en utilisant ConstraintMap dans Startup.ConfigureServices :To use a parameter transformer in a route pattern, configure it first using ConstraintMap in Startup.ConfigureServices:

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

Les transformateurs de paramètre sont utilisés par le framework pour transformer l’URI où un point de terminaison est résolu.Parameter transformers are used by the framework to transform the URI where an endpoint resolves. Par exemple, ASP.NET Core MVC utilise des transformateurs de paramètre pour convertir la valeur de routage utilisée et la faire correspondre à un area, controller, action et 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:slugify=Home}/{action:slugify=Index}/{id?}");

Avec la route précédente, l’action SubscriptionManagementController.GetAll() est mise en correspondance avec l’URI /subscription-management/get-all.With the preceding route, the action SubscriptionManagementController.GetAll() is matched with the URI /subscription-management/get-all. Un transformateur de paramètre ne modifie pas les valeurs de routage utilisées pour générer un lien.A parameter transformer doesn't change the route values used to generate a link. Par exemple, Url.Action("GetAll", "SubscriptionManagement") produit /subscription-management/get-all.For example, Url.Action("GetAll", "SubscriptionManagement") outputs /subscription-management/get-all.

ASP.NET Core fournit des conventions d’API pour l’utilisation des transformateurs de paramètre avec des routages générés :ASP.NET Core provides API conventions for using a parameter transformers with generated routes:

  • La convention de l’API Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention est fournie avec ASP.NET Core MVC.ASP.NET Core MVC has the Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention API convention. Cette convention applique un transformateur de paramètre spécifié à tous les routages d’attributs dans l’application.This convention applies a specified parameter transformer to all attribute routes in the app. Le transformateur de paramètre transforme les jetons de routage d’attribut quand ils sont remplacés.The parameter transformer transforms attribute route tokens as they are replaced. Pour plus d’informations, consultez Utiliser un transformateur de paramètre pour personnaliser le remplacement des jetons.For more information, see Use a parameter transformer to customize token replacement.
  • Razor Pages a la convention d’API Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention.Razor Pages has the Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention API convention. Cette convention applique un transformateur de paramètre spécifié à toutes les pages Razor découvertes automatiquement.This convention applies a specified parameter transformer to all automatically discovered Razor Pages. Le transformateur de paramètre transforme les segments du nom de dossier et du nom de fichier des routes Razor Pages.The parameter transformer transforms the folder and file name segments of Razor Pages routes. Pour plus d’informations, consultez Utiliser un transformateur de paramètre pour personnaliser les routages de pages.For more information, see Use a parameter transformer to customize page routes.

Informations de référence sur la génération d’URLURL generation reference

L’exemple suivant montre comment générer un lien vers une route selon un dictionnaire de valeurs de route et un RouteCollection données.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/>");
});

Le VirtualPath généré à la fin de l’exemple précédent est /package/create/123.The VirtualPath generated at the end of the preceding sample is /package/create/123. Le dictionnaire fournit les valeurs de route operation et id du modèle « Suivi de package de route », package/{operation}/{id}.The dictionary supplies the operation and id route values of the "Track Package Route" template, package/{operation}/{id}. Pour plus d’informations, consultez l’exemple de code dans la section Utilisation du middleware de routage ou l’exemple d’application.For details, see the sample code in the Use Routing Middleware section or the sample app.

Le deuxième paramètre pour le constructeur VirtualPathContext est une collection de valeurs ambiantes.The second parameter to the VirtualPathContext constructor is a collection of ambient values. Les valeurs ambiantes sont pratiques à utiliser, car elles limitent le nombre de valeurs qu’un développeur doit spécifier dans un contexte de requête.Ambient values are convenient to use because they limit the number of values a developer must specify within a request context. Les valeurs de route actuelles de la requête actuelle sont considérées comme des valeurs ambiantes pour la génération de liens.The current route values of the current request are considered ambient values for link generation. Dans l’action About de HomeController d’une application ASP.NET Core MVC, vous n’avez pas besoin de spécifier la valeur de route du contrôleur pour créer un lien vers l’action Index : la valeur ambiante de Home est utilisée.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.

Les valeurs ambiantes qui ne correspondent pas à un paramètre sont ignorées.Ambient values that don't match a parameter are ignored. Les valeurs ambiantes sont également ignorées quand une valeur explicitement fournie remplace la valeur ambiante.Ambient values are also ignored when an explicitly provided value overrides the ambient value. La mise en correspondance se produit de gauche à droite dans l’URL.Matching occurs from left to right in the URL.

Les valeurs fournies explicitement mais qui n’ont pas de correspondance avec un segment de la route sont ajoutées à la chaîne de requête.Values explicitly provided but that don't match a segment of the route are added to the query string. Le tableau suivant présente le résultat en cas d’utilisation du modèle de routage {controller}/{action}/{id?}.The following table shows the result when using the route template {controller}/{action}/{id?}.

Valeurs ambiantesAmbient Values Valeurs explicitesExplicit Values RésultatResult
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 une route a une valeur par défaut qui ne correspond pas à un paramètre et que cette valeur est explicitement fournie, elle doit correspondre à la valeur par défaut :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 génération de liens génère un lien pour cette route seulement quand les valeurs correspondantes pour controller et pour action sont fournies.Link generation only generates a link for this route when the matching values for controller and action are provided.

Segments complexesComplex segments

Les segments complexes (par exemple, [Route("/x{token}y")]) sont traités par la mise en correspondance des littéraux de droite à gauche de manière non gourmande.Complex segments (for example [Route("/x{token}y")]) are processed by matching up literals from right to left in a non-greedy way. Consultez ce code pour obtenir une explication détaillée de la façon dont les segments complexes sont mis en correspondance.See this code for a detailed explanation of how complex segments are matched. L’exemple de code n’est pas utilisé par ASP.NET Core, mais il fournit une bonne explication des segments complexes.The code sample is not used by ASP.NET Core, but it provides a good explanation of complex segments.