ASP.NET Core - Tipos de Retorno Action em Web APIs

Hoje vou apresentar os principais tipos de retornos de métodos Action usados em Apis da Web ou Web API com ASP .NET Core. (Reproduzido da documentação oficial)

A ASP .NET Core oferece os seguintes tipos de retorno em métodos Action para Web APIs.

  1. Tipo Específico
  2. IActionResult
  3. ActionResult<T>

A seguir vamos discutir cada um deles e ver qual tipo é mais adequado dependendo do cenário.

1 - Tipo Específico

A Action mais simples pode retornar um tipo de dados primitivo ou complexo (string ou um objeto). Veja o exemplo a seguir que retorna uma coleção de objetos Produtos:

[HttpGet]
public IEnumerable<Produto> Get()
{
    return _repository.GetProdutos();
}

Sem as condições conhecidas para fazer a validação durante a execução da Action, um tipo de retorno específico pode ser suficiente. A Action do exemplo não aceita parâmetros, portanto, a validação de restrições de parâmetro não é necessária.

Quando condições conhecidas precisam ser consideradas em uma Action, vários caminhos de retorno são introduzidos. Nesse caso, é comum misturar um tipo de retorno ActionResult com o tipo de retorno primitivo ou complexo. Tanto IActionResult quanto ActionResult<T> são necessários para acomodar esse tipo de Action.

2 - Tipo IActionResult

O tipo de retorno IActionResult é apropriado quando vários tipos de retorno ActionResult são possíveis em uma Action.

Os tipos ActionResult representam vários códigos de status HTTP. Alguns tipos de retorno comuns nessa categoria são BadRequestResult (400), NotFoundResult (404) e OkObjectResult (200).

Como existem vários tipos de retorno e caminhos na Action, o uso liberal do atributo [ProducesResponseType] é necessário. Esse atributo produz detalhes de resposta mais descritivos para páginas de ajuda da API geradas por ferramentas como o Swagger.

O Atributo [ProducesResponseType] indica os tipos conhecidos e códigos de status HTTP a serem retornados pela ação.

Veja o trecho de código onde temos um método Action síncrono onde existem dois tipos de retornos:

[HttpGet("{id}")]
[ProducesResponseType(typeof(Produto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById(int id)
{
    if (!_repository.TryGetProduto(id, out var produto))
    {
        return NotFound();
    }

    return Ok(produto);
}

No exemplo acima o código de status 404 é retornado quando o produto representado por id não existe na base de dados.

O método auxiliar NotFound é chamado como um atalho para retornar o novo NotFoundResult().

Se o produto existir, um objeto Produto representando a carga útil será retornado com um código de status 200. O método de ajuda Ok é chamado como a forma abreviada de retornar o novo OkObjectResult (produto).

Agora vejamos outro exemplo, desta vez um método Action Assíncrono onde são possíveis dois tipos de retorno:

[HttpPost]
[ProducesResponseType(typeof(Produto), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync([FromBody] Produto produto)
{
    if (produto.Description.Contains("XYZ Demo"))
    {
        return BadRequest();
    }

    await _repository.AddProdutoAsync(produto);

    return CreatedAtAction(nameof(GetById), new { id = produto.Id }, produto);
}

Neste código temos que :

Se o atributo [ApiController], introduzido no ASP.NET Core 2.1, for aplicado, os erros de validação do modelo resultarão em um código de status 400 automaticamente.

3 - ActionResult<T>

A partir da ASP.NET Core 2.1 temos o tipo de retorno ActionResult<T> para Actions das Web APIs que permite que você retorne um tipo derivado de ActionResult ou retorne um tipo específico.

O tipo de retorno ActionResult<T> oferece os seguintes benefícios sobre o tipo IActionResult:

[ProducesResponseType (200, Type = typeof (Produto))] é simplificado para [ProducesResponseType (200)].

    O tipo de retorno esperado da ação é inferido do T em ActionResult<T>.

Como a linguagem C# não suporta operadores de conversão implícitos em interfaces, a conversão da interface para um tipo concreto é necessária para usar o ActionResult<T>. Por exemplo, o uso de IEnumerable no exemplo a seguir não funciona:

[HttpGet]
public ActionResult<IEnumerable<Produto>> Get()
{
    return _repository.GetProdutos();
}

Uma opção para corrigir o código anterior é retornar _repository.GetProdutos().ToList().

Assim, a maioria das Actions tem um tipo de retorno específico. Condições inesperadas podem ocorrer durante a execução da Action e, nesse caso, o tipo específico não é retornado. Por exemplo, o parâmetro de entrada de uma Action pode falhar na validação do modelo.

Nesse caso, é comum retornar o tipo ActionResult apropriado em vez do tipo específico.

E estamos conversados...

"Pensai nas coisas que são de cima, e não nas que são da terra;"
Colossenses 3:2

Veja os Destaques e novidades do SUPER DVD Visual Basic (sempre atualizado) : clique e confira !

Quer migrar para o VB .NET ?

Quer aprender C# ??

Quer aprender os conceitos da Programação Orientada a objetos ?

Quer aprender o gerar relatórios com o ReportViewer no VS 2013 ?

Quer aprender a criar aplicações Web Dinâmicas usando a ASP .NET MVC 5 ?

 

  Gostou ?   Compartilhe no Facebook   Compartilhe no Twitter

Referências:

José Carlos Macoratti