Configuration

Global options

All options are set via AddZeridionFlare() in Program.cs. Only ApiKey is required — everything else has sensible defaults.

builder.Services.AddZeridionFlare(options =>
{
    options.ApiKey = "zf_live_sk_...";                  // Required
    options.ApiBaseUrl = "https://api.zeridion.com";    // Default
    options.ConcurrencyLimit = 10;                      // Max parallel jobs
    options.PollInterval = TimeSpan.FromSeconds(2);     // Poll frequency
});

Options reference

Property	Type	Default	Description
ApiKey	string	(required)	API key from the Zeridion Flare dashboard. Throws ArgumentException if not set.
ApiBaseUrl	string	https://api.zeridion.com	Cloud API base URL. Override to http://localhost:5100 for local dev.
DefaultQueue	string	"default"	Declared but not currently consumed by the enqueue path. Use [JobConfig] or JobOptions instead.
DefaultMaxAttempts	int	3	Declared but not currently consumed by the enqueue path. Use [JobConfig] or JobOptions instead.
DefaultTimeout	TimeSpan	30 minutes	Declared but not currently consumed by the enqueue path. Use [JobConfig] or JobOptions instead.
ConcurrencyLimit	int	10	Max parallel jobs the worker processes simultaneously. Higher values improve throughput but use more memory and CPU.
PollInterval	TimeSpan	2 seconds	Interval between poll cycles when no jobs are available. Lower values increase responsiveness but make more API calls.
JobAssemblies	Assembly[]?	null (entry assembly)	Assemblies to scan for IJob<T> and IRecurringJob implementations. If null, the entry assembly is scanned automatically.

note

ZeridionFlareOptions has DefaultQueue, DefaultMaxAttempts, and DefaultTimeout properties, but they are not currently consumed by the SDK's enqueue path. The effective cascade is JobOptions > [JobConfig] > hardcoded defaults. See Option Precedence for details.

Per-job configuration with [JobConfig]

Apply the JobConfigAttribute to a job class to set defaults that apply every time the job runs:

[JobConfig(Queue = "critical", MaxAttempts = 5, TimeoutSeconds = 600)]
public class ProcessPayment : IJob<PaymentRequest>
{
    public async Task ExecuteAsync(PaymentRequest payload, JobContext ctx)
    {
        // Runs on the "critical" queue with 5 retries and a 10-minute timeout
    }
}

For recurring jobs, add CronSchedule to set the execution interval:

[JobConfig(CronSchedule = "0 3 * * *", Queue = "maintenance")]
public class CleanupExpiredSessions : IRecurringJob
{
    public async Task ExecuteAsync(JobContext ctx)
    {
        // Runs daily at 3:00 AM UTC
    }
}

Property	Type	Default	Description
Queue	string	"default"	Default queue for this job.
MaxAttempts	int	3	Default max retry attempts.
TimeoutSeconds	int	1800	Default job timeout in seconds.
CronSchedule	string?	null	Cron expression for recurring jobs (5-field format, e.g. "0 3 * * *"). Only applicable to IRecurringJob implementations.

Per-call configuration with JobOptions

Override any default at enqueue time by passing a JobOptions instance. Properties left as null fall through to the [JobConfig] or global default.

await jobs.EnqueueAsync<ProcessPayment>(payload, new JobOptions
{
    Queue = "urgent",
    MaxAttempts = 10,
    Timeout = TimeSpan.FromMinutes(5),
    IdempotencyKey = $"payment-{payload.OrderId}",
    Tags = new() { ["order_id"] = payload.OrderId }
});

Property	Type	Default	Description
Queue	string?	null	Override the queue for this enqueue call.
MaxAttempts	int?	null	Override max retry attempts.
Timeout	TimeSpan?	null	Override the job timeout.
Tags	Dictionary<string, string>?	null	Custom metadata tags visible in the dashboard.
IdempotencyKey	string?	null	Prevents duplicate jobs — a second enqueue with the same key returns a 409 Conflict.

Option precedence

Settings resolve in a two-level cascade with hardcoded fallbacks. The most specific value wins:

For example, given this configuration:

• [JobConfig(MaxAttempts = 5)] on the job class
• new JobOptions { MaxAttempts = 10 } at enqueue time

The job gets 10 attempts, because JobOptions has the highest priority.

If the JobOptions.MaxAttempts were left as null, the job would get 5 attempts from the [JobConfig] attribute. If neither were set, it would fall back to the hardcoded default of 3.

See also

• ZeridionFlareOptions — global SDK options registered via DI
• JobOptions — per-call overrides (highest priority in the cascade)
• Quick Start — runnable end-to-end walkthrough