ZennoBrowser.Sdk 0.1.0-preview.1

ZennoBrowser.Sdk

SDK for the ZennoBrowser Public API: typed request/response models, async/await, retries, and typed exceptions.

Contents

• Requirements
• Installation
• Quick start
• Listing profiles
• Cookie robot with manual polling
• Error handling
• DI registration and logging
• Retries
• Low-level access

Requirements

• .NET 8.0 or newer.
• A running ZennoBrowser instance with Public API enabled, and its address (e.g. https://your-zennobrowser-host:8160).
• An API token: created in the ZennoBrowser UI under Settings → Public API and passed to ApiKeyCredential.

Installation

dotnet add package ZennoBrowser.Sdk

Quick start

Scenario: create a profile → start a browser → stop it → export cookies.

Every domain (profiles, proxies, threads, workspaces, presets, extensions, browser instances, profile/proxy folders, product info) has a matching IXxxAPI interface with full CRUD/bulk methods — this Quick Start only exercises a couple of them. Request/response/domain types live under the ZennoBrowser.Sdk.Abstracts.* namespaces (one sub-namespace per domain); import the ones you need.

using ZennoBrowser.Sdk.Abstracts.BrowserInstances;
using ZennoBrowser.Sdk.Abstracts.Cookies;
using ZennoBrowser.Sdk.Abstracts.Profiles;
using ZennoBrowser.Sdk;

using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(2));
var ct = cts.Token;

using var client = new ZennoBrowserClient(
    new ApiKeyCredential("YOUR_API_TOKEN"),
    new Uri("http://localhost:8160"));
// The endpoint argument is optional and defaults to ZennoBrowserClient.DefaultEndpoint
// (http://localhost:8160) when omitted.

var profileId = await client.Profiles.CreateProfileAsync(new CreateProfileRequest { Name = "demo" }, ct);
var browser = await client.BrowserInstances.StartBrowserInstanceAsync(new StartBrowserInstanceRequest { ProfileId = profileId }, ct);
Console.WriteLine($"Browser started: {browser.ConnectionString}");
await client.BrowserInstances.StopBrowserInstanceAsync(new StopBrowserInstanceRequest { ProfileId = profileId }, ct);
var cookies = await client.Profiles.ExportCookiesAsync(new ExportCookiesRequest { ProfileId = profileId }, ct);

Listing profiles

Each call is a single REST request; the service caps Total at 1000 per call. Page manually via Start if you need more.

var profiles = await client.Profiles.GetProfilesAsync(new GetProfilesRequest(), ct);
foreach (var profile in profiles.Items)
    Console.WriteLine(profile.Name);

Cookie robot with manual polling

Starting a run returns immediately with a run id; the caller polls its status explicitly. The run itself always continues on the server regardless of whether or how often you poll.

var run = await client.Profiles.RunCookieRobotAsync(
    new RunCookieRobotRequest { Ids = new[] { profileId }, Urls = new[] { "https://example.com" } },
    ct);

var status = await client.Profiles.GetScriptRunStatusAsync(new GetScriptRunStatusRequest { RunId = run.RunId }, ct);

Error handling

API errors are mapped to typed exceptions: ApiValidationException, AuthenticationException, AccessDeniedException / WorkspaceAccessDeniedException, NotFoundException, ConflictException, RateLimitException, ServiceException (all inherit from ZennoBrowserApiException, which carries Status and RequestId).

DI registration and logging

Logging is built on Microsoft.Extensions.Logging. When registered via DI, the log provider (Serilog, NLog, console, …) is picked up from the container automatically — just like in any standard .NET project:

using ZennoBrowser.Sdk;

// Serilog/NLog/console are wired up the usual way, via Microsoft.Extensions.Logging
services.AddLogging(b => b.AddSerilog());

services.AddZennoBrowserClient(
    new Uri("https://your-zennobrowser-host:8160"),
    "YOUR_API_TOKEN",
    options =>
    {
        options.Retry = new RetryOptions { MaxRetries = 5, Mode = RetryMode.Exponential };
        options.NetworkTimeout = TimeSpan.FromSeconds(60);
        options.Diagnostics.ApplicationId = "my-app";
    });

Without DI, pass an ILoggerFactory directly:

var options = new ZennoBrowserClientOptions();
options.Diagnostics.LoggerFactory = loggerFactory; // any Microsoft.Extensions.Logging provider
using var client = new ZennoBrowserClient(credential, endpoint, options);

Retries

A built-in BCL-based retry pipeline runs with no external dependencies, configurable via RetryOptions:

var options = new ZennoBrowserClientOptions
{
    Retry = new RetryOptions { MaxRetries = 5, Mode = RetryMode.Exponential },
};
using var client = new ZennoBrowserClient(credential, endpoint, options);

To use a different resilience library instead, implement IRetryPipeline and set ZennoBrowserClientOptions.RetryPipeline.

Low-level access

Per-call headers via RequestContext, your own DelegatingHandler in ZennoBrowserClientOptions.Handlers, and the low-level Kiota adapter via client.GetRequestAdapter().