GeeTest v4 in C#: GeetestV4Async und IHttpClientFactory

Um GeeTest v4 in C# zu verwenden, lesen Sie die eine öffentliche captcha_id von der Seite, rufen Sie GeetestV4Async aus dem CapSkip-NuGet-Paket einmal pro Formularübermittlung auf und senden Sie die fünf zurückgegebenen Werte unter ihren eigenen Namen per POST. Dieser Beitrag baut das als kleinen .NET-Konsolen-Host auf. Ein typisierter HttpClient aus IHttpClientFactory spricht mit der Website, ein CapSkipClient spricht mit dem Löser auf Ihrem eigenen Windows-PC, und ein Semaphor verhindert, dass ein Stapel von Übermittlungen gleichzeitig löst. Das Produkt dahinter ist der GeeTest-v4-Löser und kostet keine Gebühr pro Lösung.
Was Sie brauchen
- Ein CapSkip-Build, der GeeTest v4 aufführt, läuft auf einem Windows-PC. Die Einrichtungsanleitung führt durch die Einrichtung. Ich konnte nicht prüfen, welche App-Version ich hatte, weil die App auf diesem PC nicht antwortete.
- Das .NET 8 SDK oder neuer und das CapSkip-Paket ab 1.8.0, die erste Version mit GeetestV4Async (Changelog-Eintrag vom 2026-11-16). Das Paket selbst zielt auf .NET Standard 2.0, aber das folgende Beispiel nutzt C#-12-Syntax und die Microsoft.Extensions-Pakete, daher habe ich es nur auf net8.0 und net10.0 ausgeführt. Hier ist nur das SDK 10.0.100 installiert, also wurde net8.0 gebaut, indem die Zeile TargetFramework geändert wurde, und auf der 8.0-Runtime ausgeführt.
- Eine Seite, die Sie automatisieren dürfen und die ein GeeTest-v4-Widget zeigt, und die Adresse des Formulars, an das sie sendet.
- Eine Adresse für CapSkip. Im Local mode kann nur der PC, auf dem es läuft, 127.0.0.1 erreichen. Der Server mode macht die API auch von anderen Rechnern aus erreichbar, und die Einrichtungsanleitung erklärt beide Modi unter Verbindungseinstellungen.
Ich konnte beim Testen keine laufende CapSkip-App erreichen, daher lief keine echte Lösung und es wurde keine echte Website kontaktiert. Jedes Ergebnis unten stammt von einem Mock, den ich geschrieben habe und der in.php, res.php und eine Website mit Kommentarformular spielt. Der Mock folgt der API-Referenz des SDK, und seine Website-Regeln stammen von mir, nicht von GeeTest. Wo eine Aussage auf der Dokumentation oder auf dem Lesen des SDK-Quellcodes beruht, sage ich das.
Schritt 1: den Host und einen typisierten Client für die Website anlegen
Legen Sie einen Projektordner an und installieren Sie die drei Pakete. Ich habe nur net8.0 und net10.0 getestet.
dotnet new console -o GeetestWorker cd GeetestWorker dotnet add package CapSkip dotnet add package Microsoft.Extensions.Hosting dotnet add package Microsoft.Extensions.Http
Tauschen Sie nur auf net8.0 die letzten beiden Befehle gegen diese festgelegten aus. Die neuesten 11.0.0-Pakete bauen auf net8.0, geben aber für jedes Paket eine Warnung wegen nicht unterstützten Frameworks aus, und die festgelegten Versionen bauten ohne eine.
# Only on net8.0: use these instead of the two Microsoft.Extensions lines above. dotnet add package Microsoft.Extensions.Hosting --version 8.0.1 dotnet add package Microsoft.Extensions.Http --version 8.0.1
Die nächsten drei C#-Blöcke sind Dateien für den Projektordner, und jede beginnt mit ihrem Dateinamen. Speichern Sie sie in der gezeigten Reihenfolge. Die letzte, Program.cs, ersetzt die Datei, die die Vorlage erzeugt hat.
Der typisierte Client gehört nur zur Ziel-Website. Nach dem SDK-Quellcode baut CapSkipClient intern seinen eigenen statischen HttpClient und hat keinen Konstruktor, der Ihren annimmt, daher hilft IHttpClientFactory bei Ihren eigenen Aufrufen und sonst nirgends. SiteClient erledigt zwei Aufgaben: Er liest die captcha_id und sendet das Formular per POST.
// SiteClient.cs
using System.Text.RegularExpressions;
using CapSkip;
// The typed client talks to the target site only. CapSkipClient has its own HttpClient.
public sealed class SiteClient(HttpClient http)
{
// Finds captchaId with either quote style, however deeply the call is nested.
static readonly Regex IdPattern = new(@"captchaId[""']?\s*:\s*[""']([0-9a-fA-F]{32})[""']");
public async Task<string> ReadCaptchaIdAsync(string pageUrl, CancellationToken ct)
{
var html = await http.GetStringAsync(pageUrl, ct);
var m = IdPattern.Match(html);
return m.Success ? m.Groups[1].Value : throw new InvalidOperationException("no captchaId on " + pageUrl);
}
// The five values go back under GeeTest's own names. "text" is this form's field.
public async Task<string> PostAsync(string pageUrl, string formUrl, SolveResult r, string text, CancellationToken ct)
{
using var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
["captcha_id"] = r.GeetestCaptchaId!,
["lot_number"] = r.LotNumber!,
["pass_token"] = r.PassToken!,
["gen_time"] = r.GenTime!,
["captcha_output"] = r.CaptchaOutput!,
["text"] = text,
});
using var request = new HttpRequestMessage(HttpMethod.Post, formUrl) { Content = form };
request.Headers.Referrer = new Uri(pageUrl); // many frameworks check it on a form post
using var response = await http.SendAsync(request, ct);
return $"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync(ct)}";
}
}GeeTest v4 hat keine Challenge, die pro Anfrage abzurufen wäre, anders als der v3-Ablauf im Beitrag zu GeeTest v3 in C#. Die Seite übergibt eine ID, für jeden Besucher dieselbe, als captchaId an initGeetest4, daher lesen Sie sie einmal und verwenden sie wieder. Wenn die Seite diesen Aufruf zur Laufzeit zusammenbaut, verweist die SDK-Dokumentation auf den Query-Parameter captcha_id der Anfrage an gcaptcha4.geetest.com/load im Network-Tab des Browsers. Der reguläre Ausdruck traf drei Mock-Seiten wie erwartet: einen Aufruf mit doppelten Anführungszeichen, einen Aufruf mit einfachen Anführungszeichen, verschachtelt in zwei Objekten, und eine Seite ohne ID, die die InvalidOperationException warf.
Zwei Details des Clients stammen aus Läufen. Die Factory poolt ihre Message-Handler, und der Standard-Handler hält für alle Anfragen ein einziges Cookie-Jar: Bei drei GETs trugen der zweite und der dritte das Cookie, das die vorherige Antwort gesetzt hatte. Mit UseCookies auf false, wie in Program.cs unten, tat das keiner (Mock, net10.0 und net8.0). Wenn Ihr Formular das Session-Cookie der Seite braucht, lesen Sie Set-Cookie pro Übermittlung und senden Sie es selbst zurück. HttpClient fügt außerdem von sich aus keinen Referer hinzu: Ohne diese Zeile sah der Mock einen leeren Header, weshalb der Code ihn setzt.
Schritt 2: eine Lösung pro Übermittlung
GeetestV4Async nimmt die captcha_id, die Seitenadresse, ein optionales Dictionary mit Optionen und ein CancellationToken entgegen. Es gibt ein SolveResult zurück. Die folgende Klasse ist die Einheit, die löst und dann per POST sendet, und ein SemaphoreSlim von drei begrenzt, wie viele Lösungen gleichzeitig laufen. Wählen Sie eine Zahl, die Ihr CapSkip-PC verkraftet, denn drei ist nur meine Einstellung im Mock.
// Submitter.cs
using CapSkip;
public sealed class Submitter(CapSkipClient solver, SiteClient site)
{
// At most 3 solves in flight. Size this to what your CapSkip PC can take.
readonly SemaphoreSlim gate = new(3);
public async Task<string> SubmitAsync(string captchaId, string pageUrl, string formUrl, string text, CancellationToken ct)
{
SolveResult result;
await gate.WaitAsync(ct);
try
{
// One solve per submission: this result is used for one form post and dropped.
result = await solver.GeetestV4Async(captchaId, pageUrl, cancellationToken: ct);
}
finally { gate.Release(); }
// The site decides whether an offline pass counts, so do not send it blindly.
if (result.IsOffline == true) return "offline pass, not sent";
return await site.PostAsync(pageUrl, formUrl, result, text, ct);
}
}Das Ergebnis trägt die fünf Werte als GeetestCaptchaId, LotNumber, PassToken, GenTime und CaptchaOutput, alle als Strings. Der erste heißt nicht CaptchaId, weil dieser Name schon die ID ist, die CapSkip der Lösung gibt (der Mock vergab 9101 und aufwärts), was das Changelog erklärt. Code behält den rohen JSON-String, den die API sendet, und im Mock-Lauf waren Token und Challenge null, da sie zu anderen Typen gehören.
Warum pro Übermittlung lösen? Das eigene Beispiel des SDK sagt, für jede Übermittlung erneut zu lösen, und mein Mock erzwingt es: Als ein Ergebnis zweimal gesendet wurde, kam ein 403, dessen Body sagte, das pass_token sei schon verwendet. Das ist die Regel des Mocks. Die GeeTest-Seite zur Server-Validierung, die ich gelesen habe, sagt nicht, ob eine Freigabe zweimal verwendet werden kann, halten Sie sich also an den Rat des SDK. Die CapSkip-Dokumentation sagt außerdem, zügig zu senden, und die GeeTest-Seite sagt, dass ein abgelaufenes pass_token die Validierung nicht besteht, was der stärkere Grund ist, pro Übermittlung zu lösen.
Wer prüft das Ergebnis? Der eigene Server der Website. Laut der GeeTest-Dokumentation zur Server-Validierung (die Seite ist auf Chinesisch) sendet er lot_number, captcha_output, pass_token und gen_time an GeeTest, dazu captcha_id und ein sign_token, ein HMAC-SHA256 von lot_number, gebildet mit dem privaten Schlüssel der Website. CapSkip sieht diesen Schlüssel nie, und Ihr Code braucht ihn nicht.
IsOffline ist ein nullable bool. Laut Dokumentation ist es true, wenn GeeTest nicht erreichbar war und sein Widget ohne Challenge bestand, und die Website entscheidet dann, ob sie es akzeptiert. Das SDK liest true, das Wort true in jeder Groß- und Kleinschreibung und eine Zahl ungleich 0 als true, 0 und das Wort false als false und alles, was es nicht lesen kann, als null (Antworten des Mocks, alle sechs Formen). Der Code oben überspringt eine Offline-Freigabe. Wenn Ihre Website sie akzeptiert, löschen Sie diese Zeile.
Beide Optionen sind optional. Dieser Ausschnitt ersetzt den Aufruf von GeetestV4Async in Submitter.cs:
// Snippet, not a file: replace the GeetestV4Async call in Submitter.cs with this one.
result = await solver.GeetestV4Async(captchaId, pageUrl, new Dictionary<string, object?>
{
["risk_type"] = "slide",
["proxy"] = new Proxy("HTTP", "login:[email protected]:8080"),
}, ct);Laut Dokumentation nimmt risk_type einen von zehn Werten an: slide, icon, nine, word, phrase, match, winlinze, svg_seed, svg_icon und ai. GeeTest wendet einen nur an, wo die Website dem Aufrufer die Wahl erlaubt. Das SDK prüft den Wert nicht: Es kürzte Leerraum, verwarf einen leeren Wert und sendete einen Unsinnswert unverändert, und eine Zahl wies es mit einer ValidationException ab. Die Schreibweise riskType funktioniert als Alias. Verwenden Sie proxy, wenn die Website für die Lösung und den Formular-POST dieselbe Adresse braucht, wie der Beitrag zu Proxys für Captcha-Löser erklärt. Ein reiner Adress-String bedeutet HTTP, und ein Typ außerhalb von HTTP, HTTPS, SOCKS5 und SOCKS5H wird lokal abgelehnt.
Denken Sie bei einem gleichzeitigen Stapel auch an das Netzwerk. Die CapSkip-API-Dokumentation sagt, GeeTest bewertet das Netzwerk, und ein stetiger Strom von Anfragen von einer Adresse ist es, was seine Ratenbegrenzung erfasst. Fügen Sie in der CapSkip-App unter Settings, Captcha types, GeeTest, Configure Proxies einen Proxy-Pool hinzu. Ein Pool bedient v3 und v4, und ein Proxy, den Sie mit einer Aufgabe senden, hat Vorrang vor dem Pool.
Schritt 3: mehrere Übermittlungen gleichzeitig ausführen
Program.cs baut den Host nur für seinen Dependency-Container, ruft also nie RunAsync auf. Es liest die captcha_id einmal, startet fünf Übermittlungen zusammen und gibt jedes Ergebnis aus. Die fünf Platzhalter sind Ihre eigenen Formulartexte. Ändern Sie zuerst PageUrl und FormUrl, denn wie eingefügt zeigen sie auf example.com, das kein Widget hat.
// Program.cs
using CapSkip;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
// Implicit usings import System, which has a TimeoutException too.
using SolverTimeout = CapSkip.TimeoutException;
const string PageUrl = "https://example.com/login"; // the page that shows the widget
const string FormUrl = "https://example.com/comment"; // where its form posts
var builder = Host.CreateApplicationBuilder(args);
builder.Logging.SetMinimumLevel(LogLevel.Warning); // the host logs every HttpClient call at Information
// Local mode. In Server mode use the server's address, and pass apiKey if validation is on.
builder.Services.AddSingleton(new CapSkipClient(host: "127.0.0.1", port: 8080));
// The factory's pooled handler keeps one cookie jar for every request, so switch it off.
builder.Services.AddHttpClient<SiteClient>(c => c.Timeout = TimeSpan.FromSeconds(20))
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { UseCookies = false });
builder.Services.AddSingleton<Submitter>();
using var host = builder.Build();
using var budget = new CancellationTokenSource(TimeSpan.FromMinutes(2));
Console.CancelKeyPress += (_, e) => { e.Cancel = true; budget.Cancel(); };
var site = host.Services.GetRequiredService<SiteClient>();
var submitter = host.Services.GetRequiredService<Submitter>();
var texts = new[] { "first", "second", "third", "fourth", "fifth" };
string captchaId;
try { captchaId = await site.ReadCaptchaIdAsync(PageUrl, budget.Token); }
catch (Exception ex) { Console.WriteLine("could not read the captcha id: " + ex.Message); return 1; }
var results = await Task.WhenAll(texts.Select(async text =>
{
try { return await submitter.SubmitAsync(captchaId, PageUrl, FormUrl, text, budget.Token); }
catch (Exception ex) { return Describe(ex); } // one failure must not hide the others
}));
for (var i = 0; i < texts.Length; i++) Console.WriteLine($"{texts[i]}: {results[i]}");
return results.All(r => r.StartsWith("200")) ? 0 : 1;
string Describe(Exception ex) => ex switch
{
// A cancelled submit surfaces as a NetworkException, a cancelled poll as a TaskCanceledException.
_ when budget.IsCancellationRequested => "the budget ran out",
ValidationException => "CapSkip refused the arguments: " + ex.Message,
ApiException => "CapSkip answered " + ex.Message,
SolverTimeout => "no answer in time: " + ex.Message,
NetworkException => "CapSkip is not reachable: " + ex.Message,
// HttpClient reports its own timeout as a TaskCanceledException.
TaskCanceledException => "the site did not answer within 20 seconds",
HttpRequestException => "the site could not be reached: " + ex.Message,
_ => ex.GetType().Name + ": " + ex.Message,
};Jede Übermittlung hat ihren eigenen try-Block. Task.WhenAll wirft nur den ersten Fehler erneut, und abgebrochene Tasks tragen keine Exception zum Lesen, daher behält das Abfangen innerhalb des Lambdas jedes Ergebnis. Starten Sie das Programm mit dotnet run. Diese Zeilen sind Mock-Ergebnisse, und sie waren auf net10.0 und net8.0 identisch.
| Mock-Einstellung | Was das Programm ausgab |
|---|---|
| Standardeinstellungen des Mocks | Fünf Zeilen mit 200 und dem Text, Exit-Code 0 |
| Jede Lösung nach 2 Sekunden bereit | Höchstens 3 Lösungen gleichzeitig, die letzten beiden wurden 3,8 Sekunden nach den ersten drei gesendet, und der ganze Lauf dauerte etwa 8 Sekunden |
| Die ersten zwei Lösungen schlagen fehl | Zwei Zeilen mit dem API-Fehler, drei mit 200, Exit-Code 1 |
| Die Mock-Website lehnt zwei Formular-POSTs mit 403 ab | Zwei 403-Zeilen, drei 200-Zeilen, und nichts wurde wiederholt |
| Jede Antwort trägt isOffline true | Fünf Zeilen mit Offline-Freigabe, nicht gesendet, Exit-Code 1 |
Abbruch und die beiden TimeoutException
Das CancellationToken erreicht sowohl das SDK als auch HttpClient, daher deckt ein Budget den ganzen Stapel ab. Bei einem Mock, der nie fertig wird, und einem Budget von 3 Sekunden meldeten alle fünf Zeilen, dass das Budget abgelaufen war, und der Prozess endete nach etwa 3,5 Sekunden. Ein Abbruch, während in.php hing, ergab eine NetworkException, die eine TaskCanceledException umschließt, und ein Abbruch während des Abfragens eine einfache TaskCanceledException. Das Budget-Token zuerst in Describe zu prüfen, behandelt beide.
CapSkip wirft auch seine eigene TimeoutException, wenn das Abfragen sein Limit überschreitet, und Implicit Usings importieren System, das ebenfalls eine hat. Ein einfaches catch für TimeoutException neben using CapSkip ließ sich nicht kompilieren (CS0104), weshalb Program.cs die Klasse des SDK als SolverTimeout aliasiert. HttpClient wirft allerdings keine System.TimeoutException auf Sie. Bei einer Mock-Website, die 25 Sekunden schlief, und einem Client-Limit von 20 kam jede Übermittlung nach etwa 20 Sekunden als TaskCanceledException zurück, und der Lauf dauerte insgesamt etwa 20,6 Sekunden.
GeetestV4Async nutzt recaptchaTimeout, standardmäßig 300 Sekunden, nicht defaultTimeout (laut Changelog). Ich habe es geprüft: Mit defaultTimeout 1 und recaptchaTimeout 5 gegen einen Mock, der nie antwortete, kam die Exception nach 7,87 Sekunden auf net10.0 und 7,85 auf net8.0. Das SDK fragt bei etwa 0; 0,25; 0,75; 1,75 und 3,75 Sekunden ab und schläft dann noch 4, sodass die Frist erst bemerkt wird, wenn dieses letzte Schlafen endet, weit nach den 5 Sekunden, die Sie gesetzt haben.
Häufige Fehler
| Was Sie sehen | Ursache | Beheben |
|---|---|---|
| ValidationException | Vor jeder Anfrage abgelehnt: eine leere captcha_id, eine Seitenadresse, die keine absolute http- oder https-URL ist, ein risk_type, der kein String ist, oder eine Option wie gt oder challenge aus v3 | Korrigieren Sie das Argument. Eine Wiederholung hilft nicht |
| ApiException mit ERROR_KEY_DOES_NOT_EXIST | Der Mock lehnte den Schlüssel ab. Laut Dokumentation antwortet die echte App so, wenn API Key Validation eingeschaltet und der Schlüssel unbekannt ist | Übergeben Sie den Schlüssel in CapSkipClient |
| ApiException mit ERROR_CAPTCHA_UNSOLVABLE | Die Lösung ist fehlgeschlagen. Ich habe sie mit einem Mock erzeugt und konnte nicht prüfen, wie die echte App eine fehlgeschlagene v4-Lösung meldet | Lösen Sie erneut und senden Sie niemals das alte Ergebnis |
| NetworkException | Am CapSkip-Host und Port antwortete nichts, oder der Aufruf wurde abgebrochen | Starten Sie CapSkip oder prüfen Sie den Host in CapSkipClient |
| CapSkip TimeoutException | Das Abfragen überschritt recaptchaTimeout, und das SDK bemerkt es erst, wenn sein nächstes Schlafen endet | Erhöhen Sie recaptchaTimeout, wenn Ihre Lösungen langsam sind |
| Die Website antwortet mit 403 oder 400 | In meinem Mock: ein bereits verwendetes Ergebnis, ein fehlendes Feld oder eine Offline-Freigabe. Eine echte Website legt ihre eigenen Regeln fest | Senden Sie alle fünf Felder aus einer frischen Lösung per POST |
Server mode: Löser und Host auf getrennten Rechnern
Dieser Host kann auf einem zweiten PC laufen, während CapSkip auf einem Windows-Rechner bleibt, den Sie kontrollieren. Schalten Sie den Server mode in den Verbindungseinstellungen des Löser-PCs ein und tragen Sie dann die Adresse dieses PCs im Argument host von CapSkipClient ein. Sonst ändert sich im Code nichts. Der Server mode verlangt laut Einrichtungsanleitung, dass CapSkip als Administrator läuft. Die Einrichtungsanleitung empfiehlt eine statische öffentliche IP für stabilen Zugriff und erklärt die Verbindungseinstellungen ausführlich.
Wenn der Server mode startet, öffnet CapSkip seinen Port für jede Adresse. Um ihn auf die Rechner zu beschränken, die Sie erwarten, fügen Sie eine Windows-Firewall-Blockregel für alle anderen hinzu und schalten Sie API Key Validation ein, damit CapSkipClient einen Schlüssel vorlegen muss.
FAQ
Warum heißt die Ergebnis-Eigenschaft GeetestCaptchaId?
CaptchaId war vergeben: Es ist die ID, die CapSkip der Lösung gibt. GeetestCaptchaId enthält die GeeTest-captcha_id, die das Widget zurückspiegelt, und ist eines der fünf Felder, die die Website zurückerwartet.
Kann ich einen CapSkipClient über mehrere Threads teilen?
Ich habe fünf Lösungen gleichzeitig über eine einzige Instanz ausgeführt, ohne Probleme im Mock, und der Quellcode kopiert seine Parameter pro Aufruf. Weiter habe ich es nicht getestet. Wenn Sie sie wie oben als Singleton registrieren, begrenzt der Semaphor die Last.
GeeTest v4 in C# besteht aus einer gelesenen captcha_id, einem GeetestV4Async-Aufruf pro Übermittlung und fünf zusammen per POST gesendeten Feldern. Da CapSkip ein pauschal lizenzierter Captcha-Löser ist, der auf Ihrem eigenen PC läuft, ist jede zusätzliche Lösung nach einer Ablehnung kostenlos. Für die anderen Typen in .NET siehe die C#-Captcha-Solver-Seite, und für das Anfrageformat lesen Sie die GeeTest-v4-Sektion der API-Dokumentation.
