HttpListener Класс

Определение

Предоставляет простой программно управляемый прослушиватель протокола HTTP.Provides a simple, programmatically controlled HTTP protocol listener. Этот класс не наследуется.This class cannot be inherited.

public ref class HttpListener sealed : IDisposable
public sealed class HttpListener : IDisposable
type HttpListener = class
    interface IDisposable
Public NotInheritable Class HttpListener
Implements IDisposable
Наследование
HttpListener
Реализации

Примеры

В следующем примере кода показано использование HttpListener .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();
}
Public Shared Sub SimpleListenerExample(prefixes As String())
    If Not HttpListener.IsSupported Then
        Console.WriteLine("Windows XP SP2 or Server 2003 is required to use the HttpListener class.")
        Return
    End If
    ' URI prefixes are required,
    ' for example "http://contoso.com:8080/index/".
    If prefixes Is Nothing Or prefixes.Length = 0 Then
        Throw New ArgumentException("prefixes")
    End If

    ' Create a listener
    Dim listener = New HttpListener()

    For Each s As String In prefixes
        listener.Prefixes.Add(s)
    Next
    listener.Start()
    Console.WriteLine("Listening...")
    ' Note: The GetContext method blocks while waiting for a request.
    Dim context As HttpListenerContext = listener.GetContext()
    Console.WriteLine("Listening...")
    ' Obtain a response object
    Dim request As HttpListenerRequest = context.Request
    ' Construct a response.
    Dim response As HttpListenerResponse = context.Response
    Dim responseString As String = "<HTML><BODY> Hello world!</BODY></HTML>"
    Dim buffer As Byte() = System.Text.Encoding.UTF8.GetBytes(responseString)
    ' Get a response stream and write the response to it.
    response.ContentLength64 = buffer.Length
    Dim output As System.IO.Stream = response.OutputStream
    output.Write(buffer, 0, buffer.Length)
    'You must close the output stream.
    output.Close()
    listener.Stop()
End Sub

Комментарии

С помощью HttpListener класса можно создать простой прослушиватель протокола HTTP, отвечающий на HTTP-запросы.Using the HttpListener class, you can create a simple HTTP protocol listener that responds to HTTP requests. Прослушиватель активен в течение всего времени существования HttpListener объекта и выполняется в приложении с его разрешениями.The listener is active for the lifetime of the HttpListener object and runs within your application with its permissions.

Чтобы использовать HttpListener , создайте новый экземпляр класса с помощью HttpListener конструктора и используйте Prefixes свойство, чтобы получить доступ к коллекции, содержащей строки, указывающие, какой универсальный идентификатор ресурса (URI) HttpListener должен обрабатываться.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.

Строка префикса URI состоит из схемы (HTTP или HTTPS), узла, дополнительного порта и необязательного пути.A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path. Пример полной строки префикса: http://www.contoso.com:8080/customerData/ .An example of a complete prefix string is http://www.contoso.com:8080/customerData/. Префиксы должны оканчиваться косой чертой ("/").Prefixes must end in a forward slash ("/"). HttpListenerОбъект с префиксом, который наиболее близко соответствует запрошенному URI, отвечает на запрос.The HttpListener object with the prefix that most closely matches a requested URI responds to the request. Несколько HttpListener объектов не могут добавить один и тот же префикс; Win32Exception исключение создается, если HttpListener добавляет префикс, который уже используется.Multiple HttpListener objects cannot add the same prefix; a Win32Exception exception is thrown if a HttpListener adds a prefix that is already in use.

Если указан порт, элемент Host можно заменить на " * ", чтобы указать, что HttpListener принимает запросы, отправляемые на порт, если запрашиваемый URI не совпадает ни с каким другим префиксом.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. Например, чтобы получить все запросы, отправленные на порт 8080, если запрашиваемый URI не обрабатывается ни одним из них HttpListener , то префиксом будет http:// * : 8080/.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/. Аналогично, чтобы указать, что HttpListener компонент принимает все запросы, отправляемые в порт, замените элемент Host символом "+".Similarly, to specify that the HttpListener accepts all requests sent to a port, replace the host element with the "+" character. Например, https://+:8080 .For example, https://+:8080. Символы " * " и "+" могут присутствовать в префиксах, включающих пути.The "*" and "+" characters can be present in prefixes that include paths.

Начиная с .NET Core 2,0 или платформа .NET Framework 4,6 в Windows 10, поддомены с подстановочными знаками поддерживаются в префиксах URI, управляемых HttpListener объектом.Starting with .NET Core 2.0 or .NET Framework 4.6 on Windows 10, wildcard subdomains are supported in URI prefixes that are managed by an HttpListener object. Чтобы указать поддомен с подстановочными знаками, используйте * символ "" как часть имени узла в префиксе URI.To specify a wildcard subdomain, use the "*" character as part of the hostname in a URI prefix. Например, http:// * . foo.com/.For example, http://*.foo.com/. Передайте его в качестве аргумента в Add метод.Pass this as the argument to the Add method. Это работает начиная с .NET Core 2,0 или платформа .NET Framework 4,6 в Windows 10; в более ранних версиях это создает HttpListenerException .This works as of .NET Core 2.0 or .NET Framework 4.6 on Windows 10; in earlier versions, this generates an HttpListenerException.

Предупреждение

Не следует использовать подстановочные привязки верхнего уровня (http:// * : 8080/ и http://+:8080 ). Top-level wildcard bindings (http://*:8080/ and http://+:8080) should not be used. Это может создать уязвимость и поставить ваше приложение под угрозу.Top-level wildcard bindings can open up your app to security vulnerabilities. Сюда относятся и строгие, и нестрогие подстановочные знаки.This applies to both strong and weak wildcards. Вместо этого используйте имена узлов в явном виде.Use explicit host names rather than wildcards. Привязки с подстановочными знаками на уровне дочерних доменов (например *.mysub.com) не создают таких угроз безопасности, если вы полностью контролируете родительский домен (в отличие от варианта *.com, создающего уязвимость).Subdomain wildcard binding (for example, *.mysub.com) doesn't have this security risk if you control the entire parent domain (as opposed to *.com, which is vulnerable). Дополнительные сведения см. в документе rfc7230, раздел 5.4.See rfc7230 section-5.4 for more information.

Чтобы начать прослушивание запросов от клиентов, добавьте префиксы URI в коллекцию и вызовите Start метод.To begin listening for requests from clients, add the URI prefixes to the collection and call the Start method. HttpListener предлагает как синхронные, так и асинхронные модели для обработки клиентских запросов.HttpListener offers both synchronous and asynchronous models for processing client requests. Доступ к запросам и связанным с ними ответам осуществляется с помощью HttpListenerContext объекта, возвращаемого GetContext методом, или его асинхронными аналогами, BeginGetContext EndGetContext методами и.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. Используя синхронную модель, вызовите GetContext метод, который ожидает отправки клиентом запроса.Using the synchronous model, call the GetContext method, which waits for a client to send a request. Метод возвращает объект для HttpListenerContext обработки, когда происходит событие.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. Используйте BeginGetContext метод, чтобы указать определяемый приложением метод, вызываемый для каждого входящего запроса.Use the BeginGetContext method to specify an application-defined method to be called for each incoming request. В этом методе вызовите EndGetContext метод, чтобы получить запрос, обработать его и ответить.Within that method, call the EndGetContext method to obtain the request, process it, and respond.

В любой из этих моделей доступ к входящим запросам осуществляется с помощью HttpListenerContext.Request Свойства и представляются HttpListenerRequest объектами.In either model, incoming requests are accessed using the HttpListenerContext.Request property and are represented by HttpListenerRequest objects. Аналогично, доступ к ответам осуществляется с помощью HttpListenerContext.Response Свойства и представляются HttpListenerResponse объектами.Similarly, responses are accessed using the HttpListenerContext.Response property and are represented by HttpListenerResponse objects. Эти объекты совместно используют некоторые функциональные возможности HttpWebRequest с HttpWebResponse объектами и, но последние объекты не могут использоваться совместно с, HttpListener поскольку они реализуют клиент, а не сервер, поведение.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.

HttpListenerМожет требоваться проверка подлинности клиента.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. Дополнительные сведения см. в разделе User AuthenticationSchemes свойства, и AuthenticationSchemeSelectorDelegate .For additional information, see the User, AuthenticationSchemes, and AuthenticationSchemeSelectorDelegate properties.

Примечание

При создании HttpListener с помощью HTTPS необходимо выбрать сертификат сервера для этого прослушивателя.If you create an HttpListener using https, you must select a Server Certificate for that listener. В противном случае HttpWebRequest запрос HttpListener будет завершаться с непредвиденным закрытием соединения.Otherwise, an HttpWebRequest query of this HttpListener will fail with an unexpected close of the connection.

Примечание

Сертификаты сервера и другие параметры прослушивателя можно настроить с помощью сетевой оболочки (netsh.exe).You can configure Server Certificates and other listener options by using Network Shell (netsh.exe). Дополнительные сведения см. в разделе Сетевая оболочка (Netsh) .See Network Shell (Netsh) for more details. Исполняемый файл начал доставляться с Windows Server 2008 и Windows Vista.The executable began shipping with Windows Server 2008 and Windows Vista.

Примечание

Если для задано несколько схем проверки подлинности HttpListener , прослушиватель выполнит запрос клиентов в следующем порядке: Negotiate , NTLM , Digest и Basic .If you specify multiple authentication schemes for the HttpListener, the listener will challenge clients in the following order: Negotiate, NTLM, Digest, and then Basic.

HTTP.sysHTTP.sys

HttpListenerКласс строится на основе HTTP.sys , который является прослушивателем режима ядра, который обрабатывает весь трафик HTTP для Windows.The HttpListener class is built on top of HTTP.sys, which is the kernel mode listener that handles all HTTP traffic for Windows. HTTP.sys обеспечивает управление подключениями, регулирование пропускной способности и ведение журнала веб-сервера.HTTP.sys provides connection management, bandwidth throttling, and web server logging. Используйте средство HttpCfg.exe для добавления SSL-сертификатов.Use the HttpCfg.exe tool to add SSL certificates.

Конструкторы

HttpListener()

Инициализирует новый экземпляр класса HttpListener.Initializes a new instance of the HttpListener class.

Свойства

AuthenticationSchemes

Возвращает или задает схему, используемую для аутентификации клиентов.Gets or sets the scheme used to authenticate clients.

AuthenticationSchemeSelectorDelegate

Возвращает или задает делегат, вызываемый для определения протокола, который будет использоваться для аутентификации клиентов.Gets or sets the delegate called to determine the protocol used to authenticate clients.

DefaultServiceNames

Получает список имен поставщиков услуг (SPN) по умолчанию в соответствии с зарегистрированными префиксами.Gets a default list of Service Provider Names (SPNs) as determined by registered prefixes.

ExtendedProtectionPolicy

Получает или задает объект ExtendedProtectionPolicy, который используется для расширенной защиты сеанса.Gets or sets the ExtendedProtectionPolicy to use for extended protection for a session.

ExtendedProtectionSelectorDelegate

Получает или задает делегат, вызываемый для определения объекта ExtendedProtectionPolicy, который следует использовать для каждого запроса.Gets or sets the delegate called to determine the ExtendedProtectionPolicy to use for each request.

IgnoreWriteExceptions

Возвращает или задает значение Boolean, которое определяет, получает ли приложение исключения, которые возникают при отправке прослушивателем HttpListener ответа клиенту.Gets or sets a Boolean value that specifies whether your application receives exceptions that occur when an HttpListener sends the response to the client.

IsListening

Возвращает значение, показывающее, был ли запущен прослушиватель HttpListener.Gets a value that indicates whether HttpListener has been started.

IsSupported

Возвращает значение, которое указывает, можно ли использовать прослушиватель HttpListener в текущей операционной системе.Gets a value that indicates whether HttpListener can be used with the current operating system.

Prefixes

Возвращает префиксы URI, обрабатываемые этим объектом HttpListener.Gets the Uniform Resource Identifier (URI) prefixes handled by this HttpListener object.

Realm

Возвращает или задает область или раздел ресурса, связанные с этим объектом HttpListener.Gets or sets the realm, or resource partition, associated with this HttpListener object.

TimeoutManager

Диспетчер времени ожидания для этого экземпляра HttpListener.The timeout manager for this HttpListener instance.

UnsafeConnectionNtlmAuthentication

Возвращает или задает значение Boolean, которое определяет, должны ли дополнительные запросы, использующие то же TCP-подключение, проходить аутентификацию при использовании протокола NTLM.Gets 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.

Методы

Abort()

Незамедлительно завершает работу объекта HttpListener, отменяя все текущие запросы в очереди.Shuts down the HttpListener object immediately, discarding all currently queued requests.

BeginGetContext(AsyncCallback, Object)

Начинает асинхронное получение входящего запроса.Begins asynchronously retrieving an incoming request.

Close()

Завершает работу HttpListener.Shuts down the HttpListener.

EndGetContext(IAsyncResult)

Завершает асинхронную операцию получения входящего клиентского запроса.Completes an asynchronous operation to retrieve an incoming client request.

Equals(Object)

Определяет, равен ли указанный объект текущему объекту.Determines whether the specified object is equal to the current object.

(Унаследовано от Object)
GetContext()

Ожидает входящий запрос и выполняет возврат при его получении.Waits for an incoming request and returns when one is received.

GetContextAsync()

Ожидает входящий запрос как асинхронную операцию.Waits for an incoming request as an asynchronous operation.

GetHashCode()

Служит хэш-функцией по умолчанию.Serves as the default hash function.

(Унаследовано от Object)
GetType()

Возвращает объект Type для текущего экземпляра.Gets the Type of the current instance.

(Унаследовано от Object)
MemberwiseClone()

Создает неполную копию текущего объекта Object.Creates a shallow copy of the current Object.

(Унаследовано от Object)
Start()

Позволяет этому экземпляру получать входящие запросы.Allows this instance to receive incoming requests.

Stop()

Предписывает этому экземпляру прекратить получение новых входящих запросов и завершает обработку всех текущих запросов.Causes this instance to stop receiving new incoming requests and terminates processing of all ongoing requests.

ToString()

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

(Унаследовано от Object)

Явные реализации интерфейса

IDisposable.Dispose()

Освобождает ресурсы, удерживаемые этим объектом HttpListener.Releases the resources held by this HttpListener object.

Применяется к

См. также раздел