Comment se connecter à un serveur HTTP à l’aide de Windows.Web.Http (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 ]

Vous pouvez envoyer une requête GET à un service Web et extraire la réponse à l’aide de la classe Windows.Web.Http.HttpClient dans l’espace de noms Windows.Web.Http.

[Obtenir l’exemple HTTPClient maintenant.]

Les classes incluses dans l’espace de noms Windows.Web.Http offrent une interface de programmation pour les applications clientes HTTP modernes. L’espace de noms Windows.Web.Http et les espaces de noms associés Windows.Web.Http.Headers et Windows.Web.Http.Filters fournissent des composants clients HTTP qui permettent aux utilisateurs d’effectuer des requêtes HTTP et de recevoir des requêtes HTTP à partir de services Web modernes sur HTTP.

Windows 8.1 introduit Windows.Web.Http, l’espace de noms Windows Runtime à utiliser pour les applications Windows qui se connectent à des services Web HTTP et REST (Representational State Transfer). Cette nouvelle API prend en charge des fonctionnalités complètes sur l’ensemble des langages pris en charge et remplace l’API HTTP initialement publiée pour Windows 8.

Cette nouvelle API remplace les trois API aux fonctionnalités différentes qui étaient auparavant nécessaires pour chaque projection de langage dans Windows 8.

WinJS.xhr pour JavaScript
System.Net.Http.HttpClient dans l’espace de noms System.Net.Http pour C# et VB.Remarque Non pris en charge sur Windows Phone.
XML HTTP Extended Request (IXMLHTTPRequest2) pour C++

Pour les opérations de requête élémentaires, la nouvelle API présente une interface simple permettant de gérer les tâches les plus courantes et fournit des paramètres par défaut judicieux pour l’authentification (AUTH) qui s’appliquent à la plupart des scénarios. Pour les opérations HTTP plus complexes, les fonctionnalités suivantes ont été ajoutées :

méthodes pour les verbes courants (DELETE, GET, PUT et POST) ;
prise en charge des modèles et paramètres d’authentification courants ;
accès aux détails SSL (Secure Sockets Layer) sur le transport ;
capacité à inclure des filtres personnalisés dans les applications avancées ;
capacité à obtenir, définir et supprimer des cookies ;
informations de progression de requête HTTP disponibles sur les méthodes asynchrones.

La classe Windows.Web.Http.HttpClient sert à envoyer et à recevoir des requêtes de base sur HTTP. Il s’agit de la classe principale pour l’envoi de requêtes HTTP et la réception de réponses HTTP depuis une source identifiée par un URI (Uniform Resource Identifier). Vous pouvez utiliser cette classe pour transmettre une requête GET, PUT, POST, DELETE ou toute autre requête à un service Web. Chacune de ces requêtes est envoyée dans le cadre d’une opération asynchrone.

La classe Windows.Web.Http.HttpRequestMessage représente un message de requête HTTP envoyé par Windows.Web.Http.HttpClient. La classe Windows.Web.Http.HttpResponseMessage représente un message de réponse HTTP reçu d’une requête HTTP. Les messages HTTP sont définis par la norme RFC 2616 de l’IETF (Internet Engineering Task Force).

L’espace de noms Windows.Web.Http fournit différentes classes qui représentent le contenu HTTP (le corps d’entité HTTP et les en-têtes de contenu, y compris les cookies) associé à une requête HTTP ou à une réponse HTTP. Trois classes différentes permettent au contenu d’utiliser une mémoire tampon, une chaîne, un flux, ainsi que des données nom/valeur codées avec le type MIME application/x-www-form-urlencoded, le type MIME multipart/* et le type MIME multipart/form-data. Vous pouvez également définir du contenu personnalisé.

Dans cet exemple, la classe HttpStringContent sert à représenter la réponse HTTP sous forme de chaîne.

L’espace de noms Windows.Web.Http.Headers prend en charge la création de cookies et d’en-têtes HTTP, qui sont ensuite associés comme propriétés aux objets HttpRequestMessage et HttpResponseMessage.

Prérequis

Les exemples suivants dans cette rubrique sont en langage JavaScript et HTML. Une connaissance de base des requêtes HTTP telles qu’elles sont détaillées dans la norme RFC 2616 est nécessaire.

Vous pouvez aussi effectuer des requêtes HTTP dans une application en JavaScript et HTML à l’aide de WinJS.xhr et XMLHttpRequest. Pour plus d’informations, voir Connexion à un service web (applications Windows Runtime en JavaScript).

Instructions

Étape 1: Créer un projet

Ouvrez Microsoft Visual Studio 2013 et sélectionnez Nouveau projet dans le menu Fichier.
Dans la liste des modèles, choisissez JavaScript.
Sous la section, choisissez Store apps.
Sous la section, sélectionnez Universal Apps, Windows apps, ou Windows Phone apps (en fonction de votre plateforme cible), puis Application vide.
Nommez l’application HttpClientGet et cliquez sur OK.

Étape 2: Définir les fonctionnalités pour activer l’accès réseau

Vous devez définir les fonctionnalités réseau de votre application pour autoriser l’accès à un réseau domestique privé, un réseau professionnel ou à Internet. Pour cette application, vous devez normalement activer les fonctionnalités réseau puisque le client est connecté aux services Web.

Pour qu’une application utilisant la classe Windows.Web.Http.HttpClient puisse se connecter à un service Web sur un autre ordinateur, il faut que les capacités réseau soient définies pour cette application. Si l’application doit pouvoir se connecter en qualité de client à un service Web sur Internet, la fonctionnalité Internet (client) est nécessaire. Si l’application doit pouvoir se connecter en qualité de client à des services Web sur un réseau domestique privé ou un réseau professionnel, la capacité Réseaux privés (client et serveur) est requise.

Remarque Sur Windows Phone, il existe une seule fonctionnalité réseau (Internet (client et serveur), qui active tout l’accès réseau pour l’application.

Si le service Web est exécuté sur le même ordinateur que l’application, ceci nécessite un accès en boucle. Les applications développées et exécutées dans Visual Studio 2013 sont automatiquement inscrites comme n’étant pas concernées par les restrictions de bouclage. Pour plus d’informations, voir Comment activer le bouclage et déboguer l’isolement réseau.

Pour plus d’informations sur l’accès réseau, voir Comment configurer les fonctionnalités réseau.

Ces étapes sont nécessaires pour définir les fonctionnalités réseau d’une application avant son déploiement si elle accède à un service Web sur Internet ou sur un réseau privé ou professionnel.

Utilisez Visual Studio 2013 pour ouvrir le fichier package.appxmanifest.
Sélectionnez l’onglet Capacités.
Pour générer la version Windows de l’exemple, sélectionnez les fonctionnalités Internet (client) et Réseaux privés (client et serveur).

Pour générer la version Windows Phone de cet exemple, sélectionnez la fonctionnalité Internet (client et serveur).
Enregistrez et fermez le fichier manifeste.

Étape 3: Ajouter une interface utilisateur HTML

Dans cette section, nous définissons la structure des applications en HTML pour spécifier la taille et la position approximatives de chaque objet dans l’application. Nous complétons l’interface utilisateur de l’application en ajoutant des contrôles et du contenu pour afficher les données.

Cet exemple utilise des éléments d’interface utilisateur HTML parmi lesquels :

un contrôle avec class utilisé pour une étiquette de texte et le champ d’entrée pour l’adresse URI d’entrée et un button utilisé pour démarrer la requête asynchrone ;
un contrôle avec class avec une étiquette de texte et un champ de texte pour afficher l’état actuel. C’est à cet emplacement que les messages d’état et d’erreur sont affichés. Ce contrôle contient également un élément class où les données en sortie reçues du service Web sont affichées. Dans cet exemple, le résultat de l’opération GET HTTP est affiché sous la forme de texte brut contenant le balisage HTML.

Ouvrez le dossier js, ouvrez le fichier default.js existant et ajoutez-y les éléments d’interface utilisateur suivants.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>HttpClientGet</title>

    <!-- WinJS references - Windows -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <!-- WinJS references - Phone -->
    <link href="/css/ui-themed.css" rel="stylesheet" />
    <script src="//Microsoft.Phone.WinJS.2.1/js/base.js"></script>
    <script src="//Microsoft.Phone.WinJS.2.1/js/ui.js"></script>

    <!-- HttpClientGet references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
    <script src="/js/mainpage.js"></script>
</head>

<body>
    <div data-win-control="SampleInput">
        <p> Download the contents of a page and display it. </p>
        <p class="clear">
            <label for="inputAddress">URI Address:</label>
            <input type="text" id="inputAddress" value="https://www.contoso.com" />
        </p>
        <p>
            <button id="startButton">Start</button>
        </p>
    </div>
    <div data-win-control="SampleOutput">
        <p class="clear">
            <label for="statusText">Status:</label>
            <input type="text" id="statusText" value="" />
        </p>
        <textarea id="outputView"></textarea>
    </div>
</body>
</html>

Étape 4: Créer le HttpClient

Tout d’abord, créez l’objet Windows.Web.Http.HttpClient et ajoutez un en-tête d’agent utilisateur.

Par défaut, aucun en-tête d’agent utilisateur n’est envoyé avec la requête HTTP au service Web par l’objet HttpClient. Certains serveurs HTTP, y compris certains serveurs Web Microsoft, nécessitent qu’un en-tête d’agent utilisateur soit fourni avec la requête HTTP envoyée à partir du client. Le serveur HTTP renvoie une erreur si aucun en-tête n’est présent. Nous devons ajouter un en-tête d’agent utilisateur à l’aide de classes dans l’espace de noms Windows.Web.Http.Headers. Nous ajoutons cet en-tête à la propriété HttpClient.DefaultRequestHeaders pour éviter ces erreurs.

Ouvrez le dossier js, ajoutez un nouveau fichier mainpage.js et ajoutez-y le code suivant.

(function () {
    "use strict";

    var httpClient;
    var httpPromise;

    var page = WinJS.UI.Pages.define("/html/mainpage.html", {
        ready: function (element, options) {
            document.getElementById("startButton").addEventListener("click", start, false);

            httpClient = new Windows.Web.Http.HttpClient();

            // Add a user-agent header
            headers = httpClient.defaultRequestHeaders;

            // UserAgent is a HttpProductInfoHeaderValueCollection
            // A collection of HttpProductInfoHeaderValue items

            // The safe way to check a header value from the user is the TryParseAdd method
            // Since we know this header is okay, we use ParseAdd with will throw an exception
            // with a bad value 

            headers.userAgent.parseAdd("ie");
            headers.userAgent.parseAdd("Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)");
        }
    });
})();

Ouvrez le dossier js et le fichier default.js et ajoutez-y le code suivant.

(// For an introduction to the Blank template, see the following documentation:
// https://go.microsoft.com/fwlink/p/?LinkID=232509
(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                startButton.onclick = start;

            } else {
                startButton.onclick = start;
            }
            args.setPromise(WinJS.UI.processAll());
        }
    };

    app.oncheckpoint = function (args) {
        // This application is about to be suspended. Save any state
        // that needs to persist across suspensions here. You might use the
        // WinJS.Application.sessionState object, which is automatically
        // saved and restored across suspension. If you need to complete an
        // asynchronous operation before your application is suspended, call
        // args.setPromise().
    };

    app.start();
})();

Étape 5: Envoyer la requête GET et recevoir la réponse

En cas de clic sur le bouton Démarrer, nous vérifions d’abord que l’URI spécifié dans inputAddress est valide. Ensuite, nous envoyons la requête GET à l’aide de l’URI et nous attendons de recevoir la réponse du serveur HTTP.

La plupart des tâches sont réalisées dans le gestionnaire d’événements de clic du bouton (Button) de démarrage. En cas de clic sur ce bouton, le texte des éléments d’interface utilisateur statusText et outputView est mis à jour. L’adresse d’URI d’entrée est tout d’abord vérifiée pour s’assurer que l’utilisateur a transmis une adresse URI valide. Si c’est le cas, l’application envoie la requête GET HTTP à l’URI spécifié et attend la réponse HTTP. Si une erreur ou une exception survient, les résultats s’affichent dans l’élément d’interface utilisateur statusText. En l’absence d’erreur, la réponse donnée par le service Web apparaît dans l’élément outputView de l’interface utilisateur.

Une exception est levée quand une chaîne d’URI non valide est transmise au constructeur pour l’objet Windows.Foundation.Uri.

En JavaScript, il n’existe aucune méthode pour essayer d’analyser une chaîne en URI. Pour intercepter cette exception dans ce cas, utilisez un bloc try/catch autour du code où l’URI est construit.

L’exemple vérifie également que le schéma HTTP dans l’URI est HTTP ou HTTPS, puisqu’il s’agit des seuls schémas pris en charge par Windows.Web.Http.HttpClient.

Avec les mots clés then et done en JavaScript, le code permettant d’envoyer la requête GET et de récupérer la réponse de manière asynchrone équivaut au code que nous utiliserions pour mener cette opération de manière synchrone.

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. Pour plus d’informations sur la gestion des exceptions réseau, voir Gestion des exceptions dans les applications réseau.

La méthode HttpResponse.EnsureSuccessStatusCode lève une exception si le serveur Web a renvoyé un code d’état d’erreur HTTP, un HttpResponse.StatusCode situé en dehors de la plage Successful (200-299) pour la requête. Nous utilisons un bloc try/catch pour toutes les exceptions et nous affichons le message d’exception dans l’élément statusText de l’interface utilisateur si une erreur se produit.

La propriété HttpResponse.Content désigne le contenu de la réponse HTTP. La méthode HttpClient.GetAsync(Uri) lit le contenu HTTP dans une chaîne par une opération asynchrone. Nous remplaçons toutes les balises <br> présentes dans le code HTML renvoyé par de nouvelles lignes à des fins d’affichage. Si la méthode réussit, nous affichons le HttpResponse.StatusCode dans l’élément d’interface utilisateur statusText et le HttpResponse.Content renvoyé par le service Web dans l’élément d’interface utilisateur outputView.

Ouvrez le dossier js et ajoutez le code suivant au fichier mainpage.js.
```
    function start()
    {

        var response = new Windows.Web.Http.HttpResponseMessage();

        var statusText = document.getElementById("statusText");
        var outputView = document.getElementById("outputView");

        // The value of 'inputAddress' is set by the user 
        // and is therefore untrusted input. 
        // If we can't create a valid absolute URI, 
        // We notify the user about the incorrect input.

        statusText.Text = "Testing URI is valid.";

        var uriString = document.getElementById("inputAddress").value.trim();
        if (!uriString) {
            return;
        }

        var resourceUri;
        try {
           resourceUri = new Windows.Foundation.Uri(uriString);
        }
        catch (Exception) {
            statusText.Text = "Invalid URI, please re-enter a valid URI.";
            return;
        }

        if (resourceUri.schemeName != "http" && resourceUri.schemeName != "https") {
            statusText.Text = "Only 'http' and 'https' schemes supported. Please re-enter URI";
            return;
        }

        var responseBodyAsText="";
        outputView.Text = "";
        statusText.Text = "Waiting for response ...";

        httpPromise = httpClient.getAsync(resourceUri).then(function (response) {
            outputStatus = response.statusCode + " " + response.reasonPhrase;

            response.EnsureSuccessStatusCode();

            response.content.readAsStringAsync().then(function (responseBodyAsText) {
            // Format the HTTP response to display better
            responseBodyAsText = responseBodyAsText.replace(/<br>/g, "\r\n");
            outputView.value = responseBodyAsText;
            return response;
        });
    )};

    httpPromise.done(function (response) {
        statusText.value = response.StatusCode + " " + response.ReasonPhrase + "\r\n";
    }, onError);

    function onError(error) {
        statusText.value = "Error = " + error.number + "  Message: " + error.message;
    }

})();
```
Windows.Web.Http.HttpClient utilise WinInet pour envoyer des requêtes de service Web et HTTP et pour recevoir des réponses. La valeur de délai d’expiration par défaut utilisée par WinInet pour une opération de connexion HTTP est de 60 secondes. Si un serveur HTTP ou un service Web est momentanément défaillant ou bloqué par un pare-feu et que le serveur ne répond pas ou ne peut pas répondre à la requête Windows.Web.Http.HttpClient, WinInet patiente pendant 60 secondes avant de renvoyer une erreur qui génère une exception dans l’application. Si la requête de nom pour un nom de serveur HTTP renvoie plusieurs adresses IP, WinInet essaie plusieurs des autres adresses IP pour le site, chacune avec un délai d’expiration de 60 secondes. Une application qui effectue une requête HTTP ou de service Web risque de consacrer plusieurs minutes à réessayer avec plusieurs adresses IP avant qu’une erreur soit renvoyée par WinInet et qu’une exception soit levée. Ce comportement pourrait faire croire à l’utilisateur que l’application a cessé de fonctionner. Le délai d’expiration par défaut utilisé par WinInet pour les opérations d’envoi et de réception après l’établissement d’une connexion est de 30 secondes.

Pour augmenter la réactivité de l’application et limiter ce genre de problème, vous pouvez réduire le délai d’expiration pour les opérations Windows.Web.Http.HttpClient, afin que celles-ci échouent plus rapidement, par rapport aux paramètres par défaut de WinInet. Pour plus d’informations sur la façon de définir un délai d’expiration, voir Définition de valeurs de temporisation avec WinJS.xhr ou HttpClient et Comment définir des délais d’attente sur les opérations de socket.

Remarques

Dans cette rubrique, nous avons vu comment utiliser la classe Windows.Web.Http.HttpClient pour envoyer une requête GET à un service Web et récupérer la réponse à l’aide des classes Windows.Web.Http.HttpResponseMessage et des classes associées dans l’espace de noms Windows.Web.Http.Headers.