Comment gérer les exceptions dans les applications réseau (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Cette rubrique explique comment gérer les exceptions lorsque des API de réseau sont utilisées dans une application du Windows Store écrite en JavaScript et HTML.

Ce que vous devez savoir

Technologies

Windows.Networking.Sockets

Autorise les communications réseau à l’aide de sockets et de WebSockets.
Windows.Web.Http

Fournit une API cliente HTTP et REST moderne pour les applications du Windows Store.

Prérequis

Les informations suivantes s’appliquent aux applications du Windows Store qui utilisent des API de réseau pour établir des connexions distantes. Cette rubrique concerne les applications écrites en JavaScript et HTML pour Windows 8.1, Windows Phone 8.1 ou Windows Server 2012 R2.

Pour plus d’informations sur la gestion des exceptions dans les applications du Windows Store écrites en C++/XAML et les applications utilisant .NET Framework 4.5 en C#, VB.NET ou C++ managé pour Windows 8.1, Windows Phone 8.1 ou Windows Server 2012 R2, voir Gestion des exceptions dans les applications réseau.

Exceptions dans les applications réseau

Une exception qui se produit dans une application est le signe de l’existence d’un problème ou d’une défaillance de taille. Les exceptions peuvent se produire pour diverses raisons. Votre code peut présenter des lacunes à l’origine d’une exception. Dans d’autres cas, notamment avec les API de réseau, l’exception peut être imputable à des changements dans la connectivité réseau et à d’autres problèmes réseau.

Les exceptions liées à l’utilisation d’API de réseau peuvent avoir les causes suivantes :

erreur de validation de paramètre ;
échec de résolution de nom lors de la recherche d’un nom d’hôte ou d’un URI ;
perte de connectivité réseau ;
échec de connexion réseau lors de l’utilisation de sockets et d’API clientes HTTP ;
erreur de serveur réseau ou de point de terminaison distant ;
diverses erreurs réseau.

Des exceptions liées à des erreurs réseau (perte de connectivité, échec de connexion et échec de serveur HTTP, par exemple) peuvent se produire à tout moment. Ces erreurs donnent lieu à la levée d’exceptions. Si votre application ne gère pas une exception, le runtime peut arrêter entièrement votre application.

Vous devez écrire du code capable de gérer les exceptions au moment où vous appelez la plupart des méthodes réseau asynchrones. Parfois, quand une exception se produit, vous pouvez essayer de résoudre le problème en rappelant une méthode réseau. Dans d’autres cas, votre application doit pouvoir poursuivre sans connectivité réseau en utilisant les données préalablement mises en cache.

Les applications Windows Runtime lèvent généralement une seule exception. Votre gestionnaire d’exceptions peut récupérer des informations plus détaillées sur la cause de l’exception dans le but d’analyser l’échec et de prendre des décisions appropriées.

JavaScript prend en charge une méthode permettant d’accéder à ces informations plus détaillées. Une exception est projetée en tant que valeur HRESULT dans les applications Windows Runtime. Le fichier include Winerror.h contient une très grande liste de valeurs HRESULT possibles qui comprend des erreurs réseau.

Les API de réseau prennent en charge différentes méthodes permettant de récupérer ces informations détaillées sur la cause d’une exception :

une méthode d’assistance qui convertir la valeur HRESULT de l’exception en valeur d’énumération ;
la méthode brute selon le langage utilisé pour récupérer la valeur HRESULT.

Exceptions dans Windows.Networking.Sockets

L’espace de noms Windows.Networking.Sockets propose des méthodes et des énumérations d’assistance pratiques qui permettent de gérer les erreurs lorsque des sockets et des WebSockets sont utilisés. Ceci peut s’avérer utile pour gérer différemment certaines exceptions réseau dans votre application.

Une erreur rencontrée dans une opération DatagramSocket, StreamSocket ou StreamSocketListener est renvoyée sous forme de valeur HRESULT. La méthode SocketError.GetStatus sert à convertir une erreur réseau résultant d’une opération de socket en valeur d’énumération SocketErrorStatus. La plupart des valeurs d’énumération SocketErrorStatus correspondent à une erreur renvoyée par l’opération de socket Windows native. Une application peut filtrer des valeurs d’énumération SocketErrorStatus spécifiques pour modifier son comportement en fonction de la cause de l’exception.

Une erreur rencontrée dans une opération MessageWebSocket ou StreamWebSocket est renvoyée sous forme de valeur HRESULT. La méthode WebSocketError.GetStatus sert à convertir une erreur réseau d’opération résultant d’une opération WebSocket en valeur d’énumération WebErrorStatus. La plupart des valeurs d’énumération WebErrorStatus correspondent à une erreur renvoyée par l’opération cliente HTTP native. Une application peut filtrer des valeurs d’énumération WebErrorStatus spécifiques pour modifier son comportement en fonction de la cause de l’exception.

L’exemple de code suivant montre comment filtrer sur une exception à l’aide de l’énumération 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);
    }
}

Pour les erreurs de validation de paramètre, une application peut également utiliser la valeur HRESULT à partir de l’exception pour obtenir des informations plus détaillées sur l’erreur à l’origine de l’exception. Quand une exception se produit dans une application en JavaScript et que cette application est en cours d’exécution, l’objet Error représente une erreur. La propriété Error.number renvoie la valeur HRESULT affectée à l’exception spécifique. Les valeurs HRESULT possibles sont répertoriées dans le fichier d’en-tête Winerror.h. Pour la plupart des erreurs de validation de paramètre, la valeur HRESULT retournée est E_INVALIDARG.

Exceptions dans Windows.Networking.BackgroundTransfer

L’espace de noms Windows.Networking.backgroundTransfer propose des méthodes d’assistance pratiques et utilise des énumérations dans l’espace de noms Windows.Networking.Sockets pour la gestion des erreurs. Ceci peut s’avérer utile pour gérer différemment certaines exceptions réseau dans votre application.

Une erreur rencontrée sur une méthode asynchrone dans l’espace de noms Windows.Networking.backgroundTransfer est retournée en tant que valeur HRESULT. La méthode BackgroundTransferError.GetStatus sert à convertir une erreur réseau résultant d’une opération de transfert en arrière-plan en valeur d’énumération WebErrorStatus. La plupart des valeurs d’énumération WebErrorStatus correspondent à une erreur retournée par l’opération cliente HTTP ou FTP native. Une application peut filtrer sur des valeurs d’énumération WebErrorStatus spécifiques pour modifier son comportement en fonction de la cause de l’exception.

Exceptions dans Windows.Web.Http

L’espace de noms Windows.Web.Http est dépourvu d’une fonction pratique. De ce fait, une application utilisant HttpClient et les autres classes de cet espace de noms doit utiliser la valeur HRESULT.

Quand une exception se produit dans une application en JavaScript et que cette application est en cours d’exécution, l’objet Error représente une erreur. La propriété Error.number renvoie la valeur HRESULT affectée à l’exception spécifique. La propriété Error.description renvoie le message de description de l’exception. Toutefois, il peut manquer une valeur à certaines exceptions pour la propriété Error.description. La plupart des valeurs HRESULT possibles sont répertoriées dans le fichier d’en-tête Winerror.h. Une application peut filtrer sur des valeurs HRESULT spécifiques pour modifier son comportement en fonction de la cause de l’exception.

Pour la plupart des erreurs de validation de paramètre, la valeur HRESULT retournée est E_INVALIDARG. Pour certains appels de méthodes non conformes, la valeur HRESULT retournée est E_ILLEGAL_METHOD_CALL.

L’exemple de code suivant montre comment filtrer sur une exception à l’aide de la valeur 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);
    }
}