HttpClient 클래스를 사용하여 HTTP 요청 만들기

이 문서에서는 HTTP 요청을 수행하고 HttpClient 클래스를 사용하여 응답을 처리하는 방법을 알아봅니다.

HTTP 엔드포인트는 일반적으로 JSON(JavaScript Object Notation) 데이터를 반환하지만 항상 그런 것은 아닙니다. 편의를 위해 선택적 System.Net.Http.Json NuGet 패키지는 📦 System.Text.Json NuGet 패키지를 사용하여 HttpClient 및 HttpContent 객체에 대해 자동 직렬화 및 역직렬화를 수행하는 몇 가지 확장 메서드를 제공합니다. 이 문서의 예제에서는 이러한 확장을 사용할 수 있는 위치에 주의를 기울입니다.

HttpClient 개체 만들기

이 문서의 대부분의 예제는 동일한 HttpClient 인스턴스를 다시 사용하므로 인스턴스를 한 번 구성하고 나머지 예제에 사용할 수 있습니다. HttpClient 개체를 만들려면 HttpClient 클래스 생성자를 사용합니다. 자세한 내용은 HttpClient 사용 지침을 참조하세요.

// HttpClient lifecycle management best practices:
// https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use
private static HttpClient sharedClient = new()
{
    BaseAddress = new Uri("https://jsonplaceholder.typicode.com"),
};

코드는 다음 작업을 완료합니다.

• 새 HttpClient 인스턴스를 static 변수로 인스턴스화합니다. 지침에 따라 애플리케이션 수명 주기 동안 HttpClient 인스턴스를 다시 사용하는 것이 좋습니다.
• HttpClient.BaseAddress 속성을 "https://jsonplaceholder.typicode.com"으로 설정합니다.

이 HttpClient 인스턴스는 기본 주소를 사용하여 후속 요청을 수행합니다. 다른 구성을 적용하려면 다음 API를 고려합니다.

• HttpClient.DefaultRequestHeaders 속성을 설정합니다.
• 기본이 아닌 HttpClient.Timeout 속성을 적용합니다.
• HttpClient.DefaultRequestVersion 속성을 지정합니다.

HTTP 요청 수행

HTTP 요청을 수행하려면 다음 API 메서드를 호출합니다.

^†USER SPECIFIED 요청은 SendAsync 메서드가 유효한 HttpMethod 개체를 허용한다는 것을 나타냅니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <application android:usesCleartextTraffic="true"></application>
  <!-- omitted for brevity -->
</manifest>

HTTP 콘텐츠 이해

HttpContent 형식은 HTTP 엔터티 본문 및 해당 콘텐츠 헤더를 나타내는 데 사용됩니다. 본문(POST, PUT, PATCH)이 필요한 HTTP 메서드(또는 요청 메서드)의 경우 HttpContent 클래스를 사용하여 요청 본문을 지정합니다. 대부분의 예제에서는 JSON 페이로드를 사용하여 StringContent 서브클래스를 준비하는 방법을 보여 주지만 다른 콘텐츠(MIME) 형식에 대한 다른 서브클래스도 존재합니다.

• ByteArrayContent: 바이트 배열에 따라 HTTP 콘텐츠를 제공합니다.
• FormUrlEncodedContent: "application/x-www-form-urlencoded" MIME 형식을 사용하여 인코딩된 이름/값 튜플에 대한 HTTP 콘텐츠를 제공합니다.
• JsonContent: JSON에 따라 HTTP 콘텐츠를 제공합니다.
• MultipartContent: "multipart/*" MIME 형식 사양을 사용하여 serialize되는 HttpContent 개체의 컬렉션을 제공합니다.
• MultipartFormDataContent: "multipart/form-data" MIME 형식을 사용하여 인코딩된 콘텐츠에 대한 컨테이너를 제공합니다.
• ReadOnlyMemoryContent: ReadOnlyMemory<T> 값을 기반으로 HTTP 콘텐츠를 제공합니다.
• StreamContent: 스트림에 따라 HTTP 콘텐츠를 제공합니다.
• StringContent: 문자열에 따라 HTTP 콘텐츠를 제공합니다.

HttpContent 클래스는 HttpResponseMessage.Content 속성에서 액세스할 수 있는 HttpResponseMessage 클래스의 응답 본문을 나타내는 데도 사용됩니다.

HTTP GET 요청 사용

GET 요청은 본문을 보내면 안 됩니다. 이 요청은 메서드 이름에서 알 수 있듯이 리소스에서 데이터를 검색(또는 가져오기)하는 데 사용됩니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP GET 요청을 만들려면 HttpClient.GetAsync 메서드를 사용합니다.

static async Task GetAsync(HttpClient httpClient)
{
    using HttpResponseMessage response = await httpClient.GetAsync("todos/3");
    
    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();
    
    var jsonResponse = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"{jsonResponse}\n");

    // Expected output:
    //   GET https://jsonplaceholder.typicode.com/todos/3 HTTP/1.1
    //   {
    //     "userId": 1,
    //     "id": 3,
    //     "title": "fugiat veniam minus",
    //     "completed": false
    //   }
}

코드는 다음 작업을 완료합니다.

• GET 요청을 "https://jsonplaceholder.typicode.com/todos/3" 엔드포인트로 합니다.
• 응답이 성공하는지 확인합니다.
• 콘솔에 요청 세부 정보를 씁니다.
• 응답 본문을 문자열로 읽습니다.
• 콘솔에 JSON 응답 본문을 씁니다.

WriteRequestToConsole 메서드는 프레임워크의 일부가 아닌 사용자 지정 확장입니다. 구현에 대해 궁금한 경우 다음 C# 코드를 고려하세요.

static class HttpResponseMessageExtensions
{
    internal static void WriteRequestToConsole(this HttpResponseMessage response)
    {
        if (response is null)
        {
            return;
        }

        var request = response.RequestMessage;
        Console.Write($"{request?.Method} ");
        Console.Write($"{request?.RequestUri} ");
        Console.WriteLine($"HTTP/{request?.Version}");        
    }
}

이 기능은 다음 형식으로 콘솔에 요청 세부 정보를 작성하는 데 사용됩니다.

<HTTP Request Method> <Request URI> <HTTP/Version>

예를 들어 "https://jsonplaceholder.typicode.com/todos/3" 엔드포인트에 대한 GET 요청은 다음 메시지를 출력합니다.

GET https://jsonplaceholder.typicode.com/todos/3 HTTP/1.1

JSON에서 HTTP GET 요청 만들기

https://jsonplaceholder.typicode.com/todos 엔드포인트는 Todo 개체의 JSON 배열을 반환합니다. 해당 JSON 구조는 다음 형식과 유사합니다.

[
  {
    "userId": 1,
    "id": 1,
    "title": "example title",
    "completed": false
  },
  {
    "userId": 1,
    "id": 2,
    "title": "another example title",
    "completed": true
  },
]

C# Todo 개체는 다음과 같이 정의됩니다.

public record class Todo(
    int? UserId = null,
    int? Id = null,
    string? Title = null,
    bool? Completed = null);

record class 형식이며 선택적 IdTitle, Completed 및 UserId 속성이 있습니다. record 형식에 대한 자세한 내용은 C#의 레코드 형식 소개를 참조하세요. GET 요청을 강력한 형식의 C# 개체로 자동으로 역직렬화하려면 📦 System.Net.Http.Json NuGet 패키지의 일부인 GetFromJsonAsync 확장 메서드를 사용합니다.

static async Task GetFromJsonAsync(HttpClient httpClient)
{
    var todos = await httpClient.GetFromJsonAsync<List<Todo>>(
        "todos?userId=1&completed=false");

    Console.WriteLine("GET https://jsonplaceholder.typicode.com/todos?userId=1&completed=false HTTP/1.1");
    todos?.ForEach(Console.WriteLine);
    Console.WriteLine();

    // Expected output:
    //   GET https://jsonplaceholder.typicode.com/todos?userId=1&completed=false HTTP/1.1
    //   Todo { UserId = 1, Id = 1, Title = delectus aut autem, Completed = False }
    //   Todo { UserId = 1, Id = 2, Title = quis ut nam facilis et officia qui, Completed = False }
    //   Todo { UserId = 1, Id = 3, Title = fugiat veniam minus, Completed = False }
    //   Todo { UserId = 1, Id = 5, Title = laboriosam mollitia et enim quasi adipisci quia provident illum, Completed = False }
    //   Todo { UserId = 1, Id = 6, Title = qui ullam ratione quibusdam voluptatem quia omnis, Completed = False }
    //   Todo { UserId = 1, Id = 7, Title = illo expedita consequatur quia in, Completed = False }
    //   Todo { UserId = 1, Id = 9, Title = molestiae perspiciatis ipsa, Completed = False }
    //   Todo { UserId = 1, Id = 13, Title = et doloremque nulla, Completed = False }
    //   Todo { UserId = 1, Id = 18, Title = dolorum est consequatur ea mollitia in culpa, Completed = False }
}

코드는 다음 작업을 완료합니다.

• GET 요청을 "https://jsonplaceholder.typicode.com/todos?userId=1&completed=false"에 만듭니다.

  쿼리 문자열은 요청에 대한 필터링 조건을 나타냅니다. 명령이 성공하면 응답이 자동으로 List<Todo> 개체로 역직렬화됩니다.

• 각 Todo 개체와 함께 요청 세부 정보를 콘솔에 씁니다.

HTTP POST 요청 사용

POST 요청은 처리를 위해 데이터를 서버로 보냅니다. 요청의 Content-Type 헤더는 본문이 보내는 MIME 형식을 의미합니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP POST 요청을 만들려면 HttpClient.PostAsync 메서드를 사용합니다.

static async Task PostAsync(HttpClient httpClient)
{
    using StringContent jsonContent = new(
        JsonSerializer.Serialize(new
        {
            userId = 77,
            id = 1,
            title = "write code sample",
            completed = false
        }),
        Encoding.UTF8,
        "application/json");

    using HttpResponseMessage response = await httpClient.PostAsync(
        "todos",
        jsonContent);

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();
    
    var jsonResponse = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"{jsonResponse}\n");

    // Expected output:
    //   POST https://jsonplaceholder.typicode.com/todos HTTP/1.1
    //   {
    //     "userId": 77,
    //     "id": 201,
    //     "title": "write code sample",
    //     "completed": false
    //   }
}

코드는 다음 작업을 완료합니다.

• 요청의 JSON 본문("application/json"MIME 형식)을 사용하여 StringContent 인스턴스를 준비합니다.
• POST 요청을 "https://jsonplaceholder.typicode.com/todos" 엔드포인트로 보냅니다.
• 응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.
• 응답 본문을 콘솔에 문자열로 씁니다.

HTTP POST 요청을 JSON으로 만들기

POST 요청 인수를 자동으로 직렬화하고 응답을 강력한 형식의 C# 개체로 역직렬화하려면 PostAsJsonAsync NuGet 패키지의 일부인 확장 메서드를 사용합니다.

static async Task PostAsJsonAsync(HttpClient httpClient)
{
    using HttpResponseMessage response = await httpClient.PostAsJsonAsync(
        "todos", 
        new Todo(UserId: 9, Id: 99, Title: "Show extensions", Completed: false));

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();

    var todo = await response.Content.ReadFromJsonAsync<Todo>();
    Console.WriteLine($"{todo}\n");

    // Expected output:
    //   POST https://jsonplaceholder.typicode.com/todos HTTP/1.1
    //   Todo { UserId = 9, Id = 201, Title = Show extensions, Completed = False }
}

코드는 다음 작업을 완료합니다.

• Todo 인스턴스를 JSON으로 직렬화하고 "https://jsonplaceholder.typicode.com/todos" 엔드포인트에 POST 요청을 합니다.
• 응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.
• 응답 본문을 Todo 인스턴스로 역직렬화하고 Todo 개체를 콘솔에 씁니다.

HTTP PUT 요청 사용

PUT 요청 메서드는 기존 리소스를 대체하거나 요청 본문 페이로드를 사용하여 새 리소스를 만듭니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP PUT 요청을 만들려면 HttpClient.PutAsync 메서드를 사용합니다.

static async Task PutAsync(HttpClient httpClient)
{
    using StringContent jsonContent = new(
        JsonSerializer.Serialize(new 
        {
            userId = 1,
            id = 1,
            title = "foo bar",
            completed = false
        }),
        Encoding.UTF8,
        "application/json");

    using HttpResponseMessage response = await httpClient.PutAsync(
        "todos/1",
        jsonContent);

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();
    
    var jsonResponse = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"{jsonResponse}\n");

    // Expected output:
    //   PUT https://jsonplaceholder.typicode.com/todos/1 HTTP/1.1
    //   {
    //     "userId": 1,
    //     "id": 1,
    //     "title": "foo bar",
    //     "completed": false
    //   }
}

코드는 다음 작업을 완료합니다.

• 요청의 JSON 본문("application/json"MIME 형식)을 사용하여 StringContent 인스턴스를 준비합니다.
• PUT 요청을 "https://jsonplaceholder.typicode.com/todos/1" 엔드포인트에 하세요.
• 응답이 성공하는지 확인하고 JSON 응답 본문을 사용하여 요청 세부 정보를 콘솔에 씁니다.

HTTP PUT 요청을 JSON으로 만들기

PUT 요청 인수를 자동으로 직렬화하고 응답을 강력한 형식의 C# 개체로 역직렬화하려면 PutAsJsonAsync NuGet 패키지의 일부인 확장 메서드를 사용합니다.

static async Task PutAsJsonAsync(HttpClient httpClient)
{
    using HttpResponseMessage response = await httpClient.PutAsJsonAsync(
        "todos/5",
        new Todo(Title: "partially update todo", Completed: true));

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();

    var todo = await response.Content.ReadFromJsonAsync<Todo>();
    Console.WriteLine($"{todo}\n");

    // Expected output:
    //   PUT https://jsonplaceholder.typicode.com/todos/5 HTTP/1.1
    //   Todo { UserId = , Id = 5, Title = partially update todo, Completed = True }
}

코드는 다음 작업을 완료합니다.

• Todo 인스턴스를 JSON으로 직렬화하고 "https://jsonplaceholder.typicode.com/todos/5" 엔드포인트에 PUT 요청을 합니다.
• 응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.
• 응답 본문을 Todo 인스턴스로 역직렬화하고 Todo 개체를 콘솔에 씁니다.

HTTP PATCH 요청 사용

PATCH 요청은 기존 리소스에 대한 부분 업데이트입니다. 이 요청은 새 리소스를 만들지 않으며 기존 리소스를 대체하기 위한 것이 아닙니다. 대신 이 메서드는 리소스를 부분적으로만 업데이트합니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP PATCH 요청을 만들려면 HttpClient.PatchAsync 메서드를 사용합니다.

static async Task PatchAsync(HttpClient httpClient)
{
    using StringContent jsonContent = new(
        JsonSerializer.Serialize(new
        {
            completed = true
        }),
        Encoding.UTF8,
        "application/json");

    using HttpResponseMessage response = await httpClient.PatchAsync(
        "todos/1",
        jsonContent);

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();

    var jsonResponse = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"{jsonResponse}\n");

    // Expected output
    //   PATCH https://jsonplaceholder.typicode.com/todos/1 HTTP/1.1
    //   {
    //     "userId": 1,
    //     "id": 1,
    //     "title": "delectus aut autem",
    //     "completed": true
    //   }
}

코드는 다음 작업을 완료합니다.

• 요청의 JSON 본문("application/json"MIME 형식)을 사용하여 StringContent 인스턴스를 준비합니다.
• "https://jsonplaceholder.typicode.com/todos/1" 엔드포인트에 PATCH 요청을 합니다.
• 응답이 성공하는지 확인하고 JSON 응답 본문을 사용하여 요청 세부 정보를 콘솔에 씁니다.

PATCH NuGet 패키지에는 System.Net.Http.Json 요청에 대한 확장 메서드가 존재하지 않습니다.

HTTP DELETE 요청 사용

DELETE 요청은 기존 리소스를 제거하고, 요청은 멱등적이지만 안전하지는 않습니다. 동일한 리소스에 대한 여러 DELETE 요청은 동일한 결과를 생성하지만 요청은 리소스의 상태에 영향을 줍니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP DELETE 요청을 만들려면 HttpClient.DeleteAsync 메서드를 사용합니다.

static async Task DeleteAsync(HttpClient httpClient)
{
    using HttpResponseMessage response = await httpClient.DeleteAsync("todos/1");
    
    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();

    var jsonResponse = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"{jsonResponse}\n");

    // Expected output
    //   DELETE https://jsonplaceholder.typicode.com/todos/1 HTTP/1.1
    //   {}
}

코드는 다음 작업을 완료합니다.

• "https://jsonplaceholder.typicode.com/todos/1" 엔드포인트로 DELETE 요청을 보냅니다.
• 응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.

HTTP HEAD 요청 살펴보기

HEAD 요청은 GET 요청과 유사합니다. 이 요청은 리소스를 반환하는 대신 리소스와 연결된 헤더만 반환합니다. HEAD 요청에 대한 응답은 본문을 반환하지 않습니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP HEAD 요청을 만들려면 HttpMethod 형식이 HttpMethod.Head설정된 HttpClient.SendAsync 메서드를 사용합니다.

static async Task HeadAsync(HttpClient httpClient)
{
    using HttpRequestMessage request = new(
        HttpMethod.Head, 
        "https://www.example.com");

    using HttpResponseMessage response = await httpClient.SendAsync(request);

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();

    foreach (var header in response.Headers)
    {
        Console.WriteLine($"{header.Key}: {string.Join(", ", header.Value)}");
    }
    Console.WriteLine();

    // Expected output:
    //   HEAD https://www.example.com/ HTTP/1.1
    //   Accept-Ranges: bytes
    //   Age: 550374
    //   Cache-Control: max-age=604800
    //   Date: Wed, 10 Aug 2022 17:24:55 GMT
    //   ETag: "3147526947"
    //   Server: ECS, (cha / 80E2)
    //   X-Cache: HIT
}

코드는 다음 작업을 완료합니다.

• "https://www.example.com/" 엔드포인트에 HEAD 요청을 합니다.
• 응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.
• 모든 응답 헤더를 반복하고 각 헤더를 콘솔에 씁니다.

HTTP OPTIONS 요청 살펴보기

OPTIONS 요청은 서버 또는 엔드포인트가 지원하는 HTTP 메서드를 식별하는 데 사용됩니다. HttpClient 인스턴스 및 Uri 개체가 지정된 HTTP OPTIONS 요청을 만들려면 HttpMethod 형식이 HttpMethod.Options설정된 HttpClient.SendAsync 메서드를 사용합니다.

static async Task OptionsAsync(HttpClient httpClient)
{
    using HttpRequestMessage request = new(
        HttpMethod.Options, 
        "https://www.example.com");

    using HttpResponseMessage response = await httpClient.SendAsync(request);

    response.EnsureSuccessStatusCode()
        .WriteRequestToConsole();

    foreach (var header in response.Content.Headers)
    {
        Console.WriteLine($"{header.Key}: {string.Join(", ", header.Value)}");
    }
    Console.WriteLine();

    // Expected output
    //   OPTIONS https://www.example.com/ HTTP/1.1
    //   Allow: OPTIONS, GET, HEAD, POST
    //   Content-Type: text/html; charset=utf-8
    //   Expires: Wed, 17 Aug 2022 17:28:42 GMT
    //   Content-Length: 0
}

코드는 다음 작업을 완료합니다.

• "https://www.example.com/" 엔드포인트에 OPTIONS HTTP 요청을 보냅니다.
• 응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.
• 모든 응답 콘텐츠 헤더를 반복하고 각 헤더를 콘솔에 씁니다.

HTTP TRACE 요청 살펴보기

TRACE 요청은 요청 메시지의 애플리케이션 수준 루프백을 제공하기 때문에 디버깅에 유용할 수 있습니다. HTTP TRACE 요청을 만들려면 HttpMethod.Trace 형식을 사용하여 HttpRequestMessage 만듭니다.

using HttpRequestMessage request = new(
    HttpMethod.Trace, 
    "{ValidRequestUri}");

HTTP 응답 처리

HTTP 응답을 처리할 때 HttpResponseMessage 형식과 상호 작용합니다. 응답의 유효성을 평가하는 데 여러 멤버가 사용됩니다. HTTP 상태 코드는 HttpResponseMessage.StatusCode 속성에서 사용할 수 있습니다.

클라이언트 인스턴스가 지정된 요청을 전송한다고 가정합니다.

using HttpResponseMessage response = await httpClient.SendAsync(request);

response OK(HTTP 상태 코드 200)되도록 하려면 다음 예제와 같이 값을 평가할 수 있습니다.

if (response is { StatusCode: HttpStatusCode.OK })
{
    // Omitted for brevity...
}

CREATED(HTTP 상태 코드 201), ACCEPTED(HTTP 상태 코드 202), NO CONTENT(HTTP 상태 코드 204) 및 RESET CONTENT(HTTP 상태 코드 205)와 같은 성공적인 응답을 나타내는 다른 HTTP 상태 코드가 있습니다. HttpResponseMessage.IsSuccessStatusCode 속성을 사용하여 이러한 코드도 평가할 수 있습니다. 그러면 응답 상태 코드가 200-299 범위 내에 있는지 확인할 수 있습니다.

if (response.IsSuccessStatusCode)
{
    // Omitted for brevity...
}

프레임워크에서 HttpRequestException 오류를 발생시켜야 한다면, HttpResponseMessage.EnsureSuccessStatusCode() 메서드를 호출할 수 있습니다.

response.EnsureSuccessStatusCode();

응답 상태 코드가 200-299 범위 내에 있지 않으면 이 코드는 HttpRequestException 오류를 throw합니다.

HTTP 유효한 콘텐츠 응답 살펴보기

유효한 응답을 사용하면 Content 속성을 사용하여 응답 본문에 액세스할 수 있습니다. 본문은 스트림, 바이트 배열 또는 문자열로 본문에 액세스하는 데 사용할 수 있는 HttpContent 인스턴스로 사용할 수 있습니다.

다음 코드는 responseStream 개체를 사용하여 응답 본문을 읽습니다.

await using Stream responseStream =
    await response.Content.ReadAsStreamAsync();

다른 개체를 사용하여 응답 본문을 읽을 수 있습니다. responseByteArray 개체를 사용하여 응답 본문을 읽습니다.

byte[] responseByteArray = await response.Content.ReadAsByteArrayAsync();

responseString 개체를 사용하여 응답 본문을 읽습니다.

string responseString = await response.Content.ReadAsStringAsync();

HTTP 엔드포인트가 JSON을 반환하는 것을 알고 있는 경우 System.Net.Http.Json NuGet 패키지를 사용하여 응답 본문을 유효한 C# 개체로 역직렬화할 수 있습니다.

T? result = await response.Content.ReadFromJsonAsync<T>();

이 코드에서 result 값은 형식 T로 응답 본문이 역직렬화된 것입니다.

HTTP 오류 처리 사용

HTTP 요청이 실패하면 시스템에서 HttpRequestException 개체를 발생시킵니다. 예외를 처리하는 것만으로는 충분하지 않을 수 있습니다. 처리를 고려할 수 있는 다른 잠재적인 예외가 발생할 수 있습니다. 예를 들어 호출 코드는 요청이 완료되기 전에 취소된 취소 토큰을 사용할 수 있습니다. 이 시나리오에서는 TaskCanceledException 오류를 잡을 수 있습니다.

using var cts = new CancellationTokenSource();
try
{
    // Assuming:
    //   httpClient.Timeout = TimeSpan.FromSeconds(10)

    using var response = await httpClient.GetAsync(
        "http://localhost:5001/sleepFor?seconds=100", cts.Token);
}
catch (OperationCanceledException ex) when (cts.IsCancellationRequested)
{
    // When the token has been canceled, it is not a timeout.
    Console.WriteLine($"Canceled: {ex.Message}");
}

마찬가지로 HTTP 요청을 수행할 때 HttpClient.Timeout 값을 초과하기 전에 서버가 응답하지 않으면 동일한 예외가 throw됩니다. 이 시나리오에서는 TaskCanceledException 오류를 포착할 때 Exception.InnerException 속성을 평가하여 시간 초과가 발생했는지 식별할 수 있습니다.

try
{
    // Assuming:
    //   httpClient.Timeout = TimeSpan.FromSeconds(10)

    using var response = await httpClient.GetAsync(
        "http://localhost:5001/sleepFor?seconds=100");
}
catch (OperationCanceledException ex) when (ex.InnerException is TimeoutException tex)
{
    Console.WriteLine($"Timed out: {ex.Message}, {tex.Message}");
}

코드에서 내부 예외가 TimeoutException 형식인 경우 시간 초과가 발생하고 취소 토큰이 요청을 취소하지 않습니다.

HttpRequestException 개체를 catch할 때 HTTP 상태 코드를 평가하려면 HttpRequestException.StatusCode 속성을 평가할 수 있습니다.

try
{
    // Assuming:
    //   httpClient.Timeout = TimeSpan.FromSeconds(10)

    using var response = await httpClient.GetAsync(
        "http://localhost:5001/doesNotExist");

    response.EnsureSuccessStatusCode();
}
catch (HttpRequestException ex) when (ex is { StatusCode: HttpStatusCode.NotFound })
{
    // Handle 404
    Console.WriteLine($"Not found: {ex.Message}");
}

코드에서 EnsureSuccessStatusCode() 메서드는 응답이 성공하지 못한 경우 예외를 throw하기 위해 호출됩니다. 그런 다음, HttpRequestException.StatusCode 속성이 평가되어 응답이 404(HTTP 상태 코드 404)인지 확인합니다. HttpClient 개체에는 사용자 대신 EnsureSuccessStatusCode 메서드를 암시적으로 호출하는 몇 가지 도우미 메서드가 있습니다.

HTTP 오류 전달의 경우 다음 API를 고려합니다.

• HttpClient.GetByteArrayAsync 메서드
• HttpClient.GetStreamAsync 메서드
• HttpClient.GetStringAsync 메서드

이러한 메서드를 호출할 때 HttpRequestException 개체를 처리하고 HttpRequestException.StatusCode 속성을 평가하여 응답의 HTTP 상태 코드를 확인할 수 있습니다.

try
{
    // These extension methods will throw HttpRequestException
    // with StatusCode set when the HTTP request status code isn't 2xx:
    //
    //   GetByteArrayAsync
    //   GetStreamAsync
    //   GetStringAsync

    using var stream = await httpClient.GetStreamAsync(
        "https://localhost:5001/doesNotExists");
}
catch (HttpRequestException ex) when (ex is { StatusCode: HttpStatusCode.NotFound })
{
    // Handle 404
    Console.WriteLine($"Not found: {ex.Message}");
}

코드에서 HttpRequestException 개체를 던져야 하는 상황이 있을 수 있습니다. HttpRequestException() 생성자는 공용이며 사용자 지정 메시지와 함께 예외를 throw하는 데 사용할 수 있습니다.

try
{
    using var response = await httpClient.GetAsync(
        "https://localhost:5001/doesNotExists");

    // Throw for anything higher than 400.
    if (response is { StatusCode: >= HttpStatusCode.BadRequest })
    {
        throw new HttpRequestException(
            "Something went wrong", inner: null, response.StatusCode);
    }
}
catch (HttpRequestException ex) when (ex is { StatusCode: HttpStatusCode.NotFound })
{
    Console.WriteLine($"Not found: {ex.Message}");
}

HTTP 프록시 구성

HTTP 프록시는 두 가지 방법 중 하나로 구성할 수 있습니다. 기본값은 HttpClient.DefaultProxy 속성에 지정됩니다. 또는 HttpClientHandler.Proxy 속성에 프록시를 지정할 수 있습니다.

전역 기본 프록시 사용

HttpClient.DefaultProxy 속성은 생성자를 통해 전달된 HttpClientHandler 개체에 명시적으로 설정된 프록시가 없는 경우 모든 HttpClient 인스턴스에서 사용하는 기본 프록시를 결정하는 정적 속성입니다.

이 속성에서 반환되는 기본 인스턴스는 플랫폼에 따라 다른 규칙 집합에 따라 초기화됩니다.

• Windows: 환경 변수에서 프록시 구성을 읽거나 변수가 정의되지 않은 경우 사용자 프록시 설정에서 읽습니다.
• macOS: 환경 변수에서 프록시 구성을 읽거나 변수가 정의되지 않은 경우 시스템 프록시 설정에서 읽습니다.
• Linux: 환경 변수에서 프록시 구성을 읽거나 변수가 정의되지 않은 경우 모든 주소를 무시하도록 구성되지 않은 인스턴스를 초기화합니다.

Windows 및 Unix 기반 플랫폼에서 DefaultProxy 속성 초기화는 다음 환경 변수를 사용합니다.

• HTTP_PROXY: HTTP 요청에 사용되는 프록시 서버입니다.
• HTTPS_PROXY: HTTPS 요청에 사용되는 프록시 서버입니다.
• ALL_PROXY: HTTP_PROXY 및/또는 HTTPS_PROXY 변수가 정의되지 않은 경우 HTTP 및/또는 HTTPS 요청에 사용되는 프록시 서버입니다.
• NO_PROXY: 프록시에서 제외할 호스트 이름의 쉼표로 구분된 목록입니다. 와일드카드에는 별표가 지원되지 않습니다. 하위 도메인과 일치하려는 경우 선행 마침표(.)를 사용합니다. 예: NO_PROXY=.example.com(앞에 마침표 포함)은 www.example.com과 일치하지만 example.com와는 일치하지 않습니다. NO_PROXY=example.com(선행 기간 제외)은 www.example.com일치하지 않습니다. 이 동작은 나중에 다른 에코시스템과 더 잘 일치하도록 다시 검토될 수 있습니다.

환경 변수가 대/소문자를 구분하는 시스템에서 변수 이름은 모두 소문자 또는 모든 대문자일 수 있습니다. 소문자 이름이 먼저 확인됩니다.

프록시 서버는 호스트 이름 또는 IP 주소일 수 있으며, 필요에 따라 콜론 및 포트 번호가 뒤따를 수도 있고, http URL일 수도 있고, 필요에 따라 프록시 인증을 위한 사용자 이름 및 암호를 포함할 수도 있습니다. URL은 https아닌 http시작해야 하며 호스트 이름, IP 또는 포트 뒤의 텍스트를 포함할 수 없습니다.

클라이언트당 프록시 구성

HttpClientHandler.Proxy 속성은 인터넷 리소스에 대한 요청을 처리하는 데 사용할 WebProxy 개체를 식별합니다. 프록시를 사용하지 않도록 지정하려면 Proxy 속성을 GlobalProxySelection.GetEmptyWebProxy() 메서드에서 반환된 프록시 인스턴스로 설정합니다.

로컬 컴퓨터 또는 애플리케이션 구성 파일은 기본 프록시가 사용되도록 지정할 수 있습니다. Proxy 속성이 지정된 경우 Proxy 속성의 프록시 설정은 로컬 컴퓨터 또는 애플리케이션 구성 파일을 재정의하고 처리기는 지정된 프록시 설정을 사용합니다. 구성 파일에 프록시가 지정되지 않고 Proxy 속성이 지정되지 않은 경우 처리기는 로컬 컴퓨터에서 상속된 프록시 설정을 사용합니다. 프록시 설정이 없으면 요청이 서버로 직접 전송됩니다.

HttpClientHandler 클래스는 로컬 컴퓨터 설정에서 상속된 와일드카드 문자를 사용하여 프록시 바이패스 목록을 구문 분석합니다. 예를 들어 HttpClientHandler 클래스는 브라우저에서 "nt*"의 바이패스 목록을 "nt.*"의 정규식으로 구문 분석합니다. 따라서 http://nt.com URL은 HttpClientHandler 클래스를 사용하여 프록시를 무시합니다.

HttpClientHandler 클래스는 로컬 프록시 바이패스를 지원합니다. 클래스는 다음 조건이 충족되는 경우 대상을 로컬로 간주합니다.

• 대상에는 고정 이름(URL에 마침표(.) 없음)이 포함됩니다.
• 대상에 루프백 주소(Loopback 또는 IPv6Loopback)가 포함되거나 대상에 로컬 컴퓨터에 할당된 IPAddress 속성이 포함됩니다.
• 대상의 도메인 접미사는 DomainName 속성에 정의된 대로 로컬 컴퓨터의 도메인 접미사와 일치합니다.

프록시 구성에 대한 자세한 내용은 다음 API를 참조하세요.

• WebProxy.Address 속성
• WebProxy.BypassProxyOnLocal 속성
• WebProxy.BypassArrayList 속성

다음 단계

• .NET의 HTTP 지원
• HttpClient 사용 지침
• .NET이 포함된 HTTP 클라이언트 팩터리
• HttpClient에서 HTTP/3 사용
• HttpRepl을 사용하여 웹 API 테스트