Einrichtung des C#-HttpClient-Proxys: Anmeldedaten, Zeitlimits und Überprüfung

Diese Anleitung zeigt, wie man einen HttpClient-Proxy in C# unter .NET 8 konfiguriert: einen WebProxy mit NetworkCredential, die Wahl zwischen HttpClientHandler und SocketsHttpHandler, die korrekte Wiederverwendung von Clients mit IHttpClientFactory, Timeouts und Abbruch, die Konfiguration über Umgebungsvariablen, Bypass-Listen sowie die beiden Ausnahmen, auf die Sie in der Produktion tatsächlich stoßen werden. Der Beitrag endet mit einem vollständigen Konsolenprogramm, das eine „sticky“ Residential-Sitzung eröffnet, die Ausgangs-IP überprüft und bei einem Fehler einen erneuten Versuch mit einer neuen Sitzung unternimmt.

Alle folgenden Ausführungen beziehen sich auf .NET 8 mit Top-Level-Anweisungen, doch die API ist seit .NET Core 3.0 stabil, und derselbe Code lässt sich auch unter .NET 6 und 7 kompilieren.

WebProxy und NetworkCredential

Der Baustein lautet System.Net.WebProxy und ist auf learn.microsoft.com dokumentiert. Er enthält die Proxy-Adresse und über seine Eigenschaft Credentials den Benutzernamen und das Passwort, die der Handler sendet, wenn der Proxy eine 407-Anfrage stellt.

using System.Net;

var proxy = new WebProxy("http://premium-residential.geonode.com:9000")
{
    Credentials = new NetworkCredential("USERNAME", "PASSWORD")
};

Das Adressschema lautet http://, auch wenn die Ziele HTTPS-Adressen sind. Bei einer https://-URL sendet der Handler eine CONNECT-Anfrage an den Proxy und führt TLS mit dem Ziel innerhalb dieses Tunnels durch, sodass der Proxy-Hop selbst im reinen HTTP-Modus bleibt und die Zertifikatsvalidierung für das Ziel genau so erfolgt, wie es ohne Proxy der Fall wäre.

Da die Anmeldedaten in einer NetworkCredential-URL und nicht in der URL selbst enthalten sind, müssen Sie Sonderzeichen im Passwort nicht prozentkodieren. Dies ist ein praktischer Vorteil gegenüber Clients, die „userinfo“ nur in der Proxy-URL akzeptieren.

HttpClientHandler im Vergleich zu SocketsHttpHandler

Zwei Handler-Klassen unterstützen Proxys. HttpClientHandler ist die seit langem etablierte API; seit .NET Core 2.1 delegiert sie auf allen Plattformen an SocketsHttpHandler, sodass es hinsichtlich der Proxy-Unterstützung keinen funktionalen Unterschied gibt. Der Grund für die direkte Verwendung von SocketsHttpHandler sind die zusätzlichen Einstellmöglichkeiten, die diese Klasse bietet, und eine davon ist für Proxys von großer Bedeutung.

// Option A: HttpClientHandler
var handlerA = new HttpClientHandler
{
    Proxy = proxy,
    UseProxy = true
};

// Option B: SocketsHttpHandler (preferred for new code)
var handlerB = new SocketsHttpHandler
{
    Proxy = proxy,
    UseProxy = true,
    PooledConnectionLifetime = TimeSpan.FromMinutes(2)
};

PooledConnectionLifetime ist diese Einstellmöglichkeit. HttpClient bündelt Verbindungen und verwendet sie über mehrere Anfragen hinweg wieder. Bei einem rotierenden Proxy auf Port 9000 wird die Ausgangs-IP bei Herstellung der Verbindung zum Proxy ausgewählt; nachfolgende Anfragen über dieselbe gebündelte Verbindung behalten möglicherweise dieselbe Ausgangs-IP bei. Wenn man gepoolten Verbindungen eine begrenzte Lebensdauer zuweist, wird eine regelmäßige Neuverbindung erzwungen, wodurch auch DNS-Änderungen für den Proxy-Host übernommen werden. Zwei Minuten sind ein sinnvoller Standardwert; verkürzen Sie diesen, wenn Sie möchten, dass die Rotation häufiger stattfindet, als es Ihre natürliche Verbindungsfluktuation zulässt.

Die Tabelle fasst zusammen, wann welche Option geeignet ist.

Anforderung	Handler	Einstellung
Minimale Proxy-Konfiguration, bestehender Code	HttpClientHandler	Proxy, UseProxy = true
Begrenzte Wiederverwendung von Verbindungen mit rotierenden IPs	SocketsHttpHandler	PooledConnectionLifetime
Begrenzung der Verbindungen pro Proxy-Host	SocketsHttpHandler	MaxConnectionsPerServer
Proxy für einen Client deaktivieren	beliebig	UseProxy = false

Einen HttpClient wiederverwenden

HttpClient ist so konzipiert, dass er einmal erstellt und für die gesamte Laufzeit der Anwendung wiederverwendet wird. Das Erstellen einer neuen Instanz pro Anfrage erschöpft die Sockets unter Last, und bei Verwendung eines Proxys werden zudem die gepoolten CONNECT-Tunnel verworfen, für deren Aufbau Sie gerade Latenz in Kauf genommen haben. Verwenden Sie in einer Konsolenanwendung oder einem Worker eine einzige statische Instanz.

var http = new HttpClient(handlerB)
{
    Timeout = TimeSpan.FromSeconds(30)
};

IHttpClientFactory in ASP.NET Core

Registrieren Sie in ASP.NET Core einen benannten Client und fügen Sie den Handler über ConfigurePrimaryHttpMessageHandler hinzu. Die Factory verwaltet die Lebensdauer der Handler für Sie und wechselt diese nach einem festgelegten Zeitplan aus, wodurch sowohl das Problem der Socket-Erschöpfung als auch veraltete DNS-Einträge vermieden werden.

// Program.cs
using System.Net;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient("geonode", client =>
{
    client.Timeout = TimeSpan.FromSeconds(30);
})
.ConfigurePrimaryHttpMessageHandler(() =>
{
    var proxy = new WebProxy("http://premium-residential.geonode.com:9000")
    {
        Credentials = new NetworkCredential(
            Environment.GetEnvironmentVariable("GEONODE_USER"),
            Environment.GetEnvironmentVariable("GEONODE_PASS"))
    };

    return new SocketsHttpHandler
    {
        Proxy = proxy,
        UseProxy = true,
        PooledConnectionLifetime = TimeSpan.FromMinutes(2)
    };
});

var app = builder.Build();

app.MapGet("/ip", async (IHttpClientFactory factory) =>
{
    var client = factory.CreateClient("geonode");
    return await client.GetStringAsync("https://api.ipify.org?format=json");
});

app.Run();

Injizieren Sie IHttpClientFactory überall dort, wo Sie den Client benötigen, und rufen Sie CreateClient("geonode") auf. Die Erstellung des zurückgegebenen HttpClient ist kostengünstig, da der darunterliegende ressourcenintensive Handler gemeinsam genutzt wird.

Zeitüberschreitungen und CancellationToken

HttpClient.Timeout ist die Gesamtzeit, die für eine Anfrage zur Verfügung steht, einschließlich der Verbindung zum Proxy, des CONNECT-Handshakes, der TLS-Verbindung zum Ziel und des Lesens der Antwort-Header. Der Standardwert beträgt 100 Sekunden, was für einen Scraper-Worker zu lang ist. Legen Sie diesen Wert auf dem Client fest und übergeben Sie für eine feinere Steuerung pro Anfrage einen CancellationToken-Wert.

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(15));

try
{
    var body = await http.GetStringAsync("https://example.com/", cts.Token);
}
catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
{
    // HttpClient.Timeout elapsed
}
catch (TaskCanceledException)
{
    // the CancellationToken was cancelled (our 15 s budget)
}

Privathaushalts-Ausgänge verursachen im Vergleich zu einer direkten Verbindung zusätzliche Latenz; planen Sie daher pro Anfrage einige zusätzliche Sekunden ein. Ein konsistentes Timeout in derselben Phase bei vielen Anfragen deutet in der Regel auf ein Problem mit dem Netzwerkpfad zum Proxy-Host hin, nicht auf ein langsames Ziel.

DefaultProxy und Umgebungsvariablen

Wenn Sie im Handler keinen Wert für „Proxy“ festlegen, verwendet .NET „HttpClient.DefaultProxy“. Unter .NET Core 3.0 und höher wird diese statische Eigenschaft anhand der Umgebungsvariablen „HTTP_PROXY“, „HTTPS_PROXY“ und „NO_PROXY“ initialisiert, wobei die URL Anmeldedaten enthalten kann.

export HTTP_PROXY="http://USERNAME:PASSWORD@premium-residential.geonode.com:9000"
export HTTPS_PROXY="http://USERNAME:PASSWORD@premium-residential.geonode.com:9000"
export NO_PROXY="localhost,127.0.0.1,.internal"

Sie können HttpClient.DefaultProxy auch beim Start im Code zuweisen, was sich auf jeden Handler auswirkt, der Proxy nicht überschreibt. Dies ist in Containern praktisch, stellt jedoch einen globalen Zustand dar: Ein Health-Check-Client oder ein Aufruf einer internen API durchläuft ebenfalls den Residential-Proxy, es sei denn, NO_PROXY listet diese Hosts auf. Für alles, was über ein einmaliges Skript hinausgeht, ist ein explizites WebProxy für einen benannten Handler übersichtlicher.

BypassList und BypassProxyOnLocal

WebProxy verfügt über einen eigenen Ausschlussmechanismus. BypassProxyOnLocal = true umgeht den Proxy für Hosts, deren Name keinen Punkt enthält (wie z. B. localhost oder einen reinen Maschinennamen). BypassList akzeptiert reguläre Ausdrücke, die mit der Ziel-URI abgeglichen werden.

var proxy = new WebProxy("http://premium-residential.geonode.com:9000")
{
    Credentials = new NetworkCredential("USERNAME", "PASSWORD"),
    BypassProxyOnLocal = true,
    BypassList = new[] { @"^https?://(.*\.)?internal\.example(:\d+)?/" }
};

Beachten Sie, dass es sich hierbei um reguläre Ausdrücke und nicht um Glob-Muster handelt; ein nicht maskierter Punkt entspricht jedem beliebigen Zeichen.

Umgang mit 407 und anderen Fehlern

Zwei Fehlerarten machen fast alle HttpClient-Proxy-Fehler aus. Der erste ist ein 407 „Proxy Authentication Required“, was bedeutet, dass der Proxy die Anmeldedaten abgelehnt hat, bevor er Daten weitergeleitet hat. Dies wird in der Regel als „HttpRequestException“ angezeigt; je nach .NET-Version und Fehlerursache kann stattdessen auch eine Antwort mit dem Statuscode „HttpStatusCode.ProxyAuthenticationRequired“ zurückgegeben werden. Überprüfen Sie beide.

using System.Net;
using System.Net.Http;

try
{
    using var response = await http.GetAsync("https://example.com/");

    if (response.StatusCode == HttpStatusCode.ProxyAuthenticationRequired)
    {
        throw new InvalidOperationException("proxy rejected credentials (407)");
    }

    response.EnsureSuccessStatusCode();
    var html = await response.Content.ReadAsStringAsync();
}
catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.ProxyAuthenticationRequired)
{
    // Also 407: fix the username grammar or password; retrying will not help.
}
catch (HttpRequestException ex)
{
    // Connection refused, DNS failure, TLS error, or EnsureSuccessStatusCode on 4xx/5xx.
    Console.Error.WriteLine($"request failed: {ex.Message} (status {ex.StatusCode})");
}

Der zweite Fehler ist „TaskCanceledException“ für Zeitüberschreitungen, wie oben beschrieben. Die wichtige Regel für beide Fälle lautet: Ein 407-Fehler ist ein Konfigurationsfehler und darf nicht erneut versucht werden; eine Zeitüberschreitung oder ein 5xx-Fehler vom Ziel ist vorübergehend und ein sinnvoller Kandidat für einen erneuten Versuch in einer neuen Sitzung.

Sticky-Sessions über den Benutzernamen

Port 9000 vergibt für jede neue Verbindung eine neue Ausgangs-IP-Adresse. Wenn ein Ablauf eine einzige IP-Adresse für mehrere Anfragen benötigt (Anmeldung gefolgt von Datenseiten oder paginierten Ergebnissen), verwenden Sie Port 10000 und wählen Sie die Sitzung über den Benutzernamen aus. Die Grammatik fügt Ihrem Basis-Benutzernamen Suffixe hinzu: -country-xx für Geo-Targeting, -session-XXXXXXXX mit einer 8-stelligen alphanumerischen ID und optional -lifetime-SECONDS im Bereich von 180 bis 86400.

static string NewSessionId() =>
    Guid.NewGuid().ToString("N")[..8]; // 8 alphanumeric chars

static WebProxy StickyProxy(string baseUser, string pass, string country = "us", int lifetime = 600)
{
    var user = $"{baseUser}-country-{country}-session-{NewSessionId()}-lifetime-{lifetime}";
    return new WebProxy("http://premium-residential.geonode.com:10000")
    {
        Credentials = new NetworkCredential(user, pass)
    };
}

Jede Anfrage über einen auf diesem Proxy basierenden Client nutzt zehn Minuten lang dieselbe Ausgangs-IP-Adresse. Um die IP-Adresse zu wechseln, erstellen Sie einen neuen Handler mit einer neuen Sitzungs-ID. Da die Sitzung an die Anmeldedaten gebunden ist, teilen sich zwei Clients mit demselben Benutzernamen dieselbe Ausgangs-IP-Adresse, auch über Prozesse hinweg.

Überprüfung der Ausgangs-IP

Gehen Sie niemals davon aus, dass der HttpClient-Proxy verwendet wird; überprüfen Sie dies. Fordern Sie https://api.ipify.org?format=json (oder https://httpbin.org/ip) über den Client an und vergleichen Sie die angezeigte IP-Adresse mit Ihrer tatsächlichen Adresse. Bei einer „Sticky Session“ geben beide Aufrufe dieselbe IP-Adresse zurück; bei Port 9000 und einer neuen Verbindung unterscheiden sie sich.

using System.Text.Json;

var json = await http.GetStringAsync("https://api.ipify.org?format=json");
var ip = JsonDocument.Parse(json).RootElement.GetProperty("ip").GetString();
Console.WriteLine($"exit IP: {ip}");

Vollständiges Konsolenbeispiel (.NET 8)

Das folgende Programm vereint alle Komponenten: eine „Sticky Session“, begrenzte Timeouts, die Erkennung des Fehlers 407 sowie bis zu drei Versuche mit einer neuen Sitzung bei vorübergehenden Fehlern. Erstellen Sie es mit dotnet new console -n ProxyDemo, ersetzen Sie Program.cs, legen Sie GEONODE_USER und GEONODE_PASS fest und führen Sie dotnet run aus.

// Program.cs  (.NET 8, top-level statements)
using System.Net;
using System.Text.Json;

var baseUser = Environment.GetEnvironmentVariable("GEONODE_USER")
    ?? throw new InvalidOperationException("GEONODE_USER not set");
var password = Environment.GetEnvironmentVariable("GEONODE_PASS")
    ?? throw new InvalidOperationException("GEONODE_PASS not set");

var target = args.Length > 0 ? args[0] : "https://api.ipify.org?format=json";

for (var attempt = 1; attempt <= 3; attempt++)
{
    var sessionId = Guid.NewGuid().ToString("N")[..8];
    var user = $"{baseUser}-country-us-session-{sessionId}-lifetime-600";

    var handler = new SocketsHttpHandler
    {
        Proxy = new WebProxy("http://premium-residential.geonode.com:10000")
        {
            Credentials = new NetworkCredential(user, password)
        },
        UseProxy = true,
        PooledConnectionLifetime = TimeSpan.FromMinutes(2)
    };

    using var http = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(20));

    try
    {
        // 1. Confirm the exit IP for this session.
        var ipJson = await http.GetStringAsync("https://api.ipify.org?format=json", cts.Token);
        var ip = JsonDocument.Parse(ipJson).RootElement.GetProperty("ip").GetString();
        Console.WriteLine($"[attempt {attempt}] session {sessionId} exit IP {ip}");

        // 2. Fetch the real target on the same IP.
        using var response = await http.GetAsync(target, cts.Token);

        if (response.StatusCode == HttpStatusCode.ProxyAuthenticationRequired)
        {
            Console.Error.WriteLine("407: proxy rejected credentials, not retrying");
            return;
        }

        if ((int)response.StatusCode is 403 or 429 or >= 500)
        {
            Console.Error.WriteLine($"[attempt {attempt}] got {(int)response.StatusCode}, rotating session");
            continue;
        }

        var body = await response.Content.ReadAsStringAsync(cts.Token);
        Console.WriteLine($"{(int)response.StatusCode} {target} ({body.Length} chars)");
        return;
    }
    catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.ProxyAuthenticationRequired)
    {
        Console.Error.WriteLine("407: proxy rejected credentials, not retrying");
        return;
    }
    catch (HttpRequestException ex)
    {
        Console.Error.WriteLine($"[attempt {attempt}] network error: {ex.Message}");
    }
    catch (TaskCanceledException)
    {
        Console.Error.WriteLine($"[attempt {attempt}] timed out");
    }

    await Task.Delay(TimeSpan.FromMilliseconds(500 * attempt));
}

Console.Error.WriteLine("gave up after 3 attempts");

Der Handler wird absichtlich bei jedem Versuch neu erstellt: Eine „Sticky Session“ ist an den Benutzernamen in den Anmeldedaten gebunden, sodass für eine neue Sitzung ein neues WebProxy erforderlich ist. In einem lang laufenden Dienst würden Sie einen Client pro Sitzungs-ID statt pro Anfrage zwischenspeichern.

Häufige Fehler

Erstellung eines HttpClient pro Anfrage

Jeder neue Client öffnet einen neuen CONNECT-Tunnel und hinterlässt Sockets in TIME_WAIT. Verwenden Sie eine Instanz wieder oder nutzen Sie IHttpClientFactory und überlassen Sie die Rotation PooledConnectionLifetime.

Verwendung einer „https://“-Proxy-Adresse

Der Proxy-Hop erfolgt über einfaches HTTP; HTTPS-Ziele werden innerhalb des CONNECT-Tunnels übertragen. Ein https://-Schema auf der Adresse WebProxy weist .NET an, TLS mit dem Proxy selbst auszuhandeln, was bei einem Endpunkt, der einfaches HTTP erwartet, fehlschlägt.

Wiederholung eines 407-Fehlers

Ein 407-Fehler bedeutet, dass der Proxy die Anmeldedaten nicht akzeptiert hat. Ein erneuter Versuch mit demselben Benutzernamen und Passwort ist reine Zeitverschwendung. Brechen Sie den Vorgang frühzeitig ab und überprüfen Sie die Gültigkeit des Benutzernamens, insbesondere die Länge der Sitzungs-ID und den Gültigkeitszeitraum.

Ignorieren von NO_PROXY und BypassList

Wenn der Proxy von DefaultProxy stammt, wird er von jedem ausgehenden Aufruf im Prozess verwendet, einschließlich Zustandsprüfungen und interner APIs. Führen Sie diese Hosts in NO_PROXY oder BypassList auf, oder konfigurieren Sie den Proxy nur für einen namentlich genannten Client.

Nächster Schritt

Der obige Code läuft unverändert mit den Geonode-Proxys für Privathaushalte: 2,5 Millionen IP-Adressen in über 195 Ländern, HTTP, HTTPS und SOCKS5 auf einem Host sowie Sticky-Sessions von bis zu 24 Stunden, ausgewählt anhand der hier gezeigten Benutzernamen-Grammatik. Für das Targeting nach Land, Bundesland, Stadt und ASN werden dieselben Suffixe verwendet, sodass die Eingrenzung des Ausgangsstandorts lediglich eine Änderung der Zeichenfolge und keine Codeänderung erfordert. Die Preisgestaltung entspricht pay-as-you-go ohne Vertragsbindung, ab 10 GB für 7,92 $ pro Monat, mit einer 3-tägigen Testphase für 5 $. Weitere Informationen finden Sie unter Privathaushalts-Proxys oder vergleichen Sie die Tarife auf der Preisseite. Für den weiteren Verlauf der Pipeline beginnen Sie mit dem Anwendungsfall „Web-Scraping“.

FAQ

Wie richte ich in C# einen HttpClient-Proxy mit Benutzername und Passwort ein?

Erstellen Sie ein WebProxy mit der Proxy-Adresse und setzen Sie dessen Credentials-Eigenschaft auf ein NetworkCredential, das den Benutzernamen und das Passwort enthält. Weisen Sie dieses WebProxy der Eigenschaft Proxy eines HttpClientHandler oder SocketsHttpHandler zu, setzen Sie UseProxy auf „true“ und übergeben Sie den Handler an den Konstruktor von HttpClient. Der Handler sendet die Anmeldedaten, wenn der Proxy den Status 407 zurückgibt.

Sollte ich für einen Proxy „HttpClientHandler“ oder „SocketsHttpHandler“ verwenden?

Unter .NET Core 2.1 und höher ist HttpClientHandler ein dünner Wrapper um SocketsHttpHandler, daher funktionieren beide. SocketsHttpHandler stellt PooledConnectionLifetime bereit, womit Sie gepoolte Verbindungen regelmäßig wiederverwenden können. Das ist bei rotierenden Proxys von Bedeutung, da eine wiederverwendete Verbindung dieselbe Ausgangs-IP beibehält, bis sie geschlossen wird. Verwenden Sie für neuen Code vorzugsweise SocketsHttpHandler.

Warum löst meine HttpClient-Proxy-Anfrage eine „TaskCanceledException“ aus?

HttpClient meldet ein Timeout als TaskCanceledException und nicht als eigene Timeout-Ausnahme. Sie wird ausgelöst, wenn HttpClient.Timeout abläuft oder wenn das von Ihnen übergebene CancellationToken abgebrochen wird. Unter .NET 5 und höher ist die innere Ausnahme eine TimeoutException, wenn das Client-Timeout die Ursache war, wodurch Sie die beiden Fälle unterscheiden können.

Liest der HttpClient die Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY?

Ja. Unter .NET Core 3.0 und höher wird HttpClient.DefaultProxy aus HTTP_PROXY, HTTPS_PROXY und NO_PROXY initialisiert, und Handler verwenden es, wenn kein explizites Proxy festgelegt ist. Anmeldeinformationen können in die URL aufgenommen werden. Das Setzen der Umgebungsvariablen ist in Containern praktisch, aber ein expliziter WebProxy im Code ist leichter nachzuvollziehen.

Wie behalte ich über mehrere HttpClient-Proxy-Anfragen hinweg dieselbe IP-Adresse bei?

Verwenden Sie den Sticky-Port 10000 und fügen Sie dem Benutzernamen ein Sitzungssuffix hinzu, zum Beispiel USER-country-us-session-a1b2c3d4-lifetime-600. Alle mit diesem Benutzernamen gesendeten Anfragen teilen sich eine Ausgangs-IP für die in Sekunden angegebene Laufzeit zwischen 180 und 86.400. Generieren Sie eine neue 8-stellige Sitzungs-ID, wenn Sie eine neue IP-Adresse wünschen.

Welche Beschränkungen gelten beim Scraping über einen privaten HttpClient-Proxy?

Die Bandbreite wird pro Gigabyte abgerechnet. Laden Sie daher nur das herunter, was Sie benötigen, und vermeiden Sie nach Möglichkeit Bilder. „Sticky Sessions“ behalten eine IP-Adresse für maximal 24 Stunden bei und können vorzeitig enden, wenn das Gerät offline geht. Ihr Code muss daher mit einem IP-Wechsel umgehen können. Ein Proxy befreit Sie nicht von den Nutzungsbedingungen einer Website, den Robots-Richtlinien oder den Ratenbeschränkungen.