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 プロパティを使用して、HttpListener が処理する Uniform Resource Identifier (URI) プレフィックスを指定する文字列を格納しているコレクションへのアクセスを取得します。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 ("/"). 要求された URI に最も近いプレフィックスを持つ HttpListener オブジェクトは、要求に応答します。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 要素を "*" に置き換えることで、要求された URI が他のプレフィックスと一致しない場合に、HttpListener がポートに送信された要求を受け入れることを示すことができます。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. たとえば、要求された URI が HttpListenerによって処理されない場合に、ポート8080に送信されるすべての要求を受信するために、プレフィックスは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 または Windows 10 の .NET Framework 4.6 以降では、HttpListener オブジェクトによって管理される URI プレフィックスでワイルドカードサブドメインがサポートされています。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 または Windows 10 の .NET Framework 4.6 の場合に機能します。以前のバージョンでは、これによって 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. 要求とそれに関連付けられた応答には、GetContext メソッドによって返された HttpListenerContext オブジェクト、またはそれに対応する非同期の 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.

同期モデルは、クライアント要求を待機している間にアプリケーションがブロックする必要があり、一度に1つの要求のみを処理する場合に適しています。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. クライアントの id に関する情報を取得するには、何らかの形式の認証が必要です。You must require some form of authentication to obtain information about the client's identity. 詳細については、UserAuthenticationSchemes、および AuthenticationSchemeSelectorDelegate の各プロパティを参照してください。For additional information, see the User, AuthenticationSchemes, and AuthenticationSchemeSelectorDelegate properties.

注意

Https を使用して HttpListener を作成する場合は、そのリスナーのサーバー証明書を選択する必要があります。If you create an HttpListener using https, you must select a Server Certificate for that listener. それ以外の場合、この HttpListenerHttpWebRequest クエリは、接続が予期せず終了して失敗します。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に対して複数の認証方式を指定した場合、リスナーは、NegotiateNTLMDigest、および 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の上に構築されます。これは、Windows のすべての HTTP トラフィックを処理するカーネルモードリスナーです。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 は、接続管理、帯域幅調整、および web サーバーのログ記録を提供します。HTTP.sys provides connection management, bandwidth throttling, and web server logging. SSL 証明書を追加するには、 httpcfg.exeツールを使用します。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: Service Provider Name) の一覧を取得します。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

この HttpListener オブジェクトによって処理される URI (Uniform Resource Identifier) プレフィックスを取得します。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

NTLM が使用されているときに、同じ TCP (Transmission Control Protocol) 接続を使用した別の要求を認証する必要があるかどうかを制御する Boolean 値を取得または設定します。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()

現在のオブジェクトを表す string を返します。Returns a string that represents the current object.

(継承元 Object)

明示的なインターフェイスの実装

IDisposable.Dispose()

この HttpListener オブジェクトに保持されているリソースを解放します。Releases the resources held by this HttpListener object.

適用対象

こちらもご覧ください