Risultati delle azioni nell'API Web 2

  • Articolo

È consigliabile usare ASP.NET Core'API Web. Offre i vantaggi seguenti rispetto ASP.NET'API Web 4.x:

  • ASP.NET Core è un framework open source multipiattaforma per la creazione di app Web moderne basate sul cloud in Windows, macOS e Linux.
  • I controller MVC e i controller API Web ASP.NET Core sono unificati.
  • Progettazione finalizzata alla testabilità.
  • Possibilità di sviluppo ed esecuzione in Windows, macOS e Linux.
  • Focalizzati su risorse open source e sulle community.
  • Integrazione di framework lato client moderni e flussi di lavoro di sviluppo.
  • Un sistema di configurazione basato sull'ambiente, pronto per il cloud.
  • Inserimento delle dipendenze incorporato.
  • Una pipeline di richiesta HTTP leggera, ad alte prestazioni e modulare.
  • Possibilità di ospitare in Kestrel, IIS, HTTP.sys, Nginx, Apache e Docker.
  • Controllo delle versioni side-by-side.
  • Gli strumenti che semplificano lo sviluppo del web moderno.

In questo argomento viene descritto come API Web ASP.NET converte il valore restituito da un'azione del controller in un messaggio di risposta HTTP.

Un'azione del controller API Web può restituire uno dei seguenti elementi:

  1. void
  2. HttpResponseMessage
  3. IHttpActionResult
  4. Altri tipi

A seconda di quale di queste opzioni viene restituita, l'API Web usa un meccanismo diverso per creare la risposta HTTP.

Tipo restituito Come l'API Web crea la risposta
void Restituisce vuoto 204 (nessun contenuto)
HttpResponseMessage Convertire direttamente in un messaggio di risposta HTTP.
IHttpActionResult Chiamare ExecuteAsync per creare un httpResponseMessage, quindi convertire in un messaggio di risposta HTTP.
Altro tipo Scrivere il valore restituito serializzato nel corpo della risposta; restituisce 200 (OK).

Il resto di questo argomento descrive in modo più dettagliato ogni opzione.

void

Se il tipo restituito è void, l'API Web restituisce semplicemente una risposta HTTP vuota con codice di stato 204 (nessun contenuto).

Controller di esempio:

public class ValuesController : ApiController
{
    public void Post()
    {
    }
}

Risposta HTTP:

HTTP/1.1 204 No Content
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 02:13:26 GMT

HttpResponseMessage

Se l'azione restituisce un oggetto HttpResponseMessage, l'API Web converte il valore restituito direttamente in un messaggio di risposta HTTP, usando le proprietà dell'oggetto HttpResponseMessage per popolare la risposta.

Questa opzione offre un notevole controllo sul messaggio di risposta. Ad esempio, l'azione del controller seguente imposta l'intestazione Cache-Control.

public class ValuesController : ApiController
{
    public HttpResponseMessage Get()
    {
        HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value");
        response.Content = new StringContent("hello", Encoding.Unicode);
        response.Headers.CacheControl = new CacheControlHeaderValue()
        {
            MaxAge = TimeSpan.FromMinutes(20)
        };
        return response;
    } 
}

Risposta:

HTTP/1.1 200 OK
Cache-Control: max-age=1200
Content-Length: 10
Content-Type: text/plain; charset=utf-16
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

Se si passa un modello di dominio al metodo CreateResponse , l'API Web usa un formattatore multimediale per scrivere il modello serializzato nel corpo della risposta.

public HttpResponseMessage Get()
{
    // Get a list of products from a database.
    IEnumerable<Product> products = GetProductsFromDB();

    // Write the list to the response body.
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
    return response;
}

L'API Web usa l'intestazione Accept nella richiesta per scegliere il formattatore. Per altre informazioni, vedere Negoziazione del contenuto.

IHttpActionResult

L'interfaccia IHttpActionResult è stata introdotta nell'API Web 2. In pratica, definisce una factory HttpResponseMessage . Ecco alcuni vantaggi dell'uso dell'interfaccia IHttpActionResult :

  • Semplifica il testing unità dei controller.
  • Sposta la logica comune per la creazione di risposte HTTP in classi separate.
  • Rende più chiara la finalità dell'azione del controller nascondendo i dettagli di basso livello della costruzione della risposta.

IHttpActionResult contiene un singolo metodo , ExecuteAsync, che crea in modo asincrono un'istanza HttpResponseMessage .

public interface IHttpActionResult
{
    Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}

Se un'azione del controller restituisce un oggetto IHttpActionResult, l'API Web chiama il metodo ExecuteAsync per creare un oggetto HttpResponseMessage. Converte quindi HttpResponseMessage in un messaggio di risposta HTTP.

Ecco una semplice implementazione di IHttpActionResult che crea una risposta in testo normale:

public class TextResult : IHttpActionResult
{
    string _value;
    HttpRequestMessage _request;

    public TextResult(string value, HttpRequestMessage request)
    {
        _value = value;
        _request = request;
    }
    public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        var response = new HttpResponseMessage()
        {
            Content = new StringContent(_value),
            RequestMessage = _request
        };
        return Task.FromResult(response);
    }
}

Esempio di azione del controller:

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return new TextResult("hello", Request);
    }
}

Risposta:

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: text/plain; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

Più spesso si usano le implementazioni IHttpActionResult definite nello spazio dei nomi System.Web.Http.Results . La classe ApiController definisce i metodi helper che restituiscono questi risultati predefiniti dell'azione.

Nell'esempio seguente, se la richiesta non corrisponde a un ID prodotto esistente, il controller chiama ApiController.NotFound per creare una risposta 404 (Non trovato). In caso contrario, il controller chiama ApiController.OK, che crea una risposta 200 (OK) che contiene il prodotto.

public IHttpActionResult Get (int id)
{
    Product product = _repository.Get (id);
    if (product == null)
    {
        return NotFound(); // Returns a NotFoundResult
    }
    return Ok(product);  // Returns an OkNegotiatedContentResult
}

Altri tipi restituiti

Per tutti gli altri tipi restituiti, l'API Web usa un formattatore multimediale per serializzare il valore restituito. L'API Web scrive il valore serializzato nel corpo della risposta. Il codice di stato della risposta è 200 (OK).

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

Uno svantaggio di questo approccio è che non è possibile restituire direttamente un codice di errore, ad esempio 404. Tuttavia, è possibile generare un'eccezione HttpResponseException per i codici di errore. Per altre informazioni, vedere Gestione delle eccezioni in API Web ASP.NET.

L'API Web usa l'intestazione Accept nella richiesta per scegliere il formattatore. Per altre informazioni, vedere Negoziazione del contenuto.

Richiesta di esempio

GET http://localhost/api/products HTTP/1.1
User-Agent: Fiddler
Host: localhost:24127
Accept: application/json

Risposta di esempio

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT
Content-Length: 56

[{"Id":1,"Name":"Yo-yo","Category":"Toys","Price":6.95}]