Routing in ASP.NET CoreRouting in ASP.NET Core

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

La funzionalità di routing è responsabile dell'esecuzione del mapping di una richiesta in ingresso a un gestore di route.Routing functionality is responsible for mapping an incoming request to a route handler. Le route sono definite nell'app ASP.NET e vengono configurate all'avvio dell'app.Routes are defined in the ASP.NET app and configured when the app starts up. 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 ASP.NET, la funzionalità di routing è anche in grado di generare URL che eseguono il mapping ai gestori di route.Using route information from the ASP.NET app, the routing functionality is also able to generate URLs that map to route handlers. Di conseguenza, il routing è in grado di trovare un gestore di route in base a un URL oppure l'URL corrispondente a un gestore di route specifico in base alle informazioni del gestore di route.Therefore, routing can find a route handler based on a URL, or the URL corresponding to a given route handler based on route handler information.

Importante

Questo documento descrive il routing di basso livello di ASP.NET Core.This document covers the low level ASP.NET Core routing. Per il routing di ASP.NET Core MVC, vedere Route ad azioni del controllerFor ASP.NET Core MVC routing, see Route to controller actions

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

Nozioni fondamentali sul routingRouting basics

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 routemap incoming requests to route handlers

  • generare gli URL usati nelle rispostegenerate URLs used in responses

In genere, un'app ha un'unica raccolta di route.Generally, an app has a single collection of routes. Quando arriva una richiesta, la raccolta di route viene elaborata in ordine.When a request arrives, the route collection is processed in order. La richiesta in ingresso cerca una route corrispondente all'URL di richiesta chiamando il metodo RouteAsync per ogni route disponibile nella raccolta di route.The incoming request looks for a route that matches the request URL by calling the RouteAsync method on each available route in the route collection. Al contrario, una risposta può usare il routing per generare URL, ad esempio per il reindirizzamento o i collegamenti, in base alle informazioni sulla route e in questo modo si evita di impostare gli URL come hardcoded ottimizzando la manutenibilità.By contrast, a response can use routing to generate URLs (for example, for redirection or links) based on route information, and thus avoid having to hard-code URLs, which helps maintainability.

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 middleware come parte della configurazione.ASP.NET Core MVC adds routing to the middleware pipeline as part of its configuration. Per informazioni sull'uso del routing come componente autonomo, vedere Uso del middleware di routing.To learn about using routing as a standalone component, see Using routing middleware.

Corrispondenza URLURL matching

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 in genere 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 generally 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'applicazione.The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an application.

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 diverso da 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 will be invoked to process the request. Se tutte le route vengono tentate e non viene trovato un gestore per la richiesta, il middleware chiama next e viene richiamato il middleware successivo nella pipeline di richieste.If all routes are tried and no handler is found for the request, the middleware calls next and the next middleware in the request pipeline is invoked.

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 verranno impostati quando una route corrisponde.The RouteContext.Handler and RouteContext.RouteData are outputs that will be set after a route matches.

Una corrispondenza durante RouteAsync imposta anche le proprietà di RouteContext.RouteData sui valori appropriati in base all'elaborazione della richiesta eseguita fino a questo punto.A match during RouteAsync will also set the properties of the RouteContext.RouteData to appropriate values based on the request processing done so far. Se una route corrisponde a una richiesta, RouteContext.RouteData conterrà informazioni importanti sullo stato relative al risultato.If a route matches a request, the RouteContext.RouteData will contain important state information about the result.

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'applicazione.These values are usually determined by tokenizing the URL, and can be used to accept user input, or to make further dispatching decisions inside the application.

RouteData.DataTokens è 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 sono disponibili per supportare l'associazione dei dati sullo stato con ogni route in modo che l'applicazione in un secondo tempo sia in grado di prendere decisioni in base alla route corrispondente.DataTokens are provided to support associating state data with each route so the application can make decisions later 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 nei token di dati possono essere di qualsiasi tipo, a differenza dei valori di route, che devono essere facilmente convertibili in e da stringhe.Additionally, values stashed in data tokens can be of any type, in contrast to route values, which must be easily convertible to and from strings.

RouteData.Routers è 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 e la proprietà Routers riflette il percorso attraverso l'albero logico di route che hanno prodotto una corrispondenza.Routes can be nested inside one another, and the Routers property reflects the path through the logical tree of routes that resulted in a match. 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 i gestori e gli URL che vi accedono.This allows for a logical separation between your 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 starts with user or framework code calling into the GetVirtualPath method of the route collection. Per ogni route il metodo GetVirtualPath verrà quindi chiamato in sequenza finché non viene restituito un valore VirtualPathData diverso da Null.Each route will then have 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:

  • VirtualPathContext.HttpContext

  • VirtualPathContext.Values

  • VirtualPathContext.AmbientValues

Le route usano principalmente i valori di route specificati da Values e AmbientValues per decidere dove è possibile generare un URL e quali valori includere.Routes primarily use the route values provided by the Values and AmbientValues to decide where it's possible to generate a URL and what values to include. Gli elementi AmbientValues sono il set di valori di route prodotti dalla corrispondenza della richiesta corrente con il sistema di routing.The AmbientValues are the set of route values that were produced from matching the current request with the routing system. 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 richieda la disponibilità di servizi o dati aggiuntivi associati al contesto corrente.The HttpContext is provided in case a route needs to get services or additional data associated with the current context.

Suggerimento: considerare Values come un set di override per AmbientValues.Tip: Think of Values as being a set of overrides for the AmbientValues. La generazione di URL tenta di usare nuovamente i valori di route della richiesta corrente per semplificare la generazione di URL per i collegamenti che usano la stessa route o gli stessi valori di route.URL generation tries to reuse route values from the current request to make it easy to generate URLs for links using the same route or route values.

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

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. Ad esempio, per eseguire il rendering in HTML dell'URL generato, è necessario anteporre il percorso di base dell'applicazione.For instance, if you want to render the generated URL in HTML you need to prepend the base path of the application.

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.

Creazione di routeCreating 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 dell'URL quando si chiama RouteAsync.Route uses the route template syntax to define patterns that will match against the URL path when RouteAsync is called. Route userà lo stesso modello di route per generare un URL quando si chiama GetVirtualPath.Route will use the same route template to generate a URL when GetVirtualPath is called.

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

Nota: MapRoute non accetta un parametro del gestore di route, aggiunge solo le route che verranno gestite da DefaultHandler.Note: MapRoute doesn't take a route handler parameter - it only adds routes that will be handled by the DefaultHandler. Poiché il gestore predefinito è un oggetto IRouter, può decidere di non gestire la richiesta.Since the default handler is an IRouter, it may decide not to handle the request. Ad esempio, ASP.NET 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 MVC is typically configured as a default handler that only handles requests that match an available controller and action. Per altre informazioni sul routing per MVC, vedere Route ad azioni del controller.To learn more about routing to MVC, see Route to controller actions.

Questo è un esempio di una chiamata MapRoute usata da una tipica definizione di route di ASP.NET MVC:This is an example of a MapRoute call used by a typical ASP.NET MVC route definition:

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

Questo modello confronta un percorso URL come /Products/Details/17 ed estrae i valori della route { controller = Products, action = Details, id = 17 }.This template will match a URL path like /Products/Details/17 and extract the route values { controller = Products, action = Details, id = 17 }. I valori della route vengono determinati suddividendo il percorso URL in segmenti e confrontando ogni segmento con il nome del parametro di route nel modello di route.The route values are determined by splitting the URL path into segments, and matching each segment with the route parameter name in the route template. I parametri di route sono denominati.Route parameters are named. Vengono definiti racchiudendo il nome del parametro tra parentesi graffe { }.They're defined by enclosing the parameter name in braces { }.

Il modello precedente può anche confrontare il percorso URL / generando i valori { controller = Home, action = Index }.The template above could also match the URL path / and would 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 happens 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 il parametro come facoltativo.A question mark ? after the route parameter name defines the parameter as optional. I parametri di route con un valore predefinito producono sempre un valore di route quando la route corrisponde. I parametri facoltativi non producono un valore di route, se non esiste un segmento di percorso URL corrispondente.Route parameters with a default value always produce a route value when the route matches - optional parameters won't produce a route value if there was no corresponding URL path segment.

Vedere Riferimento per i modelli di route per una descrizione completa delle funzionalità e della sintassi del modello di route.See route-template-reference for a thorough description of route template features and syntax.

Questo esempio include un vincolo di route:This example includes a route constraint:

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 will match a URL path like /Products/Details/17, but not /Products/Details/Apples. La definizione del parametro di route {id:int} definisce un vincolo di route per il parametro di route id.The route parameter definition {id:int} defines a route constraint for the id route parameter. 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 spiegazione più dettagliata dei vincoli di route specificati dal framework.See route-constraint-reference for a more detailed explanation of route constraints that are 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. Questi parametri aggiuntivi di MapRoute sono definiti come tipo object.These additional parameters of MapRoute are defined as type object. 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.

I due esempi seguenti creano route equivalenti:The following two examples create equivalent routes:

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

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

Suggerimento: la sintassi inline per definire i vincoli e i valori predefiniti può essere più utile per le route semplici.Tip: The inline syntax for defining constraints and defaults can be more convenient for simple routes. Tuttavia, esistono funzionalità, ad esempio i token di dati, che non sono supportate dalla sintassi inline.However, there are features such as data tokens which are not supported by inline syntax.

Questo esempio illustra alcune altre funzionalità:This example demonstrates a few more features:

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

Questo modello confronta un percorso URL come /Blog/All-About-Routing/Introduction ed estrae i valori { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction }.This template will match a URL path like /Blog/All-About-Routing/Introduction and will extract the values { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction }. 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 dall'aspetto 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.

In questo esempio vengono aggiunti i vincoli di route e i token di dati:This example adds route constraints and data tokens:

routes.MapRoute(
    name: "us_english_products",
    template: "en-US/Products/{id}",
    defaults: new { controller = "Products", action = "Details" },
    constraints: new { id = new IntRouteConstraint() },
    dataTokens: new { locale = "en-US" });

Questo modello 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 }.This template matches a URL path like /en-US/Products/5 and extracts the values { controller = Products, action = Details, id = 5 } and the data tokens { locale = en-US }.

Token della finestra Variabili locali

Generazione di URLURL 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.Tip: To better understand URL generation, imagine what URL you want to generate and then think about how a route template would match that URL. 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.

In questo esempio viene usata una route di base in stile ASP.NET MVC:This example uses a basic ASP.NET MVC style route:

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

Con i valori di route { controller = Products, action = List } questa route genera l'URL /Products/List.With the route values { controller = Products, action = List }, this route will generate the URL /Products/List. 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, non è un problema se non ha un valore.Since id is an optional route parameter, it's no problem that it doesn't have a value.

Con i valori di route { controller = Home, action = Index } questa route genera l'URL /.With the route values { controller = Home, action = Index }, this route will generate the URL /. I valori di specificati corrispondono ai valori predefiniti, quindi i segmenti corrispondenti a tali valori possono essere omessi.The route values that were provided match the default values so the segments corresponding to those values can be safely omitted. Si noti che per entrambi gli URL generati viene eseguito il round trip con questa definizione di route e vengono prodotti gli stessi valori di route usati per generare l'URL.Note that both URLs generated would round-trip with this route definition and produce the same route values that were used to generate the URL.

Suggerimento: un'app che usa ASP.NET MVC deve usare UrlHelper per generare gli URL anziché eseguire la chiamata direttamente nel routing.Tip: An app using ASP.NET MVC should use UrlHelper to generate URLs instead of calling into routing directly.

Per altre informazioni sul processo di generazione degli URL, vedere Riferimento per la generazione di URL.For more details about the URL generation process, see url-generation-reference.

Uso del middleware di routingUsing Routing Middleware

Aggiungere il pacchetto NuGet "Microsoft.AspNetCore.Routing".Add the NuGet package "Microsoft.AspNetCore.Routing".

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

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

Le route devono essere configurate nel metodo Configure della classe Startup.Routes must be configured in the Configure method in the Startup class. Nell'esempio seguente vengono usate queste API:The sample below uses these APIs:

  • RouteBuilder
  • Build
  • MapGet Confronta solo le richieste HTTP GETMapGet Matches only HTTP GET requests
  • UseRouter
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    var trackPackageRouteHandler = new RouteHandler(context =>
    {
        var routeValues = context.GetRouteData().Values;
        return context.Response.WriteAsync(
            $"Hello! Route values: {string.Join(", ", routeValues)}");
    });

    var routeBuilder = new RouteBuilder(app, trackPackageRouteHandler);

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

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

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

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

URIURI RispostaResponse
/package/create/3/package/create/3 Hello!Hello! Route values: [operation, create], [id, 3]Route values: [operation, create], [id, 3]
/package/track/-3/package/track/-3 Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track/-3//package/track/-3/ Hello!Hello! Route values: [operation, track], [id, -3]Route values: [operation, track], [id, -3]
/package/track//package/track/ <Passaggio, nessuna corrispondenza><Fall through, no match>
GET /hello/JoeGET /hello/Joe Hi, Joe!Hi, Joe!
POST /hello/JoePOST /hello/Joe <Passaggio, corrispondenza solo con HTTP GET><Fall through, matches HTTP GET only>
GET /hello/Joe/SmithGET /hello/Joe/Smith <Passaggio, nessuna corrispondenza><Fall through, no match>

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

Il framework offre un set di metodi di estensione per la creazione di route, ad esempio:The framework provides a set of extension methods for creating routes such as:

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

Alcuni di questi metodi, ad esempio MapGet, richiedono che sia specificato un oggetto RequestDelegate.Some of these methods such as MapGet require a RequestDelegate to be provided. RequestDelegate verrà usato come gestore di route quando la route corrisponde.The RequestDelegate will be 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 which will be used as the route handler. Se il metodo Map metodo non accetta un gestore, ad esempio MapRoute, userà DefaultHandler.If the Map method doesn't accept a handler, such as MapRoute, then it will use 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. Ad esempio, vedere 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 verranno associati se esiste una corrispondenza per la route.Tokens within curly braces ({ }) define route parameters which will be 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, poiché non è presente un valore letterale tra {controller} e {action}.For example {controller=Home}{action=Index} wouldn't be 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 del delimitatore letterale dei parametri di route { o }, eseguirne l'escape ripetendo il carattere ({{ o }}).To match the literal route parameter delimiter { or }, escape it by repeating the character ({{ or }}).

I modelli di URL che tentano di acquisire un nome file con un'estensione facoltativa usano considerazioni aggiuntive.URL patterns that attempt to capture a filename with an optional file extension have additional considerations. Ad esempio, se si usa il modello files/{filename}.{ext?} quando esistono sia filename che ext, verranno popolati entrambi i valori.For example, using the template files/{filename}.{ext?} - When both filename and ext exist, both values will be populated. Se esiste solo filename nell'URL, la route corrisponde perché il punto finale . è facoltativo.If only filename exists in the URL, the route matches because the trailing period . is optional. I seguenti URL corrispondono a questa route:The following URLs would match this route:

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

È possibile usare il carattere * come prefisso per un parametro di route da associare al resto dell'URI, ovvero un parametro catch-all.You can use the * character as a prefix to a route parameter to bind to the rest of the URI - this is called a catch-all parameter. Ad esempio, blog/{*slug} corrisponde a qualsiasi URI che inizia con /blog seguito da qualsiasi valore (che verrebbe assegnato al valore di route slug).For example, blog/{*slug} would match any URI that started with /blog and had any value following it (which would be assigned to the slug route value). I parametri catch-all possono anche corrispondere alla stringa vuota.Catch-all parameters can also match the empty string.

I parametri di route possono avere valori predefiniti, definiti specificando il valore predefinito dopo il nome del parametro, separato da un segno =.Route parameters may have default values, designated by specifying the default after the parameter name, separated by an =. Ad esempio, {controller=Home} definisce Home come valore predefinito per controller.For example, {controller=Home} would define 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. Oltre ai valori predefiniti, i parametri di route possono essere facoltativi, specificati aggiungendo ? alla fine del nome del parametro, come in id?.In addition to default values, route parameters may be optional (specified by appending a ? to the end of the parameter name, as in id?). La differenza tra parametri facoltativi e parametri "con valori 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.The difference between optional and "has default" is that a route parameter with a default value always produces a value; an optional parameter has a value only when one is provided.

I parametri di route possono anche presentare dei vincoli, che devono corrispondere al valore di route associato dall'URL.Route parameters may also have constraints, which 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 specificati tra parentesi ( ) dopo il nome del vincolo.If the constraint requires arguments those are provided 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 viene passato al servizio IInlineConstraintResolver per creare un'istanza di IRouteConstraint da usare nell'elaborazione dell'URL.The constraint name is passed to the IInlineConstraintResolver service to create an instance of IRouteConstraint to use in URL processing. Ad esempio, il modello di route blog/{article:minlength(10)} specifica il vincolo minlength con l'argomento 10.For example, the route template blog/{article:minlength(10)} specifies the minlength constraint with the argument 10. Per altre descrizioni dei vincoli di route e un elenco dei vincoli specificati dal framework, vedere Riferimento per i vincoli di route.For more description route constraints, and a listing of the constraints provided by the framework, see route-constraint-reference.

La tabella seguente illustra alcuni modelli di route con il relativo comportamento.The following table demonstrates some route templates and their behavior.

Modello di routeRoute Template Esempio di URL corrispondenteExample Matching URL NoteNotes
hellohello /hello/hello Verifica la corrispondenza solo del singolo percorso /helloOnly matches the single path /hello
{Page=Home}{Page=Home} / Verifica la corrispondenza e imposta Page su HomeMatches and sets Page to Home
{Page=Home}{Page=Home} /Contact/Contact Verifica la corrispondenza e imposta Page su ContactMatches and sets Page to Contact
{controller}/{action}/{id?}{controller}/{action}/{id?} /Products/List/Products/List Esegue il mapping al controller Products e all'azione ListMaps to Products controller and List action
{controller}/{action}/{id?}{controller}/{action}/{id?} /Products/Details/123/Products/Details/123 Esegue il mapping al controller Products e all'azione Details.Maps to Products controller and Details action. id impostato su 123id set to 123
{controller=Home}/{action=Index}/{id?}{controller=Home}/{action=Index}/{id?} / Esegue il mapping al controller Home e al metodo Index; id viene ignorato.Maps to 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 vedere in che modo le implementazioni del routing, ad esempio Route, corrispondono alle richieste.Tip: 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 una Route corrisponde alla sintassi dell'URL in ingresso e suddivide il percorso URL in valori di route in formato token.Route constraints execute when a Route has matched the syntax of the incoming URL and tokenized the URL path into route values. I vincoli di route in genere controllano il valore di route associato usando il modello di route e stabiliscono con una semplice decisione sì/no se il valore è o non è accettabile.Route constraints generally inspect the route value associated via the route template and make a simple yes/no decision about whether or not the value is acceptable. 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.

Avviso

Evitare l'uso di vincoli per la convalida dell'input, poiché un input non valido genera un errore 404 (Non trovato) anziché 400 con messaggio di errore appropriato.Avoid using constraints for input validation, because doing so means that invalid input will result in a 404 (Not Found) instead of a 400 with an appropriate error message. I vincoli di route devono essere usati per evitare ambiguità tra route simili, non per convalidare gli input per una route specifica.Route constraints should be used to disambiguate between similar routes, not to validate the inputs for a particular route.

La tabella seguente illustra alcuni vincoli di route con il relativo comportamento.The following table demonstrates some 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 possono essere convertiti in un tipo CLR, ad esempio int o DateTime, usano sempre le impostazioni cultura inglese non dipendenti da paese/area geografica, presupponendo che l'URL sia non localizzabile.Route constraints that verify the URL can be converted to a CLR type (such as int or DateTime) always use the invariant culture - they assume the URL is non-localizable. 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 will be stored as strings. Ad esempio, il vincolo di route Float tenterà di 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 route constraint will attempt to convert the route value to a float, but the converted value is used only to verify it can be converted to a float.

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. Vedere l'articolo sull'enumerazione RegexOptions per una descrizione di questi membri.See RegexOptions Enumeration 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. Ad esempio, per usare l'espressione regolare ^\d{3}-\d{2}-\d{4}$ nel routing, è necessario digitare i caratteri \ come \\ nel file di origine C# per eseguire l'escape del carattere di escape \ della stringa, a meno che non si usino valori letterali stringa verbatim.For example, to use the regular expression ^\d{3}-\d{2}-\d{4}$ in Routing, it needs to have the \ characters typed in as \\ in the C# source file to escape the \ string escape character (unless using verbatim string literals. Raddoppiare i caratteri {, }, '[' e ']' per eseguire l'escape dei caratteri di delimitazione dei parametri di routing.The { , } , '[' and ']' characters need to be escaped by doubling them to escape the Routing parameter delimiter characters. Nella tabella che segue sono riportate due espressioni regolari con la relativa versione dopo l'escape.The table below shows a regular expression and the escaped version.

EspressioneExpression NotaNote
^\d{3}-\d{2}-\d{4}$ Espressione regolareRegular expression
^\\d{{3}}-\\d{{2}}-\\d{{4}}$ Con caratteri di escapeEscaped
^[a-z]{2}$ Espressione regolareRegular expression
^[[a-z]]{{2}}$ Con caratteri di escapeEscaped

Le espressioni regolari usate nel routing spesso iniziano con il carattere ^ (corrispondenza con la posizione iniziale della stringa) e terminano con il carattere $ (corrispondenza con la posizione finale della stringa).Regular expressions used in routing will often start with the ^ character (match starting position of the string) and end with the $ character (match ending position of the string). 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 corrisponderà a qualsiasi sottostringa all'interno della stringa e spesso questo non è il risultato desiderato.Without the ^ and $ characters the regular expression will match any substring within the string, which is often not what you want. La tabella seguente illustra alcuni esempi e spiega perché si verifica o non si verifica la corrispondenza.The table below shows some 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.Refer to .NET Framework Regular Expressions for more information on regular expression syntax.

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 passata nel dizionario di vincoli, la stringa "^(list|get|create)$" sarebbe equivalente.If passed into the constraints dictionary, the string "^(list|get|create)$" would be 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.

Riferimento per la generazione di URLURL Generation Reference

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

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

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

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

L'oggetto VirtualPath generato alla fine dell'esempio precedente è /package/create/123.The VirtualPath generated at the end of the sample above is /package/create/123.

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 di un determinato contesto di richiesta.Ambient values provide convenience by limiting the number of values a developer must specify within a certain 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. Ad esempio, in un'app ASP.NET MVC se si è nell'azione About di HomeController, non è necessario specificare il valore di route del controller per collegarsi all'azione Index poiché verrà usato il valore di ambiente di Home.For example, in an ASP.NET MVC app if you are in the About action of the HomeController, you don't need to specify the controller route value to link to the Index action (the ambient value of Home will be used).

I valori di ambiente vengono ignorati se non corrispondono a un parametro e quando vengono sostituiti da valori specificati in modo esplicito, procedendo da sinistra verso destra nell'URL.Ambient values that don't match a parameter are ignored, and ambient values are also ignored when an explicitly-provided value overrides it, going from left to right in the URL.

I valori specificati in modo esplicito ma che non corrispondono ad alcun elemento vengono aggiunti alla stringa di query.Values that are explicitly provided but which don't match anything 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, il valore 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. Ad esempio:For example:

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

La funzionalità di generazione del collegamento genera un collegamento per questa route solo se vengono specificati i valori corrispondenti per il controller e l'azione.Link generation would only generate a link for this route when the matching values for controller and action are provided.