Agent & Automation Guide

This page is a compact entry point for assistants, scripts, and contributors who need the main NCronJob concepts quickly.

Primary public entry points

Registration

  • AddNCronJob(...) registers the scheduler and typed jobs
  • AddNCronJob(Delegate jobDelegate, string cronExpression, TimeZoneInfo? timeZoneInfo = null) registers a delegate-based recurring job
  • AddNCronJob(Delegate jobDelegate, string cronExpression, TimeZoneInfo? timeZoneInfo, string jobName) registers a named delegate-based recurring job

Startup behavior

  • UseNCronJobAsync(IHost) and UseNCronJob(IHost) must be called when any job uses RunAtStartup(...)
  • For regular recurring jobs and instant jobs, these calls are optional

Job authoring

  • IJob is the main typed-job abstraction; IJob<TParameter> is a job that accepts a parameter
  • IJobExecutionContext provides the attempt count, correlation id, and execution metadata; IJobExecutionContext<TParameter> adds the typed Parameter
  • The minimal API style resolves services directly from the delegate signature

Scheduling options

  • Builder order is WithName(...), then WithCronExpression(...), then WithParameter(...) / RunAtStartup(...); WithName is not available after the cron expression
  • WithCronExpression(...) accepts cron expressions (with optional seconds) and macros such as @hourly, @daily, @weekly, @monthly, @yearly, @every_minute and @every_second; see Cron macros
  • WithTimeout(TimeSpan) cancels a run that executes too long; see Timeouts and run expiry
  • WithMaxDegreeOfParallelism(int) limits concurrently executing jobs scheduler-wide; see Global concurrency

Observability

  • Every run executes in a log scope with JobName, JobRunId, CorrelationId and TriggerType; see Log level and log scopes
  • Every run is an Activity from the "NCronJob" ActivitySource (NCronJobDiagnostics.ActivitySourceName); see Tracing with OpenTelemetry
  • Runs, failures, retries, skipped/expired runs and run duration are metrics of the "NCronJob" Meter (NCronJobDiagnostics.MeterName); see Metrics with OpenTelemetry
  • NCronJob.Dashboard package: services.AddNCronJobDashboard() + app.MapNCronJobDashboard(path, configureEndpoints) serve a Blazor Server dashboard; see Dashboard

Runtime interaction

  • IInstantJobRegistry triggers instant and delayed jobs
  • IRuntimeJobRegistry adds, removes, enables, disables, and updates named recurring jobs at runtime
  1. Getting Started
  2. Define and Schedule Jobs
  3. Triggering instant jobs
  4. Timeouts and run expiry
  5. Global concurrency
  6. Dynamic Job Control
  7. Observing job progress and log scopes
  8. Known gotchas

High-signal behavioral notes

  • Use named jobs when the same job type is registered multiple times or when runtime management is needed
  • RunInstantJob<TJob>() can become ambiguous if multiple registrations exist for the same job type; prefer RunInstantJob("job-name") in that case
  • Parameters are passed by reference, not serialized, so mutation after enqueueing can affect execution
  • A job accepts a parameter only if it implements IJob<TParameter>; a parameter that isn’t assignable to TParameter throws ArgumentException at registration or trigger time. A run without a parameter gets default(TParameter); IJob<object?> accepts anything
  • Forced instant jobs (ForceRunInstantJob / ForceRunScheduledJob) bypass queue and concurrency protection
  • A timed-out run is Cancelled and does not trigger dependencies; jobs must honor the CancellationToken
  • After Build(), call UseNCronJobAsync() or UseNCronJob() whenever RunAtStartup(...) is used; see Running Startup Jobs

Repository sample map

  • sample/MinimalSample: minimal recurring delegate job
  • sample/NCronJobSample: typed jobs, notifications, retries, concurrency, dependencies, a startup job, instant job endpoints, and the dashboard at /ncronjob
  • sample/RunOnceSample: startup job flow

Preferred source of truth

When an example and prose disagree, prefer:

  1. Public API and XML docs in src/NCronJob
  2. The sample applications in sample/*
  3. The feature pages in docs/*

Machine-friendly documentation files

  • llms.txt provides a compact discovery index
  • llms-full.md provides a compact Markdown reference for retrieval and prompting