How alnuaimicoder/aspire-hosting-quartz works
1. What this repo is
- This is a .NET library for integrating Quartz.NET with .NET Aspire.
- The architecture is split into a reusable runtime package, an Aspire hosting package, and a small abstractions package, with a sample Aspire app proving the end-to-end flow.
2. Core layering
- Aspire.Quartz.Abstractions defines the minimal job contract and job metadata types.
- Aspire.Quartz contains the runtime client, serialization, idempotency, validation, and health-check logic.
- Aspire.Hosting.Quartz adds Aspire resource/hosting integration, including migration handling and resource extensions.
3. Job contract boundary
- Jobs implement IJob from the abstractions package.
- JobContext, JobOptions, and RetryPolicy are the cross-layer data model used to describe execution, retries, and scheduling behavior without tying callers to Quartz internals.
4. Runtime scheduling path
- The service-side package exposes IBackgroundJobClient and QuartzClientExtensions so application code can enqueue or schedule jobs dynamically.
- BackgroundJobClient, JobSerializer, and CronExpressionValidator form the runtime path from API call to Quartz persistence and trigger creation.
- DuplicateJobException and IdempotencyStore enforce “don’t run twice” semantics around job submission.
5. Quartz persistence and database access
- Persistent scheduling is database-backed rather than in-memory.
- DbConnectionFactory abstracts connection creation, while the README and sample indicate support for PostgreSQL, SQL Server, MySQL, and SQLite.
- The repo treats the Quartz database as a shared infrastructure dependency for scheduling, state, and idempotency.
6. Aspire hosting integration
- Aspire.Hosting.Quartz is the boundary where Quartz becomes an Aspire resource.
- QuartzResource, QuartzHostingExtensions, and QuartzResourceExtensions let an AppHost declare and configure Quartz as part of the distributed application model.
- QuartzMigrationService plus the SQL migration script classes handle automatic schema setup during hosting.
7. Sample distributed application
- samples/QuartzSample.AppHost is the orchestration entry point.
- It composes the infrastructure, references the API service, and wires shared dependencies using Aspire conventions.
- The README’s sample flow emphasizes that jobs run inside the API service, so there is no separate worker process.
8. API service role in the sample
- samples/QuartzSample.ApiService is where Quartz is configured and where jobs execute.
- It contains Quartz job classes, a job scheduler service, a listener, and a SignalR hub for job-status notifications.
- It also includes EF Core database context and migrations for the sample’s persistence/demo features.
9. Web client and user-facing monitoring
- samples/QuartzSample.Web is a Blazor front end.
- It talks to the API through QuartzApiClient, and the presence of QuartzDashboard.razor and the SignalR hub suggests the sample exposes live job-monitoring UI.
- This web project is not the scheduler itself; it is an observer/control plane for the sample system.
10. Operational concerns
- QuartzHealthCheck provides Aspire Dashboard-friendly health reporting for scheduler availability.
- OpenTelemetry is called out in the README as a first-class concern, so observability is part of the runtime architecture rather than an afterthought.
- The hosting package’s migration support is another operational boundary: schema readiness is handled alongside app startup.
11. Testing and release structure
- The repo is organized as a typical library workspace with unit-test projects for abstractions, runtime behavior, and hosting behavior.
- CI/release workflows, versioning docs, and packaging configuration indicate the main deliverable is NuGet packages rather than a standalone application.
12. How data flows end to end
- AppHost declares the infrastructure and service references.
- The API service configures Quartz with persistence and hosted execution.
- Application code submits jobs through IBackgroundJobClient or schedules them statically.
- Quartz persists and executes jobs against the shared database, while health checks and the sample UI surface status back to operators.
Main entry points: BackgroundJobClient.cs BackgroundJobClient · Program.cs ApiService · QuartzResource.cs QuartzResource · QuartzMigrationService.cs Migration service
Components 30
Abstractions
Shared job contract and execution model.
- IJob · Minimal job boundary implemented by app jobs.
src/Aspire.Quartz.Abstractions/IJob.cs - JobContext · Cross-layer execution context passed to jobs.
src/Aspire.Quartz.Abstractions/JobContext.cs - JobOptions · Metadata for scheduling and execution behavior.
src/Aspire.Quartz.Abstractions/JobOptions.cs - RetryPolicy · Retry configuration shared across layers.
src/Aspire.Quartz.Abstractions/RetryPolicy.cs
Runtime
Client, serialization, persistence, and health logic.
- BackgroundJobClient · Runtime API for enqueueing and scheduling jobs.
src/Aspire.Quartz/BackgroundJobClient.cs - QuartzClientExtensions · Registers the runtime client in application services.
src/Aspire.Quartz/QuartzClientExtensions.cs - JobSerializer · Converts job payloads to Quartz-storable form.
src/Aspire.Quartz/JobSerializer.cs - CronValidator · Checks cron expressions before persistence.
src/Aspire.Quartz/CronExpressionValidator.cs - IdempotencyStore · Prevents duplicate job submissions.
src/Aspire.Quartz/IdempotencyStore.cs - DuplicateJobException · Raised when a job would be submitted twice.
src/Aspire.Quartz/DuplicateJobException.cs - DbConnectionFactory · Creates database connections for Quartz persistence.
src/Aspire.Quartz/DbConnectionFactory.cs - QuartzHealthCheck · Reports scheduler readiness to Aspire dashboard.
src/Aspire.Quartz/QuartzHealthCheck.cs
Hosting
Aspire resource integration and schema setup.
- QuartzResource · Represents Quartz in the Aspire app model.
src/Aspire.Hosting.Quartz/QuartzResource.cs - Hosting extensions · Adds Quartz resource wiring to AppHost.
src/Aspire.Hosting.Quartz/QuartzHostingExtensions.cs - Resource extensions · Configures the Quartz resource and dependencies.
src/Aspire.Hosting.Quartz/QuartzResourceExtensions.cs - Migration service · Runs Quartz schema migrations during startup.
src/Aspire.Hosting.Quartz/QuartzMigrationService.cs - PostgreSQL script · PostgreSQL Quartz schema definitions.
src/Aspire.Hosting.Quartz/PostgreSqlMigrationScript.cs - SQL Server script · SQL Server Quartz schema definitions.
src/Aspire.Hosting.Quartz/SqlServerMigrationScript.cs
Sample app
End-to-end Aspire sample application.
- AppHost · Declares the sample distributed application.
samples/QuartzSample.AppHost/AppHost.cs - ApiService · Hosts Quartz and runs scheduled jobs.
samples/QuartzSample.ApiService/Program.cs - Quartz setup · Configures Quartz and runtime integration in the API service.
samples/QuartzSample.ApiService/Extensions/QuartzExtensions.cs - Job scheduler · Coordinates job submission from the API service.
samples/QuartzSample.ApiService/Services/QuartzJobScheduler.cs - Job listener · Observes job events inside the API service.
samples/QuartzSample.ApiService/Listeners/QuartzJobListener.cs - Quartz hub · Pushes job-status updates to the web UI.
samples/QuartzSample.ApiService/Hubs/QuartzHub.cs - Web UI · User-facing dashboard and control plane.
samples/QuartzSample.Web/Program.cs - Api client · Calls the API service from the web app.
samples/QuartzSample.Web/Services/QuartzApiClient.cs - Dashboard · Blazor page for live job monitoring.
samples/QuartzSample.Web/Components/Pages/QuartzDashboard.razor
Tests
Unit tests for the main packages.
- Abstractions tests · Validates shared job models and retry policy.
tests/CommunityToolkit.Aspire.Quartz.Abstractions.Tests/CommunityToolkit.Aspire.Quartz.Abstractions.Tests.csproj - Runtime tests · Covers runtime submission and duplicate detection.
tests/CommunityToolkit.Aspire.Quartz.Tests/CommunityToolkit.Aspire.Quartz.Tests.csproj - Hosting tests · Covers Aspire resource behavior.
tests/CommunityToolkit.Aspire.Hosting.Quartz.Tests/CommunityToolkit.Aspire.Hosting.Quartz.Tests.csproj
Connections 27
- IJob → JobContext: executes with · Jobs receive a shared context.
- JobOptions → RetryPolicy: contains · Job options include retry behavior.
- QuartzClientExtensions → BackgroundJobClient: registers · Extensions expose the submission client.
- BackgroundJobClient → JobSerializer: serializes · Payloads are prepared for Quartz storage.
- BackgroundJobClient → CronValidator: validates · Cron expressions are checked before scheduling.
- BackgroundJobClient → IdempotencyStore: guards · Duplicate submissions are blocked.
- IdempotencyStore → DuplicateJobException: throws · Conflicting submissions raise an exception.
- BackgroundJobClient → DbConnectionFactory: persists via · Jobs are written through database connections.
- QuartzHealthCheck → DbConnectionFactory: checks · Health depends on database-backed scheduler readiness.
- Hosting extensions → QuartzResource: adds · AppHost gets a Quartz resource.
- Resource extensions → QuartzResource: configures · Resource extensions shape deployment settings.
- Migration service → PostgreSQL script: uses · Migration service can apply PostgreSQL schema.
- Migration service → SQL Server script: uses · Migration service can apply SQL Server schema.
- AppHost → Hosting extensions: wires · Sample orchestration composes Quartz hosting.
- AppHost → ApiService: references · AppHost includes the API service.
- ApiService → Quartz setup: configures · API service initializes Quartz.
- Quartz setup → BackgroundJobClient: uses · Service wiring exposes the runtime client.
- ApiService → Job scheduler: hosts · The API service contains job scheduling logic.
- ApiService → Job listener: observes · Job events are monitored in-process.
- ApiService → Quartz hub: publishes · Status updates flow to SignalR clients.
- Web UI → Api client: calls · The web UI talks to the API service.
- Web UI → Dashboard: renders · Dashboard page shows job monitoring.
- Api client → Quartz hub: receives updates · Client consumes live job notifications.
- Abstractions tests → IJob: covers · Tests validate contract behavior.
- Abstractions tests → RetryPolicy: covers · Tests validate retry policy behavior.
- Runtime tests → DuplicateJobException: covers · Runtime tests verify duplicate detection.
- Hosting tests → QuartzResource: covers · Hosting tests verify resource integration.