HttpClient

API importantes

• HttpClient
• Windows. Web.Http
• Windows. Web.Http.HttpResponseMessage

Utilisez HttpClient et le reste de la Windows. API d’espace de noms Web.Http pour envoyer et recevoir des informations à l’aide des protocoles HTTP 2.0 et HTTP 1.1.

Vue d’ensemble de HttpClient et de l’espace de noms Windows.Web.Http

Les classes de l’espace de noms Windows.Web.Http ainsi que des espaces de noms connexes Windows.Web.Http.Headers et Windows.Web.Http.Filters fournissent une interface de programmation pour les applications Windows qui agissent comme clients HTTP afin d’effectuer des requêtes GET de base ou d’implémenter des fonctionnalités HTTP plus avancées décrites ci-dessous.

• Méthodes pour les verbes courants (DELETE, GET, PUT et POST). Chacune de ces demandes est envoyée en tant qu’opération asynchrone.

• Prise en charge des paramètres et modèles d’authentification courants.

• Accès aux détails SSL (Secure Sockets Layer) sur le transport.

• Possibilité d’inclure des filtres personnalisés dans des applications avancées.

• Possibilité d’obtenir, de définir et de supprimer des cookies.

• Informations de progression de la requête HTTP disponibles sur les méthodes asynchrones.

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 en réponse à une requête HTTP. Les messages HTTP sont définis dans RFC 2616 par l’IETF.

L’espace de noms Windows.Web.Http représente le contenu HTTP sous forme de corps et d’en-têtes d’entité HTTP, y compris les cookies. Le contenu HTTP peut être associé à une requête HTTP ou à une réponse HTTP. L’espace de noms Windows.Web.Http fournit différentes classes pour représenter du contenu HTTP.

• HttpBufferContent. Contenu en tant que mémoire tampon
• HttpFormUrlEncodedContent. Contenu en tant que nom et tuples de valeur encodés avec le type MIME application/x-www-form-urlencoded
• HttpMultipartContent. Contenu sous la forme du type MIME multipart/* .
• HttpMultipartFormDataContent. Contenu encodé en tant que type MIME multipart/form-data .
• HttpStreamContent. Contenu en tant que flux (le type interne est utilisé par la méthode HTTP GET pour recevoir des données et la méthode HTTP POST pour charger des données)
• HttpStringContent. Contenu sous forme de chaîne.
• IHttpContent : interface de base permettant aux développeurs de créer leurs propres objets de contenu

L’extrait de code de la section « Envoyer une requête GET simple sur HTTP » utilise la classe HttpStringContent pour représenter la réponse HTTP à partir d’une requête HTTP GET sous forme de chaîne.

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

Envoyer une requête GET simple via HTTP

Comme mentionné précédemment dans cet article, le Windows. L’espace de noms Web.Http permet aux applications Windows d’envoyer des requêtes GET. L’extrait de code suivant montre comment envoyer une requête GET à http://www.contoso.com l’aide du Windows. Classe Web.Http.HttpClient et Windows. Classe Web.Http.HttpResponseMessage pour lire la réponse de la requête GET.

//Create an HTTP client object
Windows.Web.Http.HttpClient httpClient = new Windows.Web.Http.HttpClient();

//Add a user-agent header to the GET request.
var headers = httpClient.DefaultRequestHeaders;

//The safe way to add a header value is to use the TryParseAdd method and verify the return value is true,
//especially if the header value is coming from user input.
string header = "MyApp/1.0";
if (!headers.UserAgent.TryParseAdd(header))
{
    throw new Exception("Invalid header value: " + header);
}

Uri requestUri = new Uri("http://www.contoso.com");

//Send the GET request asynchronously and retrieve the response as a string.
Windows.Web.Http.HttpResponseMessage httpResponse = new Windows.Web.Http.HttpResponseMessage();
string httpResponseBody = "";

try
{
    //Send the GET request
    httpResponse = await httpClient.GetAsync(requestUri);
    httpResponse.EnsureSuccessStatusCode();
    httpResponseBody = await httpResponse.Content.ReadAsStringAsync();
}
catch (Exception ex)
{
    httpResponseBody = "Error: " + ex.HResult.ToString("X") + " Message: " + ex.Message;
}

// pch.h
#pragma once
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Web.Http.Headers.h>

// main.cpp : Defines the entry point for the console application.
#include "pch.h"
#include <iostream>
using namespace winrt;
using namespace Windows::Foundation;

int main()
{
    init_apartment();

    // Create an HttpClient object.
    Windows::Web::Http::HttpClient httpClient;

    // Add a user-agent header to the GET request.
    auto headers{ httpClient.DefaultRequestHeaders() };

    // The safe way to add a header value is to use the TryParseAdd method, and verify the return value is true.
    // This is especially important if the header value is coming from user input.
    std::wstring header{ L"MyApp/1.0" };
    if (!headers.UserAgent().TryParseAdd(header))
    {
        throw L"Invalid header value: " + header;
    }

    Uri requestUri{ L"http://www.contoso.com" };

    // Send the GET request asynchronously, and retrieve the response as a string.
    Windows::Web::Http::HttpResponseMessage httpResponseMessage;
    std::wstring httpResponseBody;

    try
    {
        // Send the GET request.
        httpResponseMessage = httpClient.GetAsync(requestUri).get();
        httpResponseMessage.EnsureSuccessStatusCode();
        httpResponseBody = httpResponseMessage.Content().ReadAsStringAsync().get();
    }
    catch (winrt::hresult_error const& ex)
    {
        httpResponseBody = ex.message();
    }
    std::wcout << httpResponseBody;
}

Envoyer des données binaires via HTTP

L’exemple de code C++/WinRT ci-dessous illustre l’utilisation de données de formulaire et d’une requête POST pour envoyer une petite quantité de données binaires en tant que chargement de fichier sur un serveur web. Le code utilise la classe HttpBufferContent pour représenter les données binaires et la classe HttpMultipartFormDataContent pour représenter les données de formulaire en plusieurs parties.

// pch.h
#pragma once
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Security.Cryptography.h>
#include <winrt/Windows.Storage.Streams.h>
#include <winrt/Windows.Web.Http.Headers.h>

// main.cpp : Defines the entry point for the console application.
#include "pch.h"
#include <iostream>
#include <sstream>
using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Storage::Streams;

int main()
{
    init_apartment();

    auto buffer{
        Windows::Security::Cryptography::CryptographicBuffer::ConvertStringToBinary(
            L"A sentence of text to encode into binary to serve as sample data.",
            Windows::Security::Cryptography::BinaryStringEncoding::Utf8
        )
    };
    Windows::Web::Http::HttpBufferContent binaryContent{ buffer };
    // You can use the 'image/jpeg' content type to represent any binary data;
    // it's not necessarily an image file.
    binaryContent.Headers().Append(L"Content-Type", L"image/jpeg");

    Windows::Web::Http::Headers::HttpContentDispositionHeaderValue disposition{ L"form-data" };
    binaryContent.Headers().ContentDisposition(disposition);
    // The 'name' directive contains the name of the form field representing the data.
    disposition.Name(L"fileForUpload");
    // Here, the 'filename' directive is used to indicate to the server a file name
    // to use to save the uploaded data.
    disposition.FileName(L"file.dat");

    Windows::Web::Http::HttpMultipartFormDataContent postContent;
    postContent.Add(binaryContent); // Add the binary data content as a part of the form data content.

    // Send the POST request asynchronously, and retrieve the response as a string.
    Windows::Web::Http::HttpResponseMessage httpResponseMessage;
    std::wstring httpResponseBody;

    try
    {
        // Send the POST request.
        Uri requestUri{ L"https://www.contoso.com/post" };
        Windows::Web::Http::HttpClient httpClient;
        httpResponseMessage = httpClient.PostAsync(requestUri, postContent).get();
        httpResponseMessage.EnsureSuccessStatusCode();
        httpResponseBody = httpResponseMessage.Content().ReadAsStringAsync().get();
    }
    catch (winrt::hresult_error const& ex)
    {
        httpResponseBody = ex.message();
    }
    std::wcout << httpResponseBody;
}

Pour PUBLIER le contenu d’un fichier binaire réel (plutôt que les données binaires explicites utilisées ci-dessus), vous trouverez plus facile d’utiliser un objet HttpStreamContent . Construisez-en un et, en tant qu’argument à son constructeur, transmettez la valeur retournée à partir d’un appel à StorageFile.OpenReadAsync. Cette méthode retourne un flux pour les données à l’intérieur de votre fichier binaire.

En outre, si vous chargez un fichier volumineux (supérieur à environ 10 Mo), nous vous recommandons d'utiliser les API de transfert en arrière-plan Windows Runtime.

Envoyer des données JSON par requête POST HTTP

L’exemple suivant publie un code JSON sur un point de terminaison, puis écrit le corps de la réponse.

using System;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.Storage.Streams;
using Windows.Web.Http;

private async Task TryPostJsonAsync()
{
    try
    {
        // Construct the HttpClient and Uri. This endpoint is for test purposes only.
        HttpClient httpClient = new HttpClient();
        Uri uri = new Uri("https://www.contoso.com/post");

        // Construct the JSON to post.
        HttpStringContent content = new HttpStringContent(
            "{ \"firstName\": \"Eliot\" }",
            UnicodeEncoding.Utf8,
            "application/json");

        // Post the JSON and wait for a response.
        HttpResponseMessage httpResponseMessage = await httpClient.PostAsync(
            uri,
            content);

        // Make sure the post succeeded, and write out the response.
        httpResponseMessage.EnsureSuccessStatusCode();
        var httpResponseBody = await httpResponseMessage.Content.ReadAsStringAsync();
        Debug.WriteLine(httpResponseBody);
    }
    catch (Exception ex)
    {
        // Write out any exceptions.
        Debug.WriteLine(ex);
    }
}

// pch.h
#pragma once
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Security.Cryptography.h>
#include <winrt/Windows.Storage.Streams.h>
#include <winrt/Windows.Web.Http.Headers.h>

// main.cpp : Defines the entry point for the console application.
#include "pch.h"
#include <iostream>
#include <sstream>
using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Storage::Streams;

int main()
{
    init_apartment();

    Windows::Web::Http::HttpResponseMessage httpResponseMessage;
    std::wstring httpResponseBody;

    try
    {
        // Construct the HttpClient and Uri. This endpoint is for test purposes only.
        Windows::Web::Http::HttpClient httpClient;
        Uri requestUri{ L"https://www.contoso.com/post" };

        // Construct the JSON to post.
        Windows::Web::Http::HttpStringContent jsonContent(
            L"{ \"firstName\": \"Eliot\" }",
            UnicodeEncoding::Utf8,
            L"application/json");

        // Post the JSON, and wait for a response.
        httpResponseMessage = httpClient.PostAsync(
            requestUri,
            jsonContent).get();

        // Make sure the post succeeded, and write out the response.
        httpResponseMessage.EnsureSuccessStatusCode();
        httpResponseBody = httpResponseMessage.Content().ReadAsStringAsync().get();
        std::wcout << httpResponseBody.c_str();
    }
    catch (winrt::hresult_error const& ex)
    {
        std::wcout << ex.message().c_str();
    }
}

Exceptions dans Windows. Web.Http

Une exception est levée lorsqu’une chaîne non valide pour un identificateur de ressource uniforme (URI) est passée au constructeur de l’objet Windows.Foundation.Uri.

.NET : Le type Windows.Foundation.Uri apparaît comme System.Uri en C# et VB.

En C# et Visual Basic, cette erreur peut être évitée à l’aide de la classe System.Uri dans la .NET 4.5 et l’une des méthodes System.Uri.TryCreate pour tester la chaîne reçue d’un utilisateur avant la construction de l’URI.

En C++, il n’existe aucune méthode pour essayer d’analyser une chaîne à un URI. Si une application obtient une entrée de l’utilisateur pour le Windows. Foundation.Uri, le constructeur doit se trouver dans un bloc try/catch. Si une exception est levée, l’application peut avertir l’utilisateur et demander un nouveau nom d’hôte.

Le Windows. Web.Http ne dispose pas d’une fonction pratique. Par conséquent, une application utilisant HttpClient et d’autres classes dans cet espace de noms doit utiliser la valeur HRESULT .

Dans les applications utilisant C++/WinRT, le struct winrt ::hresult_error représente une exception levée pendant l’exécution de l’application. La fonction winrt ::hresult_error ::code retourne le HRESULT affecté à l’exception spécifique. La fonction winrt ::hresult_error ::message retourne la chaîne fournie par le système associée à la valeur HRESULT . Pour plus d’informations, consultez Gestion des erreurs avec C++/WinRT

Les valeurs HRESULT possibles sont répertoriées dans le fichier d’en-tête Winerror.h . Votre application peut filtrer sur des valeurs HRESULT spécifiques pour modifier le comportement de l’application en fonction de la cause de l’exception.

Dans les applications utilisant le .NET Framework 4.5 en C#, VB.NET, system.Exception représente une erreur lors de l’exécution de l’application lorsqu’une exception se produit. La propriété System.Exception.HResult retourne le HRESULT affecté à l’exception spécifique. La propriété System.Exception.Message retourne le message qui décrit l’exception.

C++/CX a été remplacé par C++/WinRT. Toutefois, dans les applications utilisant C++/CX, l’exception Platform ::Exception représente une erreur lors de l’exécution de l’application lorsqu’une exception se produit. La propriété Platform ::Exception ::HResult retourne le HRESULT affecté à l’exception spécifique. La propriété Platform ::Exception ::Message retourne la chaîne fournie par le système associée à la valeur HRESULT .

Pour la plupart des erreurs de validation de paramètre, HRESULT retourné est E_INVALIDARG. Pour certains appels de méthode non valides, le HRESULT retourné est E_ILLEGAL_METHOD_CALL.