HttpClient クラス

定義

public ref class HttpClient : System::Net::Http::HttpMessageInvoker

public class HttpClient : System.Net.Http.HttpMessageInvoker

type HttpClient = class
    inherit HttpMessageInvoker

Public Class HttpClient
Inherits HttpMessageInvoker

継承

Object

HttpMessageInvoker

HttpClient

例

// HttpClient is intended to be instantiated once per application, rather than per-use. See Remarks.
static readonly HttpClient client = new HttpClient();

static async Task Main()
{
    // Call asynchronous network methods in a try/catch block to handle exceptions.
    try
    {
        using HttpResponseMessage response = await client.GetAsync("http://www.contoso.com/");
        response.EnsureSuccessStatusCode();
        string responseBody = await response.Content.ReadAsStringAsync();
        // Above three lines can be replaced with new helper method below
        // string responseBody = await client.GetStringAsync(uri);

        Console.WriteLine(responseBody);
    }
    catch (HttpRequestException e)
    {
        Console.WriteLine("\nException Caught!");
        Console.WriteLine("Message :{0} ", e.Message);
    }
}

open System.Net.Http

// HttpClient is intended to be instantiated once per application, rather than per-use. See Remarks.
let client = new HttpClient()

let main =
    task {
        // Call asynchronous network methods in a try/catch block to handle exceptions.
        try
            use! response = client.GetAsync "http://www.contoso.com/"
            response.EnsureSuccessStatusCode() |> ignore
            let! responseBody = response.Content.ReadAsStringAsync()
            // Above three lines can be replaced with new helper method below
            // let! responseBody = client.GetStringAsync uri

            printfn $"{responseBody}"
        with
        | :? HttpRequestException as e ->
            printfn "\nException Caught!"
            printfn $"Message :{e.Message} "
    }

main.Wait()

' HttpClient is intended to be instantiated once per application, rather than per-use. See Remarks.
Shared ReadOnly client As HttpClient = New HttpClient()

Private Shared Async Function Main() As Task
    ' Call asynchronous network methods in a try/catch block to handle exceptions.
    Try
        Using response As HttpResponseMessage = Await client.GetAsync("http://www.contoso.com/")
            response.EnsureSuccessStatusCode()
            Dim responseBody As String = Await response.Content.ReadAsStringAsync()
            ' Above three lines can be replaced with new helper method below
            ' Dim responseBody As String = Await client.GetStringAsync(uri)

            Console.WriteLine(responseBody)
        End Using
    Catch e As HttpRequestException
        Console.WriteLine(Environment.NewLine & "Exception Caught!")
        Console.WriteLine("Message :{0} ", e.Message)
    End Try
End Function

注釈

HttpClient クラス インスタンスは、HTTP 要求を送信するセッションとして機能します。 HttpClient インスタンスは、そのインスタンスによって実行されるすべての要求に適用される設定のコレクションです。 さらに、すべての HttpClient インスタンスは独自の接続プールを使用し、他の HttpClient インスタンスによって実行される要求から要求を分離します。

Instancing

HttpClient は、1 回インスタンス化され、アプリケーションの有効期間中に再利用されることを目的としています。 .NET Core および .NET 5 以降では、ハンドラー インスタンス内の接続を HttpClient プールし、複数の要求にわたって接続を再利用します。 要求ごとに HttpClient クラスをインスタンス化すると、負荷の大きい場合に使用可能なソケットの数が不足します。 この枯渇により、 SocketException エラーが発生します。

HttpClientHandler (または .NET Core 2.1 以降のSocketsHttpHandler) などの "ハンドラー" をコンストラクターの一部として渡すことで、追加のオプションを構成できます。 要求が送信された後はハンドラーの接続プロパティを変更できないため、新しい HttpClient インスタンスを作成する理由の 1 つは、接続プロパティを変更する必要がある場合です。 異なる要求で異なる設定が必要な場合は、アプリケーションに複数の HttpClient インスタンスがあり、各インスタンスが適切に構成され、関連するクライアントで要求が発行される可能性もあります。

HttpClient では、接続が作成されるときにのみ DNS のエントリが解決されます。 DNS サーバーによって指定されている有効期限 (TTL) の期間は追跡されません。 DNS エントリが定期的に変更され、一部のコンテナー シナリオで発生する可能性がある場合、クライアントはこれらの更新プログラムを尊重しません。 この問題を解決するには、接続が置き換えられるときに DNS 参照が必要になるように、 SocketsHttpHandler.PooledConnectionLifetime プロパティを設定することで、接続の有効期間を制限できます。

public class GoodController : ApiController
{
    private static readonly HttpClient httpClient;

    static GoodController()
    {
        var socketsHandler = new SocketsHttpHandler
        {
            PooledConnectionLifetime = TimeSpan.FromMinutes(2)
        };

        httpClient = new HttpClient(socketsHandler);
    }
}

HttpClient インスタンスを 1 つだけ作成する代わりに、IHttpClientFactoryを使用してHttpClient インスタンスを管理することもできます。 詳細については、「HttpClient の使用に関するガイドライン」を参照してください。

導出

HttpClientは、より具体的な HTTP クライアントの基底クラスとしても機能します。 たとえば、Facebook Web サービスに固有の追加のメソッド (たとえば、FacebookHttpClient メソッド) を提供するGetFriendsです。 派生クラスは、クラスの仮想メソッドをオーバーライドしないでください。 代わりに、 HttpMessageHandler を受け入れるコンストラクター オーバーロードを使用して、要求前または要求後の処理を構成します。

Transports

HttpClientは、実行される各プラットフォームで使用できる下位レベルの機能をラップする高度な API です。

各プラットフォームで、 HttpClient は使用可能な最適なトランスポートの使用を試みます。

ユーザーは、HttpClientを受け取るHttpClientコンストラクターを呼び出すことによって、HttpMessageHandlerの特定のトランスポートを構成することもできます。

.NETフレームワークとMono

既定では、.NET Framework と Mono では、 HttpWebRequest を使用してサーバーに要求を送信します。 この動作は、 HttpMessageHandler パラメーターを使用してコンストラクター オーバーロードの 1 つで別のハンドラーを指定することで変更できます。 認証やキャッシュなどの機能が必要な場合は、 WebRequestHandler を使用して設定を構成し、インスタンスをコンストラクターに渡すことができます。 返されたハンドラーは、 HttpMessageHandler パラメーターを持つコンストラクター オーバーロードに渡すことができます。

.NET コア

.NET Core 2.1 以降では、System.Net.Http.SocketsHttpHandlerではなく HttpClientHandler クラスによって、HttpClientなどの上位レベルの HTTP ネットワーク クラスで使用される実装が提供されます。 SocketsHttpHandlerの使用には、いくつかの利点があります。

• 以前の実装と比較して、パフォーマンスが大幅に向上しています。
• プラットフォームの依存関係が排除され、デプロイとサービスが簡略化されます。 たとえば、 libcurl は macOS 用の .NET Core と Linux 用の .NET Core への依存関係ではなくなりました。
• すべての .NET プラットフォームで一貫した動作。

この変更が望ましくない場合、Windows ではWinHttpHandlerを参照して HttpClient のコンストラクターに手動で渡すことで、を引き続き使用できます。

ランタイム構成オプションを使用して動作を構成する

HttpClientの動作の特定の側面は、ランタイム構成オプションを使用してカスタマイズできます。 ただし、これらのスイッチの動作は.NET バージョンによって異なります。 たとえば、.NET Core 2.1 から 3.1 では、 SocketsHttpHandler を既定で使用するかどうかを構成できますが、そのオプションは .NET 5 以降では使用できなくなります。

コネクションプーリング

HttpClient は可能な限り HTTP 接続をプールし、複数の要求に使用します。 接続ハンドシェイクは 1 回だけ実行されるため、特に HTTPS 要求の場合、パフォーマンスに大きなメリットがあります。

接続プールのプロパティは、構築時にHttpClientHandlerやSocketsHttpHandlerを渡して設定でき、MaxConnectionsPerServer、PooledConnectionIdleTimeout、PooledConnectionLifetimeを含めることができます。

HttpClient インスタンスを破棄すると、開いている接続が閉じられ、保留中の要求が取り消されます。

バッファリングと要求の有効期間

既定では、 HttpClient メソッド ( GetStreamAsyncを除く) はサーバーからの応答をバッファー処理し、非同期結果を返す前にすべての応答本文をメモリに読み込みます。 これらの要求は、次のいずれかが発生するまで続行されます。

• Task<TResult>は成功し、結果を返します。
• Timeoutに達すると、Task<TResult>は取り消されます。
• 一部のメソッド オーバーロードに通用する CancellationToken が発生します。
• CancelPendingRequests() が呼び出されます
• HttpClient は破棄されます。

一部のメソッド オーバーロードで使用できる HttpCompletionOption パラメーターを使用して、要求ごとにバッファリング動作を変更できます。 この引数を使用して、応答ヘッダーのみを読み取った後、または応答の内容を読み取ってバッファー処理した後に、 Task<TResult> を完了と見なす必要があるかどうかを指定できます。

HttpClient名前空間でSystem.Net.Httpおよび関連クラスを使用するアプリが大量のデータ (50 メガバイト以上) をダウンロードする場合、アプリはそれらのダウンロードをストリーミングし、既定のバッファリングを使用しないようにする必要があります。 既定のバッファリングを使用すると、クライアントのメモリ使用量が非常に大きくなり、パフォーマンスが大幅に低下する可能性があります。

スレッドの安全性

次のメソッドはスレッド セーフです。

• CancelPendingRequests
• DeleteAsync
• GetAsync
• GetByteArrayAsync
• GetStreamAsync
• GetStringAsync
• PostAsync
• PutAsync
• SendAsync

プロキシ

既定では、 HttpClient は、プラットフォームに応じて、環境変数またはユーザー/システム設定からプロキシ構成を読み取ります。 この動作を変更するには、優先順位に従って WebProxy または IWebProxy を渡します。

• Proxyの構築中に渡されたHttpClientHandlerのHttpClientプロパティ
• DefaultProxy静的プロパティ (すべてのインスタンスに影響します)

UseProxyを使用してプロキシを無効にすることができます。 Windows ユーザーの既定の構成では、ネットワーク検出を使用してプロキシを検出しようとしますが、これは低速になる可能性があります。 プロキシが必要ないことがわかっている高スループット アプリケーションの場合は、プロキシを無効にする必要があります。

プロキシ設定 ( Credentialsなど) は、 HttpClientを使用して最初の要求が行われる前にのみ変更する必要があります。 HttpClientを初めて使用した後に行われた変更は、後続の要求に反映されない場合があります。

タイムアウト

Timeoutを使用して、HttpClient インスタンスからのすべての HTTP 要求の既定のタイムアウトを設定できます。 タイムアウトは、要求/応答が開始される xxxAsync メソッドにのみ適用されます。 タイムアウトに達すると、その要求の Task<TResult> は取り消されます。

SocketsHttpHandler オブジェクトを構築するときに、HttpClient インスタンスを渡す場合は、いくつかの追加のタイムアウトを設定できます。

HttpClient は、接続の作成時にのみ DNS エントリを解決します。 DNS サーバーによって指定されている有効期限 (TTL) の期間は追跡されません。 一部のコンテナー シナリオで発生する可能性がある DNS エントリが定期的に変更される場合は、 PooledConnectionLifetime を使用して接続の有効期間を制限し、接続を置き換えるときに DNS 参照が必要になるようにすることができます。

こちらもご覧ください

• HttpClient の使用に関するガイドライン
• HttpClient サンプル