Resultados de Ação na Web API 2

Considere usar ASP.NET API web Core. Tem as seguintes vantagens sobre ASP.NET API Web 4.x:

• ASP.NET Core é uma framework de código aberto e multiplataforma para construir aplicações web modernas baseadas na cloud no Windows, macOS e Linux.
• Os controladores ASP.NET Core MVC e os controladores web API estão unificados.
• Arquitetado para a testabilidade.
• Capacidade de desenvolver e correr em Windows, macOS e Linux.
• Código aberto e focado na comunidade.
• Integração de frameworks modernos do lado do cliente e fluxos de trabalho de desenvolvimento.
• Um sistema de configuração pronto para a cloud e baseado no ambiente.
• Injeção de dependência incorporada.
• Um pipeline de pedidos HTTP leve, de alto desempenho e modular.
• Capacidade de hospedar em Kestrel, IIS, HTTP.sys, Nginx, Apache e Docker.
• Controle de versões simultâneas.
• Ferramentas que simplificam o desenvolvimento web moderno.

Este tópico descreve como ASP.NET Web API converte o valor de retorno de uma ação do controlador numa mensagem de resposta HTTP.

Uma ação de controlador de API Web pode devolver qualquer um dos seguintes:

1. Vazio
2. HttpResponseMessage
3. IHttpActionResult
4. Algum outro tipo

Dependendo de qual destes é devolvido, a Web API utiliza um mecanismo diferente para criar a resposta HTTP.

O resto deste tópico descreve cada opção com mais detalhe.

Vazio

Se o tipo de retorno for void, a Web API simplesmente devolve uma resposta HTTP vazia com o código de estado 204 (Sem Conteúdo).

Exemplo de controlador:

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

Resposta HTTP:

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

HttpResponseMessage

Se a ação devolver uma HttpResponseMessage, a Web API converte o valor de retorno diretamente numa mensagem de resposta HTTP, usando as propriedades do objeto HttpResponseMessage para preencher a resposta.

Esta opção dá-te muito controlo sobre a mensagem de resposta. Por exemplo, a seguinte ação do controlador define o cabeçalho 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;
    } 
}

Resposta:

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 passar um modelo de domínio para o método CreateResponse , a Web API usa um formatador de media para escrever o modelo serializado no corpo da resposta.

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;
}

A Web API utiliza o cabeçalho Accept no pedido para escolher o formatador. Para mais informações, consulte Negociação de Conteúdos.

IHttpActionResult

A interface IHttpActionResult foi introduzida na Web API 2. Essencialmente, define uma fábrica HttpResponseMessage . Aqui estão algumas vantagens de usar a interface IHttpActionResult :

• Simplifica o teste unitário dos teus controladores.
• Move a lógica comum para criar respostas HTTP para classes separadas.
• Torna a intenção da ação do controlador mais clara, ao esconder os detalhes de baixo nível da construção da resposta.

O IHttpActionResult contém um único método, ExecuteAsync, que cria assíncronamente uma instância HttpResponseMessage .

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

Se uma ação do controlador devolver um IHttpActionResult, a Web API chama o método ExecuteAsync para criar uma HttpResponseMessage. Depois, converte a HttpResponseMessage numa mensagem de resposta HTTP.

Aqui está uma implementação simples do IHttpActionResult que cria uma resposta em texto simples:

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);
    }
}

Exemplo de ação do comando:

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

Resposta:

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

Mais frequentemente, utiliza-se as implementações IHttpActionResult definidas no espaço de nomes System.Web.Http.Results . A classe ApiController define métodos auxiliares que retornam estes resultados de ações incorporados.

No exemplo seguinte, se o pedido não corresponder a um ID de produto existente, o controlador chama o ApiController.NotFound para criar uma resposta 404 (Não Encontrado). Caso contrário, o controlador chama ApiController.OK, que cria uma resposta 200 (OK) que contém o produto.

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

Outros Tipos de Retorno

Para todos os outros tipos de retorno, a Web API utiliza um formatador de media para serializar o valor de retorno. A API web grava o valor serializado no corpo da resposta. O código de estado da resposta é 200 (OK).

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

Uma desvantagem desta abordagem é que não pode devolver diretamente um código de erro, como o 404. No entanto, pode lançar um HttpResponseException para códigos de erro. Para mais informações, consulte Gestão de Exceções na ASP.NET Web API.

A Web API utiliza o cabeçalho Accept no pedido para escolher o formatador. Para mais informações, consulte Negociação de Conteúdos.

Exemplo de pedido

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

Resposta de exemplo

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}]