Routing in ASP.NET CoreRouting in ASP.NET Core

Di Ryan Nowak, Steve Smith e Rick AndersonBy Ryan Nowak, Steve Smith, and Rick Anderson

Per la versione 1.1 di questo argomento, scaricare Routing in ASP.NET Core (versione 1.1, PDF).For the 1.1 version of this topic, download Routing in ASP.NET Core (version 1.1, PDF).

Il routing è responsabile del mapping degli URI delle richieste ai selettori degli endpoint e dell'invio delle richieste agli endpoint.Routing is responsible for mapping request URIs to endpoint selectors and dispatching incoming requests to endpoints. Le route sono definite nell'app e vengono configurate all'avvio dell'app.Routes are defined in the app and configured when the app starts. Una route può facoltativamente estrarre valori dall'URL contenuto nella richiesta e questi valori possono quindi essere usati per l'elaborazione della richiesta.A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. Usando le informazioni sulla route dell'app, la funzionalità di routing è anche in grado di generare URL che eseguono il mapping ai selettori degli endpoint.Using route information from the app, routing is also able to generate URLs that map to endpoint selectors.

Per usare gli scenari di routing più recenti in ASP.NET Core 2.2, specificare la versione di compatibilità nella registrazione dei servizi MVC in 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'opzione EnableEndpointRouting determina se il routing deve usare internamente la logica basata sugli endpoint o la logica basata su IRouter di ASP.NET Core 2.1 o versioni precedenti.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. Quando la versione di compatibilità è impostata su 2.2 o versioni successive, il valore predefinito è true.When the compatibility version is set to 2.2 or later, the default value is true. Impostare il valore su false per usare la logica di routing precedente: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);

Per altre informazioni sul routing basato su IRouter, vedere la versione per ASP.NET Core 2.1 di questo argomento.For more information on IRouter-based routing, see the ASP.NET Core 2.1 version of this topic.

Il routing è responsabile del mapping degli URI delle richieste ai gestori di route e dell'invio delle richieste in ingresso.Routing is responsible for mapping request URIs to route handlers and dispatching an incoming requests. Le route sono definite nell'app e vengono configurate all'avvio dell'app.Routes are defined in the app and configured when the app starts. Una route può facoltativamente estrarre valori dall'URL contenuto nella richiesta e questi valori possono quindi essere usati per l'elaborazione della richiesta.A route can optionally extract values from the URL contained in the request, and these values can then be used for request processing. Con l'uso di route configurate dall'app, il routing è in grado di generare gli URL che eseguono il mapping ai gestori di route.Using configured routes from the app, routing is able to generate URLs that map to route handlers.

Per usare gli scenari di routing più recenti in ASP.NET Core 2.1, specificare la versione di compatibilità nella registrazione dei servizi MVC in Startup.ConfigureServices:To use the latest routing scenarios in ASP.NET Core 2.1, specify the compatibility version to the MVC services registration in Startup.ConfigureServices:

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

Importante

Questo documento descrive il routing di basso livello di ASP.NET Core.This document covers low-level ASP.NET Core routing. Per informazioni sul routing di ASP.NET Core MVC, vedere Routing ad azioni del controller in ASP.NET Core.For information on ASP.NET Core MVC routing, see Routing ad azioni del controller in ASP.NET Core. Per informazioni sulle convenzioni di routing in Razor Pages, vedere Convenzioni di route e app per Razor Pages in ASP.NET Core.For information on routing conventions in Razor Pages, see Convenzioni di route e app per Razor Pages in ASP.NET Core.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Nozioni fondamentali sul routingRouting basics

La maggior parte delle app dovrebbe scegliere uno schema di routing semplice e descrittivo in modo che gli URL siano leggibili e significativi.Most apps should choose a basic and descriptive routing scheme so that URLs are readable and meaningful. La route convenzionale predefinita {controller=Home}/{action=Index}/{id?}:The default conventional route {controller=Home}/{action=Index}/{id?}:

  • Supporta uno schema di routing semplice e descrittivo.Supports a basic and descriptive routing scheme.
  • È un punto iniziale utile per le app basate su interfaccia utente.Is a useful starting point for UI-based apps.

Gli sviluppatori solitamente aggiungono ulteriori route brevi nelle aree a traffico elevato dell'app in situazioni specifiche (ad esempio, endpoint di blog e e-commerce) usando il routing degli attributi o route convenzionali dedicate.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.

Le API Web devono usare il routing degli attributi per modellare le funzionalità dell'app come set di risorse in cui le operazioni sono rappresentate da verbi 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. Questo significa che molte operazioni (ad esempio, GET, POST) sulla stessa risorsa logica useranno lo stesso URL.This means that many operations (for example, GET, POST) on the same logical resource will use the same URL. Il routing degli attributi offre un livello di controllo necessario per progettare con attenzione il layout dell'endpoint pubblico di un'API.Attribute routing provides a level of control that's needed to carefully design an API's public endpoint layout.

Le app Razor Pages usano il routing convenzionale predefinito per servire le risorse denominate nella cartella Pagine dell'app.Razor Pages apps use default conventional routing to serve named resources in the Pages folder of an app. Sono disponibili convenzioni aggiuntive che consentono di personalizzare il comportamento di routing di Razor Pages.Additional conventions are available that allow you to customize Razor Pages routing behavior. Per altre informazioni, vedere Introduzione a Razor Pages in ASP.NET Core e Convenzioni di route e app per Razor Pages in ASP.NET Core.For more information, see Introduzione a Razor Pages in ASP.NET Core and Convenzioni di route e app per Razor Pages in ASP.NET Core.

Il supporto della generazione di URL consente di sviluppare l'app senza URL hardcoded per collegare l'app.URL generation support allows the app to be developed without hard-coding URLs to link the app together. Il supporto consente di iniziare con una configurazione di routing di base e di modificare le route dopo aver determinato il layout delle risorse dell'app.This support allows for starting with a basic routing configuration and modifying the routes after the app's resource layout is determined.

Il routing usa gli endpoint (Endpoint) per rappresentare gli endpoint logici in un'app.Routing uses endpoints (Endpoint) to represent logical endpoints in an app.

Un endpoint definisce un delegato per l'elaborazione delle richieste e una raccolta di metadati arbitrari.An endpoint defines a delegate to process requests and a collection of arbitrary metadata. I metadati vengono usati per implementare gli elementi trasversali in base ai criteri e la configurazione associata a ogni endpoint.The metadata is used implement cross-cutting concerns based on policies and configuration attached to each endpoint.

Il sistema di routing ha le caratteristiche seguenti:The routing system has the following characteristics:

  • La sintassi del modello di route viene usata per definire le route con parametri di route in formato token.Route template syntax is used to define routes with tokenized route parameters.

  • La configurazione degli endpoint basata su convenzioni e attributi è consentita.Conventional-style and attribute-style endpoint configuration is permitted.

  • IRouteConstraint consente di determinare se un parametro URL contiene un valore valido per il vincolo di un endpoint specifico.IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.

  • I modelli di app, ad esempio MVC o Razor Pages, registrano tutti i relativi endpoint, che hanno un'implementazione stimabile degli scenari di routing.App models, such as MVC/Razor Pages, register all of their endpoints, which have a predictable implementation of routing scenarios.

  • L'implementazione del routing determina le decisioni relative al routing nel punto desiderato della pipeline del middleware.The routing implementation makes routing decisions wherever desired in the middleware pipeline.

  • Il middleware successivo a un middleware di routing può esaminare il risultato della decisione dell'endpoint del middleware di routing per un URI di richiesta specifico.Middleware that appears after a Routing Middleware can inspect the result of the Routing Middleware's endpoint decision for a given request URI.

  • È possibile enumerare tutti gli endpoint nell'app in un punto qualsiasi della pipeline del middleware.It's possible to enumerate all of the endpoints in the app anywhere in the middleware pipeline.

  • Un'app può usare il routing per generare URL, ad esempio per il reindirizzamento o i collegamenti, in base alle informazioni degli endpoint. In questo modo si evita di impostare gli URL come hardcoded ottimizzando la manutenibilità.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 generazione degli URL è basata sugli indirizzi, che supportano l'estensibilità arbitraria:URL generation is based on addresses, which support arbitrary extensibility:

    • L'API del generatore di collegamenti (LinkGenerator) può essere risolta ovunque tramite l'inserimento delle dipendenze per generare gli URL.The Link Generator API (LinkGenerator) can be resolved anywhere using dependency injection (DI) to generate URLs.
    • Se l'API del generatore di collegamenti non è disponibile tramite l'inserimento delle dipendenze, IUrlHelper offre metodi per la generazione degli URL.Where the Link Generator API isn't available via DI, IUrlHelper offers methods to build URLs.

Nota

Con il rilascio del routing degli endpoint in ASP.NET Core 2.2, il collegamento degli endpoint è limitato alle azioni o alle pagine di MVC o 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. Le espansioni delle funzionalità di collegamento degli endpoint sono previste per le versioni future.The expansions of endpoint-linking capabilities is planned for future releases.

Il routing usa le route (implementazioni di IRouter) per:Routing uses routes (implementations of IRouter) to:

  • Eseguire il mapping di richieste in ingresso ai gestori di route.Map incoming requests to route handlers.
  • Generare gli URL usati nelle risposte.Generate the URLs used in responses.

Per impostazione predefinita, un'app ha una sola raccolta di route.By default, an app has a single collection of routes. Quando arriva una richiesta, le route della raccolta vengono elaborate nell'ordine in cui si trovano nella raccolta.When a request arrives, the routes in the collection are processed in the order that they exist in the collection. Il framework tenta di associare l'URL di una richiesta in ingresso a una route della raccolta chiamando il metodo RouteAsync in ogni route della raccolta.The framework attempts to match an incoming request URL to a route in the collection by calling the RouteAsync method on each route in the collection. Una risposta può usare il routing per generare gli URL, ad esempio per il reindirizzamento o i collegamenti, in base alle informazioni delle route. In questo modo si evita di impostare gli URL come hardcoded ottimizzando la manutenibilità.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.

Il sistema di routing ha le caratteristiche seguenti:The routing system has the following characteristics:

  • La sintassi del modello di route viene usata per definire le route con parametri di route in formato token.Route template syntax is used to define routes with tokenized route parameters.
  • La configurazione degli endpoint basata su convenzioni e attributi è consentita.Conventional-style and attribute-style endpoint configuration is permitted.
  • IRouteConstraint consente di determinare se un parametro URL contiene un valore valido per il vincolo di un endpoint specifico.IRouteConstraint is used to determine whether a URL parameter contains a valid value for a given endpoint constraint.
  • I modelli di app, ad esempio MVC o Razor Pages, registrano tutte le relative route, che hanno un'implementazione stimabile degli scenari di routing.App models, such as MVC/Razor Pages, register all of their routes, which have a predictable implementation of routing scenarios.
  • Una risposta può usare il routing per generare gli URL, ad esempio per il reindirizzamento o i collegamenti, in base alle informazioni delle route. In questo modo si evita di impostare gli URL come hardcoded ottimizzando la manutenibilità.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 generazione degli URL è basata sulle route, che supportano l'estensibilità arbitraria.URL generation is based on routes, which support arbitrary extensibility. IUrlHelper offre metodi per generare gli URL.IUrlHelper offers methods to build URLs.

Il routing è connesso alla pipeline middleware per mezzo della classe RouterMiddleware.Routing is connected to the middleware pipeline by the RouterMiddleware class. ASP.NET Core MVC aggiunge il routing alla pipeline del middleware come parte della configurazione e gestisce il routing nelle app MVC e 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. Per informazioni sull'uso del routing come componente autonomo, vedere la sezione Usare il middleware di routing.To learn how to use routing as a standalone component, see the Use Routing Middleware section.

Corrispondenza URLURL matching

La corrispondenza dell'URL è il processo con cui il routing invia una richiesta in ingresso a un endpoint.URL matching is the process by which routing dispatches an incoming request to an endpoint. Questo processo si basa sui dati presenti nel percorso URL, ma può essere esteso in modo da prendere in considerazione tutti i dati della richiesta.This process is based on data in the URL path but can be extended to consider any data in the request. La possibilità di inviare le richieste a gestori separati è fondamentale per ridurre le dimensioni e la complessità di un'app.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

Il sistema di routing nell'endpoint di routing è responsabile di tutte le decisioni relative all'invio.The routing system in endpoint routing is responsible for all dispatching decisions. Poiché il middleware applica i criteri in base all'endpoint selezionato, è importante che qualsiasi decisione che può influire sull'invio o l'applicazione dei criteri di sicurezza venga effettuata all'interno del sistema di routing.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.

Quando viene eseguito il delegato dell'endpoint, le proprietà di RouteContext.RouteData vengono impostate sui valori appropriati in base all'elaborazione della richiesta eseguita fino a quel punto.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 corrispondenza dell'URL è il processo con cui il routing invia una richiesta in ingresso a un gestore.URL matching is the process by which routing dispatches an incoming request to a handler. Questo processo si basa sui dati presenti nel percorso URL, ma può essere esteso in modo da prendere in considerazione tutti i dati della richiesta.This process is based on data in the URL path but can be extended to consider any data in the request. La possibilità di inviare le richieste a gestori separati è fondamentale per ridurre le dimensioni e la complessità di un'app.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an app.

Le richieste in ingresso immettono RouterMiddleware, che chiama il metodo RouteAsync per ogni route della sequenza.Incoming requests enter the RouterMiddleware, which calls the RouteAsync method on each route in sequence. L'istanza di IRouter sceglie se gestire la richiesta impostando RouteContext.Handler su un valore RequestDelegate non Null.The IRouter instance chooses whether to handle the request by setting the RouteContext.Handler to a non-null RequestDelegate. Se una route imposta un gestore per la richiesta, l'elaborazione della route si interrompe e viene richiamato il gestore per elaborare la richiesta.If a route sets a handler for the request, route processing stops, and the handler is invoked to process the request. Se non viene individuato alcun gestore di route per elaborare la richiesta, il middleware passa la richiesta al middleware successivo nella pipeline delle richieste.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'input principale per RouteAsync è l'elemento RouteContext.HttpContext associato alla richiesta corrente.The primary input to RouteAsync is the RouteContext.HttpContext associated with the current request. RouteContext.Handler e RouteContext.RouteData sono gli output che vengono impostati quando una route corrisponde.The RouteContext.Handler and RouteContext.RouteData are outputs set after a route is matched.

Una corrispondenza che chiama RouteAsync imposta anche le proprietà di RouteContext.RouteData sui valori appropriati in base all'elaborazione della richiesta eseguita fino a quel punto.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 è un dizionario di valori di route prodotti dalla route.RouteData.Values is a dictionary of route values produced from the route. Questi valori in genere sono determinati dalla suddivisione in token dell'URL e possono essere usati per accettare l'input dell'utente o per prendere ulteriori decisioni riguardo all'invio all'interno dell'app.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 è un elenco proprietà dei dati aggiuntivi correlati alla route corrispondente.RouteData.DataTokens is a property bag of additional data related to the matched route. Gli elementi DataTokens vengono forniti per supportare l'associazione dei dati sullo stato con ogni route in modo che l'app sia in grado di prendere decisioni in base alla route corrispondente.DataTokens are provided to support associating state data with each route so that the app can make decisions based on which route matched. Questi valori sono definiti dallo sviluppatore e non influiscono sul comportamento del routing in alcun modo.These values are developer-defined and do not affect the behavior of routing in any way. Inoltre, i valori accantonati in RouteData.DataTokens possono essere di qualsiasi tipo, a differenza dei valori RouteData.Values che devono essere convertibili in e da stringhe.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 è un elenco delle route che hanno preso parte alla corrispondenza corretta della richiesta.RouteData.Routers is a list of the routes that took part in successfully matching the request. Le route possono essere annidate l'una nell'altra.Routes can be nested inside of one another. La proprietà Routers rispecchia il percorso tramite l'albero logico di route che hanno prodotto una corrispondenza.The Routers property reflects the path through the logical tree of routes that resulted in a match. In genere il primo elemento in Routers è la raccolta di route e deve essere usato per la generazione di URL.Generally, the first item in Routers is the route collection and should be used for URL generation. L'ultimo elemento in Routers è il gestore di route corrispondente.The last item in Routers is the route handler that matched.

Generazione di URLURL generation

La generazione di URL è il processo con cui il routing crea un percorso URL basato su un set di valori di route.URL generation is the process by which routing can create a URL path based on a set of route values. Questo consente di avere una separazione logica tra gli endpoint e gli URL che vi accedono.This allows for a logical separation between your endpoints and the URLs that access them.

Il routing di endpoint include l'API del generatore di collegamenti (LinkGenerator).Endpoint routing includes the Link Generator API (LinkGenerator). LinkGenerator è un servizio singleton che può essere recuperato dall'inserimento delle dipendenze.LinkGenerator is a singleton service that can be retrieved from DI. L'API può essere usata all'esterno del contesto di una richiesta in esecuzione.The API can be used outside of the context of an executing request. IUrlHelper e gli scenari di MVC basati su IUrlHelper, ad esempio helper tag, helper HTML e risultati delle azioni, usano il generatore di collegamenti per offrire le funzionalità di generazione di collegamenti.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.

Il generatore di collegamenti si basa sui concetti di indirizzo e di schemi di indirizzi.The link generator is backed by the concept of an address and address schemes. Lo schema di indirizzi consente di determinare gli endpoint che devono essere considerati per la generazione dei collegamenti.An address scheme is a way of determining the endpoints that should be considered for link generation. Ad esempio, gli scenari di nome route e valori di route noti a numerosi utenti in MVC o Razor Pages vengono implementati come schema di indirizzi.For example, the route name and route values scenarios many users are familiar with from MVC/Razor Pages are implemented as an address scheme.

Il generatore di collegamenti può collegarsi alle azioni e alle pagine MVC o Razor Pages tramite i metodi di estensione seguenti:The link generator can link to MVC/Razor Pages actions and pages via the following extension methods:

Un overload di questi metodi accetta gli argomenti che includono HttpContext.An overload of these methods accepts arguments that include the HttpContext. Questi metodi sono funzionalmente equivalenti a Url.Action e Url.Page ma offrono una maggiore flessibilità e altre opzioni.These methods are functionally equivalent to Url.Action and Url.Page but offer additional flexibility and options.

I metodi GetPath* sono più simili a Url.Action e Url.Page poiché generano un URI che contiene un percorso assoluto.The GetPath* methods are most similar to Url.Action and Url.Page in that they generate a URI containing an absolute path. I metodi GetUri* generano sempre un URI assoluto contenente uno schema e un host.The GetUri* methods always generate an absolute URI containing a scheme and host. I metodi che accettano HttpContext generano un URI nel contesto della richiesta in esecuzione.The methods that accept an HttpContext generate a URI in the context of the executing request. Se non vengono sovrascritti, vengono usati i valori di route di ambiente, il percorso base dell'URL, lo schema e l'host dalla richiesta in esecuzione.The ambient route values, URL base path, scheme, and host from the executing request are used unless overridden.

LinkGenerator viene chiamato con un indirizzo.LinkGenerator is called with an address. La generazione di un URI viene eseguita in due passaggi:Generating a URI occurs in two steps:

  1. Un indirizzo viene associato a un elenco di endpoint che corrispondono all'indirizzo.An address is bound to a list of endpoints that match the address.
  2. RoutePattern di ogni endpoint viene valutato fino a quando non viene individuato un formato di route che corrisponde ai valori specificati.Each endpoint's RoutePattern is evaluated until a route pattern that matches the supplied values is found. L'output risultante viene unito alle altre parti dell'URI specificate nel generatore di collegamenti e restituito.The resulting output is combined with the other URI parts supplied to the link generator and returned.

I metodi forniti da LinkGenerator supportano le funzionalità di generazione di collegamenti standard per tutti i tipi di indirizzi.The methods provided by LinkGenerator support standard link generation capabilities for any type of address. È consigliabile usare il generatore di collegamenti tramite i metodi di estensione che eseguono le operazioni per un tipo di indirizzo specifico.The most convenient way to use the link generator is through extension methods that perform operations for a specific address type.

Metodo di estensioneExtension Method DescriptionDescription
GetPathByAddress Genera un URI con un percorso assoluto in base ai valori specificati.Generates a URI with an absolute path based on the provided values.
GetUriByAddress Genera un URI assoluto in base ai valori specificati.Generates an absolute URI based on the provided values.

Avviso

Prestare attenzione alle implicazioni seguenti della chiamata ai metodi LinkGenerator:Pay attention to the following implications of calling LinkGenerator methods:

  • Usare i metodi di estensione GetUri* con cautela in una configurazione di app che non convalida l'intestazione Host delle richieste in ingresso.Use GetUri* extension methods with caution in an app configuration that doesn't validate the Host header of incoming requests. Se l'intestazione Host delle richieste in ingresso non viene convalidata, l'input delle richieste non attendibili può essere inviato nuovamente al client negli URI di una visualizzazione o pagina.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. È consigliabile che in tutte le app di produzione il server sia configurato per la convalida dell'intestazione Host rispetto ai valori validi noti.We recommend that all production apps configure their server to validate the Host header against known valid values.

  • Usare LinkGenerator con cautela nel middleware in associazione a Map o MapWhen.Use LinkGenerator with caution in middleware in combination with Map or MapWhen. Map* modifica il percorso di base della richiesta in esecuzione, che ha effetto sull'output della generazione di collegamenti.Map* changes the base path of the executing request, which affects the output of link generation. Tutte le API LinkGenerator consentono di specificare un percorso di base.All of the LinkGenerator APIs allow specifying a base path. Specificare sempre un percorso di base vuoto per annullare l'effetto di Map* sulla generazione di collegamenti.Always specify an empty base path to undo Map*'s affect on link generation.

Differenze rispetto alle versioni precedenti del routingDifferences from earlier versions of routing

Tra il routing di endpoint in ASP.NET Core 2.2 o versioni successive e le versioni precedenti del routing in ASP.NET Core esistono alcune differenze:A few differences exist between endpoint routing in ASP.NET Core 2.2 or later and earlier versions of routing in ASP.NET Core:

  • Il sistema di routing di endpoint non supporta l'estensibilità basata su IRouter, inclusa l'eredità da Route.The endpoint routing system doesn't support IRouter-based extensibility, including inheriting from Route.

  • Il routing di endpoint non supporta WebApiCompatShim.Endpoint routing doesn't support WebApiCompatShim. Usare la versione di compatibilità 2.1 (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) per continuare a usare lo shim per la compatibilità.Use the 2.1 compatibility version (.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)) to continue using the compatibility shim.

  • Il routing di endpoint ha un comportamento diverso per l'utilizzo delle maiuscole e delle minuscole degli URI generati quando si usano le route convenzionali.Endpoint Routing has different behavior for the casing of generated URIs when using conventional routes.

    Esaminare il modello di route predefinito seguente:Consider the following default route template:

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

    Si supponga di generare un collegamento a un'azione usando la route seguente:Suppose you generate a link to an action using the following route:

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

    Con il routing basato su IRouter, questo codice genera un URI di /blog/ReadPost/17, che rispetta le maiuscole e le minuscole del valore di route specificato.With IRouter-based routing, this code generates a URI of /blog/ReadPost/17, which respects the casing of the provided route value. Il routing di endpoint in ASP.NET Core 2.2 o versioni successive produce /Blog/ReadPost/17 ("Blog" viene convertita in lettere maiuscole).Endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 ("Blog" is capitalized). Il routing di endpoint offre l'interfaccia IOutboundParameterTransformer che può essere usata per personalizzare questo comportamento globalmente o per applicare convenzioni diverse per il mapping degli URL.Endpoint routing provides the IOutboundParameterTransformer interface that can be used to customize this behavior globally or to apply different conventions for mapping URLs.

    Per altre informazioni, vedere la sezione Riferimento ai trasformatori di parametro.For more information, see the Parameter transformer reference section.

  • La generazione di collegamenti usata da MVC o Razor Pages con le route convenzionali ha un comportamento diverso quando si tenta il collegamento a un controller/azione o a una pagina non esistente.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.

    Esaminare il modello di route predefinito seguente:Consider the following default route template:

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

    Si supponga di generare un collegamento a un'azione usando il modello predefinito con il codice seguente:Suppose you generate a link to an action using the default template with the following:

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

    Con il routing basato su IRouter, il risultato è sempre /Blog/ReadPost/17, anche se BlogController non è presente o non ha un metodo di azione 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. Come previsto, il routing di endpoint in ASP.NET Core 2.2 o versioni successive produce /Blog/ReadPost/17 se è presente il metodo di azione.As expected, endpoint routing in ASP.NET Core 2.2 or later produces /Blog/ReadPost/17 if the action method exists. Tuttavia, il routing di endpoint produce una stringa vuota se l'azione non è presente.However, endpoint routing produces an empty string if the action doesn't exist. Concettualmente, il routing di endpoint non presume che l'endpoint sia presente se l'azione non è presente.Conceptually, endpoint routing doesn't assume that the endpoint exists if the action doesn't exist.

  • L'algoritmo di invalidamento dei valori di ambiente della generazione di collegamenti ha un comportamento diverso quando viene usato con il routing di endpoint.The link generation ambient value invalidation algorithm behaves differently when used with endpoint routing.

    L'invalidamento dei valori di ambiente è l'algoritmo che decide quali valori di route della richiesta in esecuzione (valori di ambiente) possono essere usati nelle operazioni di generazione di collegamenti.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. Il routing convenzionale ha sempre invalidato i valori di route aggiuntivi durante il collegamento a un'azione diversa.Conventional routing always invalidated extra route values when linking to a different action. Prima del rilascio di ASP.NET Core 2.2, il routing degli attributi non aveva questo comportamento.Attribute routing didn't have this behavior prior to the release of ASP.NET Core 2.2. Nelle versioni precedenti di ASP.NET Core i collegamenti a un'altra azione con gli stessi nomi di parametro di route causavano errori nella generazione dei collegamenti.In earlier versions of ASP.NET Core, links to another action that use the same route parameter names resulted in link generation errors. In ASP.NET Core 2.2 o versioni successive entrambi i tipi di routing invalidano i valori in caso di collegamento a un'altra azione.In ASP.NET Core 2.2 or later, both forms of routing invalidate values when linking to another action.

    Esaminare l'esempio seguente in ASP.NET Core 2.1 o versioni precedenti.Consider the following example in ASP.NET Core 2.1 or earlier. In caso di collegamento a un'altra azione o a un'altra pagina, i valori di route possono essere riutilizzati in modi indesiderati.When linking to another action (or another page), route values can be reused in undesirable ways.

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

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

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

    @page "{id?}"
    

    Se l'URI è /Store/Product/18 in ASP.NET Core 2.1 o versioni precedenti, il collegamento generato nella pagina Store/Info da @Url.Page("/Login") è /Login/18.If the URI is /Store/Product/18 in ASP.NET Core 2.1 or earlier, the link generated on the Store/Info page by @Url.Page("/Login") is /Login/18. Il valore id di 18 viene riutilizzato, anche se la destinazione del collegamento è una parte diversa dell'app.The id value of 18 is reused, even though the link destination is different part of the app entirely. Il valore di route id nel contesto della pagina /Login è probabilmente un valore di ID utente, non un valore di ID prodotto del punto vendita.The id route value in the context of the /Login page is probably a user ID value, not a store product ID value.

    Nel routing di endpoint con ASP.NET Core 2.2 o versioni successive, il risultato è /Login.In endpoint routing with ASP.NET Core 2.2 or later, the result is /Login. I valori di ambiente non vengono riutilizzati quando la destinazione collegata è costituita da un'azione o una pagina diversa.Ambient values aren't reused when the linked destination is a different action or page.

  • Sintassi dei parametri di route di round trip: le barre non vengono codificate quando viene usata una sintassi del parametro catch-all con doppio asterisco (**).Round-tripping route parameter syntax: Forward slashes aren't encoded when using a double-asterisk (**) catch-all parameter syntax.

    Durante la generazione di collegamenti, il sistema di routing codifica il valore acquisito in un parametro catch-all con doppio asterisco (**) (ad esempio, {**myparametername}) escludendo le barre.During link generation, the routing system encodes the value captured in a double-asterisk (**) catch-all parameter (for example, {**myparametername}) except the forward slashes. Il parametro catch-all con doppio asterisco è supportato con il routing basato su IRouter in ASP.NET Core 2.2 o versioni successive.The double-asterisk catch-all is supported with IRouter-based routing in ASP.NET Core 2.2 or later.

    La sintassi del parametro catch-all con asterisco singolo nelle versioni precedenti di ASP.NET Core ({*myparametername}) resta supportata e le barre vengono codificate.The single asterisk catch-all parameter syntax in prior versions of ASP.NET Core ({*myparametername}) remains supported, and forward slashes are encoded.

    RouteRoute Collegamento generato conLink generated with
    Url.Action(new { category = "admin/products" })
    /search/{*page} /search/admin%2Fproducts (la barra viene codificata)/search/admin%2Fproducts (the forward slash is encoded)
    /search/{**page} /search/admin/products

Esempio di middlewareMiddleware example

Nell'esempio seguente un middleware usa l'API LinkGenerator per creare il collegamento a un metodo di azione che elenca i prodotti del punto vendita.In the following example, a middleware uses the LinkGenerator API to create link to an action method that lists store products. L'uso del generatore di collegamenti tramite l'inserimento in una classe e la chiamata a GenerateLink è possibile in tutte le classi di un'app.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 generazione di URL è il processo con cui il routing crea un percorso URL basato su un set di valori di route.URL generation is the process by which routing can create a URL path based on a set of route values. Questo consente di avere una separazione logica tra i gestori di route e gli URL che vi accedono.This allows for a logical separation between route handlers and the URLs that access them.

La generazione di URL segue un processo iterativo simile, ma inizia con la chiamata del codice dell'utente o del framework nel metodo GetVirtualPath della raccolta di route.URL generation follows a similar iterative process, but it starts with user or framework code calling into the GetVirtualPath method of the route collection. Per ogni route viene chiamato in sequenza il metodo GetVirtualPath finché non viene restituito un valore VirtualPathData non Null.Each route has its GetVirtualPath method called in sequence until a non-null VirtualPathData is returned.

Gli input primari per GetVirtualPath sono:The primary inputs to GetVirtualPath are:

Le route usano principalmente i valori di route specificati da Values e AmbientValues per decidere se è possibile generare un URL e quali valori includere.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. Gli elementi AmbientValues sono il set di valori di route prodotti dalla corrispondenza della richiesta corrente.The AmbientValues are the set of route values that were produced from matching the current request. Al contrario, gli elementi Values sono i valori di route che specificano in che modo viene generato l'URL per l'operazione corrente.In contrast, Values are the route values that specify how to generate the desired URL for the current operation. HttpContext viene specificato nel caso in cui una route ottenga servizi o dati aggiuntivi associati al contesto corrente.The HttpContext is provided in case a route should obtain services or additional data associated with the current context.

Suggerimento

Considerare VirtualPathContext.Values come un set di override per VirtualPathContext.AmbientValues.Think of VirtualPathContext.Values as a set of overrides for the VirtualPathContext.AmbientValues. La generazione di URL prova a usare nuovamente i valori di route della richiesta corrente per generare URL per i collegamenti che usano la stessa route o gli stessi valori di route.URL generation attempts to reuse route values from the current request to generate URLs for links using the same route or route values.

L'output di GetVirtualPath è un oggetto VirtualPathData.The output of GetVirtualPath is a VirtualPathData. VirtualPathData è un elemento parallelo di RouteData.VirtualPathData is a parallel of RouteData. VirtualPathData contiene l'elemento VirtualPath per l'URL di output e alcune proprietà aggiuntive che devono essere impostate dalla route.VirtualPathData contains the VirtualPath for the output URL and some additional properties that should be set by the route.

La proprietà VirtualPathData.VirtualPath contiene il percorso virtuale prodotto dalla route.The VirtualPathData.VirtualPath property contains the virtual path produced by the route. In base alle esigenze specifiche, può essere necessario elaborare ulteriormente il percorso.Depending on your needs, you may need to process the path further. Se si vuole eseguire il rendering in HTML dell'URL generato, anteporre il percorso di base dell'app.If you want to render the generated URL in HTML, prepend the base path of the app.

VirtualPathData.Router è un riferimento alla route che ha generato correttamente l'URL.The VirtualPathData.Router is a reference to the route that successfully generated the URL.

VirtualPathData.DataTokens è un dizionario di dati aggiuntivi correlati alla route che ha generato l'URL.The VirtualPathData.DataTokens properties is a dictionary of additional data related to the route that generated the URL. È l'elemento parallelo di RouteData.DataTokens.This is the parallel of RouteData.DataTokens.

Creare le routeCreate routes

Il routing specifica la classe Route come implementazione standard di IRouter.Routing provides the Route class as the standard implementation of IRouter. Route usa la sintassi del modello di route per definire i criteri in base ai quali confrontare il percorso URL quando si chiama RouteAsync.Route uses the route template syntax to define patterns to match against the URL path when RouteAsync is called. Route usa lo stesso modello di route per generare un URL quando si chiama GetVirtualPath.Route uses the same route template to generate a URL when GetVirtualPath is called.

La maggior parte delle app crea le route chiamando MapRoute o uno dei metodi di estensione simili definiti per IRouteBuilder.Most apps create routes by calling MapRoute or one of the similar extension methods defined on IRouteBuilder. Tutti i metodi di estensione IRouteBuilder creano un'istanza di Route e la aggiungono alla raccolta di route.Any of the IRouteBuilder extension methods create an instance of Route and add it to the route collection.

MapRoute non accetta alcun parametro del gestore di route.MapRoute doesn't accept a route handler parameter. MapRoute aggiunge solo le route che sono gestite da DefaultHandler.MapRoute only adds routes that are handled by the DefaultHandler. Per altre informazioni sul routing in MVC, vedere Routing ad azioni del controller in ASP.NET Core.To learn more about routing in MVC, see Routing ad azioni del controller in ASP.NET Core.

MapRoute non accetta alcun parametro del gestore di route.MapRoute doesn't accept a route handler parameter. MapRoute aggiunge solo le route che sono gestite da DefaultHandler.MapRoute only adds routes that are handled by the DefaultHandler. Il gestore predefinito è IRouter e il gestore potrebbe non gestire la richiesta.The default handler is an IRouter, and the handler might not handle the request. Ad esempio, ASP.NET Core MVC viene in genere configurato come un gestore predefinito che gestisce solo le richieste che corrispondono a un'azione e un controller disponibili.For example, ASP.NET Core MVC is typically configured as a default handler that only handles requests that match an available controller and action. Per altre informazioni sul routing in MVC, vedere Routing ad azioni del controller in ASP.NET Core.To learn more about routing in MVC, see Routing ad azioni del controller in ASP.NET Core.

L'esempio di codice seguente si riferisce a una chiamata MapRoute usata da una tipica definizione di route di ASP.NET Core MVC:The following code example is an example of a MapRoute call used by a typical ASP.NET Core MVC route definition:

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

Questo modello confronta un percorso URL ed estrae i valori di route.This template matches a URL path and extracts the route values. Ad esempio, il percorso /Products/Details/17 genera i valori di route seguenti: { controller = Products, action = Details, id = 17 }.For example, the path /Products/Details/17 generates the following route values: { controller = Products, action = Details, id = 17 }.

I valori di route vengono determinati suddividendo il percorso URL in segmenti e confrontando ogni segmento con il nome del parametro di route nel modello di route.Route values are determined by splitting the URL path into segments and matching each segment with the route parameter name in the route template. I parametri di route sono denominati.Route parameters are named. Parametri definiti racchiudendo il nome del parametro tra parentesi graffe { ... }.The parameters defined by enclosing the parameter name in braces { ... }.

Il modello precedente può anche confrontare il percorso URL / e generare i valori { controller = Home, action = Index }.The preceding template could also match the URL path / and produce the values { controller = Home, action = Index }. Ciò accade perché i parametri di route {controller} e {action} hanno valori predefiniti e il parametro di route id è facoltativo.This occurs because the {controller} and {action} route parameters have default values and the id route parameter is optional. Un segno di uguale (=) seguito da un valore dopo il nome del parametro di route definisce un valore predefinito per il parametro.An equals sign (=) followed by a value after the route parameter name defines a default value for the parameter. Un punto interrogativo (?) dopo il nome del parametro di route definisce un parametro facoltativo.A question mark (?) after the route parameter name defines an optional parameter.

I parametri di route con un valore predefinito producono sempre un valore di route quando la route corrisponde.Route parameters with a default value always produce a route value when the route matches. I parametri facoltativi non producono alcun valore di route se non esiste un segmento di percorso URL corrispondente.Optional parameters don't produce a route value if there was no corresponding URL path segment. Vedere la sezione Riferimento per i modelli di route per una descrizione completa degli scenari e della sintassi del modello di route.See the Route template reference section for a thorough description of route template scenarios and syntax.

Nell'esempio seguente la definizione del parametro di route {id:int} definisce un vincolo di route per il parametro di 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}");

Questo modello confronta un percorso URL come /Products/Details/17, ma non /Products/Details/Apples.This template matches a URL path like /Products/Details/17 but not /Products/Details/Apples. I vincoli di route implementano IRouteConstraint ed esaminano i valori di route per verificarli.Route constraints implement IRouteConstraint and inspect route values to verify them. In questo esempio il valore di route id deve poter essere convertito in un numero intero.In this example, the route value id must be convertible to an integer. Vedere Riferimento per i vincoli di route per una descrizione dei vincoli di route specificati dal framework.See route-constraint-reference for an explanation of route constraints provided by the framework.

Altri overload di MapRoute accettano i valori per constraints, dataTokens e defaults.Additional overloads of MapRoute accept values for constraints, dataTokens, and defaults. L'uso tipico di questi parametri è passare un oggetto tipizzato in modo anonimo, in cui i nomi di proprietà di tipo anonimo corrispondono ai nomi dei parametri di route.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.

Gli esempi MapRoute seguenti creano route equivalenti: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?}");

Suggerimento

La sintassi inline per definire i vincoli e i valori predefiniti può essere utile per le route semplici.The inline syntax for defining constraints and defaults can be convenient for simple routes. Esistono tuttavia scenari, come i token di dati, che non sono supportati dalla sintassi inline.However, there are scenarios, such as data tokens, that aren't supported by inline syntax.

L'esempio seguente illustra alcuni scenari aggiuntivi:The following example demonstrates a few additional scenarios:

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

Il modello precedente confronta un percorso URL come /Blog/All-About-Routing/Introduction ed estrae i valori { 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 }. I valori di route predefiniti per controller e action vengono generati dalla route anche se sono non presenti parametri di route corrispondenti nel modello.The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. I valori predefiniti possono essere specificati nel modello di route.Default values can be specified in the route template. Il parametro di route article è definito come catch-all in base alla presenza di un doppio asterisco (**) prima del nome del parametro di route.The article route parameter is defined as a catch-all by the appearance of an double asterisk (**) before the route parameter name. I parametri di route catch-all acquisiscono il resto del percorso URL e possono anche corrispondere alla stringa vuota.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" });

Il modello precedente confronta un percorso URL come /Blog/All-About-Routing/Introduction ed estrae i valori { 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 }. I valori di route predefiniti per controller e action vengono generati dalla route anche se sono non presenti parametri di route corrispondenti nel modello.The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. I valori predefiniti possono essere specificati nel modello di route.Default values can be specified in the route template. Il parametro di route article è definito come catch-all in base alla presenza di un asterisco (*) prima del nome del parametro di route.The article route parameter is defined as a catch-all by the appearance of an asterisk (*) before the route parameter name. I parametri di route catch-all acquisiscono il resto del percorso URL e possono anche corrispondere alla stringa vuota.Catch-all route parameters capture the remainder of the URL path and can also match the empty string.

L'esempio seguente aggiunge i vincoli di route e i token di dati: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" });

Il modello precedente confronta un percorso URL come /en-US/Products/5 ed estrae i valori { controller = Products, action = Details, id = 5 } e i token di dati { 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 }.

Token della finestra Variabili locali

Generazione di URL della classe di routeRoute class URL generation

La classe Route è inoltre in grado di eseguire la generazione di URL combinando un set di valori di route con il relativo modello di route.The Route class can also perform URL generation by combining a set of route values with its route template. Questo è logicamente il processo inverso di corrispondenza del percorso URL.This is logically the reverse process of matching the URL path.

Suggerimento

Per comprendere meglio la generazione di URL, si pensi a quale URL si vuole generare e al modo in cui un modello di route deve corrispondere a tale 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. Quali valori devono essere prodotti?What values would be produced? Questo equivale approssimativamente al funzionamento della generazione di URL nella classe Route.This is the rough equivalent of how URL generation works in the Route class.

L'esempio seguente usa una route predefinita di ASP.NET Core MVC generale:The following example uses a general ASP.NET Core MVC default route:

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

Con i valori di route { controller = Products, action = List }, viene generato l'URL /Products/List.With the route values { controller = Products, action = List }, the URL /Products/List is generated. I valori di route vengono sostituiti dai parametri di route corrispondenti per formare il percorso URL.The route values are substituted for the corresponding route parameters to form the URL path. Poiché id è un parametro di route facoltativo, l'URL è stato generato senza un valore per id.Since id is an optional route parameter, the URL is successfully generated without a value for id.

Con i valori di route { controller = Home, action = Index }, viene generato l'URL /.With the route values { controller = Home, action = Index }, the URL / is generated. Poiché i valori di route specificati corrispondono ai valori predefiniti, i segmenti corrispondenti ai valori predefiniti possono essere omessi.The provided route values match the default values, and the segments corresponding to the default values are safely omitted.

Per entrambi gli URL generati viene eseguito il round trip con la definizione di route seguente (/Home/Index e /) e vengono prodotti gli stessi valori di route usati per generare 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.

Nota

Un'app che usa ASP.NET Core MVC deve usare UrlHelper per generare gli URL invece di eseguire la chiamata direttamente nel routing.An app using ASP.NET Core MVC should use UrlHelper to generate URLs instead of calling into routing directly.

Per altre informazioni sulla generazione di URL, vedere la sezione Riferimento per la generazione di URL.For more information on URL generation, see the Url generation reference section.

Usare il middleware di routingUse Routing Middleware

Fare riferimento al metapacchetto Microsoft.AspNetCore.App nel file di progetto dell'app.Reference the Microsoft.AspNetCore.App metapackage in the app's project file.

Aggiungere il routing al contenitore del servizio in Startup.ConfigureServices:Add routing to the service container in Startup.ConfigureServices:

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

Le route devono essere configurate nel metodo Startup.Configure.Routes must be configured in the Startup.Configure method. L'app di esempio usa le API seguenti: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);

Nella tabella seguente sono elencate le risposte con gli URI specificati.The following table shows the responses with the given URIs.

URIURI RispostaResponse
/package/create/3 Hello!Hello! Route values: [operation, create], [id, 3]Route values: [operation, create], [id, 3]
/package/track/-3 Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/-3/ Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/ La richiesta non viene eseguita, nessuna corrispondenza.The request falls through, no match.
GET /hello/Joe Hi, Joe!Hi, Joe!
POST /hello/Joe La richiesta non viene eseguita, corrispondenza solo con HTTP GET.The request falls through, matches HTTP GET only.
GET /hello/Joe/Smith La richiesta non viene eseguita, nessuna corrispondenza.The request falls through, no match.

Se si sta configurando una singola route, chiamare UseRouter passando un'istanza di IRouter.If you're configuring a single route, call UseRouter passing in an IRouter instance. Non è necessario usare RouteBuilder.You won't need to use RouteBuilder.

Il framework offre un set di metodi di estensione per la creazione di route (RequestDelegateRouteBuilderExtensions):The framework provides a set of extension methods for creating routes (RequestDelegateRouteBuilderExtensions):

Alcuni dei metodi elencati, ad esempio MapGet, richiedono RequestDelegate.Some of listed methods, such as MapGet, require a RequestDelegate. RequestDelegate viene usato come gestore di route quando la route corrisponde.The RequestDelegate is used as the route handler when the route matches. Altri metodi di questa famiglia consentono di configurare una pipeline middleware che verrà usata come gestore di route.Other methods in this family allow configuring a middleware pipeline for use as the route handler. Se il metodo Map* non accetta un gestore, ad esempio MapRoute, il metodo usa DefaultHandler.If the Map* method doesn't accept a handler, such as MapRoute, it uses the DefaultHandler.

I metodi Map[Verb] usano i vincoli per limitare la route al verbo HTTP nel nome del metodo.The Map[Verb] methods use constraints to limit the route to the HTTP Verb in the method name. Vedere ad esempio MapGet e MapVerb.For example, see MapGet and MapVerb.

Riferimento per il modello di routeRoute template reference

I token all'interno di parentesi graffe ({ ... }) definiscono i parametri di route che vengono associati se esiste una corrispondenza per la route.Tokens within curly braces ({ ... }) define route parameters that are bound if the route is matched. È possibile definire più parametri di route in un segmento di route, ma devono essere separati da un valore letterale.You can define more than one route parameter in a route segment, but they must be separated by a literal value. Ad esempio, {controller=Home}{action=Index} non è una route valida perché non è presente un valore letterale tra {controller} e {action}.For example, {controller=Home}{action=Index} isn't a valid route, since there's no literal value between {controller} and {action}. Questi parametri di route devono avere un nome e possono avere attributi aggiuntivi.These route parameters must have a name and may have additional attributes specified.

Il testo letterale diverso dai parametri di route, ad esempio {id}, e il separatore di percorso / devono corrispondere al testo nell'URL.Literal text other than route parameters (for example, {id}) and the path separator / must match the text in the URL. La corrispondenza del testo non fa distinzione tra maiuscole e minuscole e si basa sulla rappresentazione decodificata del percorso degli URL.Text matching is case-insensitive and based on the decoded representation of the URLs path. Per verificare la corrispondenza di un delimitatore letterale dei parametri di route ({ o }), eseguire l'escape del delimitatore ripetendo il carattere ({{ o }}).To match a literal route parameter delimiter ({ or }), escape the delimiter by repeating the character ({{ or }}).

I modelli di URL che tentano di acquisire un nome file con un'estensione facoltativa hanno considerazioni aggiuntive.URL patterns that attempt to capture a file name with an optional file extension have additional considerations. Considerare ad esempio il modello files/{filename}.{ext?}.For example, consider the template files/{filename}.{ext?}. Se esistono i valori per filename e ext, vengono popolati entrambi i valori.When values for both filename and ext exist, both values are populated. Se esiste solo un valore per filename nell'URL, la route corrisponde perché il punto finale (.) è facoltativo.If only a value for filename exists in the URL, the route matches because the trailing period (.) is optional. Gli URL seguenti corrispondono a questa route:The following URLs match this route:

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

È possibile usare un asterisco (*) o un doppio asterisco (**) come prefisso per un parametro di route da associare alla parte rimanente dell'URI.You can use an asterisk (*) or double asterisk (**) as a prefix to a route parameter to bind to the rest of the URI. Si tratta di parametri chiamati parametri catch-all.These are called a catch-all parameters. Ad esempio, blog/{**slug} corrisponde a qualsiasi URI che inizia con /blog seguito da qualsiasi valore, che viene assegnato al valore di 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. I parametri catch-all possono anche corrispondere alla stringa vuota.Catch-all parameters can also match the empty string.

Il parametro catch-all esegue l'escape dei caratteri appropriati, incluso il separatore di percorso (/), quando la route viene usata per generare un URL.The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. Ad esempio, la route foo/{*path} con i valori di route { path = "my/path" } genera foo/my%2Fpath.For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. Si noti la barra di escape.Note the escaped forward slash. Per eseguire il round trip dei caratteri di separatore di percorso, usare il prefisso del parametro di route **.To round-trip path separator characters, use the ** route parameter prefix. La route foo/{**path} con { path = "my/path" } genera foo/my/path.The route foo/{**path} with { path = "my/path" } generates foo/my/path.

È possibile usare l'asterisco (*) come prefisso per un parametro di route da associare alla parte rimanente dell'URI,You can use the asterisk (*) as a prefix to a route parameter to bind to the rest of the URI. ovvero un parametro catch-all.This is called a catch-all parameter. Ad esempio, blog/{*slug} corrisponde a qualsiasi URI che inizia con /blog seguito da qualsiasi valore, che viene assegnato al valore di 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. I parametri catch-all possono anche corrispondere alla stringa vuota.Catch-all parameters can also match the empty string.

Il parametro catch-all esegue l'escape dei caratteri appropriati, incluso il separatore di percorso (/), quando la route viene usata per generare un URL.The catch-all parameter escapes the appropriate characters when the route is used to generate a URL, including path separator (/) characters. Ad esempio, la route foo/{*path} con i valori di route { path = "my/path" } genera foo/my%2Fpath.For example, the route foo/{*path} with route values { path = "my/path" } generates foo/my%2Fpath. Si noti la barra di escape.Note the escaped forward slash.

I parametri di route possono avere valori predefiniti, definiti specificando il valore predefinito dopo il nome del parametro, separato da un segno di uguale (=).Route parameters may have default values designated by specifying the default value after the parameter name separated by an equals sign (=). Ad esempio, {controller=Home} definisce Home come valore predefinito per controller.For example, {controller=Home} defines Home as the default value for controller. Il valore predefinito viene usato se nell'URL non è presente alcun valore per il parametro.The default value is used if no value is present in the URL for the parameter. I parametri di route vengono resi facoltativi aggiungendo un punto interrogativo (?) alla fine del nome del parametro, come in id?.Route parameters are made optional by appending a question mark (?) to the end of the parameter name, as in id?. La differenza tra parametri facoltativi e parametri di route predefiniti è che un parametro di route con un valore predefinito produce sempre un valore, mentre un parametro facoltativo ha un valore solo se ne viene specificato uno dall'URL della richiesta.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.

I parametri di route possono presentare dei vincoli che devono corrispondere al valore di route associato dall'URL.Route parameters may have constraints that must match the route value bound from the URL. Aggiungendo due punti (:) e il nome del vincolo dopo il nome del parametro di route, si specifica un vincolo inline per un parametro di route.Adding a colon (:) and constraint name after the route parameter name specifies an inline constraint on a route parameter. Se il vincolo richiede argomenti, vengono racchiusi tra parentesi ((...)) dopo il nome del vincolo.If the constraint requires arguments, they're enclosed in parentheses ((...)) after the constraint name. È possibile specificare più vincoli inline aggiungendo di nuovo i due punti (:) e il nome del vincolo.Multiple inline constraints can be specified by appending another colon (:) and constraint name.

Il nome del vincolo e gli argomenti vengono passati al servizio IInlineConstraintResolver per creare un'istanza di IRouteConstraint da usare nell'elaborazione dell'URL.The constraint name and arguments are passed to the IInlineConstraintResolver service to create an instance of IRouteConstraint to use in URL processing. Il modello di route blog/{article:minlength(10)} specifica ad esempio un vincolo minlength con l'argomento 10.For example, the route template blog/{article:minlength(10)} specifies a minlength constraint with the argument 10. Per altre informazioni sui vincoli di route e per un elenco dei vincoli specificati dal framework, vedere la sezione Riferimento per i vincoli di route.For more information on route constraints and a list of the constraints provided by the framework, see the Route constraint reference section.

I parametri di route possono avere anche trasformatori di parametro che trasformano un valore di parametro durante la generazione dei collegamenti e l'abbinamento delle azioni e delle pagine agli URI.Route parameters may also have parameter transformers, which transform a parameter's value when generating links and matching actions and pages to URLs. Come i vincoli, i trasformatori di parametro possono essere aggiunti inline a un parametro di route inserendo due punti (:) e il nome del trasformatore dopo il nome del parametro di route.Like constraints, parameter transformers can be added inline to a route parameter by adding a colon (:) and transformer name after the route parameter name. Ad esempio, il modello di route blog/{article:slugify} specifica un trasformatore slugify.For example, the route template blog/{article:slugify} specifies a slugify transformer. Per altre informazioni sui trasformatori di parametro, vedere la sezione Riferimento ai trasformatori di parametro.For more information on parameter transformers, see the Parameter transformer reference section.

La tabella seguente illustra i modelli di route di esempio e il relativo comportamento.The following table demonstrates example route templates and their behavior.

Modello di routeRoute Template URI corrispondente di esempioExample Matching URI L'URI della richiesta…The request URI…
hello /hello Verifica la corrispondenza solo del singolo percorso /hello.Only matches the single path /hello.
{Page=Home} / Verifica la corrispondenza e imposta Page su Home.Matches and sets Page to Home.
{Page=Home} /Contact Verifica la corrispondenza e imposta Page su Contact.Matches and sets Page to Contact.
{controller}/{action}/{id?} /Products/List Esegue il mapping al controller Products e all'azione List.Maps to the Products controller and List action.
{controller}/{action}/{id?} /Products/Details/123 Esegue il mapping al controller Products e all'azione Details (id impostato su 123).Maps to the Products controller and Details action (id set to 123).
{controller=Home}/{action=Index}/{id?} / Esegue il mapping al controller Home e al metodo Index (id viene ignorato).Maps to the Home controller and Index method (id is ignored).

L'uso di un modello è in genere l'approccio più semplice al routing.Using a template is generally the simplest approach to routing. I vincoli e le impostazioni predefinite possono essere specificati anche all'esterno del modello di route.Constraints and defaults can also be specified outside the route template.

Suggerimento

Abilitare la registrazione per verificare in che modo le implementazioni del routing predefinite, ad esempio Route, corrispondono alle richieste.Enable Logging to see how the built-in routing implementations, such as Route, match requests.

Nomi riservati di routingReserved routing names

Le parole chiave seguenti sono nomi riservati e non possono essere usate come nomi o parametri di route:The following keywords are reserved names and can't be used as route names or parameters:

  • action
  • area
  • controller
  • handler
  • page

Riferimento per i vincoli di routeRoute constraint reference

I vincoli di route vengono eseguiti quando si verifica una corrispondenza nell'URL in ingresso e il percorso URL viene suddiviso in valori di route in formato token.Route constraints execute when a match has occurred to the incoming URL and the URL path is tokenized into route values. I vincoli di route in genere controllano il valore di route associato usando il modello di route e stabiliscono con una decisione Sì/No se il valore è accettabile o meno.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. Alcuni vincoli di route usano i dati all'esterno del valore di route per stabilire se la richiesta può essere instradata.Some route constraints use data outside the route value to consider whether the request can be routed. Ad esempio, HttpMethodRouteConstraint può accettare o rifiutare una richiesta in base al relativo verbo HTTP.For example, the HttpMethodRouteConstraint can accept or reject a request based on its HTTP verb. I vincoli vengono usati nelle richieste del routing e nella generazione di collegamenti.Constraints are used in routing requests and link generation.

Avviso

Non usare i vincoli per la convalida dell'input.Don't use constraints for input validation. Se vengono usati vincoli per la convalida dell'input, un input non valido causa la visualizzazione di un errore di tipo 404 (Non trovato) invece di un errore di tipo 400 - Richiesta non valida con un messaggio di errore appropriato.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. I vincoli di route vengono usati per evitare ambiguità tra route simili, non per convalidare gli input per una route specifica.Route constraints are used to disambiguate similar routes, not to validate the inputs for a particular route.

La tabella seguente illustra i vincoli di route di esempio e il relativo comportamento.The following table demonstrates example route constraints and their expected behavior.

vincoloconstraint EsempioExample Esempi di corrispondenzaExample Matches NoteNotes
int {id:int} 123456789, -123456789123456789, -123456789 Corrisponde a qualsiasi numero interoMatches any integer
bool {active:bool} true, FALSEtrue, FALSE Corrisponde a true o false (senza distinzione tra maiuscole e minuscole)Matches true or false (case-insensitive)
datetime {dob:datetime} 2016-12-31, 2016-12-31 7:32pm2016-12-31, 2016-12-31 7:32pm Corrisponde a un valore DateTime valido (impostazioni cultura inglese non dipendenti da paese/area geografica, vedere avviso)Matches a valid DateTime value (in the invariant culture - see warning)
decimal {price:decimal} 49.99, -1,000.0149.99, -1,000.01 Corrisponde a un valore decimal valido (impostazioni cultura inglese non dipendenti da paese/area geografica, vedere avviso)Matches a valid decimal value (in the invariant culture - see warning)
double {weight:double} 1.234, -1,001.01e81.234, -1,001.01e8 Corrisponde a un valore double valido (impostazioni cultura inglese non dipendenti da paese/area geografica, vedere avviso)Matches a valid double value (in the invariant culture - see warning)
float {weight:float} 1.234, -1,001.01e81.234, -1,001.01e8 Corrisponde a un valore float valido (impostazioni cultura inglese non dipendenti da paese/area geografica, vedere avviso)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} Corrisponde a un valore Guid validoMatches a valid Guid value
long {ticks:long} 123456789, -123456789123456789, -123456789 Corrisponde a un valore long validoMatches a valid long value
minlength(value) {username:minlength(4)} Rick La stringa deve contenere almeno 4 caratteriString must be at least 4 characters
maxlength(value) {filename:maxlength(8)} Richard La stringa non deve contenere più di 8 caratteriString must be no more than 8 characters
length(length) {filename:length(12)} somefile.txt La stringa deve contenere esattamente 12 caratteriString must be exactly 12 characters long
length(min,max) {filename:length(8,16)} somefile.txt La stringa deve contenere almeno 8 e non più di 16 caratteriString must be at least 8 and no more than 16 characters long
min(value) {age:min(18)} 19 Il valore intero deve essere almeno 18Integer value must be at least 18
max(value) {age:max(120)} 91 Il valore intero non deve essere superiore a 120Integer value must be no more than 120
range(min,max) {age:range(18,120)} 91 Il valore intero deve essere almeno 18 ma non più di 120Integer value must be at least 18 but no more than 120
alpha {name:alpha} Rick La stringa deve essere costituita da uno o più caratteri alfabetici (a-z, senza distinzione tra maiuscole e minuscole)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 stringa deve corrispondere all'espressione regolare (vedere i suggerimenti per la definizione di un'espressione regolare)String must match the regular expression (see tips about defining a regular expression)
required {name:required} Rick Usato per imporre che un valore diverso da un parametro sia presente durante la generazione dell'URLUsed to enforce that a non-parameter value is present during URL generation

Più vincoli delimitati da punti possono essere applicati a un singolo parametro.Multiple, colon-delimited constraints can be applied to a single parameter. Ad esempio il vincolo seguente limita un parametro a un valore intero maggiore o uguale a 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) { }

Avviso

I vincoli di route che verificano l'URL e vengono convertiti in un tipo CLR, ad esempio int o DateTime, usano sempre le impostazioni cultura inglese non dipendenti da paese/area geografica,Route constraints that verify the URL and are converted to a CLR type (such as int or DateTime) always use the invariant culture. presupponendo che l'URL sia non localizzabile.These constraints assume that the URL is non-localizable. I vincoli di route specificati dal framework non modificano i valori archiviati nei valori di route.The framework-provided route constraints don't modify the values stored in route values. Tutti i valori di route analizzati dall'URL vengono archiviati come stringhe.All route values parsed from the URL are stored as strings. Ad esempio, il vincolo float prova a convertire il valore di route in un valore float, ma il valore convertito viene usato solo per verificare che può essere convertito in un valore 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.

Espressioni regolariRegular expressions

Il framework di ASP.NET Core aggiunge RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant al costruttore di espressioni regolari.The ASP.NET Core framework adds RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.CultureInvariant to the regular expression constructor. Per una descrizione di questi membri, vedere RegexOptions.See RegexOptions for a description of these members.

Le espressioni regolari usano delimitatori e token simili a quelli usati dal routing e dal linguaggio C#.Regular expressions use delimiters and tokens similar to those used by Routing and the C# language. Per i token di espressione è necessario aggiungere caratteri di escape.Regular expression tokens must be escaped. Per usare l'espressione regolare ^\d{3}-\d{2}-\d{4}$ nel routing, l'espressione deve includere i caratteri \ (barra rovesciata singola) specificati nella stringa come caratteri \\ (barra rovesciata doppia) nel file di origine C# per eseguire l'escape del carattere di escape della stringa \, a meno che non si usino valori letterali di stringa verbatim.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). Per eseguire l'escape dii caratteri delimitatori dei parametri di routing ({, }, [, ]), raddoppiare i caratteri nell'espressione ({{, }, [[, ]]).To escape routing parameter delimiter characters ({, }, [, ]), double the characters in the expression ({{, }, [[, ]]). La tabella seguente mostra un'espressione regolare e la versione dopo l'escape.The following table shows a regular expression and the escaped version.

Espressione regolareRegular Expression Espressione regolare con caratteri di escapeEscaped Regular Expression
^\d{3}-\d{2}-\d{4}$ ^\\d{{3}}-\\d{{2}}-\\d{{4}}$
^[a-z]{2}$ ^[[a-z]]{{2}}$

Le espressioni regolari usate nel routing spesso iniziano con l'accento circonflesso (^) e corrispondono alla posizione iniziale della stringa.Regular expressions used in routing often start with the caret (^) character and match starting position of the string. Le espressioni spesso terminano con il segno di dollaro ($) e corrispondono alla fine della stringa.The expressions often end with the dollar sign ($) character and match end of the string. I caratteri ^ e $ consentono di verificare che l'espressione regolare corrisponda all'intero valore del parametro di route.The ^ and $ characters ensure that the regular expression match the entire route parameter value. Senza i caratteri ^ e $ l'espressione regolare corrisponde a qualsiasi sottostringa all'interno della stringa e spesso questo non è il risultato desiderato.Without the ^ and $ characters, the regular expression match any substring within the string, which is often undesirable. La tabella seguente include alcuni esempi e descrive perché si verifica o non si verifica la corrispondenza.The following table provides examples and explains why they match or fail to match.

EspressioneExpression StringaString Corrispondenza conMatch CommentoComment
[a-z]{2} hellohello Yes Corrispondenze di sottostringheSubstring matches
[a-z]{2} 123abc456123abc456 Yes Corrispondenze di sottostringheSubstring matches
[a-z]{2} mzmz Yes Corrisponde all'espressioneMatches expression
[a-z]{2} MZMZ Yes Senza distinzione maiuscole/minuscoleNot case sensitive
^[a-z]{2}$ hellohello NoNo Vedere ^ e $ sopraSee ^ and $ above
^[a-z]{2}$ 123abc456123abc456 NoNo Vedere ^ e $ sopraSee ^ and $ above

Per altre informazioni sulla sintassi delle espressioni regolari, vedere Espressioni regolari di .NET Framework.For more information on regular expression syntax, see .NET Framework Regular Expressions.

Per limitare un parametro a un set noto di valori possibili, usare un'espressione regolare.To constrain a parameter to a known set of possible values, use a regular expression. Ad esempio, {action:regex(^(list|get|create)$)} verifica la corrispondenza del valore di route action solo con list, get o create.For example, {action:regex(^(list|get|create)$)} only matches the action route value to list, get, or create. Se viene passata nel dizionario di vincoli, la stringa ^(list|get|create)$ è equivalente.If passed into the constraints dictionary, the string ^(list|get|create)$ is equivalent. Anche i vincoli passati nel dizionario di vincoli (non inline all'interno di un modello) che non corrispondono a uno dei vincoli noti vengono considerati espressioni regolari.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.

Vincoli di route personalizzatiCustom Route Constraints

Oltre ai vincoli di route predefiniti, è possibile creare vincoli di route personalizzati implementando l'interfaccia IRouteConstraint.In addition to the built-in route constraints, custom route constraints can be created by implementing the IRouteConstraint interface. L'interfaccia IRouteConstraint contiene un singolo metodo, Match, che restituisce true se il vincolo viene soddisfatto e false in caso contrario.The IRouteConstraint interface contains a single method, Match, which returns true if the constraint is satisfied and false otherwise.

Per usare un'interfaccia IRouteConstraint personalizzata, il tipo di vincolo di route deve essere registrato con la proprietà ConstraintMap dell'app nel contenitore di servizi dell'app.To use a custom IRouteConstraint, the route constraint type must be registered with the app's ConstraintMap in the app's service container. ConstraintMap è un dizionario che esegue il mapping delle chiavi dei vincoli di route alle implementazioni di IRouteConstraint che convalidano tali vincoli.A ConstraintMap is a dictionary that maps route constraint keys to IRouteConstraint implementations that validate those constraints. La proprietà ConstraintMap di un'app può essere aggiornata in Startup.ConfigureServices come parte di una chiamata services.AddRouting o configurando RouteOptions direttamente con 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>. Ad esempio:For example:

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

Il vincolo può quindi essere applicato alle route nel modo consueto, usando il nome specificato al momento della registrazione del tipo di vincolo.The constraint can then be applied to routes in the usual manner, using the name specified when registering the constraint type. Ad esempio:For example:

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

Riferimento ai trasformatori di parametroParameter transformer reference

I trasformatori di parametro:Parameter transformers:

  • Vengono eseguiti quando si genera un collegamento per Route.Execute when generating a link for a Route.
  • Implementare Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.Implement Microsoft.AspNetCore.Routing.IOutboundParameterTransformer.
  • Vengono configurati tramite ConstraintMap.Are configured using ConstraintMap.
  • Acquisire il valore della route del parametro e trasformarlo in un nuovo valore stringa.Take the parameter's route value and transform it to a new string value.
  • Il valore trasformato viene usato nel collegamento generato.Result in using the transformed value in the generated link.

Ad esempio, un trasformatore di parametro slugify personalizzato nel modello di route blog\{article:slugify} con Url.Action(new { article = "MyTestArticle" }) genera blog\my-test-article.For example, a custom slugify parameter transformer in route pattern blog\{article:slugify} with Url.Action(new { article = "MyTestArticle" }) generates blog\my-test-article.

Per usare un trasformatore di parametro in un modello di route, configurarlo prima usando ConstraintMap in 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);
});

I trasformatori di parametro sono usati dai framework per trasformare l'URI in cui viene risolto un endpoint.Parameter transformers are used by the framework to transform the URI where an endpoint resolves. Ad esempio, ASP.NET Core MVC usa i trasformatori di parametro per trasformare il valore di route usato per abbinare area, controller, action e 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?}");

Con la route precedente, l'azione SubscriptionManagementController.GetAll() viene abbinata all'URI /subscription-management/get-all.With the preceding route, the action SubscriptionManagementController.GetAll() is matched with the URI /subscription-management/get-all. Un trasformatore di parametro non modifica i valori della route usati per generare un collegamento.A parameter transformer doesn't change the route values used to generate a link. Ad esempio, Url.Action("GetAll", "SubscriptionManagement") restituisce /subscription-management/get-all.For example, Url.Action("GetAll", "SubscriptionManagement") outputs /subscription-management/get-all.

ASP.NET Core offre convenzioni API per l'uso di trasformatori di parametro con le route generate:ASP.NET Core provides API conventions for using a parameter transformers with generated routes:

  • ASP.NET Core MVC include la convenzione API Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention.ASP.NET Core MVC has the Microsoft.AspNetCore.Mvc.ApplicationModels.RouteTokenTransformerConvention API convention. Questa convenzione applica un trasformatore di parametro specifico a tutte le route di attributi nell'app.This convention applies a specified parameter transformer to all attribute routes in the app. Il trasformatore di parametro trasforma i token di route di attributi man mano che vengono sostituiti.The parameter transformer transforms attribute route tokens as they are replaced. Per altre informazioni vedere Use a parameter transformer to customize token replacement (Usare un trasformatore di parametro per personalizzare la sostituzione di token).For more information, see Use a parameter transformer to customize token replacement.
  • Razor Pages include la convenzione API Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention.Razor Pages has the Microsoft.AspNetCore.Mvc.ApplicationModels.PageRouteTransformerConvention API convention. Questa convenzione applica un trasformatore di parametro specificato a tutte le istanze di Razor Pages individuate automaticamente.This convention applies a specified parameter transformer to all automatically discovered Razor Pages. Il trasformatore di parametro trasforma la cartella e i segmenti di nome file delle route di Razor Pages.The parameter transformer transforms the folder and file name segments of Razor Pages routes. Per altre informazioni, vedere Use a parameter transformer to customize page routes (Usare un trasformatore di parametro per personalizzare route di pagine).For more information, see Use a parameter transformer to customize page routes.

Riferimento per la generazione di URLURL generation reference

L'esempio seguente mostra come generare un collegamento a una route usando un dizionario di valori di route e un elemento RouteCollection.The following example shows how to generate a link to a route given a dictionary of route values and a RouteCollection.

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

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

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

L'elemento VirtualPath generato alla fine dell'esempio precedente è /package/create/123.The VirtualPath generated at the end of the preceding sample is /package/create/123. Il dizionario fornisce i valori di route operation e id del modello "Track Package Route", package/{operation}/{id}.The dictionary supplies the operation and id route values of the "Track Package Route" template, package/{operation}/{id}. Per informazioni dettagliate, vedere il codice di esempio nella sezione Usare il middleware di routing oppure l'app di esempio.For details, see the sample code in the Use Routing Middleware section or the sample app.

Il secondo parametro per il costruttore VirtualPathContext è una raccolta di valori di ambiente.The second parameter to the VirtualPathContext constructor is a collection of ambient values. I valori di ambiente sono utili poiché limitano il numero di valori che uno sviluppatore deve specificare all'interno del contesto di una richiesta.Ambient values are convenient to use because they limit the number of values a developer must specify within a request context. I valori di route correnti della richiesta corrente sono considerati valori di ambiente per la generazione del collegamento.The current route values of the current request are considered ambient values for link generation. Nell'azione About di un'app ASP.NET Core MVC di HomeController, non è necessario specificare il valore di route del controller per collegarsi all'azione Index. Viene usato il valore di ambiente Home.In an ASP.NET Core MVC app's About action of the HomeController, you don't need to specify the controller route value to link to the Index action—the ambient value of Home is used.

I valori di ambiente che non corrispondono a un parametro vengono ignorati.Ambient values that don't match a parameter are ignored. I valori di ambiente vengono ignorati anche quando un valore specificato in modo esplicito esegue l'override del valore di ambiente.Ambient values are also ignored when an explicitly provided value overrides the ambient value. La corrispondenza si verifica da sinistra a destra nell'URL.Matching occurs from left to right in the URL.

I valori specificati in modo esplicito ma che non corrispondono a un segmento della route vengono aggiunti alla stringa di query.Values explicitly provided but that don't match a segment of the route are added to the query string. La tabella seguente illustra il risultato ottenuto quando si usa il modello di route {controller}/{action}/{id?}.The following table shows the result when using the route template {controller}/{action}/{id?}.

Valori di ambienteAmbient Values Valori esplicitiExplicit Values RisultatoResult
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

Se una route ha un valore predefinito che non corrisponde a un parametro e tale valore viene specificato in modo esplicito, deve corrispondere al valore predefinito: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 generazione dei collegamenti genera un collegamento per questa route quando vengono specificati i valori corrispondenti per controller e action.Link generation only generates a link for this route when the matching values for controller and action are provided.

Segmenti complessiComplex segments

I segmenti complessi (ad esempio, [Route("/x{token}y")]), vengono elaborati individuando corrispondenze per i valori letterali da destra a sinistra in modalità non-greedy.Complex segments (for example [Route("/x{token}y")]) are processed by matching up literals from right to left in a non-greedy way. Vedere questo codice per una spiegazione dettagliata di come vengono confrontati i segmenti complessi.See this code for a detailed explanation of how complex segments are matched. L'esempio di codice non viene usato da ASP.NET Core, ma offre una spiegazione esauriente dei segmenti complessi.The code sample is not used by ASP.NET Core, but it provides a good explanation of complex segments.