Como resolver exceções em aplicativos de rede (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Este tópico explica como resolver exceções durante o uso de APIs de rede no aplicativo da Windows Store em JavaScript e HTML.

O que você precisa saber

Tecnologias

Windows.Networking.Sockets

Habilita comunicações de rede usando soquetes e WebSockets.
Windows.Web.Http

Oferece uma API moderna de cliente HTTP e REST para aplicativos da Windows Store.

Pré-requisitos

As informações a seguir são válidas para os aplicativos da Windows Store que usam APIs de rede para estabelecer conexões remotas. Este tópico aplica-se a aplicativos escritos em JavaScript e HTML para o Windows 8.1, Windows Phone 8.1 ou Windows Server 2012 R2.

Para saber mais sobre como lidar com exceções de aplicativos da Windows Store escritos em C++/XAML e sobre aplicativos que usam o .NET Framework 4.5 em C#, VB.NET ou C++ gerenciado para o Windows 8.1, Windows Phone 8.1 ou Windows Server 2012 R2, consulte Lidando com exceções de aplicativos de rede.

Exceções em aplicativos de rede

Uma exceção em algum aplicativo pode indicar um problema ou falha grave. As exceções podem ser causadas por diversos motivos. Pode haver problemas em seu código que provoquem a exceção. Às vezes, principalmente ao usar APIs de rede, a exceção pode ser resultado de alterações na conectividade de rede e de outros problemas de rede.

Veja a seguir alguns motivos de exceções ao usar APIs de rede:

Erros de validação de parâmetro
Falha nas resoluções de nomes durante a pesquisa por nome de host ou URI
Perda de conectividade de rede
Falhas na conexão de rede ao usar soquetes e APIs de cliente HTTP
Erros de servidor de rede ou ponto de extremidade remoto
Diversos erros de rede

As exceções por causa de erros de rede (perda de conectividade, falhas na conexão e no servidor HTTP, por exemplo) podem acontecer a qualquer momento. Esses erros geram as exceções. Quando não é resolvida pelo aplicativo, a exceção pode fazer seu aplicativo inteiro ser terminado pelo tempo de execução.

Desenvolva códigos para resolver exceções quando você chamar a maioria dos métodos de rede assíncronos. Às vezes, quando acontece uma exceção, um método de rede pode ser repetido para tentar resolver o problema. Outras vezes, o aplicativo tem de se planejar para continuar sem conectividade de rede, usando os dados que já foram armazenados em cache.

Geralmente, os aplicativos do Tempo de Execução do Windows geram uma única exceção. Seu manipulador de exceção recupera informações mais detalhadas sobre a causa da exceção para entender melhor a falha e tomar as medidas adequadas.

O JavaScript permite um método para acessar essas informações mais detalhadas. Uma exceção aparece como um valor HRESULT nos aplicativos do Tempo de Execução do Windows. O arquivo de inclusão Winerror.h contém uma lista bem grande de possíveis valores HRESULT que incluem erros de rede.

As APIs de rede permitem diferentes métodos de recuperação das informações detalhadas sobre a causa da exceção.

Um método auxiliar que converte o valor HRESULT da exceção em um valor de enumeração.
O método bruto que depende da linguagem usada para recuperar o valor HRESULT.

Exceções em Windows.Networking.Sockets

O namespace Windows.Networking.Sockets possui métodos auxiliares e enumerações práticas para resolver erros durante o uso de soquetes e WebSockets. Eles são úteis para resolver exceções de rede específicas de uma outra forma em seu aplicativo.

Um erro encontrado em uma operação DatagramSocket, StreamSocket ou StreamSocketListener é retornado como um valor HRESULT. O método SocketError.GetStatus é usado para converter um erro de rede de uma operação de soquete em um valor de enumeração SocketErrorStatus. A maioria dos valores de enumeração SocketErrorStatus corresponde a um erro retornado pela operação nativa de soquetes do Windows. Um aplicativo pode filtrar por um valor específico de enumeração SocketErrorStatus para modificar o comportamento do aplicativo, dependendo da causa da exceção.

Um erro encontrado em uma operação MessageWebSocket ou StreamWebSocket é retornado como um valor HRESULT. O método WebSocketError.GetStatus é usado para converter um erro de rede de uma operação WebSocket em um valor de enumeração WebErrorStatus. A maioria dos valores de enumeração WebErrorStatus corresponde a um erro retornado pela operação nativa de cliente HTTP. Um aplicativo pode filtrar por valores específicos de enumeração WebErrorStatus para modificar o comportamento do aplicativo, dependendo da causa da exceção.

O código de exemplo a seguir mostra como filtrar uma exceção usando a enumeração WebErrorStatus.

var uri = new Uri("https://www.contoso.com");
var messageWebSocket = new Windows.Networking.Sockets.MessageWebSocket();


// Always catch network exceptions for async methods
messageWebSocket.ConnectAsync(uri).done(function () {
        // get completed
    }, onError);

function onError(reason) {
    // Details in reason.message and reason.number       
    var errorStatus = Windows.Networking.Sockets.WebSocketError.getStatus(reason.number);
    if (errorStatus === Windows.Web.WebErrorStatus.cannotConnect || 
        errorStatus === Windows.Web.WebErrorStatus.notFound || 
        errorStatus === Windows.Web.WebErrorStatus.requestTimeout) {
        WinJS.log && WinJS.log("Cannot connect to the server");
    }
    else {
        WinJS.log && WinJS.log("Failed to connect: " + errorStatus);
    }
}

Para erros de validação de parâmetro, um aplicativo também pode usar o HRESULT baseado na exceção para obter informações mais detalhadas sobre o erro causador da exceção. Nos aplicativos em JavaScript, o objeto Error representa um erro na execução do aplicativo, quando há uma exceção. A propriedade Error.number retorna o HRESULT atribuído à exceção específica. Há uma lista dos possíveis valores HRESULT no arquivo de cabeçalho Winerror.h. Para a maioria dos erros de validação de parâmetro, o HRESULT retornado é E_INVALIDARG.

Exceções em Windows.Networking.BackgroundTransfer

O namespace Windows.Networking.backgroundTransfer tem os métodos auxiliares adequados e usa enumerações do namespace Windows.Networking.Sockets para lidar com os erros. Eles são úteis para resolver exceções de rede específicas de uma outra forma em seu aplicativo.

Um erro encontrado em um método assíncrono do namespace Windows.Networking.backgroundTransfer é retornado como um valor HRESULT. O método BackgroundTransferError.GetStatus é usado para converter um erro de rede de uma operação de transferência em segundo plano em um valor de enumeração WebErrorStatus. A maioria dos valores de enumeração WebErrorStatus corresponde a um erro retornado pela operação nativa de cliente HTTP ou FTP. Um aplicativo pode filtrar por valores específicos de enumeração WebErrorStatus para modificar o comportamento do aplicativo, dependendo da causa da exceção.

Exceções em Windows.Web.Http

O namespace Windows.Web.Http não tem uma função de praticidade. Por isso, o aplicativo que usa HttpClient e outras classes nesse namespace precisa usar o valor HRESULT.

Nos aplicativos em JavaScript, o objeto Error representa um erro na execução do aplicativo, quando há uma exceção. A propriedade Error.number retorna o HRESULT atribuído à exceção específica. A propriedade Error.description retorna a mensagem que descreve a exceção. Entretanto, algumas exceções podem não ter um valor para a propriedade Error.description . A maioria dos possíveis valores HRESULT estão listados no arquivo de cabeçalho Winerror.h. Um aplicativo pode filtrar por valores específicos HRESULT para modificar o comportamento do aplicativo, dependendo da causa da exceção.

Para a maioria dos erros de validação de parâmetro, o HRESULT retornado é E_INVALIDARG. Para algumas chamadas de método ilícitas, o HRESULT retornado é E_ILLEGAL_METHOD_CALL.

O código de exemplo a seguir mostra como filtrar uma exceção usando HRESULT.

var uri = new Uri("http://example.com/datalist.aspx");
var httpClient = new HttpClient();

// Always catch network exceptions for async methods
httpClient.GetStringAsync(uri).done(function () {
        // get completed
    }, onError);


function onError(reason) {
    // Details in error.message and error.number       
    var errorStatus = reason.number;
    if (errorStatus === INET_E_RESOURCE_NOT_FOUND || 
        errorStatus === INET_E_CANNOT_CONNECT ) {
        WinJS.log && WinJS.log("Cannot connect to the server");
    }
    else {
        WinJS.log && WinJS.log("Failed to connect: " + errorStatus);
    }
}