HttpListener, classe

À l'aide de la classe HttpListener, vous pouvez créer un écouteur de protocole HTTP simple qui répond aux requêtes HTTP. L'écouteur est actif pendant la durée de vie de l'objet HttpListener et s'exécute au sein de votre application avec ses autorisations.

Remarque
Cette classe n'est disponible que sur des ordinateurs exécutant les systèmes d'exploitation Windows XP SP2 ou Windows Server 2003. Si vous essayez de créer un objet HttpListener sur un ordinateur qui exécute un système d'exploitation antérieur, le constructeur lève une exception PlatformNotSupportedException.

Pour utiliser HttpListener, créez une nouvelle instance de la classe à l'aide du constructeur HttpListener et utilisez la propriété Prefixes pour accéder à la collection contenant les chaînes qui spécifient les préfixes URI (Uniform Resource Identifier) que le HttpListener doit traiter.

Une chaîne du préfixe URI est composée d'un schéma (http ou https), d'un hôte, d'un port facultatif et d'un chemin d'accès facultatif. Par exemple, "http://www.contoso.com:8080/customerData/" est une chaîne de préfixe complète. Les préfixes doivent se terminer par une barre oblique ("/"). L'objet HttpListener possédant le préfixe qui correspond le plus à un URI demandé répond à la demande. Plusieurs objets HttpListener ne peuvent pas ajouter le même préfixe ; une exception Win32Exception est levée si HttpListener ajoute un préfixe qui est déjà en cours d'utilisation.

Lorsqu'un port est spécifié, l'élément hôte peut être remplacé par "*" pour indiquer que HttpListener accepte les requêtes envoyées au port si l'URI demandé ne correspond à aucun autre préfixe. Par exemple, pour recevoir toutes les requêtes envoyées au port 8080 lorsque l'URI demandé n'est géré par aucun HttpListener, le préfixe est « http://*:8080/ ». De la même manière, pour spécifier que le HttpListener accepte toutes les requêtes envoyées à un port, remplacez l'élément hôte par le caractère « + » : « https://+:8080 ». Les caractères "*" et "+" peuvent être présents dans les préfixes qui incluent des chemins d'accès.

Pour commencer à écouter les requêtes de clients, ajoutez les préfixes URI à la collection et appelez la méthode Start. HttpListener propose à la fois des modèles synchrones et asynchrones pour traiter les demandes du client. Les demandes et leurs réponses associées sont accessibles à l'aide de l'objet HttpListenerContext retourné par la méthode GetContext ou ses équivalents asynchrones, les méthodes BeginGetContext et EndGetContext.

Le modèle synchrone est approprié si votre application doit rester bloquée en attendant une demande du client et si vous ne souhaitez traiter qu'une demande à la fois. À l'aide du modèle synchrone, appelez la méthode GetContext qui attend qu'un client envoie une demande. La méthode vous retourne un objet HttpListenerContext à traiter lorsqu'une demande est reçue.

Dans le modèle asynchrone plus complexe, votre application ne reste pas bloquée en attendant des demandes et chaque demande est traitée dans son propre thread d'exécution. Utilisez la méthode BeginGetContext pour spécifier une méthode définie par l'application à appeler pour chaque requête entrante. Dans cette méthode, appelez la méthode EndGetContext pour obtenir la demande, traitez-la et répondez-y.

Dans l'un ou l'autre modèle, les requêtes entrantes sont accessibles à l'aide de la propriété HttpListenerContext.Request et sont représentées par des objets HttpListenerRequest. De la même façon, les réponses sont accessibles à l'aide de la propriété HttpListenerContext.Response et sont représentées par des objets HttpListenerResponse. Ces objets partagent certaines fonctionnalités avec les objets HttpWebRequest et HttpWebResponse, mais ces derniers objets ne peuvent pas être utilisés conjointement avec HttpListener, car ils implémentent des comportements de clients, et non de serveurs.

HttpListener peut exiger l'authentification du client. Vous pouvez spécifier un schéma particulier à utiliser pour l'authentification, ou un délégué qui détermine le schéma à utiliser. Vous devez exiger une certaine forme d'authentification pour obtenir des informations relatives à l'identité du client. Pour plus d'informations, consultez les propriétés User, AuthenticationSchemes et AuthenticationSchemeSelectorDelegate.

Remarque
Si vous créez HttpListener à l'aide de https, vous devez sélectionner un certificat de serveur pour cet écouteur. Sinon, une requête HttpWebRequest de ce HttpListener échouera avec une fin inattendue de la connexion.

Remarque
Vous pouvez configurer des Certificats de serveur et d'autres options d'écouteur à l'aide de HttpCfg.exe. Consultez http://msdn.microsoft.com/zh-tw/library/aa364478(vs.85).aspx pour plus de détails. Le fichier exécutable est fourni avec Windows Server 2003 ou peut être construit à partir du code source disponible dans le Kit de développement Platform SDK.

Remarque
Si vous spécifiez plusieurs schémas d'authentification pour HttpListener, l'écouteur sélectionnera les clients dans l'ordre suivant : Negotiate, NTLM, Digest, puis Basic.

Remarque sur la plateforme Windows Server 2003 : Est requis pour utiliser cette classe.

Remarque sur la plateforme Windows XP Édition familiale, Windows XP Professionnel Édition x64, Windows Server 2003 : Le Service Pack 2 ou ultérieur est requis pour utiliser cette classe

L'exemple de code suivant illustre l'utilisation de HttpListener.

// This example requires the System and System.Net namespaces.
public static void SimpleListenerExample(string[] prefixes)
{
    if (!HttpListener.IsSupported)
    {
        Console.WriteLine ("Windows XP SP2 or Server 2003 is required to use the HttpListener class.");
        return;
    }
    // URI prefixes are required,
    // for example "http://contoso.com:8080/index/".
    if (prefixes == null || prefixes.Length == 0)
      throw new ArgumentException("prefixes");

    // Create a listener.
    HttpListener listener = new HttpListener();
    // Add the prefixes.
    foreach (string s in prefixes)
    {
        listener.Prefixes.Add(s);
    }
    listener.Start();
    Console.WriteLine("Listening...");
    // Note: The GetContext method blocks while waiting for a request. 
    HttpListenerContext context = listener.GetContext();
    HttpListenerRequest request = context.Request;
    // Obtain a response object.
    HttpListenerResponse response = context.Response;
    // Construct a response.
    string responseString = "<HTML><BODY> Hello world!</BODY></HTML>";
    byte[] buffer = System.Text.Encoding.UTF8.GetBytes(responseString);
    // Get a response stream and write the response to it.
    response.ContentLength64 = buffer.Length;
    System.IO.Stream output = response.OutputStream;
    output.Write(buffer,0,buffer.Length);
    // You must close the output stream.
    output.Close();
    listener.Stop();
}

.NET Framework

.NET Framework Client Profile

Windows 7, Windows Vista SP1 ou ultérieur, Windows XP SP3, Windows XP SP2 Édition x64, Windows Server 2008 (installation minimale non prise en charge), Windows Server 2008 R2 (installation minimale prise en charge avec SP1 ou version ultérieure), Windows Server 2003 SP2

Référence

Autres ressources