Routing nell'API Web di ASP.NET

Questo articolo descrive come ASP.NET API Web instrada le richieste HTTP ai controller.

Tabelle di routing

In ASP.NET API Web, un controller è una classe che gestisce le richieste HTTP. I metodi pubblici del controller sono chiamati metodi di azione o semplicemente azioni. Quando il framework API Web riceve una richiesta, instrada la richiesta a un'azione.

Per determinare quale azione richiamare, il framework usa una tabella di routing. Il modello di progetto di Visual Studio per l'API Web crea una route predefinita:

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Questa route viene definita nel file WebApiConfig.cs , che viene inserito nella directory App_Start :

Per altre informazioni sulla WebApiConfig classe, vedere Configurazione dell'API Web ASP.NET.

Se si ospita l'API Web self-host, è necessario impostare la tabella di routing direttamente sull'oggetto HttpSelfHostConfiguration . Per ulteriori informazioni, vedere Auto-ospitare un'API Web.

Ogni voce nella tabella di routing contiene un modello di route. Il modello di route predefinito per l'API Web è "api/{controller}/{id}". In questo modello "api" è un segmento di percorso letterale e {controller} e {id} sono variabili segnaposto.

Quando il framework API Web riceve una richiesta HTTP, tenta di trovare la corrispondenza con l'URI rispetto a uno dei modelli di route nella tabella di routing. Se nessuna route corrisponde, il client riceve un errore 404. Ad esempio, gli URI seguenti corrispondono alla route predefinita:

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

Tuttavia, l'URI seguente non corrisponde, perché manca il segmento "api":

• /contacts/1

Dopo aver trovato una route corrispondente, l'API Web seleziona il controller e l'azione:

• Per trovare il controller, l'API Web aggiunge "Controller" al valore della variabile {controller} .
• Per trovare l'azione, l'API Web esamina il verbo HTTP e quindi cerca un'azione il cui nome inizia con il nome del verbo HTTP. Ad esempio, con una richiesta GET, l'API Web cerca un'azione preceduta da "Get", ad esempio "GetContact" o "GetAllContacts". Questa convenzione si applica solo ai verbi GET, POST, PUT, DELETE, HEAD, OPTIONS e PATCH. È possibile abilitare altri verbi HTTP usando attributi nel controller. Più avanti verrà illustrato un esempio.
• Altre variabili segnaposto nel modello di route, ad esempio {id}, vengono mappate ai parametri azione.

Di seguito è descritto un esempio. Si supponga di definire il controller seguente:

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

Ecco alcune possibili richieste HTTP, insieme all'azione che viene richiamata per ognuna:

Si noti che il segmento {id} dell'URI, se presente, viene mappato al parametro ID dell'azione. In questo esempio, il controller definisce due metodi GET, uno con un parametro ID e uno senza parametri.

Si noti inoltre che la richiesta POST avrà esito negativo perché il controller non definisce un metodo "Post...".

Varianti di routing

La sezione precedente descrive il meccanismo di routing di base per ASP.NET API Web. Questa sezione descrive alcune varianti.

Verbi HTTP

Anziché usare la convenzione di denominazione per i verbi HTTP, è possibile specificare esplicitamente il verbo HTTP per un'azione decorando il metodo dell'azione con uno degli attributi seguenti:

• [HttpGet]
• [HttpPut]
• [HttpPost]
• [HttpDelete]
• [HttpHead]
• [HttpOptions]
• [HttpPatch]

Nell'esempio seguente viene eseguito il mapping del FindProduct metodo alle richieste GET:

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

Per consentire più verbi HTTP per un'azione o consentire verbi HTTP diversi da GET, PUT, POST, DELETE, HEAD, OPTIONS e PATCH, usare l'attributo [AcceptVerbs] , che accetta un elenco di verbi HTTP.

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

Routing per nome azione

Con il modello di routing predefinito, l'API Web usa il verbo HTTP per selezionare l'azione. Tuttavia, è anche possibile creare una route in cui il nome dell'azione è incluso nell'URI:

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

In questo modello di route il parametro {action} assegna un nome al metodo di azione nel controller. Con questo stile di routing, usare gli attributi per specificare i verbi HTTP consentiti. Si supponga, ad esempio, che il controller abbia il metodo seguente:

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

In questo caso, una richiesta GET per "api/products/details/1" viene mappata al Details metodo . Questo stile di routing è simile a ASP.NET MVC e può essere appropriato per un'API in stile RPC.

È possibile eseguire l'override del nome dell'azione usando l'attributo [ActionName] . Nell'esempio seguente sono disponibili due azioni mappate a "api/products/thumbnail/id. Uno supporta GET e l'altro supporta POST:

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

Azioni non

Per impedire che un metodo venga richiamato come azione, usare l'attributo [NonAction] . Questo segnala al framework che il metodo non è un'azione, anche se altrimenti corrisponderebbe alle regole di routing.

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

Altre informazioni

In questo argomento è stata fornita una visualizzazione generale del routing. Per ulteriori dettagli, vedere Routing e Action Selection, che descrive esattamente come il framework associa un URI a una route, seleziona un controller e seleziona l'azione da invocare.