HttpListener Classe

Definição

Fornece um ouvinte de protocolo HTTP simples controlado programaticamente.Provides a simple, programmatically controlled HTTP protocol listener. Essa classe não pode ser herdada.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
Herança
HttpListener
Implementações

Exemplos

O exemplo de código a seguir demonstra como usar um 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

Comentários

Usando a classe HttpListener, você pode criar um ouvinte de protocolo HTTP simples que responde às solicitações HTTP.Using the HttpListener class, you can create a simple HTTP protocol listener that responds to HTTP requests. O ouvinte está ativo durante o tempo de vida do objeto HttpListener e é executado em seu aplicativo com suas permissões.The listener is active for the lifetime of the HttpListener object and runs within your application with its permissions.

Para usar HttpListener, crie uma nova instância da classe usando o Construtor HttpListener e use a propriedade Prefixes para obter acesso à coleção que contém as cadeias de caracteres que especificam quais Uniform Resource Identifier (URI) o HttpListener deve processar.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.

Uma cadeia de caracteres de prefixo de URI é composta de um esquema (http ou HTTPS), um host, uma porta opcional e um caminho opcional.A URI prefix string is composed of a scheme (http or https), a host, an optional port, and an optional path. Um exemplo de uma cadeia de caracteres de prefixo completa é http://www.contoso.com:8080/customerData/.An example of a complete prefix string is http://www.contoso.com:8080/customerData/. Os prefixos devem terminar com uma barra ("/").Prefixes must end in a forward slash ("/"). O objeto HttpListener com o prefixo que mais se aproximar de um URI solicitado responde à solicitação.The HttpListener object with the prefix that most closely matches a requested URI responds to the request. Vários objetos HttpListener não podem adicionar o mesmo prefixo; uma exceção Win32Exception será gerada se um HttpListener adicionar um prefixo que já esteja em uso.Multiple HttpListener objects cannot add the same prefix; a Win32Exception exception is thrown if a HttpListener adds a prefix that is already in use.

Quando uma porta é especificada, o elemento host pode ser substituído por "*" para indicar que o HttpListener aceita solicitações enviadas para a porta se o URI solicitado não corresponde a nenhum outro prefixo.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. Por exemplo, para receber todas as solicitações enviadas à porta 8080 quando o URI solicitado não é tratado por nenhum HttpListener, o prefixo é 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/. Da mesma forma, para especificar que o HttpListener aceita todas as solicitações enviadas a uma porta, substitua o elemento de host pelo caractere "+".Similarly, to specify that the HttpListener accepts all requests sent to a port, replace the host element with the "+" character. Por exemplo, https://+:8080.For example, https://+:8080. Os caracteres "*" e "+" podem estar presentes em prefixos que incluem caminhos.The "*" and "+" characters can be present in prefixes that include paths.

A partir do .NET Core 2,0 ou .NET Framework 4,6 no Windows 10, subdomínios curinga têm suporte em prefixos de URI que são gerenciados por um objeto 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. Para especificar um subdomínio curinga, use o caractere "*" como parte do nome do host em um prefixo URI.To specify a wildcard subdomain, use the "*" character as part of the hostname in a URI prefix. Por exemplo, http://*. foo.com/.For example, http://*.foo.com/. Passe como o argumento para o método Add.Pass this as the argument to the Add method. Isso funciona a partir do .NET Core 2,0 ou .NET Framework 4,6 no Windows 10; em versões anteriores, isso gera um HttpListenerException.This works as of .NET Core 2.0 or .NET Framework 4.6 on Windows 10; in earlier versions, this generates an HttpListenerException.

Aviso

As associações de curinga de nível superior (http://*: 8080/ e http://+:8080) não devem ser usadas.Top-level wildcard bindings (http://*:8080/ and http://+:8080) should not be used. Associações de curinga de nível superior podem abrir o aplicativo para vulnerabilidades de segurança.Top-level wildcard bindings can open up your app to security vulnerabilities. Isso se aplica a curingas fortes e fracos.This applies to both strong and weak wildcards. Use nomes de host explícitos em vez de curingas.Use explicit host names rather than wildcards. Associações de curinga de subdomínio (por exemplo, *.mysub.com) não têm esse risco de segurança se você controlar o domínio pai completo (em vez de *.com, o qual é vulnerável).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). Veja rfc7230 section-5.4 para obter mais informações.See rfc7230 section-5.4 for more information.

Para começar a escutar solicitações de clientes, adicione os prefixos de URI à coleção e chame o método Start.To begin listening for requests from clients, add the URI prefixes to the collection and call the Start method. o HttpListener oferece modelos síncronos e assíncronos para processar solicitações de cliente.HttpListener offers both synchronous and asynchronous models for processing client requests. As solicitações e suas respostas associadas são acessadas usando o objeto HttpListenerContext retornado pelo método GetContext ou suas contrapartes assíncronas, os métodos BeginGetContext e 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.

O modelo síncrono é apropriado se o aplicativo deve ser bloqueado enquanto aguarda uma solicitação do cliente e se você deseja processar apenas uma solicitação por vez.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. Usando o modelo síncrono, chame o método GetContext, que aguarda que um cliente envie uma solicitação.Using the synchronous model, call the GetContext method, which waits for a client to send a request. O método retorna um objeto HttpListenerContext para você para processamento quando um ocorre.The method returns an HttpListenerContext object to you for processing when one occurs.

No modelo assíncrono mais complexo, seu aplicativo não é bloqueado enquanto aguarda solicitações e cada solicitação é processada em seu próprio thread de execução.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 o método BeginGetContext para especificar um método definido pelo aplicativo a ser chamado para cada solicitação de entrada.Use the BeginGetContext method to specify an application-defined method to be called for each incoming request. Dentro desse método, chame o método EndGetContext para obter a solicitação, processá-la e responder.Within that method, call the EndGetContext method to obtain the request, process it, and respond.

Em qualquer modelo, as solicitações de entrada são acessadas usando a propriedade HttpListenerContext.Request e são representadas por HttpListenerRequest objetos.In either model, incoming requests are accessed using the HttpListenerContext.Request property and are represented by HttpListenerRequest objects. Da mesma forma, as respostas são acessadas usando a propriedade HttpListenerContext.Response e são representadas por HttpListenerResponse objetos.Similarly, responses are accessed using the HttpListenerContext.Response property and are represented by HttpListenerResponse objects. Esses objetos compartilham algumas funcionalidades com os objetos HttpWebRequest e HttpWebResponse, mas os últimos objetos não podem ser usados em conjunto com HttpListener porque implementam o cliente, e não o servidor, comportamentos.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.

Um HttpListener pode exigir autenticação de cliente.An HttpListener can require client authentication. Você pode especificar um esquema específico a ser usado para autenticação ou pode especificar um delegado que determina o esquema a ser usado.You can either specify a particular scheme to use for authentication, or you can specify a delegate that determines the scheme to use. Você deve exigir alguma forma de autenticação para obter informações sobre a identidade do cliente.You must require some form of authentication to obtain information about the client's identity. Para obter informações adicionais, consulte as propriedades User, AuthenticationSchemese AuthenticationSchemeSelectorDelegate.For additional information, see the User, AuthenticationSchemes, and AuthenticationSchemeSelectorDelegate properties.

Observação

Se você criar um HttpListener usando HTTPS, deverá selecionar um certificado de servidor para esse ouvinte.If you create an HttpListener using https, you must select a Server Certificate for that listener. Caso contrário, uma consulta HttpWebRequest desse HttpListener falhará com um fechamento inesperado da conexão.Otherwise, an HttpWebRequest query of this HttpListener will fail with an unexpected close of the connection.

Observação

Você pode configurar certificados de servidor e outras opções de ouvinte usando o Shell de rede (netsh. exe).You can configure Server Certificates and other listener options by using Network Shell (netsh.exe). Consulte o Shell de rede (netsh) para obter mais detalhes.See Network Shell (Netsh) for more details. O executável começou a ser enviado com o Windows Server 2008 e o Windows Vista.The executable began shipping with Windows Server 2008 and Windows Vista.

Observação

Se você especificar vários esquemas de autenticação para o HttpListener, o ouvinte irá desafiar os clientes na seguinte ordem: Negotiate, NTLM, Digeste, em seguida, 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

A classe HttpListener é criada sobre HTTP.sys, que é o ouvinte de modo kernel que manipula todo o tráfego HTTP para 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 fornece gerenciamento de conexão, limitação de largura de banda e log de servidor Web.HTTP.sys provides connection management, bandwidth throttling, and web server logging. Use a ferramenta Httpcfg. exe para adicionar certificados SSL.Use the HttpCfg.exe tool to add SSL certificates.

Construtores

HttpListener()

Inicializa uma nova instância da classe HttpListener.Initializes a new instance of the HttpListener class.

Propriedades

AuthenticationSchemes

Obtém ou define o esquema usado para autenticar clientes.Gets or sets the scheme used to authenticate clients.

AuthenticationSchemeSelectorDelegate

Obtém ou define o delegado chamado para determinar o protocolo usado para autenticar clientes.Gets or sets the delegate called to determine the protocol used to authenticate clients.

DefaultServiceNames

Obtém uma lista padrão de SPNs (Nomes de Provedor de Serviço) conforme determinado pelos prefixos registrados.Gets a default list of Service Provider Names (SPNs) as determined by registered prefixes.

ExtendedProtectionPolicy

Obtém ou define o ExtendedProtectionPolicy a ser usado para proteção estendida em uma sessão.Gets or sets the ExtendedProtectionPolicy to use for extended protection for a session.

ExtendedProtectionSelectorDelegate

Obtém ou define o delegado chamado para determinar o ExtendedProtectionPolicy a usar em cada solicitação.Gets or sets the delegate called to determine the ExtendedProtectionPolicy to use for each request.

IgnoreWriteExceptions

Obtém ou define um valor de Boolean que especifica se o aplicativo recebe exceções que ocorrem quando um HttpListener envia a resposta ao cliente.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

Obtém um valor que indica se o HttpListener tiver sido iniciado.Gets a value that indicates whether HttpListener has been started.

IsSupported

Obtém um valor que indica se HttpListener pode ser usado com o sistema operacional atual.Gets a value that indicates whether HttpListener can be used with the current operating system.

Prefixes

Obtém os prefixos de URI (Uniform Resource Identifier) manipulados por este objeto HttpListener.Gets the Uniform Resource Identifier (URI) prefixes handled by this HttpListener object.

Realm

Obtém ou define o realm, ou partição de recurso, associado a esse objeto HttpListener.Gets or sets the realm, or resource partition, associated with this HttpListener object.

TimeoutManager

O gerenciador de tempo limite para esta instância do HttpListener.The timeout manager for this HttpListener instance.

UnsafeConnectionNtlmAuthentication

Obtém ou define um valor Boolean que controla se, ao usar o NTLM, solicitações adicionais usando a mesma conexão por protocolo TCP são ou não necessárias para autenticação.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.

Métodos

Abort()

Desliga o objeto HttpListener imediatamente, descartando todas as solicitações atualmente na fila.Shuts down the HttpListener object immediately, discarding all currently queued requests.

BeginGetContext(AsyncCallback, Object)

Começa a recuperação assíncrona de uma solicitação de entrada.Begins asynchronously retrieving an incoming request.

Close()

Desliga o HttpListener.Shuts down the HttpListener.

EndGetContext(IAsyncResult)

Conclui uma operação assíncrona para recuperar uma solicitação de cliente recebida.Completes an asynchronous operation to retrieve an incoming client request.

Equals(Object)

Determina se o objeto especificado é igual ao objeto atual.Determines whether the specified object is equal to the current object.

(Herdado de Object)
GetContext()

Aguarda uma solicitação de entrada e a retorna quando recebida.Waits for an incoming request and returns when one is received.

GetContextAsync()

Aguarda uma solicitação de entrada como uma operação assíncrona.Waits for an incoming request as an asynchronous operation.

GetHashCode()

Serve como a função de hash padrão.Serves as the default hash function.

(Herdado de Object)
GetType()

Obtém o Type da instância atual.Gets the Type of the current instance.

(Herdado de Object)
MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Herdado de Object)
Start()

Permite que essa instância receba solicitações de entrada.Allows this instance to receive incoming requests.

Stop()

Faz com que esta instância pare de receber novas solicitações de entrada e finaliza o processamento de todas as solicitações em andamento.Causes this instance to stop receiving new incoming requests and terminates processing of all ongoing requests.

ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.Returns a string that represents the current object.

(Herdado de Object)

Implantações explícitas de interface

IDisposable.Dispose()

Libera os recursos mantidos por esse objeto HttpListener.Releases the resources held by this HttpListener object.

Aplica-se a

Veja também