Windows.Web.Http.Filters Espace de noms

Classes

Interfaces

Énumérations

Remarques

L’espace de noms Windows.Web.Http et les espaces de noms Windows.Web.Http.Headers et Windows.Web.Http.Filters associés fournissent une interface de programmation HTTP pour l’application UWP qui souhaite se connecter aux services HTTP. L’API HTTP fournit une prise en charge cohérente en JavaScript, C#, VB.NET et C++ pour les développeurs. L’API prend également en charge l’ajout de filtres personnalisés sur les requêtes et les réponses. Les filtres peuvent simplifier la gestion des problèmes réseau plus complexes. L’API permet également à un contrôle d’application de lire et d’écrire un comportement de mise en cache.

Les classes de l’espace de noms Windows.Web.Http prennent en charge l’utilisation de filtres basés sur les classes de l’espace de noms Windows.Web.Http.Filters. Les classes de l’espace de noms Windows.Web.Http.Filters permettent également à un contrôle d’application de lire et d’écrire un comportement de mise en cache sur le client. HttpCacheDirectiveHeaderValueCollection dans Windows.Web.Http.Headers fournit un conteneur de collection pour les instances des directives de cache dans l’en-tête HTTP Cache-Control sur le contenu HTTP associé à une requête ou réponse HTTP. L’en-tête Cache-Control permet à une application de contrôler davantage le comportement de mise en cache.

Les classes de l’espace de noms Windows.Web.Http.Headers représentent des en-têtes HTTP tels que définis dans la RFC 2616 par l’IETF.

La classe HttpClient de l’espace de noms Windows.Web.Http fournit une classe de base pour l’envoi de requêtes HTTP et la réception de réponses HTTP. Les filtres fournissent un mécanisme de gestionnaire pour aider à résoudre les problèmes courants liés au service HTTP. Les filtres simples peuvent être chaînés dans une séquence pour gérer les problèmes de service HTTP plus complexes.

Un filtre HTTP est une zone noire qui accepte un message de requête HTTP et produit un message de réponse HTTP. La façon dont le filtre obtient une réponse HTTP est déterminée par le développeur de filtres. Les filtres ajoutent ou modifient généralement des en-têtes, gèrent l’autorisation (éventuellement à l’aide de WebAuthenticationBroker), ou autorisent ou interdisent une requête en fonction des conditions réseau. Les filtres apportent généralement des modifications, puis transmettent la demande à un filtre interne, qui est généralement défini lors de la construction d’un filtre.

Cette approche permet à un filtre d’être uniquement responsable d’un aspect spécifique de l’exécution d’une requête HTTP et de déléguer d’autres aspects à d’autres filtres. Un filtre peut implémenter la mise en cache, l’authentification, les redirections, les cookies, la communication réelle avec le serveur ou une combinaison de ceux-ci. Le filtre le plus bas (de base) est généralement celui qui effectue la communication réelle avec le réseau.

De nombreuses applications qui utilisent HTTP pour l’accès réseau doivent souvent répondre à diverses conditions. Voici quelques exemples courants :

• Nouvelle tentative réseau (avec back-off).
• Adaptation aux réseaux mesurés (lorsqu’une connexion réseau est itinérante, par exemple).
• Authentification auprès de sites de réseaux sociaux.
• Journalisation et télémétrie.

Il n’est pas difficile de gérer l’un de ces problèmes réseau par lui-même. Cela devient un problème complexe lorsque plusieurs de ces problèmes sont combinés. La prise en charge des filtres personnalisés dans l’espace de noms Windows.Web.Http.Filters permet aux développeurs de créer du code modulaire pour des filtres simples. Une série de filtres simples peut être liée dans une chaîne de filtres pour gérer des combinaisons complexes de problèmes. Le développeur choisit tout sur la chaîne de filtre :

• Filtres à ajouter.
• Ordre de les placer dans la chaîne de filtre.

HttpClient est la classe main utilisée pour envoyer et recevoir des requêtes via HTTP. HttpBaseProtocolFilter est ce que HttpClient utilise pour envoyer et recevoir des données. Par conséquent, HttpBaseProtocolFilter est généralement le bas de toute chaîne de filtre personnalisée. HttpBaseProtocolFilter peut également être utilisé pour contrôler la mise en cache et d’autres comportements de la connexion HTTP. Chaque instance HttpClient peut avoir une chaîne de filtre ou un pipeline différent.

Pour écrire un filtre personnalisé, une application implémente une version personnalisée de l’interface IHttpFilter . Le code permettant d’implémenter le comportement de filtre se trouve dans la méthode IHttpFilter.SendRequestAsync . Les filtres peuvent être écrits en C#/VB.NET ou C++. Les filtres peuvent être appelés et utilisés à partir de n’importe quel langage pris en charge pour l’application UWP, y compris JavaScript.

L’exemple de code montre un filtre pour ajouter un en-tête personnalisé aux requêtes et réponses HTTP.

public class PlugInFilter : IHttpFilter {
    private IHttpFilter innerFilter;

    public PlugInFilter(IHttpFilter innerFilter) {
        if (innerFilter == null) {
            throw new ArgumentException("innerFilter cannot be null.");
        }
        this.innerFilter = innerFilter;
    }

    public IAsyncOperationWithProgress<HttpResponseMessage, HttpProgress> SendRequestAsync(HttpRequestMessage request) {
        return AsyncInfo.Run<HttpResponseMessage, HttpProgress>(async (cancellationToken, progress) =>
        {
            request.Headers.Add("Custom-Header", "CustomRequestValue");
            HttpResponseMessage response = await innerFilter.SendRequestAsync(request).AsTask(cancellationToken, progress);

            cancellationToken.ThrowIfCancellationRequested();

            response.Headers.Add("Custom-Header", "CustomResponseValue");
        return response;
        });
    }

    public void Dispose() {
        innerFilter.Dispose();
        GC.SuppressFinalize(this);
    }
}

Pour utiliser un filtre, une application utilise le constructeur HttpClient(IHttpFilter) en passant l’interface du filtre à utiliser pour le instance HttpClient. Pour configurer la chaîne de filtre, le nouveau filtre est lié à un filtre précédent et à HttpBaseProtocolFilter en bas.

L’exemple de code montre la création d’un HttpClient pour utiliser un filtre personnalisé.

internal static void CreateHttpClient(ref HttpClient httpClient)
{
    if (httpClient != null) {
        httpClient.Dispose();
    }

    // HttpClient can be extended by plugging multiple filters together,
    // providing HttpClient with the configured filter pipeline.
    var baseFilter = new HttpBaseProtocolFilter();

    // Adds a custom header to every request and response message.
    var myFilter = new PlugInFilter(baseFilter);
    httpClient = new HttpClient(myFilter);

}

Voir aussi

• HttpClient
• Windows.Web.Http
• Windows.Web.Http.Headers
• Exemple HttpClient (Windows 10)