Introduction

If you are writing modern .NET code, HttpClient is usually the right choice for downloading files. WebClient still exists in older code and is simple for small examples, but it belongs to the older networking API surface and is not the preferred approach for current applications.

Why HttpClient Is Preferred

HttpClient gives you better control over requests, headers, streaming, cancellation, and error handling. It also fits the rest of the modern .NET HTTP stack, including dependency injection and IHttpClientFactory in server applications.

WebClient is easier for tiny scripts, but it is limited and tied to older patterns. If you are choosing fresh code today, start with HttpClient.

Simple File Download with HttpClient

A modern approach is to stream the response and copy it directly to a file.

1using System;
2using System.IO;
3using System.Net.Http;
4using System.Threading.Tasks;
5
6class Program
7{
8    static async Task Main()
9    {
10        using HttpClient client = new HttpClient();
11        using HttpResponseMessage response = await client.GetAsync(
12            "https://example.com/file.zip",
13            HttpCompletionOption.ResponseHeadersRead
14        );
15
16        response.EnsureSuccessStatusCode();
17
18        await using Stream httpStream = await response.Content.ReadAsStreamAsync();
19        await using FileStream fileStream = File.Create("file.zip");
20        await httpStream.CopyToAsync(fileStream);
21    }
22}

This avoids loading the entire file into memory before writing it to disk, which matters for large downloads.

What WebClient Looked Like

Older code often uses WebClient because of its compact API.

1using System.Net;
2
3using WebClient client = new WebClient();
4client.DownloadFile("https://example.com/file.zip", "file.zip");

That works, but it offers less flexibility and does not fit current .NET networking guidance as well as HttpClient.

Handling Cancellation and Timeouts

One advantage of HttpClient is that it integrates cleanly with cancellation tokens.

1using System;
2using System.IO;
3using System.Net.Http;
4using System.Threading;
5using System.Threading.Tasks;
6
7static async Task DownloadAsync(string url, string path, CancellationToken token)
8{
9    using HttpClient client = new HttpClient();
10    using HttpResponseMessage response = await client.GetAsync(
11        url,
12        HttpCompletionOption.ResponseHeadersRead,
13        token
14    );
15
16    response.EnsureSuccessStatusCode();
17
18    await using Stream input = await response.Content.ReadAsStreamAsync(token);
19    await using FileStream output = File.Create(path);
20    await input.CopyToAsync(output, token);
21}

This is useful in desktop apps, services, and web backends where downloads may need to be aborted cleanly.

When WebClient Is Still Acceptable

For a quick internal script on an older codebase, WebClient can still be serviceable. The issue is not that it suddenly stopped working. The issue is that it is no longer the API you should standardize on for modern design.

If the surrounding code already uses HttpClient, introducing WebClient only adds inconsistency.

Common Pitfalls

• Choosing WebClient for new application code locks you into an older API without any real advantage over HttpClient. Prefer the modern stack unless you are maintaining legacy code.
• Using GetByteArrayAsync for large files can waste memory because the full response is buffered before writing. Stream large downloads instead.
• Forgetting EnsureSuccessStatusCode can leave you writing an error page or partial response to disk. Validate the HTTP status before saving.
• Creating and disposing many HttpClient instances in high-throughput applications can cause resource issues. In long-lived apps, use IHttpClientFactory or a shared client strategy.
• Ignoring cancellation and timeout behavior makes file downloads harder to control in real applications. Pass cancellation tokens when the caller may need to abort the operation.

Summary

• 'HttpClient is the preferred .NET API for modern file downloads.'
• It supports streaming, cancellation, headers, and better integration with the current .NET ecosystem.
• 'WebClient is simple but belongs to older networking patterns.'
• Stream large files directly to disk instead of buffering them fully in memory.
• If you are starting new code, use HttpClient unless you have a strong legacy constraint.