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 는 애플리케이션의 수명 동안 한 번 인스턴스화되고 다시 사용되도록 의도된 것입니다. .NET Core 및 .NET 5 이상 HttpClient 에서는 처리기 인스턴스 내의 연결을 풀하고 여러 요청에서 연결을 다시 사용합니다. 모든 요청에 대해 클래스를 HttpClient 인스턴스화하면 부하가 많은 상태에서 사용할 수 있는 소켓 수가 소진됩니다. 이 고갈로 인해 오류가 발생합니다 SocketException .

생성자의 일부로 "처리기"를 전달하여 추가 옵션을 구성할 수 있으며, 예를 들어 HttpClientHandler 또는 .NET Core 2.1 이상에서는 SocketsHttpHandler을 사용할 수 있습니다. 요청이 제출된 후에는 처리기의 연결 속성을 변경할 수 없으므로 새 HttpClient 인스턴스를 만드는 한 가지 이유는 연결 속성을 변경해야 하는 경우입니다. 각각 다른 요청이 다른 설정을 필요로 하는 경우, 이는 또한 애플리케이션이 여러 HttpClient 인스턴스를 갖게 될 수 있으며, 각 인스턴스는 적절하게 구성되어 있고, 그런 다음 관련 클라이언트에서 요청이 발급됩니다.

HttpClient는 연결을 설정할 때 DNS 항목만 확인합니다. DNS 서버에서 지정한 TTL(Time to Live) 기간을 추적하지 않습니다. 일부 컨테이너 시나리오에서 발생할 수 있는 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 인스턴스를 생성하는 대신, IHttpClientFactory을 사용하여 HttpClient 인스턴스를 관리할 수도 있습니다. 자세한 내용은 HttpClient 사용 지침을 참조하세요.

파생

또한 더 HttpClient 구체적인 HTTP 클라이언트에 대한 기본 클래스로도 작동합니다. 예를 들어, Facebook 웹 서비스에 특정한 추가 메서드를 제공하는 FacebookHttpClient가 있을 수 있습니다 (예: GetFriends 메서드). 파생 클래스는 클래스의 가상 메서드를 재정의해서는 안 됩니다. 대신 사전 요청 또는 사후 요청 처리를 구성하는 데 허용하는 HttpMessageHandler 생성자 오버로드를 사용합니다.

Transports

이 HttpClient API는 실행되는 각 플랫폼에서 사용할 수 있는 하위 수준 기능을 래핑하는 상위 수준 API입니다.

각 플랫폼에서 HttpClient 사용 가능한 최상의 전송을 사용하려고 합니다.

사용자는 HttpClient을(를) 받는 HttpClient 생성자를 호출해서 특정 전송 HttpMessageHandler을 구성할 수도 있습니다.

.NET Framework 및 Mono

기본적으로 .NET Framework 및 Mono HttpWebRequest 는 서버에 요청을 보내는 데 사용됩니다. 이 동작은 HttpMessageHandler 매개 변수를 사용하는 생성자 오버로드 중 하나에서 다른 처리기를 지정하여 수정할 수 있습니다. 인증 또는 캐싱과 같은 기능이 필요한 경우 설정을 구성하는 데 사용할 WebRequestHandler 수 있으며 인스턴스를 생성자에 전달할 수 있습니다. 반환된 처리기를 HttpMessageHandler 매개 변수를 가진 생성자 오버로드에 전달할 수 있습니다.

.NET 코어

.NET Core 2.1 System.Net.Http.SocketsHttpHandler 부터 클래스는 HttpClientHandler 같은 상위 수준의 HTTP 네트워킹 클래스에서 사용하는 구현을 HttpClient대신 제공합니다. 사용 SocketsHttpHandler 은 다음과 같은 여러 가지 이점을 제공합니다.

• 이전 구현보다 월등히 향상된 성능.
• 배포 및 서비스를 간소화하는 플랫폼 종속성을 제거합니다. 예를 들어 libcurl 더 이상 macOS용 .NET Core 및 Linux용 .NET Core에 대한 종속성이 없습니다.
• 모든 .NET 플랫폼에서 일관된 동작.

이 변경이 바람직하지 않은 경우 Windows에서는 WinHttpHandler 참조하고 HttpClient의 생성자에 수동으로 전달하여 계속 사용할 수 있습니다.

런타임 구성 옵션을 사용하여 동작 구성

동작의 HttpClient특정 측면은 런타임 구성 옵션을 통해 사용자 지정할 수 있습니다. 그러나 이러한 스위치의 동작은 .NET 버전마다 다릅니다. 예를 들어 .NET Core 2.1 - 3.1에서 기본적으로 사용되는지 여부를 SocketsHttpHandler 구성할 수 있지만 해당 옵션은 .NET 5부터 더 이상 사용할 수 없습니다.

연결 풀링 (Connection Pooling)

HttpClient 는 가능한 경우 HTTP 연결을 풀로 만들고 둘 이상의 요청에 사용합니다. 연결 핸드셰이크가 한 번만 수행되므로 이는 특히 HTTPS 요청의 경우 상당한 성능 이점을 얻을 수 있습니다.

연결 풀 속성은 HttpClientHandler 또는 SocketsHttpHandler에 구성될 수 있으며, 생성 중에 전달되는 MaxConnectionsPerServer, PooledConnectionIdleTimeout, 및 PooledConnectionLifetime를 포함합니다.

인스턴스를 삭제하면 HttpClient 열려 있는 연결이 닫히고 보류 중인 요청이 취소됩니다.

버퍼링 및 요청 수명

기본적으로 HttpClient 메서드(제외 GetStreamAsync)는 비동기 결과를 반환하기 전에 모든 응답 본문을 메모리로 읽어 서버의 응답을 버퍼링합니다. 이러한 요청은 다음 중 하나가 발생할 때까지 계속됩니다.

• Task<TResult>이 성공하여 결과를 반환합니다.
• 경우 Timeout에 이르면 Task<TResult> 취소될 것입니다.
• CancellationToken 일부 메서드 오버로드가 실행됩니다.
• CancelPendingRequests()을 호출합니다.
• HttpClient가 삭제됩니다.

일부 메서드 오버로드에서 사용할 수 있는 매개 변수를 사용하여 HttpCompletionOption 요청별로 버퍼링 동작을 변경할 수 있습니다. 이 인수는 응답 헤더만 읽은 후 또는 응답 콘텐츠를 읽고 버퍼링한 후에 완료로 간주되어야 하는지 여부를 Task<TResult> 지정하는 데 사용할 수 있습니다.

네임스페이스의 HttpClient 사용 및 관련 클래스를 사용하는 System.Net.Http 앱이 대량의 데이터(50MB 이상)를 다운로드하려는 경우 앱은 해당 다운로드를 스트리밍하고 기본 버퍼링을 사용하지 않아야 합니다. 기본 버퍼링을 사용하는 경우 클라이언트 메모리 사용량이 매우 커져 성능이 크게 저하될 수 있습니다.

스레드 안전성

다음 메서드는 스레드로부터 안전합니다.

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

프록시

기본적으로 HttpClient 플랫폼에 따라 환경 변수 또는 사용자/시스템 설정에서 프록시 구성을 읽습니다. 이 동작을 변경하려면 먼저 WebProxy 또는 IWebProxy을 우선 순위에 따라 전달하십시오.

• Proxy 생성 중에 전달된 HttpClientHandler의 HttpClient 속성
• DefaultProxy 정적 속성(모든 인스턴스에 영향을 줍니다.)

를 사용하여 UseProxy프록시를 사용하지 않도록 설정할 수 있습니다. Windows 사용자의 기본 설정은 네트워크 검색 기능을 사용하여 프록시를 자동으로 감지하는 것이며, 이는 속도가 느려질 수 있습니다. 프록시가 필요하지 않다고 알려진 높은 처리량 애플리케이션의 경우 프록시를 사용하지 않도록 설정해야 합니다.

프록시 설정(예: Credentials)은 HttpClient첫 번째 요청이 사용되기 전에 변경해야 합니다. 처음 사용한 HttpClient 후의 변경 내용은 후속 요청에 반영되지 않을 수 있습니다.

Timeouts

Timeout를 사용하여 HttpClient 인스턴스의 모든 HTTP 요청에 대한 기본 시간 제한을 설정할 수 있습니다. 시간 제한은 요청/응답을 시작하는 xxxAsync 메서드에만 적용됩니다. 시간 제한에 도달 Task<TResult> 하면 해당 요청에 대한 요청이 취소됩니다.

SocketsHttpHandler 인스턴스를 전달하여 HttpClient 개체를 생성할 때 몇 가지 추가 시간 제한을 설정할 수 있습니다.

HttpClient 만 연결을 만들 때 DNS 항목을 확인합니다. DNS 서버에서 지정한 TTL(Time to Live) 기간을 추적하지 않습니다. 일부 컨테이너 시나리오에서 발생할 수 있는 DNS 항목이 정기적으로 변경되는 경우 연결을 바꿀 때 DNS 조회가 필요하도록 연결의 수명을 제한하는 데 사용할 PooledConnectionLifetime 수 있습니다.

추가 정보

• HttpClient 사용 지침
• HttpClient 샘플