Tutorials 4 min read

C# HttpClient Proxy: WebProxy, Credentials and SOCKS5 in .NET (2026)

The proxy belongs to the handler, not the HttpClient. Get that right and the rest of the .NET proxy setup falls into place.

In .NET, a C# HttpClient proxy is configured on the message handler, not on HttpClient itself. That one detail explains most problems: you can't change a client's proxy after its first request, and creating a new HttpClient per request to switch proxies leads to socket exhaustion. This guide shows the right structure for .NET 6, 7 and 8, including SOCKS5 and IHttpClientFactory.

Basic Authenticated Proxy

using System.Net;

var proxy = new WebProxy("http://global.nodeproxies.xyz:8080")
{
    Credentials = new NetworkCredential("USERNAME-country-us", "PASSWORD")
};

var handler = new SocketsHttpHandler
{
    Proxy = proxy,
    UseProxy = true,
    PooledConnectionLifetime = TimeSpan.FromMinutes(5)
};

using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
var ip = await client.GetStringAsync("https://api.ipify.org");
Console.WriteLine(ip);

SocketsHttpHandler is the default implementation behind HttpClientHandler in modern .NET and exposes connection lifetime settings. HttpClientHandler with Proxy and UseProxy works the same way if you prefer it.

SOCKS5 in .NET

Since .NET 6, WebProxy accepts socks5:// addresses, and credentials work for SOCKS5 too:

var socks = new WebProxy("socks5://global.nodeproxies.xyz:1080")
{
    Credentials = new NetworkCredential("USERNAME", "PASSWORD")
};
var handler = new SocketsHttpHandler { Proxy = socks, UseProxy = true };

On .NET Framework 4.x, SOCKS isn't supported; use the HTTP endpoint. Differences between the two are in SOCKS5 vs HTTP proxies.

Why You Can't Swap the Proxy Mid-Flight

Once a handler has sent a request, changing its Proxy property throws an InvalidOperationException. And because handlers pool connections, a kept-alive tunnel keeps its exit IP. So the rule is: one handler (and one HttpClient) per proxy identity, reused for its lifetime.

One Client per Sticky Session

static HttpClient CreateSessionClient(string sessionId, string country = "us")
{
    var proxy = new WebProxy("http://global.nodeproxies.xyz:8080")
    {
        Credentials = new NetworkCredential(
            $"USERNAME-country-{country}-session-{sessionId}-time-10", "PASSWORD")
    };
    var handler = new SocketsHttpHandler
    {
        Proxy = proxy,
        UseProxy = true,
        PooledConnectionLifetime = TimeSpan.FromMinutes(10)
    };
    return new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
}

Keep a small dictionary of session ids to clients and dispose clients when their session ends. Matching PooledConnectionLifetime to the session time stops a pooled connection from outliving the IP. When to choose sticky over rotating is covered in rotating vs sticky proxies.

Rotating IPs per Request

Without a session option the gateway gives a new IP per request, but connection pooling can reuse a tunnel. If you want a different IP on every call, make the handler stop reusing connections:

var handler = new SocketsHttpHandler
{
    Proxy = proxy,
    UseProxy = true,
    PooledConnectionLifetime = TimeSpan.Zero
};

That costs a new TCP and TLS handshake per request, so it's slower. For most scraping, a short session time is a better balance.

Using IHttpClientFactory in ASP.NET Core

builder.Services.AddHttpClient("proxied", c => c.Timeout = TimeSpan.FromSeconds(30))
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        Proxy = new WebProxy("http://global.nodeproxies.xyz:8080")
        {
            Credentials = new NetworkCredential(
                builder.Configuration["Proxy:User"], builder.Configuration["Proxy:Pass"])
        },
        UseProxy = true
    });

Inject IHttpClientFactory and call CreateClient("proxied"). Keep the credentials in configuration or a secret store, not in source.

Reading Proxy Errors

  • HttpRequestException with status 407 (ProxyAuthenticationRequired): wrong credentials or inactive plan. See how to fix proxy error 407.
  • 402 from the proxy: plan out of bandwidth. Stop and top up rather than retrying.
  • TaskCanceledException: the request hit HttpClient.Timeout. Raise it for residential exits.
  • 502 or 503 on CONNECT: the proxy couldn't reach the target. Retry with a new session.

In .NET 5 and later, HttpRequestException.StatusCode carries the code, so you can branch on it without parsing messages.

Bypass Lists and the Default Proxy

WebProxy can skip the proxy for local and listed hosts. BypassList entries are regular expressions, so escape the dots:

var proxy = new WebProxy("http://global.nodeproxies.xyz:8080")
{
    Credentials = new NetworkCredential("USERNAME", "PASSWORD"),
    BypassProxyOnLocal = true,
    BypassList = new[] { @"internal\.example\.com", @".*\.svc\.cluster\.local" }
};

If you don't set a proxy at all, HttpClient uses HttpClient.DefaultProxy, which is built from the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables when they exist, and on Windows falls back to the system proxy settings. That's convenient in containers, but it also means a proxy variable left in a deployment's environment silently routes your app's traffic. Set UseProxy = false on handlers that must always connect directly.

Verify Before You Scale

Before running thousands of requests, call https://api.ipify.org through each configured client once and log the IP and the session id it belongs to. Two clients that print the same IP point to a duplicated session id. A client that prints your server's IP means UseProxy is off or a different handler was used. Never log the NetworkCredential itself.

Using .NET with NodeProxies

Create a WebProxy for http://global.nodeproxies.xyz:8080 or socks5://global.nodeproxies.xyz:1080 with your dashboard credentials. If you're building a product on top of proxies, the API in the docs lets you manage plans programmatically. Register and compare residential and datacenter options on pricing.

FAQ

How do I add proxy credentials to HttpClient in C#?

Create a WebProxy with Credentials = new NetworkCredential(user, pass) and assign it to the handler's Proxy property.

Does .NET HttpClient support SOCKS5?

Yes, from .NET 6 onward. Use a socks5:// address in WebProxy. .NET Framework doesn't support it.

Can I change the proxy on an existing HttpClient?

No. Once the handler has sent a request its proxy is fixed. Create a separate client per proxy configuration.

NodeProxies

Ready to get started?

90M+ residential, mobile & datacenter proxies. Datacenter from $0.30/GB, residential from $0.42/GB. No contracts.

Create free account