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
{
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
let! 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
Dim 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)
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 します。
コンストラクターの一部として "ハンドラー" HttpClientHandler (または SocketsHttpHandler .NET Core 2.1 以降) を渡すことで、追加のオプションを構成できます。 ハンドラーの接続プロパティは要求が送信されると変更できないため、新しい 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 つだけ作成する代わりに、HttpClient インスタンスの管理にも使用 IHttpClientFactory できます。 詳細については、「 HttpClient の使用に関するガイドライン」を参照してください。
派生
また、 HttpClient より具体的な HTTP クライアントの基底クラスとしても機能します。 たとえば、Facebook Web サービスに固有の追加メソッド (メソッドなど GetFriends ) を提供する FacebookHttpClient です。 派生クラスは、クラスの仮想メソッドをオーバーライドしないでください。 代わりに、要求前または要求後の HttpMessageHandler 処理を構成するために受け入れるコンストラクター オーバーロードを使用します。
トランスポート
これは HttpClient 、実行される各プラットフォームで使用できる下位レベルの機能をラップする高レベルの API です。
各プラットフォームで、 HttpClient 使用可能な最適なトランスポートの使用を試みます。
| ホスト/ランタイム | バックエンド |
|---|---|
| Windows/.NET Framework | HttpWebRequest |
| Windows/Mono | HttpWebRequest |
| Windows/UWP | ネイティブWinHttpHandlerWindows (HTTP 2.0 対応) |
| Windows/.NET Core 1.0-2.0 | ネイティブWinHttpHandlerWindows (HTTP 2.0 対応) |
| Android/Xamarin | ビルド時に選択されます。 Androidのネイティブを使用するように使用するかHttpWebRequest、構成できますHttpURLConnection |
| iOS、tvOS、watchOS/Xamarin | ビルド時に選択されます。 HttpWebRequest Apple (HTTP 2.0 対応) を使用するか、または Apple NSUrlSession を使用するように構成できます |
| macOS/Xamarin | ビルド時に選択されます。 HttpWebRequest Apple (HTTP 2.0 対応) を使用するか、または Apple NSUrlSession を使用するように構成できます |
| macOS/Mono | HttpWebRequest |
| macOS/.NET Core 1.0-2.0 | libcurl-based HTTP トランスポート (HTTP 2.0 対応) |
| Linux/Mono | HttpWebRequest |
| Linux/.NET Core 1.0-2.0 | libcurl-based HTTP トランスポート (HTTP 2.0 対応) |
| .NET Core 2.1 以降 | System.Net.Http.SocketsHttpHandler |
ユーザーは、.HttpClient HttpClient HttpMessageHandler
.NET Framework & Mono
既定では、.NET Framework と Mono は、HttpWebRequestサーバーに要求を送信するために使用されます。 この動作は、いずれかのコンストラクター オーバーロードでパラメーターを使用 HttpMessageHandler して別のハンドラーを指定することで変更できます。 認証やキャッシュなどの機能が必要な場合は、設定を構成するために使用 WebRequestHandler でき、インスタンスをコンストラクターに渡すことができます。 返されたハンドラーは、パラメーターを持つコンストラクター オーバーロードに HttpMessageHandler 渡すことができます。
.NET Core
.NET Core 2.1 以降では、クラスの代わりに、 System.Net.Http.SocketsHttpHandler より高いレベルの HttpClientHandler HTTP ネットワーク クラスで使用される実装が HttpClient提供されます。 この使用 SocketsHttpHandler には、次のような多くの利点があります。
- 以前の実装と比較して、パフォーマンスが大幅に向上しています。
- プラットフォームの依存関係が排除され、デプロイとサービスが簡略化されます。 たとえば、
libcurlmacOS の .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、渡したりすることもできます 。これにはMaxConnectionsPerServer、.PooledConnectionLifetimePooledConnectionIdleTimeout..
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 は、プラットフォームに応じて、環境変数またはユーザー/システム設定からプロキシ構成を読み取ります。 この動作を変更するには、優先順位に WebProxy 従って次の値を渡します IWebProxy 。
- Proxy HttpClient の構築中に渡された HttpClientHandler のプロパティ
- DefaultProxy静的プロパティ (すべてのインスタンスに影響します)
を使用して UseProxyプロキシを無効にすることができます。 Windows ユーザーの既定の構成は、ネットワーク検出を使用してプロキシを検出することです。これは低速になる可能性があります。 プロキシが必要ないことがわかっているスループットの高いアプリケーションでは、プロキシを無効にする必要があります。
Timeouts
HttpClient インスタンスからのすべての HTTP 要求の既定のタイムアウトを設定するために使用 Timeout できます。 タイムアウトは、要求/応答が開始される xxxAsync メソッドにのみ適用されます。 タイムアウトに達すると、 Task<TResult> その要求は取り消されます。
HttpClient オブジェクトを構築するときにインスタンスを渡す場合は、 SocketsHttpHandler いくつかの追加のタイムアウトを設定できます。
| プロパティ | 説明 |
|---|---|
| ConnectTimeout | 要求で新しい TCP 接続を作成する必要がある場合に使用されるタイムアウトを指定します。 タイムアウトが発生した場合、要求 Task<TResult> は取り消されます。 |
| PooledConnectionLifetime | 接続プール内の各接続に使用するタイムアウトを指定します。 接続がアイドル状態の場合、接続はすぐに閉じられます。それ以外の場合は、現在の要求の最後に接続が閉じられます。 |
| PooledConnectionIdleTimeout | 接続プール内の接続がこの長い間アイドル状態の場合、接続は閉じられます。 |
| Expect100ContinueTimeout | 要求に "Expect: 100-continue" ヘッダーがある場合、タイムアウトになるまで、または "100 継続" 応答が受信されるまでコンテンツの送信が遅延します。 |
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) |