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

아티클
08/19/2024

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

중요

모든 예제 HTTP 요청은 다음 URL 중 하나를 대상으로 합니다.

https://jsonplaceholder.typicode.com: 테스트 및 프로토타입 생성을 위한 무료 fake API입니다.
https://www.example.com: 이 도메인은 문서의 설명 예제에서 사용하기 위한 것입니다.

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

팁

이 문서의 모든 소스 코드는 GitHub: .NET Docs 리포지토리에서 사용할 수 있습니다.

`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 인스턴스는 후속 요청을 수행할 때 기준 주소를 사용합니다. 다른 구성을 적용하려면 다음을 고려합니다.

설정 HttpClient.DefaultRequestHeaders합니다.
기본이 아닌 HttpClient.Timeout을(를) 적용합니다.
HttpClient.DefaultRequestVersion 지정

팁

또는 여러 클라이언트를 구성하고 종속성 주입 서비스로 사용할 수 있는 팩터리 패턴 방식을 사용하여 HttpClient 인스턴스를 만들 수 있습니다. 자세한 내용은 .NET이 포함된 HTTP 클라이언트 팩터리를 참조하세요.

HTTP 요청 수행

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

HTTP 메서드	API
`GET`	HttpClient.GetAsync
`GET`	HttpClient.GetByteArrayAsync
`GET`	HttpClient.GetStreamAsync
`GET`	HttpClient.GetStringAsync
`POST`	HttpClient.PostAsync
`PUT`	HttpClient.PutAsync
`PATCH`	HttpClient.PatchAsync
`DELETE`	HttpClient.DeleteAsync
^†`USER SPECIFIED`	HttpClient.SendAsync

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

경고

HTTP 요청 만들기는 네트워크 I/O 바인딩된 작업으로 간주됩니다. 동기 HttpClient.Send 메서드가 있지만, 사용해야 할 적절한 이유가 없다면 비동기 API를 대신 사용하는 것이 좋습니다.

참고 항목

Android 기기를 타겟팅하는 경우(예: .NET MAUI 개발), AndroidManifest.xml에 android:usesCleartextTraffic="true"을 <application></application>에 추가해야 합니다. 이렇게 하면 Android 보안 정책으로 인해 기본적으로 비활성화되어 있는 HTTP 요청과 같은 일반 텍스트 트래픽을 활성화할 수 있습니다. 다음 XML 설정 예시를 살펴보세요:

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

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

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

HTTP Get

GET 요청은 본문을 전송하지 않으며(메서드 이름에서 알 수 있듯이) 리소스에서 데이터를 검색하거나 가져오는 데 사용됩니다. HTTP GET 요청을 수행하려면 지정된 HttpClient 및 URI에서 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
    //   }
}

위의 코드는

"https://jsonplaceholder.typicode.com/todos/3"에 GET 요청을 합니다.
응답이 성공하는지 확인합니다.
요청 세부 정보를 콘솔에 씁니다.
응답 본문을 문자열로 읽습니다.
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>

예를 들어, GET을 https://jsonplaceholder.typicode.com/todos/3로 요청하면 다음과 같은 메시지가 출력됩니다:

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

JSON에서 HTTP 가져오기

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 본문(MIME 유형이 "application/json"인)이 포함된 StringContent 인스턴스를 준비합니다.
"https://jsonplaceholder.typicode.com/todos"에 POST 요청을 합니다.
응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.
응답 본문을 콘솔에 문자열로 씁니다.

HTTP Post as JSON

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

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 요청 메서드는 기존 리소스를 대체하거나 요청 본문 페이로드를 사용하여 새 리소스를 만듭니다. HTTP PUT 요청을 수행하려면 지정된 HttpClient 및 URI에서 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 본문(MIME 유형이 "application/json"인)이 포함된 StringContent 인스턴스를 준비합니다.
"https://jsonplaceholder.typicode.com/todos/1"에 PUT 요청을 합니다.
응답이 성공하는지 확인하고 요청 세부 정보 및 JSON 응답 본문을 콘솔에 씁니다.

HTTP Put as JSON

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

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 요청은 기존 리소스에 대한 부분 업데이트입니다. 새 리소스를 만들지 않으며 기존 리소스를 대체하기 위한 것이 아닙니다. 대신 리소스를 부분적으로만 업데이트합니다. HTTP PATCH 요청을 수행하려면 지정된 HttpClient 및 URI에서 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 본문(MIME 유형이 "application/json"인)이 포함된 StringContent 인스턴스를 준비합니다.
"https://jsonplaceholder.typicode.com/todos/1"에 PATCH 요청을 합니다.
응답이 성공하는지 확인하고 요청 세부 정보 및 JSON 응답 본문을 콘솔에 씁니다.

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

HTTP Delete

DELETE 요청은 기존 리소스를 삭제합니다. DELETE 요청은 멱등적이지만 안전하지 않습니다. 즉, 동일한 리소스에 대한 여러 DELETE 요청이 동일한 결과를 생성하지만 요청은 리소스의 상태에 영향을 줍니다. HTTP DELETE 요청을 수행하려면 지정된 HttpClient 및 URI에서 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 요청을 합니다.
응답이 성공하는지 확인하고 요청 세부 정보를 콘솔에 씁니다.

팁

DELETE 요청에 대한 응답(PUT 요청과 마찬가지로)은 본문을 포함하거나 포함하지 않을 수 있습니다.

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
}

위의 코드는

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

HTTP Trace

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

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

주의

TRACE HTTP 메서드를 모든 HTTP 서버에서 지원하는 것은 아닙니다. 잘못 사용하는 경우 보안 취약성을 노출할 수 있습니다. 자세한 내용은 OWASP(Open Web Application Security Project): 교차 사이트 추적을 참조하세요.

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을 throw해야 하는 경우 HttpResponseMessage.EnsureSuccessStatusCode() 메서드를 호출할 수 있습니다.

response.EnsureSuccessStatusCode();

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

HTTP 유효한 콘텐츠 응답

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

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

앞의 코드에서 responseStream을 사용하여 응답 본문을 읽을 수 있습니다.

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

앞의 코드에서 responseByteArray를 사용하여 응답 본문을 읽을 수 있습니다.

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

앞의 코드에서 responseString을 사용하여 응답 본문을 읽을 수 있습니다.

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

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

앞의 코드에서 result는 T 형식으로 역직렬화된 응답 본문입니다.

HTTP 오류 처리

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

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를 암시적으로 호출하는 몇 가지 도우미 메서드가 있습니다. 다음 API를 고려하세요.

팁

HttpResponseMessage를 반환하지 않는 HTTP 요청에 사용되는 모든 HttpClient 메서드는 사용자를 대신하여 EnsureSuccessStatusCode을 암시적으로 호출합니다.

이러한 메서드를 호출할 때 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을 throw해야 하는 시나리오가 있을 수 있습니다. 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의 경우: 환경 변수에서 프록시 구성을 읽거나 정의되지 않은 경우 시스템의 프록시 설정에서 프록시 구성을 읽습니다.
For 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 속성이 지정되지 않은 경우 처리기는 로컬 컴퓨터에서 상속된 프록시 설정을 사용합니다. 프록시 설정이 없으면 요청이 서버로 직접 전송됩니다.

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

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

대상에는 플랫 이름이 포함되어 있습니다(URL에 점 없음).
대상에 루프백 주소(Loopback 또는 IPv6Loopback)가 포함되거나 대상에 로컬 컴퓨터에 할당된 IPAddress가 포함됩니다.
대상의 도메인 접미사는 로컬 컴퓨터의 도메인 접미사(DomainName)와 일치합니다.

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

다음을 통해 공유

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

`HttpClient` 만들기

HTTP 요청 수행

HTTP 콘텐츠

HTTP Get

JSON에서 HTTP 가져오기

HTTP Post

HTTP Post as JSON

HTTP Put

HTTP Put as JSON

HTTP Patch

HTTP Delete

HTTP Head

HTTP Options

HTTP Trace

HTTP 응답 처리

HTTP 유효한 콘텐츠 응답

HTTP 오류 처리

HTTP 프록시

전역 기본 프록시

클라이언트당 프록시

추가 정보

추가 리소스

다음을 통해 공유

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

HttpClient 만들기

HTTP 요청 수행

HTTP 콘텐츠

HTTP Get

JSON에서 HTTP 가져오기

HTTP Post

HTTP Post as JSON

HTTP Put

HTTP Put as JSON

HTTP Patch

HTTP Delete

HTTP Head

HTTP Options

HTTP Trace

HTTP 응답 처리

HTTP 유효한 콘텐츠 응답

HTTP 오류 처리

HTTP 프록시

전역 기본 프록시

클라이언트당 프록시

추가 정보

추가 리소스

`HttpClient` 만들기