Mensagens de erro customizadas no ASP.NET Web API

Embora relegado a um segundo plano, o tratamento de erros representa uma questão de fundamental importância nos mais variados sistemas de software. Por mais que num primeiro momento esta prática remeta à exibição de mensagens de alerta e ao logging de falhas ocorridas em um programa, existem outros tipos de ações que precisam ser levadas em conta na implementação de aplicações.

No caso específico dos Web Services, isto passa pela geração de informações reportando erros ou estados inválidos durante a execução de alguma operação. A padronização no detalhamento de uma falha facilitará o trabalho em outras soluções que dependam de um serviço, simplificando a implementação de funcionalidades que se comportam de maneira consistente diante da ocorrência de problemas.

O objetivo deste artigo é demonstrar, em termos gerais, como mensagens de erro podem ser retornadas a partir das Actions em uma aplicação ASP.NET Web API. Para que isto aconteça, estaremos retomando um exemplo criado em um post anterior, no qual foi implementado um serviço Web API para a conversão de temperaturas em graus Celsius para as escalas Fahrenheit e Kelvin:

http://www.tiselvagem.com.br/geral/tipos-anonimos-asp-net-web-api/

Alterando o serviço de conversão de temperaturas

A ideia com este novo artigo é que a aplicação TesteWebAPI.TiposAnonimos efetue a validação de temperaturas informadas como parâmetro ao se invocar o serviço de conversão. Se o valor em questão for inferior a -273,15 graus Celsius (zero absoluto), um erro com uma mensagem clara e em português deverá ser retornado pelo Web Service.

O download da solução que contém os projetos apresentados neste post pode ser realizado através do link:

https://github.com/renatogroffe/TesteWebAPI-TiposAnonimos

Na Listagem 1 é possível observar o método Get do Controller ConversorTemperaturaController já modificado, de forma a contemplar a validação das temperaturas:
– Se a temperatura for um valor menor do que o zero absoluto, uma nova instância do tipo HttpResponseMessage (namespace System.Net.Http) será gerada;
– O construtor de HttpResponseMessage recebe como parâmetro um valor definido no enum HttpStatusCode (namespace System.Net). Neste exemplo específico, o valor HttpStatusCode.BadRequest corresponde ao erro HTTP de código 400;
– Estão sendo preenchidas ainda as propriedades Content (conteúdo da mensagem de erro, sendo que se utilizou aqui um alerta genérico) e ReasonPhrase (mensagem que geralmente detalha a razão que originou um erro), para a nova referência da classe HttpResponseMessage;
– Por fim, uma exceção baseada no tipo HttpResponseException (namespace System.Web.Http) é disparada, com o objeto em questão recebendo como parâmetro em seu construtor a instância de HttpResponseMessage criada anteriormente.

Listagem 1: Classe ConversorTemperaturaController já contemplando o tratamento de erros

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace TesteWebAPI.TiposAnonimos.Controllers
{
    public class ConversorTemperaturaController : ApiController
    {
        public object Get(double grausCelsius)
        {
            if (grausCelsius < -273.15)
            {
                var resp = new HttpResponseMessage(HttpStatusCode.BadRequest)
                {
                    Content = new StringContent("Erro de processamento"),
                    ReasonPhrase = "Temperatura inferior a -273.15 graus Celsius."
                };

                throw new HttpResponseException(resp);
            }
            return new
            {
                Celsius = grausCelsius,
                Fahrenheit = ((9.0 / 5.0) * grausCelsius) + 32,
                Kelvin = grausCelsius + 273.15
            };
        }
    }
}

Testando o serviço Web API com o utilitário Fiddler

Um primeiro teste deste serviço será realizado a partir do utilitário Fiddler (Imagem 1). A intenção com tal procedimento é demonstrar o retorno produzido pelo serviço, considerando para isto um valor de temperatura inválido (-400 graus Celsius).

Imagem 1. Erro gerado a partir de um teste do serviço via utilitário Fiddler

Imagem 1. Erro gerado a partir de um teste do serviço via utilitário Fiddler

Consumindo o serviço criado via Javascript/jQuery

Nesta seção será detalhado como consumir o serviço de conversão de temperaturas a partir de código Javascript. O objetivo é demonstrar, em termos gerais, como erros gerados pelo serviço de exemplo podem ser tratados em instruções escritas em jQuery. Isto acontecerá através de uma aplicação chamada “TesteWebAPI.ConsumidorServico”, a qual foi criada com base no framework ASP.NET MVC 5.2.

O primeiro dos ajustes a ser realizado no projeto MVC consiste na criação um item de configuração (“UrlServicoConversaoTemperatura”), em que constará a URL do serviço de testes. Na Listagem 2 é possível observar o arquivo Web.config já contemplando esta nova configuração.

Listagem 2: Arquivo Web.config do projeto TesteWebAPI.ConsumidorServico

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>

    ...

    <add key="UrlServicoConversaoTemperatura"
         value="http://localhost:54883/api/ConversorTemperatura" />
  </appSettings>

  ...

</configuration>

O Controller HomeController também deverá ser alterado, de forma que se associe ao objeto ViewBag a URL para acesso ao Web Service de conversão de temperaturas (Listagem 3). Esta configuração será utilizada pela View Index, durante o envio de requisições ao serviço de testes.

Listagem 3: Classe HomeController

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Configuration;

namespace TesteWebAPI.ConsumidorServico.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            ViewBag.UrlServicoConversaoTemperatura =
                ConfigurationManager
                    .AppSettings["UrlServicoConversaoTemperatura"];
            return View();
        }

        public ActionResult About()
        {
            return View();
        }

        public ActionResult Contact()
        {
            return View();
        }
    }
}

O acesso ao Web Service de conversão de temperaturas acontecerá na View Index.cshtml (Listagem 4). Analisando a estrutura deste arquivo nota-se:
– A presença de um campo para o preenchimento da temperatura (gerado através da tag input);
– Um link que deverá ser acionado para a conversão da temperatura, com este elemento invocando uma função Javascript chamada “converterTemperatura” a partir do evento onclick;
– A função $(document).ready, que será disparada logo após o carregamento da página. Dentro deste método está sendo utilizado o plugin autoNumeric, de forma a permitir apenas valores númericos no campo para preenchimento da temperatura.

Quanto à forma como a função converterTemperatura, é possível observar:
– Uma verificação logo no início deste método, com o objetivo de forçar o preenchimento da temperatura antes do envio de uma requisição ao serviço de conversão;
– A montagem da URL a partir da temperatura fornecida por um usuário, fazendo uso ainda para isto do endereço associado à propriedade ViewBag;
– Uma chamada via instrução jQuery ao método do serviço Web API responsável pela conversão da temperatura. Utilizando o comando $.ajax e a URL gerada no passo anterior, a operação Get definida no serviço Web API de país é acionada (de forma síncrona, ou seja, aguardando a execução completa do método, algo indicado por meio do parâmetro async). Caso este procedimento tenha sucesso, a função indicada em “success” exibirá uma mensagem com os valores equivalentes nas escalas Fahrenheit e Kelvin; do contrário a função especificada em “error” será executada, com a apresentação de uma mensagem em que constará a descrição de erro gerada pelo Web Service de testes.

Listagem 4: View Index.cshtml

<div class="jumbotron">
    <h1>ASP.NET Web API - Retornando mensagens de erro customizadas</h1>
    <p><a href="http://www.asp.net/web-api"
          class="btn btn-primary btn-lg">Saiba mais &raquo;</a></p>
</div>

<div style="padding: 20px;">
    <p class="lead">
        Digite a temperatura em graus Celsius a ser convertida:
        <input id="temperatura" class="form-control text-right" />
    </p>
    <a class="btn btn-primary btn-lg"
       onclick="converterTemperatura();">Converter &raquo;</a>
</div>

@section scripts{

    <script type="text/javascript">

    function converterTemperatura() {
        var temperatura = $("#temperatura").val().replace(",", ".");
        if (temperatura == "") {
            alert("Informe um valor de temperatura para conversão!");
            return;
        }

        var urlConversao = "@ViewBag.UrlServicoConversaoTemperatura" +
            "?grausCelsius=" + temperatura;

        $.ajax({
            type: 'GET',
            url: urlConversao,
            dataType: 'json',
            cache: false,
            async: false,
            success: function (data) {
                alert("Temperatura por escala (em graus)\n\n" +
                    "Celsius: " + data.Celsius + "\n" +
                    "Fahrenheit: " + data.Fahrenheit + "\n" +
                    "Kelvin: " + data.Kelvin);
            },
            error: function (xhr, status, error) {
                alert(error);
            }
        });
    }


    $(document).ready(function () {
        $("#temperatura").autoNumeric({
            aSep: '',
            aDec: ',',
            mDec: '2',
            vMin: '-999999999.99',
            vMax: '999999999.99'
        });
    });

    </script>
}

Na Imagem 2 está a tela exibida inicialmente ao se executar a aplicação TesteWebAPI.ConsumidorServico.

Imagem 2. Tela inicial da aplicação TesteWebAPI.ConsumidorServico

Imagem 2. Tela inicial da aplicação TesteWebAPI.ConsumidorServico

Um exemplo de conversão de um valor válido de temperatura é apresentado na Imagem 3.

Imagem 3. Temperatura convertida com sucesso

Imagem 3. Temperatura convertida com sucesso

Por fim, na Imagem 4 está o alerta gerado para valores inválidos de temperatura.

Imagem 4. Erro apresentado na tentativa de conversão de uma temperatura inválida

Imagem 4. Erro apresentado na tentativa de conversão de uma temperatura inválida

Conclusão

A intenção deste post foi demonstrar como mensagens de erros customizadas podem ser geradas em serviços construídos com o ASP.NET Web API. Indicar com clareza problemas e/ou estados inválidos em Web Services é um ponto extremamente importante, já que esta prática fornece às aplicações consumidoras informações detalhando condições inesperadas.

Espero que este post possa ser útil.

Até uma próxima oportunidade!

Renato Groffe – Consultor em TI, MCTS
http://rgroffe.wordpress.com/

Referências

ASP.NET Web API
http://www.asp.net/web-api

ASP.NET Web API: Implementando serviços RESTful
http://www.devmedia.com.br/asp-net-web-api-implementando-servicos-restful/31024

Criando máscaras numéricas em ASP.NET com jQuery
http://www.devmedia.com.br/criando-mascaras-numericas-em-asp-net-com-jquery/25565

HttpResponseMessage Class
http://msdn.microsoft.com/en-us/library/system.net.http.httpresponsemessage(v=vs.118).aspx

HttpStatusCode Enumeration
http://msdn.microsoft.com/en-us/library/system.net.httpstatuscode(v=vs.110).aspx

Utilitário Fiddler: Monitoramento de Web Services
http://www.devmedia.com.br/utilitario-fiddler-monitoramento-de-web-services/31274

Comentarios

comentarios

One Response to Mensagens de erro customizadas no ASP.NET Web API
  1. […] - Mensagens de erro customizadas no ASP.NET Web API http://www.tiselvagem.com.br/geral/mensagens-de-... tiselvagem.com.br/geral/desativando-xml-servicos-web-api