Export (0) Print
Expand All
12 out of 15 rated this helpful - Rate this topic

HttpListener Class

Provides a simple, programmatically controlled HTTP protocol listener. This class cannot be inherited.

System::Object
  System.Net::HttpListener

Namespace:  System.Net
Assembly:  System (in System.dll)
public ref class HttpListener sealed : IDisposable

The HttpListener type exposes the following members.

  NameDescription
Public methodHttpListenerInitializes a new instance of the HttpListener class.
Top
  NameDescription
Public propertyAuthenticationSchemesGets or sets the scheme used to authenticate clients.
Public propertyAuthenticationSchemeSelectorDelegateGets or sets the delegate called to determine the protocol used to authenticate clients.
Public propertyDefaultServiceNamesGets a default list of Service Provider Names (SPNs) as determined by registered prefixes.
Public propertyExtendedProtectionPolicyGet or set the ExtendedProtectionPolicy to use for extended protection for a session.
Public propertyExtendedProtectionSelectorDelegateGet or set the delegate called to determine the ExtendedProtectionPolicy to use for each request.
Public propertyIgnoreWriteExceptionsGets or sets a Boolean value that specifies whether your application receives exceptions that occur when an HttpListener sends the response to the client.
Public propertyIsListeningGets a value that indicates whether HttpListener has been started.
Public propertyStatic memberIsSupportedGets a value that indicates whether HttpListener can be used with the current operating system.
Public propertyPrefixesGets the Uniform Resource Identifier (URI) prefixes handled by this HttpListener object.
Public propertyRealmGets or sets the realm, or resource partition, associated with this HttpListener object.
Public propertyTimeoutManagerThe timeout manager for this HttpListener instance.
Public propertyUnsafeConnectionNtlmAuthenticationGets or sets a Boolean value that controls whether, when NTLM is used, additional requests using the same Transmission Control Protocol (TCP) connection are required to authenticate.
Top
  NameDescription
Public methodAbortShuts down the HttpListener object immediately, discarding all currently queued requests.
Public methodBeginGetContextBegins asynchronously retrieving an incoming request.
Public methodCloseShuts down the HttpListener.
Public methodEndGetContextCompletes an asynchronous operation to retrieve an incoming client request.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodGetContextWaits for an incoming request and returns when one is received.
Public methodGetContextAsyncWaits for an incoming request as an asynchronous operation.
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodStartAllows this instance to receive incoming requests.
Public methodStopCauses this instance to stop receiving incoming requests.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top
  NameDescription
Explicit interface implemetationPrivate methodIDisposable::DisposeInfrastructure. Releases the resources held by this HttpListener object.
Top

Using the HttpListener class, you can create a simple HTTP protocol listener that responds to HTTP requests. The listener is active for the lifetime of the HttpListener object and runs within your application with its permissions.

NoteNote

This class is available only on computers running the Windows XP SP2 or Windows Server 2003 operating systems. If you attempt to create an HttpListener object on a computer that is running an earlier operating system, the constructor throws a PlatformNotSupportedException exception.

To use HttpListener, create a new instance of the class using the HttpListener constructor and use the Prefixes property to gain access to the collection that holds the strings that specify which Uniform Resource Identifier (URI) prefixes the HttpListener should process.

A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path. An example of a complete prefix string is "http://www.contoso.com:8080/customerData/". Prefixes must end in a forward slash ("/"). The HttpListener object with the prefix that most closely matches a requested URI responds to the request. Multiple HttpListener objects cannot add the same prefix; a Win32Exception exception is thrown if a HttpListener adds a prefix that is already in use.

When a port is specified, the host element can be replaced with "*" to indicate that the HttpListener accepts requests sent to the port if the requested URI does not match any other prefix. For example, to receive all requests sent to port 8080 when the requested URI is not handled by any HttpListener, the prefix is "http://*:8080/". Similarly, to specify that the HttpListener accepts all requests sent to a port, replace the host element with the "+" character, "https://+:8080". The "*" and "+" characters can be present in prefixes that include paths.

To begin listening for requests from clients, add the URI prefixes to the collection and call the Start method. HttpListener offers both synchronous and asynchronous models for processing client requests. Requests and their associated responses are accessed using the HttpListenerContext object returned by the GetContext method or its asynchronous counterparts, the BeginGetContext and EndGetContext methods.

The synchronous model is appropriate if your application should block while waiting for a client request and if you want to process only one request at a time. Using the synchronous model, call the GetContext method, which waits for a client to send a request. The method returns an HttpListenerContext object to you for processing when one occurs.

In the more complex asynchronous model, your application does not block while waiting for requests and each request is processed in its own execution thread. Use the BeginGetContext method to specify an application-defined method to be called for each incoming request. Within that method, call the EndGetContext method to obtain the request, process it, and respond.

In either model, incoming requests are accessed using the HttpListenerContext::Request property and are represented by HttpListenerRequest objects. Similarly, responses are accessed using the HttpListenerContext::Response property and are represented by HttpListenerResponse objects. These objects share some functionality with the HttpWebRequest and HttpWebResponse objects, but the latter objects cannot be used in conjunction with HttpListener because they implement client, not server, behaviors.

An HttpListener can require client authentication. You can either specify a particular scheme to use for authentication, or you can specify a delegate that determines the scheme to use. You must require some form of authentication to obtain information about the client's identity. For additional information, see the User, AuthenticationSchemes, and AuthenticationSchemeSelectorDelegate properties.

NoteNote

If you create an HttpListener using https, you must select a Server Certificate for that listener. Otherwise, an HttpWebRequest query of this HttpListener will fail with an unexpected close of the connection.

NoteNote

You can configure Server Certificates and other listener options by using HttpCfg.exe. See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/http/http/httpcfg_exe.asp for more details. The executable is shipped with Windows Server 2003, or can be built from source code available in the Platform SDK.

NoteNote

If you specify multiple authentication schemes for the HttpListener, the listener will challenge clients in the following order: Negotiate, NTLM, Digest, and then Basic.

Windows Server 2003 Platform Note: Is required to use this class.

Windows XP Home Edition, Windows XP Professional x64 Edition, Windows Server 2003 Platform Note: Service Pack 2 or later is required to use this class

The following code example demonstrates using a 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

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.