Skip to main content

ZeridionFlareOptions

Global configuration for the Zeridion Flare SDK, set via the AddZeridionFlare configuration delegate.

Namespace: Zeridion.Flare · Assembly: Zeridion.Flare.dll

public sealed class ZeridionFlareOptions
{
    public string ApiKey { get; set; } = string.Empty;
    public string ApiBaseUrl { get; set; } = "https://api.zeridion.com";
    public string DefaultQueue { get; set; } = "default";
    public int DefaultMaxAttempts { get; set; } = 3;
    public TimeSpan DefaultTimeout { get; set; } = TimeSpan.FromMinutes(30);
    public int ConcurrencyLimit { get; set; } = 10;
    public TimeSpan PollInterval { get; set; } = TimeSpan.FromSeconds(2);
    public Assembly[]? JobAssemblies { get; set; }
    public long MaxResponseBytes { get; set; } = 10L * 1024 * 1024;
    public int MaxRetries { get; set; } = 3;
    public TimeSpan RetryBaseDelay { get; set; } = TimeSpan.FromMilliseconds(500);
    public TimeSpan RetryMaxDelay { get; set; } = TimeSpan.FromSeconds(30);
    public TimeSpan PerRequestTimeout { get; set; } = TimeSpan.FromSeconds(10);
}

Properties​

PropertyTypeDefaultDescription
ApiKeystring"" (required)API key from the Zeridion Flare dashboard.
ApiBaseUrlstring"https://api.zeridion.com"Cloud API base URL.
DefaultQueuestring"default"Reserved for future use. Currently ignored by the enqueue API — use [JobConfig] or JobOptions for per-job queue assignment.
DefaultMaxAttemptsint3Reserved for future use. Not currently consumed by the enqueue path.
DefaultTimeoutTimeSpan30 minutesReserved for future use. Not currently consumed by the enqueue path.
ConcurrencyLimitint10Max concurrent jobs the worker processes simultaneously.
PollIntervalTimeSpan2 secondsInterval between poll cycles when no jobs are available.
JobAssembliesAssembly[]?null (scans entry assembly)Assemblies to scan for job implementations.
MaxResponseByteslong10 MiB (10 × 1024 × 1024)Hard cap on response body size the client will read. Protects against an unbounded body. Set 0 to disable. Wired to HttpClient.MaxResponseContentBufferSize.
MaxRetriesint3Maximum retry attempts on transient HTTP failures (429 / 5xx / network). Set 0 to disable retries.
RetryBaseDelayTimeSpan500 msBase delay for the resilience handler's exponential backoff schedule.
RetryMaxDelayTimeSpan30 sUpper bound on a single backoff wait; also caps server-supplied Retry-After hints.
PerRequestTimeoutTimeSpan10 sPer-attempt timeout. Each individual attempt is cancelled if it exceeds this duration; retries continue up to MaxRetries. Distinct from HttpClient.Timeout which bounds the total request including retries.

ApiKey​

Required. An ArgumentException is thrown during service registration if the API key is empty or whitespace.

API keys use prefixes to indicate their environment:

PrefixEnvironment
zf_live_sk_Production
zf_test_sk_Test
builder.Services.AddZeridionFlare(options =>
{
    options.ApiKey = builder.Configuration["Zeridion:ApiKey"]!;
});
warning

Never hardcode API keys in source code. Use appsettings.json, environment variables, or a secrets manager.

:::tip Environment variable fallback If ApiKey is not set via code or configuration, the SDK falls back to the FLARE_API_KEY environment variable. This is the cross-SDK convention — the TypeScript, Python, Ruby, Go, Java, and PHP SDKs read the same variable name. Setting FLARE_API_KEY once in your deployment environment is enough; an explicit options.ApiKey = ... call always takes precedence. If neither source supplies a value, AddZeridionFlare throws ArgumentException at startup. :::

ApiBaseUrl​

Override the API endpoint. The default points to the Zeridion cloud API. For local development against a self-hosted Flare API, point to http://localhost:5100:

builder.Services.AddZeridionFlare(options =>
{
    options.ApiKey = builder.Configuration["Zeridion:ApiKey"]!;
    options.ApiBaseUrl = "http://localhost:5100";
});

DefaultQueue, DefaultMaxAttempts, DefaultTimeout​

These properties are defined on the options class but are not currently consumed by the SDK's enqueue path (FlareJobClient.BuildCreateRequest). The effective cascade for queue, max attempts, and timeout is JobOptions > [JobConfig] > hardcoded defaults (see Option Precedence).

Setting these properties has no effect in the current SDK version. Use [JobConfig] for per-class defaults or JobOptions for per-call overrides instead. These properties are reserved for a future release that will wire them into the cascade.

ConcurrencyLimit​

Controls how many jobs the background worker processes in parallel. Higher values improve throughput but consume more CPU and memory. Set this based on your job characteristics:

Job typeRecommended limit
I/O-bound (HTTP, DB, email)10–50
CPU-bound (image processing)1–4
Mixed workloads5–15
options.ConcurrencyLimit = 20;  // process up to 20 jobs in parallel

PollInterval​

How often the worker polls the API for new jobs when the previous poll returned nothing. Lower values increase responsiveness but generate more API traffic. The worker polls immediately after completing a job — this interval only applies to idle periods.

options.PollInterval = TimeSpan.FromSeconds(5);  // check every 5 seconds when idle

JobAssemblies​

By default, the SDK scans the entry assembly for IJob<T> and IRecurringJob implementations. If your job classes live in separate assemblies (a class library, for example), specify them explicitly:

options.JobAssemblies = new[]
{
    typeof(SendWelcomeEmail).Assembly,
    typeof(ProcessPayment).Assembly
};

Configuration from appsettings.json​

Bind options from configuration for environment-specific overrides:

{
  "Zeridion": {
    "ApiKey": "zf_live_sk_xxxxxxxxxxxxxxxxxxxx",
    "ApiBaseUrl": "https://api.zeridion.com",
    "ConcurrencyLimit": 10
  }
}
builder.Services.AddZeridionFlare(options =>
{
    var section = builder.Configuration.GetSection("Zeridion");
    options.ApiKey = section["ApiKey"]!;
    options.ApiBaseUrl = section["ApiBaseUrl"] ?? options.ApiBaseUrl;

    if (int.TryParse(section["ConcurrencyLimit"], out var concurrency))
        options.ConcurrencyLimit = concurrency;
});

Usage example​

A fully configured setup with all options:

builder.Services.AddZeridionFlare(options =>
{
    options.ApiKey = builder.Configuration["Zeridion:ApiKey"]!;
    options.ApiBaseUrl = builder.Environment.IsDevelopment()
        ? "http://localhost:5100"
        : "https://api.zeridion.com";
    options.ConcurrencyLimit = 20;
    options.PollInterval = TimeSpan.FromSeconds(3);
    options.JobAssemblies = new[] { typeof(Program).Assembly };
});

See also​