---

Marzo 2018

Volume 33 Numero 3

Il presente articolo è stato tradotto automaticamente.

Cutting Edge - API REST e API Web in ASP.NET Core

Dal Dino Esposito | 2018 marzo

Non sono mai stato una ventola di ASP.NET Web API come un framework autonomo e non è possibile non credo di un progetto in cui utilizzato. Non è il framework in sé non necessari o fuori posto. È possibile individuare solo che il valore di business che offre effettivamente è, la maggior parte dei casi, minima. D'altro canto, è possibile riconoscere in essa contenuti che alcuni deselezionare segnali l'impegno sottostante che Microsoft sta per rinnovare la pipeline di runtime ASP.NET. In generale, vorrei pensare a ASP.NET Web API come un modello di prova per quali oggi sono diventata ASP.NET Core e, in particolare, il nuovo ambiente di runtime di ASP.NET Core.

API Web è stato introdotto principalmente come un modo per semplificare la creazione di un'API RESTful comodo e in ASP.NET. Questo articolo è su come ottenere lo stesso risultato, ovvero la creazione di un'API RESTful, in ASP.NET Core.

Il costo aggiuntivo API Web in ASP.NET classico

ASP.NET Web API è stata compilata in base ai principi che l'interfaccia Web aperta per la specifica di .NET (OWIN), che è progettato per separare il server Web da applicazioni Web ospitate. Nello spazio .NET, l'introduzione di OWIN contrassegnato come un punto di svolta, in cui è stato messo in discussione l'integrazione di IIS e ASP.NET. Che è stata abbandonata completamente accoppiamento stretto in ASP.NET Core.

Qualsiasi facciata Web compilata tramite il framework di ASP.NET Web API si basa su una pipeline completamente riscritta che utilizza l'interfaccia OWIN standard alla finestra di dialogo con il server Web host sottostante. Tuttavia, un'API Web ASP.NET non è un'applicazione autonoma. Sia disponibile per i chiamanti necessiti di un ambiente host che si occupa di ascolto ad alcune porta configurata, acquisisce le richieste in ingresso e li invia alla pipeline API Web.

Un'applicazione API Web può essere ospitata in un servizio Windows o in un'applicazione console personalizzata che implementa le interfacce appropriate OWIN. Può inoltre essere ospitato da un'applicazione ASP.NET classica, se la destinazione di Web Form o ASP.NET MVC. Negli ultimi anni, Web API di hosting all'interno di un'applicazione ASP.NET MVC classica dimostrato di essere in uno scenario molto comune, ma uno dei meno efficace in termini di non elaborati delle prestazioni e footprint di memoria.

Come figura 1 illustrato, ogni volta che disponi facciata API Web all'interno di un'applicazione ASP.NET MVC, tre strutture finiscono risiedono side-by-side, l'elaborazione di ogni singola richiesta di API Web. L'host applicazione MVC ASP.NET viene incapsulato in un gestore HTTP che vivono in ambiente di runtime ASP.NET originale system.web—the. In cui, occupando memoria aggiuntiva, ovvero è la pipeline di Web API basate su OWIN.

Figura 1 Framework coinvolti in un'applicazione classico ASP.NET Web API

La visione dell'introduzione di un framework Web indipendenti dal server in questo caso, è, in modo significativo la ridotta tramite i vincoli di rimanere compatibili con la pipeline ASP.NET esistente. Pertanto, la progettazione pulita e orientato al resto dell'API Web di non sfruttare appieno il potenziale a causa dell'assembly System. Web legacy. Dal punto di vista delle prestazioni pure, solo alcuni casi d'uso di edge giustificare effettivamente l'uso dell'API Web.

Casi d'uso efficace per API Web

API Web è l'esempio più alto profilo dei principi OWIN nell'azione. Viene eseguita una libreria di API Web protetto da un'applicazione server che consente di acquisire e inoltra le richieste in ingresso. L'host può essere un'applicazione Web classica nello stack di Microsoft (Web Form, MVC ASP.NET) o può essere un'applicazione console o un servizio Windows.

In ogni caso, deve essere un'applicazione dotata di un livello di codice in grado di dialoging con il listener Web API ridotto.

Hosting di un'API Web all'esterno dell'ambiente Web rimuove alla radice tutte le dipendenze dall'assembly System. Web, rendendo in tal modo Authenticated la richiesta di pipeline come lean e la media in base alle esigenze.

Questo è il punto cruciale che ha portato il team di ASP.NET Core per compilare pipeline ASP.NET Core. Le condizioni di hosting ideale per l'API Web sono state rielaborate per le condizioni di hosting ideale per quasi tutte le applicazioni ASP.NET Core. Questa opzione abilitata una pipeline completamente nuova naturalmente di dipendenze l'assembly System. Web e behind hostable un server HTTP incorporato che espone un'interfaccia di contratto, ovvero l'interfaccia IServer.

La specifica di OWIN e Katana, l'implementazione di esso per l'ambiente accoppiato, non svolge alcun ruolo ASP.NET Core. Ma l'esperienza con queste piattaforme con lo sviluppo la visione tecnica (in particolare con casi di limite API Web), che giornate di sole sono tramite la nuova pipeline di ASP.NET Core.

La cosa divertente è che una volta l'intera pipeline ASP.NET è stata riprogettata: eccessivamente ispirati dall'ambiente di hosting ideale per l'API Web, ovvero la stessa API Web come un framework separato corrispondenza sia applicabile. Nella nuova pipeline di ASP.NET Core è necessario per il modello di una sola applicazione, ovvero il modello di applicazione MVC, basate su controller e le classi controller sono un po' più complete rispetto a in ASP.NET MVC classico, in questo modo che includa le funzioni di precedente controller di ASP.NET e Web Controller API.

Controller estesa ASP.NET Core

In ASP.NET Core, è possibile utilizzare con le classi controller se si intende gestire HTML o qualsiasi altro tipo di risposta, ad esempio JSON o PDF. Una serie di nuovi tipi di risultati di azione sono state aggiunte per semplificare la creazione di interfacce RESTful semplice e pratico. Negoziazione del contenuto è supportata completamente per tutte le classi controller e gli helper di formattazione salvati nell'infrastruttura Invoker dell'azione. Se si desidera compilare un'API Web che espone gli endpoint HTTP, è sufficiente è compilare una classe controller semplice, come illustrato di seguito:

public class ApiController : Controller
{
  // Your methods here
}

Il nome della classe controller è arbitrario. Mentre con /api altrove nell'URL è auspicabile per maggiore chiarezza, è non modo necessario. È possibile avere /api nell'URL viene richiamato se si utilizza il routing convenzionale (una classe ApiController) per eseguire il mapping degli URL per i metodi di azione oppure se si utilizza routing degli attributi. Ritengo personali, routing degli attributi è probabilmente preferibile perché consente di esporre più endpoint con lo stesso elemento /api nell'URL, mentre viene definito nelle classi controller distinti, denominato in modo arbitrario.

La classe Controller in ASP.NET Core include molte più funzionalità rispetto alla classe in classico ASP.NET MVC e la maggior parte delle estensioni si riferiscono alla creazione di un'API Web RESTful. In primo luogo, tutti i controller di ASP.NET Core supportano la negoziazione del contenuto. Negoziazione del contenuto fa riferimento a una negoziazione invisibile all'utente che si verifica tra il chiamante e l'API relativi al formato effettivo dei dati restituiti.

Contenuto negoziazione non si verifica costantemente e per appena ogni richiesta. Ha luogo solo se la richiesta in ingresso contiene un'intestazione HTTP Accept che annuncia i tipi MIME che il chiamante è in grado di comprendere. In questo caso, l'infrastruttura ASP.NET Core sono illustrati i tipi elencati nel contenuto dell'intestazione fino a quando non ne viene trovato uno per il quale esiste un formattatore della configurazione corrente dell'applicazione. Se non viene trovato alcun formattatore corrispondente nell'elenco dei tipi, quindi viene utilizzato il formattatore JSON predefinito, come illustrato di seguito:

[HttpGet]
public ObjectResult Get(Guid id)
{
  // Do something here to retrieve the resource data
  var data = FindResourceDataInSomeWay(id);
  return Ok(data);
}

Un altro aspetto notevole della negoziazione del contenuto è che sebbene non produce modifiche nel processo di serializzazione senza un'intestazione HTTP Accept, che è tecnicamente attivata solo se la risposta inviata nuovamente dal controller è di tipo ObjectResult. Il modo più comune per restituire un tipo di risultato azione ObjectResult è per la serializzazione della risposta tramite il metodo Ok. È importante notare che se si serializza risposta controller tramite, ad esempio, il metodo Json, nessuna negoziazione mai avrà luogo indipendentemente dalle intestazioni inviate. Supporto per i formattatori di output può essere aggiunti a livello di programmazione tramite le opzioni del metodo AddMvc. Ecco un esempio:

services.AddMvc(options =>
{
  options.OutputFormatters.Add(new PdfFormatter());
});

In questo esempio, la classe demo PdfFormatter contiene internamente l'elenco di tipi MIME supportati che è possibile gestire.

Si noti che tramite l'attributo produce si esegue l'override di negoziazione del contenuto, come illustrato di seguito:

[Produces("application/json")]
public class ApiController : Controller
{
  // Action methods here
}

L'attributo produce, che è possibile applicare a livello di controller o al metodo, forza l'output di tipo ObjectResult deve sempre essere serializzato nel formato specificato dall'attributo, indipendentemente dall'intestazione HTTP Accept.

Per altre informazioni su come formattare la risposta di un metodo del controller, si potrebbe voler estrarre il contenuto nella bit.ly/2klDgdY.

Tipi di risultati dell'azione orientata ai servizi REST

Se un'API Web è preferibile con una progettazione REST è un punto elevata discutibile. In generale, è abbastanza sicura dire che l'approccio REST si basa su un set noto di regole e, in questo senso, risulta più standard. Per questo motivo, è consigliabile in genere per un'API pubblica che fa parte dell'azienda dell'organizzazione. Se l'API esiste solo per soddisfare un numero limitato di client, ovvero principalmente sotto il controllo stesso dei creatori di API, quindi non esiste alcuna differenza aziendali reali tra usando REST progettazione route o un approccio più blando di chiamata di procedura remota (RPC).

In ASP.NET Core, non c'è niente un framework Web API distinto e dedicato. Sono presenti pochi controller con il set di metodi di supporto e i risultati dell'azione. Se si desidera compilare un'API Web qualunque tipo, sufficiente restituire JSON, XML o qualsiasi altra. Se si desidera compilare un'API RESTful, sufficiente dimestichezza con un altro set di metodi di supporto e i risultati dell'azione. Figura 2 presenta i nuovi tipi di risultati di azione che possono restituire i controller di ASP.NET Core. In ASP.NET Core, un tipo di risultato di azione è un tipo che implementa l'interfaccia IActionResult. 

Figura 2 tipi di risultati azione correlata all'API Web

Tipo	Descrizione
AcceptedResult	Restituisce un codice di 202 stato. Inoltre, restituisce l'URI per controllare lo stato in corso della richiesta. L'URI viene archiviato nell'intestazione Location.
BadRequestResult	Restituisce un codice di 400 stato.
CreatedResult	Restituisce un codice di 201 stato. Inoltre, viene restituito l'URI della risorsa creato, archiviato nell'intestazione Location.
NoContentResult	Restituisce un contenuto di 204 stato codice e null.
OkResult	Restituisce un codice di 200 stato.
UnsupportedMediaTypeResult	Restituisce un codice di 415 stato.

Si noti che alcuni dei tipi nel figura 2 forniti con i tipi di contatto che forniscono la stessa funzione di base ma con alcune piccole differenze. Oltre a AcceptedResult e CreatedResult, ad esempio, trovare tipi xxxAtActionResult e xxxAtRouteResult. La differenza consiste nel modo in cui i tipi di esprimere l'URI per monitorare lo stato dell'operazione è stata accettata e il percorso della risorsa appena creata. Il tipo xxxAtActionResult esprime l'URI come una coppia di stringhe di azione e del controller mentre il tipo xxxAtRouteResult utilizza un nome di route.

OkObjectResult e BadRequestObjectResult, invece, hanno una variazione xxxObjectResult. La differenza è che i tipi di oggetto risultato consentono inoltre di aggiungere un oggetto nella risposta. Pertanto, OkResult limita a impostare un codice di 200 stato, ma OkObjectResult imposta un codice di 200 stato e aggiunge un oggetto di propria scelta. Un modo comune per utilizzare questa funzionalità è restituiscono un dizionario ModelState aggiornato con l'errore rilevato quando viene gestita una richiesta non valida.

Un'altra differenza interessano è compreso tra NoContentResult ed EmptyResult. Entrambe restituiscono una risposta vuota, ma NoContentResult imposta un codice di stato di 204, mentre EmptyResult imposta un codice di 200 stato. Tutto ciò premesso, la creazione di un'API RESTful consiste nella definizione della risorsa utilizzata in e disporre una serie di chiamate utilizzando il verbo HTTP per eseguire operazioni di manipolazione comuni. Utilizzare GET per leggere, inserire da aggiornare, POST per creare una nuova risorsa e DELETE per rimuoverne uno esistente. Figura 3 Mostra lo scheletro di un'interfaccia REST intorno a un tipo di risorsa esempio poiché comporta dalle classi di ASP.NET Core.

Figura 3 scheletro RESTful comuni del codice

[HttpGet]
public ObjectResult Get(Guid id)
{
  // Do something here to retrieve the resource
  var res = FindResourceInSomeWay(id);
  return Ok(res);
}
[HttpPut]
public AcceptedResult UpdateResource(Guid id, string content)
{
  // Do something here to update the resource
  var res = UpdateResourceInSomeWay(id, content);
  var path = String.Format("/api/resource/{0}", res.Id);
  return Accepted(new Uri(path));  
}
[HttpPost]
public CreatedResult AddNews(MyResource res)
{
  // Do something here to create the resource
  var resId = CreateResourceInSomeWay(res);
  // Returns HTTP 201 and sets the URI to the Location header
  var path = String.Format("/api/resource/{0}", resId);
  return Created(path, res);
}
[HttpDelete]
public NoContentResult DeleteResource(Guid id)
{
  // Do something here to delete the resource
  // ...
  return NoContent();
}

Se si desidera approfondire ulteriormente l'implementazione dei controller di ASP.NET Core per la compilazione di un'API Web, è possibile la cartella GitHub bit.ly/2j4nyUe.

Conclusioni

Un elemento comune nella maggior parte delle applicazioni attualmente è presente un'API Web. E viene utilizzato per fornire dati a un angolare o MVC front-end, nonché per fornire servizi per le applicazioni per dispositivi mobili o desktop. Nel contesto di ASP.NET Core, il termine "API Web" infine raggiunge il relativo significato reale senza ambiguità o è necessario descrivere ulteriormente la distribuzione. Un'API Web è un'interfaccia programmatica che comprendono un numero di endpoint HTTP esposto pubblicamente che in genere (ma non necessariamente) restituiscono dati JSON o XML per i chiamanti. L'infrastruttura del controller in ASP.NET Core supporta completamente questo obiettivo con un'implementazione di attività e nuovi tipi di risultati di azione. Compilazione di un'API RESTful in ASP.NET non è mai stato così facile!

---

Dino Espositoè l'autore di "Microsoft .NET: Architettura delle applicazioni per l'azienda"(Microsoft Press, 2014) e"Programmazione ASP.NET Core"(Microsoft Press, 2018). Un autore Pluralsight e developer sostenere in JetBrains Esposito condivide la sua visione del software su Twitter: @despos.

Grazie per il seguente esperto tecnico di Microsoft per la revisione dell'articolo: Ugo Lattanzi

---

Viene illustrato in questo articolo nel forum di MSDN Magazine