HTTP endpoints commonly return JavaScript Object Notation (JSON) data, but not always. For convenience, the optional System.Net.Http.Json NuGet package provides several extension methods for HttpClient and HttpContent that perform automatic serialization and deserialization using System.Text.Json. The examples that follow call attention to places where these extensions are available.
Tip
All of the source code from this article is available in the GitHub: .NET Docs repository.
Create an HttpClient
Most of the following examples reuse the same HttpClient instance, and therefore only need to be configured once. To create an HttpClient, use the HttpClient class constructor. For more information, see Guidelines for using HttpClient.
C#
// HttpClient lifecycle management best practices:// https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-useprivatestatic HttpClient sharedClient = new()
{
BaseAddress = new Uri("https://jsonplaceholder.typicode.com"),
};
The preceding code:
Instantiates a new HttpClient instance as a static variable. As per the guidelines, it's recommended to reuse HttpClient instances during the application's lifecycle.
Alternatively, you can create HttpClient instances using a factory-pattern approach that allows you to configure any number of clients and consume them as dependency injection services. For more information, see HTTP client factory with .NET.
Make an HTTP request
To make an HTTP request, you call any of the following APIs:
†A USER SPECIFIED request indicates that the SendAsync method accepts any valid HttpMethod.
Warning
Making HTTP requests is considered network I/O-bound work. While there is a synchronous HttpClient.Send method, it is recommended to use the asynchronous APIs instead, unless you have good reason not to.
Note
While targeting Android devices (such as with .NET MAUI development), you must add android:usesCleartextTraffic="true" to <application></application> in AndroidManifest.xml. This enables clear-text traffic, such as HTTP requests, which is otherwise disabled by default due to Android security policies. Consider the following example XML settings:
XML
<?xml version="1.0" encoding="utf-8"?><manifestxmlns:android="http://schemas.android.com/apk/res/android"><applicationandroid:usesCleartextTraffic="true"></application><!-- omitted for brevity --></manifest>
The HttpContent type is used to represent an HTTP entity body and corresponding content headers. For HTTP methods (or request methods) that require a body, POST, PUT, and PATCH, you use the HttpContent class to specify the body of the request. Most examples show how to prepare the StringContent subclass with a JSON payload, but other subclasses exist for different content (MIME) types.
A GET request shouldn't send a body and is used (as the method name indicates) to retrieve (or get) data from a resource. To make an HTTP GET request, given an HttpClient and a URI, use the HttpClient.GetAsync method:
Makes a GET request to "https://jsonplaceholder.typicode.com/todos/3".
Ensures that the response is successful.
Writes the request details to the console.
Reads the response body as a string.
Writes the JSON response body to the console.
The WriteRequestToConsole is a custom extension method that isn't part of the framework, but if you're curious about how it's implemented, consider the following C# code:
publicrecordclassTodo(int? UserId = null,
int? Id = null,
string? Title = null,
bool? Completed = null);
It's a record class type, with optional Id, Title, Completed, and UserId properties. For more information on the record type, see Introduction to record types in C#. To automatically deserialize GET requests into strongly-typed C# object, use the GetFromJsonAsync extension method that's part of the System.Net.Http.Json NuGet package.
C#
staticasync 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 }
}
In the preceding code:
A GET request is made to "https://jsonplaceholder.typicode.com/todos?userId=1&completed=false".
The query string represents the filtering criteria for the request.
The response is automatically deserialized into a List<Todo> when successful.
The request details are written to the console, along with each Todo object.
HTTP Post
A POST request sends data to the server for processing. The Content-Type header of the request signifies what MIME type the body is sending. To make an HTTP POST request, given an HttpClient and a Uri, use the HttpClient.PostAsync method:
Prepares a StringContent instance with the JSON body of the request (MIME type of "application/json").
Makes a POST request to "https://jsonplaceholder.typicode.com/todos".
Ensures that the response is successful, and writes the request details to the console.
Writes the response body as a string to the console.
HTTP Post as JSON
To automatically serialize POST request arguments and deserialize responses into strongly-typed C# objects, use the PostAsJsonAsync extension method that's part of the System.Net.Http.Json NuGet package.
C#
staticasync 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 }
}
The preceding code:
Serializes the Todo instance as JSON, and makes a POST request to "https://jsonplaceholder.typicode.com/todos".
Ensures that the response is successful, and writes the request details to the console.
Deserializes the response body into a Todo instance, and writes the Todo to the console.
HTTP Put
The PUT request method either replaces an existing resource or creates a new one using request body payload. To make an HTTP PUT request, given an HttpClient and a URI, use the HttpClient.PutAsync method:
Prepares a StringContent instance with the JSON body of the request (MIME type of "application/json").
Makes a PUT request to "https://jsonplaceholder.typicode.com/todos/1".
Ensures that the response is successful, and writes the request details and JSON response body to the console.
HTTP Put as JSON
To automatically serialize PUT request arguments and deserialize responses into strongly typed C# objects, use the PutAsJsonAsync extension method that's part of the System.Net.Http.Json NuGet package.
C#
staticasync 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 }
}
The preceding code:
Serializes the Todo instance as JSON, and makes a PUT request to "https://jsonplaceholder.typicode.com/todos/5".
Ensures that the response is successful, and writes the request details to the console.
Deserializes the response body into a Todo instance, and writes the Todo to the console.
HTTP Patch
The PATCH request is a partial update to an existing resource. It doesn't create a new resource, and it's not intended to replace an existing resource. Instead, it updates a resource only partially. To make an HTTP PATCH request, given an HttpClient and a URI, use the HttpClient.PatchAsync method:
Prepares a StringContent instance with the JSON body of the request (MIME type of "application/json").
Makes a PATCH request to "https://jsonplaceholder.typicode.com/todos/1".
Ensures that the response is successful, and writes the request details and JSON response body to the console.
No extension methods exist for PATCH requests in the System.Net.Http.Json NuGet package.
HTTP Delete
A DELETE request deletes an existing resource. A DELETE request is idempotent but not safe, meaning multiple DELETE requests to the same resources yield the same result, but the request affects the state of the resource. To make an HTTP DELETE request, given an HttpClient and a URI, use the HttpClient.DeleteAsync method:
Makes a DELETE request to "https://jsonplaceholder.typicode.com/todos/1".
Ensures that the response is successful, and writes the request details to the console.
Tip
The response to a DELETE request (just like a PUT request) may or may not include a body.
HTTP Head
The HEAD request is similar to a GET request. Instead of returning the resource, it only returns the headers associated with the resource. A response to the HEAD request doesn't return a body. To make an HTTP HEAD request, given an HttpClient and a URI, use the HttpClient.SendAsync method with the HttpMethod set to HttpMethod.Head:
Makes a HEAD request to "https://www.example.com/".
Ensures that the response is successful, and writes the request details to the console.
Iterates over all of the response headers, writing each one to the console.
HTTP Options
The OPTIONS request is used to identify which HTTP methods a server or endpoint supports. To make an HTTP OPTIONS request, given an HttpClient and a URI, use the HttpClient.SendAsync method with the HttpMethod set to HttpMethod.Options:
Sends an OPTIONS HTTP request to "https://www.example.com/".
Ensures that the response is successful, and writes the request details to the console.
Iterates over all of the response content headers, writing each one to the console.
HTTP Trace
The TRACE request can be useful for debugging as it provides application-level loop-back of the request message. To make an HTTP TRACE request, create an HttpRequestMessage using the HttpMethod.Trace:
C#
using HttpRequestMessage request = new(
HttpMethod.Trace,
"{ValidRequestUri}");
Whenever you're handling an HTTP response, you interact with the HttpResponseMessage type. Several members are used when evaluating the validity of a response. The HTTP status code is available via the HttpResponseMessage.StatusCode property. Imagine that you've sent a request given a client instance:
C#
using HttpResponseMessage response = await httpClient.SendAsync(request);
To ensure that the response is OK (HTTP status code 200), you can evaluate it as shown in the following example:
C#
if (response is { StatusCode: HttpStatusCode.OK })
{
// Omitted for brevity...
}
There are other HTTP status codes that represent a successful response, such as CREATED (HTTP status code 201), ACCEPTED (HTTP status code 202), NO CONTENT (HTTP status code 204), and RESET CONTENT (HTTP status code 205). You can use the HttpResponseMessage.IsSuccessStatusCode property to evaluate these codes as well, which ensures that the response status code is within the range 200-299:
C#
if (response.IsSuccessStatusCode)
{
// Omitted for brevity...
}
This code throws an HttpRequestException if the response status code isn't within the 200-299 range.
HTTP valid content responses
With a valid response, you can access the response body using the Content property. The body is available as an HttpContent instance, which you can use to access the body as a stream, byte array, or string:
In the preceding code, the responseString can be used to read the response body.
Finally, when you know an HTTP endpoint returns JSON, you can deserialize the response body into any valid C# object by using the System.Net.Http.Json NuGet package:
C#
T? result = await response.Content.ReadFromJsonAsync<T>();
In the preceding code, result is the response body deserialized as the type T.
HTTP error handling
When an HTTP request fails, the HttpRequestException is thrown. Catching that exception alone may not be sufficient, as there are other potential exceptions thrown that you might want to consider handling. For example, the calling code may have used a cancellation token that was canceled before the request was completed. In this scenario, you'd catch the TaskCanceledException:
C#
usingvar cts = new CancellationTokenSource();
try
{
// Assuming:// httpClient.Timeout = TimeSpan.FromSeconds(10)usingvar 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}");
}
Likewise, when making an HTTP request, if the server doesn't respond before the HttpClient.Timeout is exceeded the same exception is thrown. However, in this scenario, you can distinguish that the timeout occurred by evaluating the Exception.InnerException when catching the TaskCanceledException:
In the preceding code, the EnsureSuccessStatusCode() method is called to throw an exception if the response isn't successful. The HttpRequestException.StatusCode property is then evaluated to determine if the response was a 404 (HTTP status code 404). There are several helper methods on HttpClient that implicitly call EnsureSuccessStatusCode on your behalf, consider the following APIs:
All HttpClient methods used to make HTTP requests that don't return an HttpResponseMessage implicitly call EnsureSuccessStatusCode on your behalf.
When calling these methods, you can handle the HttpRequestException and evaluate the HttpRequestException.StatusCode property to determine the HTTP status code of the response:
C#
try
{
// These extension methods will throw HttpRequestException// with StatusCode set when the HTTP request status code isn't 2xx://// GetByteArrayAsync// GetStreamAsync// GetStringAsyncusingvar 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}");
}
There might be scenarios in which you need to throw the HttpRequestException in your code. The HttpRequestException() constructor is public, and you can use it to throw an exception with a custom message:
C#
try
{
usingvar response = await httpClient.GetAsync(
"https://localhost:5001/doesNotExists");
// Throw for anything higher than 400.if (response is { StatusCode: >= HttpStatusCode.BadRequest })
{
thrownew HttpRequestException(
"Something went wrong", inner: null, response.StatusCode);
}
}
catch (HttpRequestException ex) when (ex is { StatusCode: HttpStatusCode.NotFound })
{
Console.WriteLine($"Not found: {ex.Message}");
}
HTTP proxy
An HTTP proxy can be configured in one of two ways. A default is specified on the HttpClient.DefaultProxy property. Alternatively, you can specify a proxy on the HttpClientHandler.Proxy property.
Global default proxy
The HttpClient.DefaultProxy is a static property that determines the default proxy that all HttpClient instances use if no proxy is set explicitly in the HttpClientHandler passed through its constructor.
The default instance returned by this property initializes following a different set of rules depending on your platform:
For Windows: Reads proxy configuration from environment variables or, if those aren't defined, from the user's proxy settings.
For macOS: Reads proxy configuration from environment variables or, if those aren't defined, from the system's proxy settings.
For Linux: Reads proxy configuration from environment variables or, in case those aren't defined, this property initializes a non-configured instance that bypasses all addresses.
The environment variables used for DefaultProxy initialization on Windows and Unix-based platforms are:
HTTP_PROXY: the proxy server used on HTTP requests.
HTTPS_PROXY: the proxy server used on HTTPS requests.
ALL_PROXY: the proxy server used on HTTP and/or HTTPS requests in case HTTP_PROXY and/or HTTPS_PROXY aren't defined.
NO_PROXY: a comma-separated list of hostnames that should be excluded from proxying. Asterisks aren't supported for wildcards; use a leading dot in case you want to match a subdomain. Examples: NO_PROXY=.example.com (with leading dot) will match www.example.com, but won't match example.com. NO_PROXY=example.com (without leading dot) won't match www.example.com. This behavior might be revisited in the future to match other ecosystems better.
On systems where environment variables are case-sensitive, the variable names may be all lowercase or all uppercase. The lowercase names are checked first.
The proxy server may be a hostname or IP address, optionally followed by a colon and port number, or it may be an http URL, optionally including a username and password for proxy authentication. The URL must be start with http, not https, and can't include any text after the hostname, IP, or port.
The local computer or application config file may specify that a default proxy is used. If the Proxy property is specified, then the proxy settings from the Proxy property override the local computer or application config file and the handler uses the proxy settings specified. If no proxy is specified in a config file and the Proxy property is unspecified, the handler uses the proxy settings inherited from the local computer. If there are no proxy settings, the request is sent directly to the server.
The HttpClientHandler class parses a proxy bypass list with wildcard characters inherited from local computer settings. For example, the HttpClientHandler class parses a bypass list of "nt*" from browsers as a regular expression of "nt.*". So a URL of http://nt.com would bypass the proxy using the HttpClientHandler class.
The HttpClientHandler class supports local proxy bypass. The class considers a destination to be local if any of the following conditions are met:
The destination contains a flat name (no dots in the URL).
The destination contains a loopback address (Loopback or IPv6Loopback) or the destination contains an IPAddress assigned to the local computer.
The domain suffix of the destination matches the local computer's domain suffix (DomainName).
For more information about configuring a proxy, see:
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
.NET feedback
.NET is an open source project. Select a link to provide feedback:
Consume a REST web service by using HttpClient and perform basic CRUD operations. You'll detect when your device is connected to the internet to provide a good user experience and take advantage of the native networking stacks to get top performance.