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 jobsAddNCronJob(Delegate jobDelegate, string cronExpression, TimeZoneInfo? timeZoneInfo = null)registers a delegate-based recurring jobAddNCronJob(Delegate jobDelegate, string cronExpression, TimeZoneInfo? timeZoneInfo, string jobName)registers a named delegate-based recurring job
Startup behavior¶
UseNCronJobAsync(IHost)andUseNCronJob(IHost)must be called when any job usesRunAtStartup(...)- For regular recurring jobs and instant jobs, these calls are optional
Job authoring¶
IJobis the main typed-job abstraction;IJob<TParameter>is a job that accepts a parameterIJobExecutionContextprovides the attempt count, correlation id, and execution metadata;IJobExecutionContext<TParameter>adds the typedParameter- The minimal API style resolves services directly from the delegate signature
Scheduling options¶
- Builder order is
WithName(...), thenWithCronExpression(...), thenWithParameter(...)/RunAtStartup(...);WithNameis not available after the cron expression WithCronExpression(...)accepts cron expressions (with optional seconds) and macros such as@hourly,@daily,@weekly,@monthly,@yearly,@every_minuteand@every_second; see Cron macrosWithTimeout(TimeSpan)cancels a run that executes too long; see Timeouts and run expiryWithMaxDegreeOfParallelism(int)limits concurrently executing jobs scheduler-wide; see Global concurrency
Observability¶
- Every run executes in a log scope with
JobName,JobRunId,CorrelationIdandTriggerType; see Log level and log scopes - Every run is an
Activityfrom 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.Dashboardpackage:services.AddNCronJobDashboard()+app.MapNCronJobDashboard(path, configureEndpoints)serve a Blazor Server dashboard; see Dashboard
Runtime interaction¶
IInstantJobRegistrytriggers instant and delayed jobsIRuntimeJobRegistryadds, removes, enables, disables, and updates named recurring jobs at runtime
Recommended reading order for agents¶
- Getting Started
- Define and Schedule Jobs
- Triggering instant jobs
- Timeouts and run expiry
- Global concurrency
- Dynamic Job Control
- Observing job progress and log scopes
- 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; preferRunInstantJob("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 toTParameterthrowsArgumentExceptionat registration or trigger time. A run without a parameter getsdefault(TParameter);IJob<object?>accepts anything - Forced instant jobs (
ForceRunInstantJob/ForceRunScheduledJob) bypass queue and concurrency protection - A timed-out run is
Cancelledand does not trigger dependencies; jobs must honor theCancellationToken - After
Build(), callUseNCronJobAsync()orUseNCronJob()wheneverRunAtStartup(...)is used; see Running Startup Jobs
Repository sample map¶
sample/MinimalSample: minimal recurring delegate jobsample/NCronJobSample: typed jobs, notifications, retries, concurrency, dependencies, a startup job, instant job endpoints, and the dashboard at/ncronjobsample/RunOnceSample: startup job flow
Preferred source of truth¶
When an example and prose disagree, prefer:
- Public API and XML docs in
src/NCronJob - The sample applications in
sample/* - The feature pages in
docs/*
Machine-friendly documentation files¶
llms.txtprovides a compact discovery index- llms-full.md provides a compact Markdown reference for retrieval and prompting