HttpClient クラス
定義
重要
一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。
URI によって識別されるリソースから HTTP 要求を送信し、HTTP 応答を受信するためのクラスを提供します。
public ref class HttpClient : System::Net::Http::HttpMessageInvokerpublic class HttpClient : System.Net.Http.HttpMessageInvokertype HttpClient = class
inherit HttpMessageInvokerPublic Class HttpClient
Inherits HttpMessageInvoker- 継承
例
// 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
上記のコード例では、エントリ ポイントを async Task Main() 使用しています。 この機能には C# 7.1 以降が必要です。
注釈
クラス インスタンスは HttpClient 、HTTP 要求を送信するセッションとして機能します。 HttpClientインスタンスは、そのインスタンスによって実行されるすべての要求に適用される設定のコレクションです。 さらに、すべての HttpClient インスタンスは独自の接続プールを使用し、他 HttpClient のインスタンスによって実行される要求から要求を分離します。
インスタンス化
HttpClient は、1 回インスタンス化され、アプリケーションの有効期間中に再利用されることを目的としています。 .NET Core と .NET 5 以降では、HttpClient はハンドラー インスタンス内の接続をプールし、複数の要求間で接続を再利用します。 すべての要求に対して HttpClient クラスをインスタンス化すると、大量の負荷で使用可能なソケットの数が使い果たされます。 この枯渇により、エラーが SocketException 発生します。
コンストラクターの一部として 、(または SocketsHttpHandler .NET Core 2.1 以降で) などの HttpClientHandler "ハンドラー" を渡すことで、追加のオプションを構成できます。 要求が送信された後はハンドラーの接続プロパティを変更できないため、新しい 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);
}
}
1 つの HttpClient インスタンスのみを作成する代わりに、 を使用 IHttpClientFactory して HttpClient インスタンスを管理することもできます。 詳細については、「HttpClient の使用に関するガイドライン」を参照してください。
派生
は HttpClient 、より具体的な HTTP クライアントの基底クラスとしても機能します。 たとえば、Facebook Web サービスに固有の追加のメソッド (メソッドなど GetFriends ) を提供する FacebookHttpClient があります。 派生クラスは、 クラスの仮想メソッドをオーバーライドしないでください。 代わりに、 を受け入れる HttpMessageHandler コンストラクター オーバーロードを使用して、要求前または要求後の処理を構成します。
トランスポート
HttpClientは、実行される各プラットフォームで使用できる下位レベルの機能をラップする高レベルの API です。
各プラットフォームで、 HttpClient 使用可能な最適なトランスポートの使用を試みます。
| ホスト/ランタイム | バックエンド |
|---|---|
| Windows/.NET Framework | HttpWebRequest |
| Windows/Mono | HttpWebRequest |
| Windows/UWP | Windows ネイティブ WinHttpHandler (HTTP 2.0 対応) |
| Windows/.NET Core 1.0-2.0 | Windows ネイティブ WinHttpHandler (HTTP 2.0 対応) |
| Android/Xamarin | ビルド時に選択されます。 を使用 HttpWebRequest するか、Android のネイティブを使用するように構成できます HttpURLConnection |
| iOS、tvOS、watchOS/Xamarin | ビルド時に選択されます。 を使用 HttpWebRequest するか、Apple NSUrlSession の (HTTP 2.0 対応) を使用するように構成できます |
| macOS/Xamarin | ビルド時に選択されます。 を使用 HttpWebRequest するか、Apple NSUrlSession の (HTTP 2.0 対応) を使用するように構成できます |
| macOS/Mono | HttpWebRequest |
| macOS/.NET Core 1.0-2.0 | libcurlベースの HTTP トランスポート (HTTP 2.0 対応) |
| Linux/Mono | HttpWebRequest |
| Linux/.NET Core 1.0-2.0 | libcurlベースの HTTP トランスポート (HTTP 2.0 対応) |
| .NET Core 2.1 以降 | System.Net.Http.SocketsHttpHandler |
ユーザーは、 を受け取るコンストラクターを呼び出すことによって、 の HttpClient 特定の HttpClient トランスポートを HttpMessageHandler構成することもできます。
&.NET Framework Mono
既定では、.NET Framework と Mono では、 HttpWebRequest がサーバーに要求を送信するために使用されます。 この動作は、 パラメーターを使用してコンストラクター オーバーロードの 1 つで別のハンドラーを HttpMessageHandler 指定することで変更できます。 認証やキャッシュなどの機能が必要な場合は、 を使用 WebRequestHandler して設定を構成し、インスタンスをコンストラクターに渡すことができます。 返されたハンドラーは、 パラメーターを持つ HttpMessageHandler コンストラクター オーバーロードに渡すことができます。
.NET Core
.NET Core 2.1 以降では、 System.Net.Http.SocketsHttpHandler クラスではなく、 などのHttpClient上位レベルの HttpClientHandler HTTP ネットワーク クラスで使用される実装が提供されます。 の SocketsHttpHandler 使用には、次のような多くの利点があります。
- 以前の実装と比較して、パフォーマンスが大幅に向上しています。
- プラットフォームの依存関係が排除され、デプロイとサービスが簡略化されます。 たとえば、
libcurlは macOS 用の .NET Core と Linux 用の .NET Core への依存関係ではなくなりました。 - すべての .NET プラットフォームでの一貫した動作。
この変更が望ましくない場合、Windows では、NuGet パッケージを参照し、それを HttpClient のコンストラクターに手動で渡すことで、引き続き使用WinHttpHandlerできます。
ランタイム構成オプションを使用して動作を構成する
の動作の特定の HttpClient側面は、 ランタイム構成オプションを使用してカスタマイズできます。 ただし、これらのスイッチの動作は.NET バージョンによって異なります。 たとえば、.NET Core 2.1 から 3.1 では、 が既定で使用されているかどうかを SocketsHttpHandler 構成できますが、そのオプションは .NET 5.0 以降では使用できなくなります。
接続のプール
HttpClient は、可能な限り HTTP 接続をプールし、複数の要求に使用します。 接続ハンドシェイクは 1 回だけ行われるので、特に HTTPS 要求の場合は、パフォーマンスに大きな利点があります。
接続プールのプロパティは、 でHttpClientHandler構成することもSocketsHttpHandler、、、、 PooledConnectionLifetimeなどのMaxConnectionsPerServerPooledConnectionIdleTimeout構築中に渡すこともできます。
HttpClient インスタンスを破棄すると、開いている接続が閉じ、保留中の要求が取り消されます。
注意
HTTP/1.1 要求を同じサーバーに同時に送信する場合は、新しい接続を作成できます。 インスタンスを HttpClient 再利用した場合でも、要求のレートが高い場合、またはファイアウォールの制限がある場合は、既定の TCP クリーンアップ タイマーのために使用可能なソケットが使い果たされる可能性があります。 同時実行接続の数を制限するには、 プロパティを MaxConnectionsPerServer 設定します。 既定では、同時 HTTP/1.1 接続の数は無制限です。
バッファリングと要求の有効期間
既定では、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 は、プラットフォームに応じて、環境変数またはユーザー/システム設定からプロキシ構成を読み取ります。 この動作を変更するには、 または IWebProxy を優先順位の順に渡WebProxyします。
- Proxy HttpClient の構築中に渡された HttpClientHandler の プロパティ
- DefaultProxy静的プロパティ (すべてのインスタンスに影響します)
を使用して UseProxyプロキシを無効にすることができます。 Windows ユーザーの既定の構成では、ネットワーク検出を使用してプロキシを試して検出します。これは低速になる可能性があります。 プロキシが必要ないことがわかっている高スループット アプリケーションの場合は、プロキシを無効にする必要があります。
プロキシ設定 (など Credentials) は、HttpClient を使用して最初の要求が行われる前にのみ変更する必要があります。 HttpClient を初めて使用した後に行われた変更は、後続の要求に反映されない場合があります。
Timeouts
を使用 Timeout して、HttpClient インスタンスからのすべての HTTP 要求の既定のタイムアウトを設定できます。 タイムアウトは、要求/応答が開始される xxxAsync メソッドにのみ適用されます。 タイムアウトに達すると、その要求の Task<TResult> が取り消されます。
HttpClient オブジェクトの作成時にインスタンスを渡すと、 SocketsHttpHandler 追加のタイムアウトを設定できます。
| プロパティ | 説明 |
|---|---|
| ConnectTimeout | 要求で新しい TCP 接続を作成する必要がある場合に使用されるタイムアウトを指定します。 タイムアウトが発生した場合、要求 Task<TResult> は取り消されます。 |
| PooledConnectionLifetime | 接続プール内の接続ごとに使用するタイムアウトを指定します。 接続がアイドル状態の場合、接続はすぐに閉じられます。それ以外の場合、接続は現在の要求の最後に閉じられます。 |
| PooledConnectionIdleTimeout | 接続プール内の接続がこの長い間アイドル状態の場合、接続は閉じられます。 |
| Expect100ContinueTimeout | 要求に "Expect: 100-continue" ヘッダーがある場合、タイムアウトになるまで、または "100-continue" 応答が受信されるまで、コンテンツの送信を遅延します。 |
HttpClient は、接続の作成時にのみ DNS エントリを解決します。 DNS サーバーによって指定されている有効期限 (TTL) の期間は追跡されません。 一部のコンテナー シナリオで発生する可能性がある DNS エントリが定期的に変更される場合は、 を PooledConnectionLifetime 使用して接続の有効期間を制限し、接続を置き換えるときに DNS 参照が必要になるようにすることができます。
コンストラクター
| HttpClient() |
このインスタンスが破棄されたときに破棄される HttpClientHandler を使用して、HttpClient クラスの新しいインスタンスを初期化します。 |
| HttpClient(HttpMessageHandler) |
指定したハンドラーを使用して、HttpClient クラスの新しいインスタンスを初期化します。 このインスタンスが破棄されたときに、ハンドラーは破棄されます。 |
| HttpClient(HttpMessageHandler, Boolean) |
提供されたハンドラーを使用して、HttpClient クラスの新しいインスタンスを初期化し、このインスタンスが破棄されるときにそのハンドラーを破棄するかどうかを指定します。 |
プロパティ
| BaseAddress |
要求を送信するときに使用する、インターネット リソースの Uniform Resource Identifier (URI) のベース アドレスを取得または設定します。 |
| DefaultProxy |
グローバル HTTP プロキシを取得または設定します。 |
| DefaultRequestHeaders |
各要求と一緒に送信する必要があるヘッダーを取得します。 |
| DefaultRequestVersion |
この HttpClient インスタンスによって行われる後続の要求で使用される、既定の HTTP バージョンを取得または設定します。 |
| DefaultVersionPolicy |
GetAsync(String) や PostAsync(String, HttpContent) などの便利なメソッドで暗黙的に作成される要求の既定のバージョン ポリシーを取得または設定します。 |
| MaxResponseContentBufferSize |
応答の内容を読み取るときにバッファーに格納できる最大バイト数を取得または設定します。 |
| Timeout |
要求がタイムアウトするまで待機する期間を取得または設定します。 |
メソッド
| CancelPendingRequests() |
このインスタンスの保留中の要求をすべてキャンセルします。 |
| DeleteAsync(String) |
指定された URI に DELETE 要求を非同期操作として送信します。 |
| DeleteAsync(String, CancellationToken) |
非同期操作としてキャンセル トークンを使用して削除要求を指定された Uri に送信します。 |
| DeleteAsync(Uri) |
指定された URI に DELETE 要求を非同期操作として送信します。 |
| DeleteAsync(Uri, CancellationToken) |
非同期操作としてキャンセル トークンを使用して削除要求を指定された Uri に送信します。 |
| Dispose() |
HttpMessageInvoker が使用しているアンマネージド リソースを解放し、マネージド リソースを破棄します。 (継承元 HttpMessageInvoker) |
| Dispose(Boolean) |
HttpClient が使用しているアンマネージド リソースを解放します。オプションとして、マネージド リソースを破棄することもできます。 |
| Equals(Object) |
指定されたオブジェクトが現在のオブジェクトと等しいかどうかを判断します。 (継承元 Object) |
| GetAsync(String) |
指定された URI に GET 要求を非同期操作として送信します。 |
| GetAsync(String, CancellationToken) |
非同期操作としてキャンセル トークンを使用して GET 要求を指定された Uri に送信します。 |
| GetAsync(String, HttpCompletionOption) |
非同期操作としてHTTP 完了オプションを使用して GET 要求を指定された Uri に送信します。 |
| GetAsync(String, HttpCompletionOption, CancellationToken) |
非同期操作としてキャンセル トークンおよび HTTP 完了オプションを使用して GET 要求を指定された Uri に送信します。 |
| GetAsync(Uri) |
指定された URI に GET 要求を非同期操作として送信します。 |
| GetAsync(Uri, CancellationToken) |
非同期操作としてキャンセル トークンを使用して GET 要求を指定された Uri に送信します。 |
| GetAsync(Uri, HttpCompletionOption) |
非同期操作としてHTTP 完了オプションを使用して GET 要求を指定された Uri に送信します。 |
| GetAsync(Uri, HttpCompletionOption, CancellationToken) |
非同期操作としてキャンセル トークンおよび HTTP 完了オプションを使用して GET 要求を指定された Uri に送信します。 |
| GetByteArrayAsync(String) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をバイト配列として返します。 |
| GetByteArrayAsync(String, CancellationToken) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をバイト配列として返します。 |
| GetByteArrayAsync(Uri) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をバイト配列として返します。 |
| GetByteArrayAsync(Uri, CancellationToken) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をバイト配列として返します。 |
| GetHashCode() |
既定のハッシュ関数として機能します。 (継承元 Object) |
| GetStreamAsync(String) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をストリームとして返します。 |
| GetStreamAsync(String, CancellationToken) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をストリームとして返します。 |
| GetStreamAsync(Uri) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をストリームとして返します。 |
| GetStreamAsync(Uri, CancellationToken) |
指定 URI に GET 要求を送信し、非同期操作で応答本体をストリームとして返します。 |
| GetStringAsync(String) |
指定 URI に GET 要求を送信し、非同期操作で応答本体を文字列として返します。 |
| GetStringAsync(String, CancellationToken) |
指定 URI に GET 要求を送信し、非同期操作で応答本体を文字列として返します。 |
| GetStringAsync(Uri) |
指定 URI に GET 要求を送信し、非同期操作で応答本体を文字列として返します。 |
| GetStringAsync(Uri, CancellationToken) |
指定 URI に GET 要求を送信し、非同期操作で応答本体を文字列として返します。 |
| GetType() |
現在のインスタンスの Type を取得します。 (継承元 Object) |
| MemberwiseClone() |
現在の Object の簡易コピーを作成します。 (継承元 Object) |
| PatchAsync(String, HttpContent) |
文字列として指定されている URI に PATCH 要求を非同期操作として送信します。 |
| PatchAsync(String, HttpContent, CancellationToken) |
文字列として表現されている URI に PATCH 要求をキャンセル トークン付きで非同期操作として送信します。 |
| PatchAsync(Uri, HttpContent) |
非同期操作として PATCH 要求を送信します。 |
| PatchAsync(Uri, HttpContent, CancellationToken) |
PATCH 要求をキャンセル トークンと共に非同期操作として送信します。 |
| PostAsync(String, HttpContent) |
指定された URI に POST 要求を非同期操作として送信します。 |
| PostAsync(String, HttpContent, CancellationToken) |
POST 要求をキャンセル トークンとともに非同期操作として送信します。 |
| PostAsync(Uri, HttpContent) |
指定された URI に POST 要求を非同期操作として送信します。 |
| PostAsync(Uri, HttpContent, CancellationToken) |
POST 要求をキャンセル トークンとともに非同期操作として送信します。 |
| PutAsync(String, HttpContent) |
指定された URI に PUT 要求を非同期操作として送信します。 |
| PutAsync(String, HttpContent, CancellationToken) |
PUT 要求をとキャンセル トークンと共に非同期操作として送信します。 |
| PutAsync(Uri, HttpContent) |
指定された URI に PUT 要求を非同期操作として送信します。 |
| PutAsync(Uri, HttpContent, CancellationToken) |
PUT 要求をとキャンセル トークンと共に非同期操作として送信します。 |
| Send(HttpRequestMessage) |
指定した要求を使用して HTTP 要求を送信します。 |
| Send(HttpRequestMessage, CancellationToken) |
指定した要求とキャンセル トークンを使用して HTTP 要求を送信します。 |
| Send(HttpRequestMessage, CancellationToken) |
指定した要求とキャンセル トークンを使用して HTTP 要求を送信します。 (継承元 HttpMessageInvoker) |
| Send(HttpRequestMessage, HttpCompletionOption) |
HTTP 要求を送信します。 |
| Send(HttpRequestMessage, HttpCompletionOption, CancellationToken) |
指定した要求、完了オプション、およびキャンセル トークンを使用して HTTP 要求を送信します。 |
| SendAsync(HttpRequestMessage) |
非同期操作として HTTP 要求を送信します。 |
| SendAsync(HttpRequestMessage, CancellationToken) |
非同期操作として HTTP 要求を送信します。 |
| SendAsync(HttpRequestMessage, HttpCompletionOption) |
非同期操作として HTTP 要求を送信します。 |
| SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken) |
非同期操作として HTTP 要求を送信します。 |
| ToString() |
現在のオブジェクトを表す文字列を返します。 (継承元 Object) |