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

To use System.Net.HttpListener, create a new instance of the class using the System.Net.HttpListener constructor and use the HttpListener.Prefixes property to gain access to the collection that holds the strings that specify which Uniform Resource Identifier (URI) prefixes the System.Net.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 System.Net.HttpListener object with the prefix that most closely matches a requested URI responds to the request. Multiple System.Net.HttpListener objects cannot add the same prefix; a System.ComponentModel.Win32Exception exception is thrown if a System.Net.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 System.Net.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 System.Net.HttpListener, the prefix is "http://*:8080/". Similarly, to specify that the System.Net.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 HttpListener.Start method. System.Net.HttpListener offers both synchronous and asynchronous models for processing client requests. Requests and their associated responses are accessed using the System.Net.HttpListenerContext object returned by the HttpListener.GetContext method or its asynchronous counterparts, the HttpListener.BeginGetContext(AsyncCallback, object) and HttpListener.EndGetContext(IAsyncResult) 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 HttpListener.GetContext method, which waits for a client to send a request. The method returns an System.Net.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 HttpListener.BeginGetContext(AsyncCallback, object) method to specify an application-defined method to be called for each incoming request. Within that method, call the HttpListener.EndGetContext(IAsyncResult) 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 System.Net.HttpListenerRequest objects. Similarly, responses are accessed using the HttpListenerContext.Response property and are represented by System.Net.HttpListenerResponse objects. These objects share some functionality with the System.Net.HttpWebRequest and System.Net.HttpWebResponse objects, but the latter objects cannot be used in conjunction with System.Net.HttpListener because they implement client, not server, behaviors.

An System.Net.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 HttpListenerContext.User, HttpListener.AuthenticationSchemes, and HttpListener.AuthenticationSchemeSelectorDelegate properties.

Namespace: System.Net
Assembly: System (in System.dll)
Assembly Versions: 2.0.0.0, 4.0.0.0
Since: .NET 2.0