HttpClient 클래스

정의

URI로 식별되는 리소스에서 HTTP 요청을 보내고 HTTP 응답을 받기 위한 기본 클래스를 제공합니다.Provides a base class for sending HTTP requests and receiving HTTP responses from a resource identified by a URI.

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
상속

예제

// 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);
  }
}
' 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() 진입점을 사용 합니다.The preceding code example uses an async Task Main() entry point. 이 기능에 C# 는 7.1 이상이 필요 합니다.That feature requires C# 7.1 or later.

설명

HttpClient 클래스 인스턴스는 HTTP 요청을 보내는 세션의 역할을 합니다.The HttpClient class instance acts as a session to send HTTP requests. HttpClient 인스턴스는 해당 인스턴스에서 실행 되는 모든 요청에 적용 되는 설정의 컬렉션입니다.An HttpClient instance is a collection of settings applied to all requests executed by that instance. 또한 모든 HttpClient 인스턴스는 자체 연결 풀을 사용 하 여 다른 HttpClient 인스턴스에서 실행 되는 요청에서 해당 요청을 격리 합니다.In addition, every HttpClient instance uses its own connection pool, isolating its requests from requests executed by other HttpClient instances.

또한 HttpClient은 보다 구체적인 HTTP 클라이언트에 대 한 기본 클래스 역할을 합니다.The HttpClient also acts as a base class for more specific HTTP clients. 예를 들어 Facebook 웹 서비스 (예: GetFriends 메서드)와 관련 된 추가 메서드를 제공 하는 FacebookHttpClient 있습니다.An example would be a FacebookHttpClient providing additional methods specific to a Facebook web service (a GetFriends method, for instance). 파생 클래스는 클래스의 가상 메서드를 재정의 하면 안 됩니다.Derived classes should not override the virtual methods on the class. 대신 HttpMessageHandler을 허용 하는 생성자 오버 로드를 사용 하 여 사전 또는 사후 요청 처리를 구성 합니다.Instead, use a constructor overload that accepts HttpMessageHandler to configure any pre- or post-request processing instead.

기본적으로 .NET Framework 및 Mono에서는 HttpWebRequest를 사용 하 여 서버에 요청을 보냅니다.By default on .NET Framework and Mono, HttpWebRequest is used to send requests to the server. HttpMessageHandler 인스턴스를 매개 변수로 가져오는 생성자 오버 로드 중 하나에 다른 채널을 지정 하 여이 동작을 수정할 수 있습니다.This behavior can be modified by specifying a different channel in one of the constructor overloads taking a HttpMessageHandler instance as parameter. 인증 또는 캐싱과 같은 기능이 필요한 경우에는 WebRequestHandler를 사용 하 여 설정을 구성할 수 있으며 인스턴스를 생성자에 전달할 수 있습니다.If features like authentication or caching are required, WebRequestHandler can be used to configure settings and the instance can be passed to the constructor. 반환 된 처리기는 HttpMessageHandler 매개 변수를 가져오는 생성자 오버 로드 중 하나로 전달 될 수 있습니다.The returned handler can be passed to one of the constructor overloads taking a HttpMessageHandler parameter.

HttpClient를 사용 하는 앱과 System.Net.Http 네임 스페이스의 관련 클래스에서 많은 양의 데이터 (50 메가바이트 이상)를 다운로드 하려는 경우 앱은 해당 다운로드를 스트리밍하 고 기본 버퍼링을 사용 하지 않아야 합니다.If an app using HttpClient and related classes in the System.Net.Http namespace intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. 기본 버퍼링을 사용 하는 경우 클라이언트 메모리 사용량이 매우 큰, 성능 저하 잠재적으로 인해 크게 됩니다.If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

다음 메서드는 스레드로부터 안전 합니다.The following methods are thread safe:

  1. CancelPendingRequests

  2. DeleteAsync

  3. GetAsync

  4. GetByteArrayAsync

  5. GetStreamAsync

  6. GetStringAsync

  7. PostAsync

  8. PutAsync

  9. SendAsync

HttpClient 한 번 인스턴스화되면 애플리케이션의 수명 내내 다시 사용 될 것입니다.HttpClient is intended to be instantiated once and re-used throughout the life of an application. 모든 요청에 대해 HttpClient 클래스를 인스턴스화하면 많은 부하에서 사용할 수 있는 소켓 수가 고갈 됩니다.Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. 그러면 SocketException 오류가 발생 합니다.This will result in SocketException errors. 다음은 HttpClient를 올바르게 사용 하는 예제입니다.Below is an example using HttpClient correctly.

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

    static GoodController()
    {
        HttpClient = new HttpClient();
    }
}
  Public Class GoodController
    Inherits ApiController  
   
    Private Shared ReadOnly HttpClient As HttpClient  
  
    Shared Sub New()  
        HttpClient = New HttpClient()
    End Sub
End Class

HttpClient은 실행 되는 각 플랫폼에서 사용할 수 있는 하위 수준 기능을 래핑하는 높은 수준의 API입니다.The HttpClient is a high-level API that wraps the lower-level functionality available on each platform where it runs.

각 플랫폼에서 HttpClient는 최상의 전송을 사용 하려고 시도 합니다.On each platform, HttpClient tries to use the best available transport:

호스트/런타임Host/Runtime 백 엔드Backend
Windows/.NET FrameworkWindows/.NET Framework HttpWebRequest
Windows/MonoWindows/Mono HttpWebRequest
Windows/UWPWindows/UWP Windows 네이티브 WinHttpHandler (HTTP 2.0 가능)Windows native WinHttpHandler (HTTP 2.0 capable)
Windows/.NET Core 1.0-2.0Windows/.NET Core 1.0-2.0 Windows 네이티브 WinHttpHandler (HTTP 2.0 가능)Windows native WinHttpHandler (HTTP 2.0 capable)
Android/XamarinAndroid/Xamarin 빌드 시 선택 됩니다.Selected at build-time. HttpWebRequest를 사용 하거나 Android의 기본 HttpURLConnection 를 사용 하도록 구성할 수 있습니다.Can either use HttpWebRequest or be configured to use Android's native HttpURLConnection
iOS, tvOS, watchOS/XamariniOS, tvOS, watchOS/Xamarin 빌드 시 선택 됩니다.Selected at build-time. HttpWebRequest를 사용 하거나 Apple의 NSUrlSession (HTTP 2.0 가능)를 사용 하도록 구성할 수 있습니다.Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/XamarinmacOS/Xamarin 빌드 시 선택 됩니다.Selected at build-time. HttpWebRequest를 사용 하거나 Apple의 NSUrlSession (HTTP 2.0 가능)를 사용 하도록 구성할 수 있습니다.Can either use HttpWebRequest or be configured to use Apple's NSUrlSession (HTTP 2.0 capable)
macOS/MonomacOS/Mono HttpWebRequest
macOS/.NET Core 1.0-2.0macOS/.NET Core 1.0-2.0 libcurl기반 HTTP 전송 (HTTP 2.0 가능)libcurl-based HTTP transport (HTTP 2.0 capable)
Linux/MonoLinux/Mono HttpWebRequest
Linux/.NET Core 1.0-2.0Linux/.NET Core 1.0-2.0 libcurl기반 HTTP 전송 (HTTP 2.0 가능)libcurl-based HTTP transport (HTTP 2.0 capable)
.NET Core 2.1 이상.NET Core 2.1 and later System.Net.Http.SocketsHttpHandler

사용자는 HttpMessageHandler를 사용 하는 HttpClient 생성자를 호출 하 여 HttpClient에 대 한 특정 전송을 구성할 수도 있습니다.Users can also configure a specific transport for HttpClient by invoking the HttpClient constructor that takes an HttpMessageHandler.

HttpClient 및 .NET CoreHttpClient and .NET Core

.NET Core 2.1부터 HttpClientHandler 대신 System.Net.Http.SocketsHttpHandler 클래스가 HttpClient와 같은 상위 수준 HTTP 네트워킹 클래스에서 사용 하는 구현을 제공 합니다.Starting with .NET Core 2.1, the System.Net.Http.SocketsHttpHandler class instead of HttpClientHandler provides the implementation used by higher-level HTTP networking classes such as HttpClient. SocketsHttpHandler를 사용 하는 경우 다음과 같은 여러 가지 이점을 제공 합니다.The use of SocketsHttpHandler offers a number of advantages:

  • 이전 구현보다 월등히 향상된 성능.A significant performance improvement when compared with the previous implementation.

  • 배포 및 서비스를 간소화 하는 플랫폼 종속성을 제거 합니다.The elimination of platform dependencies, which simplifies deployment and servicing. 예를 들어 libcurl은 더 이상 macOS 용 .NET Core 및 Linux 용 .NET Core에 대 한 종속성이 아닙니다.For example, libcurl is no longer a dependency on .NET Core for macOS and .NET Core for Linux.

  • 모든 .NET 플랫폼에서 일관적인 동작Consistent behavior across all .NET platforms.

이러한 변경이 바람직하지 않은 경우 다음과 같은 여러 가지 방법으로 이전 System.Net.Http.HttpClientHandler을 사용 하도록 응용 프로그램을 구성할 수 있습니다.If this change is undesirable, you can configure your application to use the older System.Net.Http.HttpClientHandler instead in a number of ways:

  • 다음과 같이 AppContext.SetSwitch 메서드를 호출 합니다.By calling the AppContext.SetSwitch method as follows:

    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
    
    AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False)
    
  • Runtimeconfig.template.json 구성 파일에서 System.Net.Http.UseSocketsHttpHandler 스위치를 정의 합니다.By defining the System.Net.Http.UseSocketsHttpHandler switch in the .netcore.runtimeconfig.json configuration file:

    "runtimeOptions": {
      "configProperties": {
          "System.Net.Http.UseSocketsHttpHandler": false
      }
    }
    
  • DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER 이라는 환경 변수를 정의 하 고이 변수를 false 또는 0으로 설정 합니다.By defining an environment variable named DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER and setting it to either false or 0.

생성자

HttpClient()

이 인스턴스가 삭제될 때 폐기되는 HttpClientHandler를 사용하여 HttpClient 클래스의 새 인스턴스를 초기화합니다.Initializes a new instance of the HttpClient class using a HttpClientHandler that is disposed when this instance is disposed.

HttpClient(HttpMessageHandler)

지정된 처리기를 사용하여 HttpClient 클래스의 새 인스턴스를 초기화합니다.Initializes a new instance of the HttpClient class with the specified handler. 이 인스턴스가 삭제될 때 처리기가 삭제됩니다.The handler is disposed when this instance is disposed.

HttpClient(HttpMessageHandler, Boolean)

제공된 처리기를 사용하여 HttpClient 클래스의 새 인스턴스를 초기화하고 이 인스턴스를 삭제할 때 해당 처리기를 삭제할지 여부를 지정합니다.Initializes a new instance of the HttpClient class with the provided handler, and specifies whether that handler should be disposed when this instance is disposed.

속성

BaseAddress

요청을 보낼 때 사용된 인터넷 리소스의 URI(Uniform Resource Identifier)의 기준 주소를 가져오거나 설정합니다.Gets or sets the base address of Uniform Resource Identifier (URI) of the Internet resource used when sending requests.

DefaultProxy

글로벌 HTTP 프록시를 가져오거나 설정합니다.Gets or sets the global Http proxy.

DefaultRequestHeaders

각 요청과 함께 보내야 하는 헤더를 가져옵니다.Gets the headers which should be sent with each request.

DefaultRequestVersion

HttpClient 인스턴스에서 수행한 후속 요청에서 사용하는 기본 HTTP 버전을 가져오거나 설정합니다.Gets or sets the default HTTP version used on subsequent requests made by this HttpClient instance.

MaxResponseContentBufferSize

응답 콘텐츠를 읽을 경우 버퍼링할 최대 바이트 수를 가져오거나 설정합니다.Gets or sets the maximum number of bytes to buffer when reading the response content.

Timeout

요청 시간 제한 범위 내에서 대기할 기간을 가져오거나 설정합니다.Gets or sets the timespan to wait before the request times out.

메서드

CancelPendingRequests()

이 인스턴스에서 보류 중인 모든 요청을 취소합니다.Cancel all pending requests on this instance.

DeleteAsync(String)

DELETE 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(String, CancellationToken)

취소 토큰이 포함된 지정한 URI에 DELETE 요청을 비동기 작업으로 보냅니다.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

DeleteAsync(Uri)

DELETE 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a DELETE request to the specified Uri as an asynchronous operation.

DeleteAsync(Uri, CancellationToken)

취소 토큰이 포함된 지정한 URI에 DELETE 요청을 비동기 작업으로 보냅니다.Send a DELETE request to the specified Uri with a cancellation token as an asynchronous operation.

Dispose()

관리되지 않는 리소스를 해제하고, HttpMessageInvoker에서 사용하는 관리되는 리소스를 삭제합니다.Releases the unmanaged resources and disposes of the managed resources used by the HttpMessageInvoker.

(다음에서 상속됨 HttpMessageInvoker)
Dispose(Boolean)

HttpClient에서 사용하는 관리되지 않는 리소스를 해제하고 관리되는 리소스를 선택적으로 삭제할 수 있습니다.Releases the unmanaged resources used by the HttpClient and optionally disposes of the managed resources.

Equals(Object)

지정한 개체와 현재 개체가 같은지 여부를 확인합니다.Determines whether the specified object is equal to the current object.

(다음에서 상속됨 Object)
GetAsync(String)

GET 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(String, CancellationToken)

취소 토큰이 포함된 지정한 URI에 GET 요청을 비동기 작업으로 보냅니다.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(String, HttpCompletionOption)

HTTP 완료 옵션이 포함된 지정한 URI에 GET 요청을 비동기 작업으로 보냅니다.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(String, HttpCompletionOption, CancellationToken)

HTTP 완료 옵션 및 취소 토큰을 사용하여 지정한 URL에 비동기 작업으로 GET 요청을 보냅니다.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetAsync(Uri)

GET 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a GET request to the specified Uri as an asynchronous operation.

GetAsync(Uri, CancellationToken)

취소 토큰이 포함된 지정한 URI에 GET 요청을 비동기 작업으로 보냅니다.Send a GET request to the specified Uri with a cancellation token as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption)

HTTP 완료 옵션이 포함된 지정한 URI에 GET 요청을 비동기 작업으로 보냅니다.Send a GET request to the specified Uri with an HTTP completion option as an asynchronous operation.

GetAsync(Uri, HttpCompletionOption, CancellationToken)

HTTP 완료 옵션 및 취소 토큰을 사용하여 지정한 URL에 비동기 작업으로 GET 요청을 보냅니다.Send a GET request to the specified Uri with an HTTP completion option and a cancellation token as an asynchronous operation.

GetByteArrayAsync(String)

GET 요청을 지정된 URI에 보내고 비동기 작업에서 바이트 배열로 응답 본문을 반환합니다.Sends a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetByteArrayAsync(Uri)

GET 요청을 지정된 URI에 보내고 비동기 작업에서 바이트 배열로 응답 본문을 반환합니다.Send a GET request to the specified Uri and return the response body as a byte array in an asynchronous operation.

GetHashCode()

기본 해시 함수로 작동합니다.Serves as the default hash function.

(다음에서 상속됨 Object)
GetStreamAsync(String)

GET 요청을 지정된 URI에 보내고 비동기 작업에서 스트림으로 응답 본문을 반환합니다.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStreamAsync(Uri)

GET 요청을 지정된 URI에 보내고 비동기 작업에서 스트림으로 응답 본문을 반환합니다.Send a GET request to the specified Uri and return the response body as a stream in an asynchronous operation.

GetStringAsync(String)

GET 요청을 지정된 URI에 보내고 비동기 작업에서 문자열로 응답 본문을 반환합니다.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetStringAsync(Uri)

GET 요청을 지정된 URI에 보내고 비동기 작업에서 문자열로 응답 본문을 반환합니다.Send a GET request to the specified Uri and return the response body as a string in an asynchronous operation.

GetType()

현재 인스턴스의 Type을 가져옵니다.Gets the Type of the current instance.

(다음에서 상속됨 Object)
MemberwiseClone()

현재 Object의 단순 복사본을 만듭니다.Creates a shallow copy of the current Object.

(다음에서 상속됨 Object)
PatchAsync(String, HttpContent)

PATCH 요청을 비동기 작업으로 지정된 Uri에 문자열로 보냅니다.Sends a PATCH request to a Uri designated as a string as an asynchronous operation.

PatchAsync(String, HttpContent, CancellationToken)

취소 토큰이 포함된 PATCH 요청을 비동기 작업으로 문자열로 표현되는 Uri로 보냅니다.Sends a PATCH request with a cancellation token to a Uri represented as a string as an asynchronous operation.

PatchAsync(Uri, HttpContent)

PATCH 요청을 비동기 작업으로 보냅니다.Sends a PATCH request as an asynchronous operation.

PatchAsync(Uri, HttpContent, CancellationToken)

취소 토큰이 포함된 PATCH 요청을 비동기 작업으로 보냅니다.Sends a PATCH request with a cancellation token as an asynchronous operation.

PostAsync(String, HttpContent)

POST 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(String, HttpContent, CancellationToken)

취소 토큰이 포함된 POST 요청을 비동기 작업으로 보냅니다.Send a POST request with a cancellation token as an asynchronous operation.

PostAsync(Uri, HttpContent)

POST 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a POST request to the specified Uri as an asynchronous operation.

PostAsync(Uri, HttpContent, CancellationToken)

취소 토큰이 포함된 POST 요청을 비동기 작업으로 보냅니다.Send a POST request with a cancellation token as an asynchronous operation.

PutAsync(String, HttpContent)

PUT 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(String, HttpContent, CancellationToken)

취소 토큰이 포함된 PUT 요청을 비동기 작업으로 보냅니다.Send a PUT request with a cancellation token as an asynchronous operation.

PutAsync(Uri, HttpContent)

PUT 요청을 지정된 URI에 비동기 작업으로 보냅니다.Send a PUT request to the specified Uri as an asynchronous operation.

PutAsync(Uri, HttpContent, CancellationToken)

취소 토큰이 포함된 PUT 요청을 비동기 작업으로 보냅니다.Send a PUT request with a cancellation token as an asynchronous operation.

SendAsync(HttpRequestMessage)

HTTP 요청을 비동기 작업으로 보냅니다.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, CancellationToken)

HTTP 요청을 비동기 작업으로 보냅니다.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption)

HTTP 요청을 비동기 작업으로 보냅니다.Send an HTTP request as an asynchronous operation.

SendAsync(HttpRequestMessage, HttpCompletionOption, CancellationToken)

HTTP 요청을 비동기 작업으로 보냅니다.Send an HTTP request as an asynchronous operation.

ToString()

현재 개체를 나타내는 문자열을 반환합니다.Returns a string that represents the current object.

(다음에서 상속됨 Object)

적용 대상

추가 정보