GeeTest v4 на C#: GeetestV4Async и IHttpClientFactory

Чтобы использовать GeeTest v4 на C#, прочитайте со страницы единственный публичный captcha_id, вызывайте GeetestV4Async из пакета CapSkip NuGet один раз на каждую отправку формы и отправляйте возвращённые пять значений под их собственными именами. В этой статье всё собирается в небольшой консольный хост .NET. Типизированный HttpClient из IHttpClientFactory общается с сайтом, один CapSkipClient общается с решателем на вашем собственном ПК с Windows, а семафор не даёт пакету отправок решаться все сразу. О продукте рассказывает страница Решатель GeeTest v4 (платы за каждое решение нет).
Что понадобится
- Сборка CapSkip с поддержкой GeeTest v4, работающая на ПК с Windows. Запуск приложения разбирает руководство по настройке по шагам. Какая у меня была версия приложения, проверить не удалось, потому что приложение на этом ПК не отвечало.
- Нужен .NET 8 SDK или новее и пакет CapSkip 1.8.0 или новее, первый выпуск с GeetestV4Async (запись в журнале изменений от 2026-11-16). Сам пакет нацелен на .NET Standard 2.0, но пример ниже использует синтаксис C# 12 и пакеты Microsoft.Extensions, поэтому я запускал его только на net8.0 и net10.0. Здесь установлен только SDK 10.0.100, поэтому net8.0 собирался заменой строки TargetFramework и запускался на среде выполнения 8.0.
- Страница, которую вам разрешено автоматизировать, с виджетом GeeTest v4, и адрес формы, на которую она отправляет данные.
- Адрес для CapSkip. В Local mode 127.0.0.1 доступен только с ПК, на котором запущено приложение. Server mode делает API доступным и с других машин, а руководство по настройке объясняет оба режима в разделе Настройки подключения.
Когда я тестировал, запущенное приложение CapSkip было недоступно, поэтому настоящих решений не было и к настоящим сайтам я не обращался. Все результаты ниже получены на имитации, которую я написал: она изображает in.php, res.php и сайт с формой комментариев. Имитация следует справочнику API из SDK, а правила сайта в ней мои, а не GeeTest. Где утверждение опирается на документацию или чтение исходного кода SDK, я это указываю.
Шаг 1: создайте хост и типизированный клиент для сайта
Создайте папку проекта и установите три пакета. Я тестировал только net8.0 и net10.0.
dotnet new console -o GeetestWorker cd GeetestWorker dotnet add package CapSkip dotnet add package Microsoft.Extensions.Hosting dotnet add package Microsoft.Extensions.Http
Только на net8.0 замените две последние команды на эти, с закреплёнными версиями. Новейшие пакеты 11.0.0 собираются на net8.0, но печатают предупреждение о неподдерживаемой платформе для каждого пакета, а закреплённые версии собирались без них.
# 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
Следующие три блока C# являются файлами для папки проекта, и каждый начинается со своего имени файла. Сохраните их в показанном порядке. Последний, Program.cs, заменяет файл, созданный шаблоном.
Типизированный клиент принадлежит только целевому сайту. Судя по исходному коду SDK, CapSkipClient внутри строит собственный статический HttpClient и не имеет конструктора, принимающего ваш, поэтому IHttpClientFactory помогает только с вашими собственными вызовами. SiteClient выполняет две задачи: читает captcha_id и отправляет форму.
// 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 для каждого запроса не нужно получать challenge, в отличие от потока v3 в статье о GeeTest v3 на C#. Страница передаёт один идентификатор, одинаковый для всех посетителей, в initGeetest4 как captchaId, поэтому читайте его один раз и используйте повторно. Когда страница строит этот вызов во время выполнения, документация SDK указывает на параметр запроса captcha_id в запросе к gcaptcha4.geetest.com/load на вкладке Network браузера. Регулярное выражение сработало на трёх страницах имитации так, как я ожидал: вызов с двойными кавычками, вызов с одинарными кавычками, вложенный в два объекта, и страница без идентификатора, которая выбросила InvalidOperationException.
Две детали клиента выяснены запусками. Фабрика объединяет свои обработчики сообщений в пул, а обработчик по умолчанию хранит один контейнер cookie на все запросы: в трёх GET второй и третий несли cookie, установленное предыдущим ответом. При UseCookies, равном false, как в Program.cs ниже, ни один не нёс (имитация, net10.0 и net8.0). Если вашей форме нужно cookie сессии со страницы, читайте Set-Cookie для каждой отправки и возвращайте его сами. HttpClient также сам не добавляет Referer: когда я убрал эту строку, имитация увидела пустой заголовок, поэтому код его задаёт.
Шаг 2: одно решение на каждую отправку
GeetestV4Async принимает captcha_id, адрес страницы, необязательный словарь параметров и CancellationToken. Он возвращает SolveResult. Класс ниже служит единицей, которая решает, а затем отправляет, а SemaphoreSlim на три ограничивает, сколько решений идёт одновременно. Выберите число, с которым справится ваш ПК с CapSkip, потому что число три выбрано лишь для моей имитации.
// 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);
}
}Результат несёт пять значений как GeetestCaptchaId, LotNumber, PassToken, GenTime и CaptchaOutput, все строки. Первое называется не CaptchaId, потому что это имя уже занято идентификатором, который CapSkip присваивает решению (имитация выдавала 9101 и выше), что объясняется в журнале изменений. Code хранит исходную строку JSON, которую присылает API, а в запуске имитации Token и Challenge были null, потому что они относятся к другим типам.
Почему решать на каждую отправку? Собственный пример SDK говорит решать заново для каждой отправки, и моя имитация это требует: повторная отправка одного результата получила 403, в теле которого сказано, что pass token уже использован. Это правило имитации. Страница серверной проверки GeeTest, которую я прочитал, не говорит, можно ли использовать пропуск дважды, поэтому следуйте совету SDK. В документации CapSkip также сказано отправлять сразу, а на странице GeeTest сказано, что просроченный pass_token не проходит проверку, и это более веский довод решать на каждую отправку.
Кто проверяет результат? Сервер самого сайта. Согласно документации по серверной проверке GeeTest (страница на китайском), он отправляет в GeeTest lot_number, captcha_output, pass_token и gen_time, а также captcha_id и sign_token, HMAC-SHA256 от lot_number, вычисленный приватным ключом сайта. CapSkip этого ключа никогда не видит, и вашему коду он не нужен.
IsOffline имеет тип nullable bool. По документации оно равно true, когда GeeTest был недоступен и его виджет прошёл без задания, и тогда сайт сам решает, принимать ли такой пропуск. SDK читает true, слово true в любом регистре и ненулевое число как true, ноль и слово false как false, а всё, что не удалось прочитать, как null (ответы имитации, все шесть форм). Код выше пропускает офлайн-пропуск. Если ваш сайт их принимает, удалите эту строку.
Оба параметра необязательны. Этот фрагмент заменяет вызов GeetestV4Async в 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);По документации risk_type принимает одно из десяти значений: slide, icon, nine, word, phrase, match, winlinze, svg_seed, svg_icon и ai. GeeTest применяет одно из них, только если сайт позволяет вызывающему выбирать. SDK значение не проверяет: он обрезал пробелы, отбросил пустое значение, отправил бессмысленное значение без изменений и отклонил число с ValidationException. Написание riskType работает как псевдоним. Используйте proxy, когда сайту нужен один и тот же адрес для решения и отправки формы. Об этом рассказывает статья о прокси для сервиса распознавания капчи подробно. Простая строка с адресом означает HTTP, а тип вне HTTP, HTTPS, SOCKS5 и SOCKS5H отклоняется локально.
Для параллельного пакета подумайте и о сети. В документации API CapSkip сказано, что GeeTest оценивает сеть, а ограничение частоты срабатывает на постоянный поток запросов с одного адреса. Добавьте пул прокси в приложении CapSkip: Settings, Captcha types, GeeTest, Configure Proxies. Один пул обслуживает и v3, и v4, а прокси, отправленный с заданием, приоритетнее пула.
Шаг 3: запустите несколько отправок одновременно
Program.cs создаёт хост только ради его контейнера зависимостей, поэтому RunAsync он не вызывает. Он читает captcha_id один раз, запускает пять отправок вместе и печатает результат каждой. Пять заглушек заменяются вашими собственными текстами форм. Сначала измените PageUrl и FormUrl, потому что в том виде, как вставлено, они указывают на example.com, где виджета нет.
// 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,
};Каждая отправка оборачивает собственный блок try. Task.WhenAll перебрасывает только первую ошибку, а у отменённых задач нет исключения, которое можно прочитать, поэтому перехват внутри лямбды сохраняет каждый результат. Запустите программу командой dotnet run. Это результаты имитации, и на net10.0 и net8.0 они были одинаковыми.
| Настройка имитации | Что напечатала программа |
|---|---|
| Настройки имитации по умолчанию | Пять строк с 200 и текстом, код выхода 0 |
| Каждое решение готово через 2 секунды | Не более 3 решений одновременно, последние две отправки ушли через 3.8 секунды после первых трёх, весь запуск занял около 8 секунд |
| Первые два решения завершаются ошибкой | Две строки с ошибкой API, три с 200, код выхода 1 |
| Сайт имитации отклоняет две отправки формы с 403 | Две строки 403, три строки 200 и ни одной повторной попытки |
| Каждый ответ несёт isOffline true | Пять строк с офлайн-пропуском, не отправлено, код выхода 1 |
Отмена и два TimeoutException
CancellationToken доходит и до SDK, и до HttpClient, поэтому один бюджет покрывает весь пакет. При имитации, которая никогда не завершается, и бюджете в 3 секунды все пять строк сообщили, что бюджет исчерпан, а процесс завершился примерно через 3.5 секунды. Отмена, пока in.php висел, дала NetworkException, оборачивающее TaskCanceledException, а отмена во время опроса дала обычный TaskCanceledException. Проверка токена бюджета первой в Describe обрабатывает оба случая.
CapSkip выбрасывает и собственный TimeoutException, когда опрос выходит за свой предел, а неявные using импортируют System, где он тоже есть. Голый catch для TimeoutException рядом с using CapSkip не собрался с ошибкой CS0104, поэтому Program.cs называет класс SDK псевдонимом SolverTimeout. Но HttpClient не выбрасывает System.TimeoutException. Когда сайт имитации спал 25 секунд, а лимит клиента был 20, каждая отправка завершалась TaskCanceledException примерно через 20 секунд, а весь запуск занял около 20.6 секунды.
GeetestV4Async использует recaptchaTimeout, по умолчанию 300 секунд, а не defaultTimeout (по журналу изменений). Я проверил: при defaultTimeout 1 и recaptchaTimeout 5 на имитации, которая никогда не отвечала, исключение пришло через 7.87 секунды на net10.0 и 7.85 на net8.0. SDK опрашивает примерно на 0, 0.25, 0.75, 1.75 и 3.75 секунды, затем спит ещё 4, поэтому срок замечается, когда заканчивается эта последняя пауза, намного позже заданных вами 5 секунд.
Частые ошибки
| Что вы видите | Причина | Исправить |
|---|---|---|
| ValidationException | Отклонено до любого запроса: пустой captcha_id, адрес страницы, который не является абсолютным http или https, risk_type, не являющийся строкой, или параметр вроде gt или challenge из v3 | Исправьте аргумент. Повтор не поможет |
| ApiException с ERROR_KEY_DOES_NOT_EXIST | Имитация отклонила ключ. По документации настоящее приложение отвечает так, когда включена API Key Validation и ключ неизвестен | Передайте ключ в CapSkipClient |
| ApiException с ERROR_CAPTCHA_UNSOLVABLE | Решение не удалось. Я получил это на имитации и не мог проверить, как настоящее приложение сообщает о неудачном решении v4 | Решайте заново и никогда не отправляйте старый результат |
| NetworkException | По хосту и порту CapSkip никто не ответил, или вызов был отменён | Запустите CapSkip или проверьте host в CapSkipClient |
| CapSkip TimeoutException | Опрос превысил recaptchaTimeout, а SDK замечает это только когда заканчивается его следующая пауза | Увеличьте recaptchaTimeout, если ваши решения медленные |
| Сайт отвечает 403 или 400 | В моей имитации: уже использованный результат, отсутствующее поле или офлайн-пропуск. У настоящего сайта свои правила | Отправляйте все пять полей из одного свежего решения |
Server mode: решатель и хост на разных машинах
Этот хост может работать на втором ПК, пока CapSkip остаётся на машине с Windows, которую вы контролируете. Включите Server mode в настройках подключения на ПК с решателем, затем укажите адрес этого ПК в аргументе host у CapSkipClient. В остальном код не меняется. Server mode требует запуска CapSkip от имени администратора (см. руководство по настройке). Руководство по настройке рекомендует статический публичный IP для стабильного доступа и подробно объясняет раздел Настройки подключения целиком.
Когда Server mode запускается, CapSkip открывает свой порт для всех адресов. Чтобы оставить доступ только машинам, которых вы ждёте, добавьте блокирующее правило Windows Firewall для всех остальных и включите API Key Validation, чтобы CapSkipClient обязан был предъявлять ключ.
FAQ
Почему свойство результата называется GeetestCaptchaId?
Имя CaptchaId было занято: это идентификатор, который CapSkip присваивает решению. GeetestCaptchaId хранит captcha_id GeeTest, который виджет возвращает эхом, и это одно из пяти полей, которые сайт ждёт обратно.
Можно ли использовать один CapSkipClient в нескольких потоках?
Я запустил пять решений одновременно через один экземпляр без проблем на имитации, и исходный код копирует свои параметры для каждого вызова. Дальше этого я не проверял. Если вы зарегистрируете его как singleton, как выше, нагрузку ограничивает семафор.
GeeTest v4 на C# сводится к одному прочитанному captcha_id, одному вызову GeetestV4Async на каждую отправку и пяти полям, отправляемым вместе. При фиксированной лицензии CapSkip даёт распознавание капчи на вашем ПК, поэтому каждое лишнее решение после отказа бесплатно. О других типах в .NET читайте на странице сервиса распознавания капчи для C#, а формат запроса смотрите здесь: Раздел GeeTest v4 документации API.
