EasyCore.Quartz 8.3.0

⏱️ EasyCore.Quartz

EasyCore.Quartz is a production-oriented job scheduling library for .NET 8. Built on Quartz.NET, it provides attribute-based jobs, an English ops dashboard, REST management APIs, dynamic HTTP jobs, and persistence with clustering for MySQL / SQL Server / PostgreSQL / Oracle.

🌍 Language

• Chinese: README.md
• English (this document)

📚 Table of Contents

Part I — Overview & Architecture

• 1. Positioning
• 2. Architecture
• 3. NuGet Packages
• 4. Database Comparison

Part II — Getting Started

• 5. Requirements
• 6. Installation
• 7. Quick Start (3 minutes)
• 8. Attributes & Options

Part III — Dashboard · REST · HTTP Jobs

• 9. Dashboard (English UI)
• 10. REST API
• 11. HTTP Jobs

Part IV — Persistence & Production

• 12. Database Configuration
• 13. Clustering & Concurrency
• 14. Demo Projects
• 15. Migrating from older versions
• 16. Production Checklist
• 17. FAQ
• 18. License

1. Positioning

EasyCore.Quartz makes Quartz easy, operable, and production-safe in ASP.NET Core:

1.1 Design Principles

1.2 Repository Layout

EasyCore.Quartz/
├── src/
│   ├── EasyCore.Quartz/                 # Core: discovery, management, REST, History
│   ├── EasyCore.Quartz.Dashboard/       # English ops dashboard
│   ├── EasyCore.Quartz.MySql/
│   ├── EasyCore.Quartz.SqlServer/
│   ├── EasyCore.Quartz.PostgreSql/
│   └── EasyCore.Quartz.Oracle/
├── demo/
│   ├── WebApp.Quartz.InMemory/          # :5101 — each demo owns SampleJob
│   ├── WebApp.Quartz.MySql/             # :5102
│   ├── WebApp.Quartz.SqlServer/         # :5103
│   ├── WebApp.Quartz.PostgreSql/        # :5104
│   └── WebApp.Quartz.Oracle/            # :5105
├── tests/EasyCore.Quartz.Tests/
└── docs/svg/

2. Architecture

2.1 Component Diagram

2.2 Job Lifecycle

2.3 Data Flow

[EasyCoreCron Job]
       │
       ▼
 JobTypeDiscovery ──► JobWrapper<T> ──► Quartz Scheduler
       │                                      │
       │                                      ▼
       │                            JobExecutionHistoryListener
       │                                      │
       └──────── IJobManagementService ◄──────┘
                      │
           ┌──────────┴──────────┐
           ▼                     ▼
     Dashboard UI           REST api/quartz

3. NuGet Packages

4. Database Comparison

4.1 Decision Tree

Need persistence / multi-node?
├── No  → In-Memory (WebApp.Quartz.InMemory)
└── Yes → Pick your existing database
        ├── MySQL / MariaDB → EasyCore.Quartz.MySql
        ├── SQL Server → EasyCore.Quartz.SqlServer
        ├── PostgreSQL → EasyCore.Quartz.PostgreSql
        └── Oracle → EasyCore.Quartz.Oracle

5. Requirements

6. Installation

dotnet add package EasyCore.Quartz
dotnet add package EasyCore.Quartz.Dashboard

# pick one as needed
dotnet add package EasyCore.Quartz.MySql
dotnet add package EasyCore.Quartz.SqlServer
dotnet add package EasyCore.Quartz.PostgreSql
dotnet add package EasyCore.Quartz.Oracle

7. Quick Start (3 minutes)

7️⃣.1️⃣ Define a job

using EasyCore.Quartz;
using Quartz;

[EasyCoreCron("0/10 * * * * ?")]
[EasyCoreDisallowConcurrentExecution]
public sealed class SampleJob : IEasyCoreJob
{
    private readonly ILogger<SampleJob> _logger;
    public SampleJob(ILogger<SampleJob> logger) => _logger = logger;

    public Task Execute(IJobExecutionContext context)
    {
        _logger.LogInformation("SampleJob running at {Time}", DateTimeOffset.Now);
        return Task.CompletedTask;
    }
}

Disable without deleting code:

[EasyCoreDisableJob]
[EasyCoreCron("0 0 * * * ?")]
public sealed class DisabledJob : IEasyCoreJob
{
    public Task Execute(IJobExecutionContext context) => Task.CompletedTask;
}

7️⃣.2️⃣ Register services (including dashboard)

// Reference EasyCore.Quartz.Dashboard
builder.Services.AddEasyCoreQuartz(options =>
{
    options.AddAssemblyFrom<SampleJob>();
    options.TimeZoneOffsetHours = +8;
    options.AutoCreateSchema = true;

    // RAM by default. For persistence, uncomment one:
    // options.UseMySql(m => m.ConnectionString = "...");
    // options.UseSqlServer(s => s.ConnectionString = "...");
    // options.UsePostgreSql(p => p.ConnectionString = "...");
    // options.UseOracle(o => o.ConnectionString = "...");

    // Dashboard URL = app base URL + PathMatch
    // No app.UseEasyCoreQuartzDashboard(...) needed
    options.UseEasyCoreQuartzDashboard(dash =>
    {
        dash.PathMatch = "/easy-quartz";
        dash.Username = "admin";
        dash.Password = "admin123";
    });
});

Open: http://localhost:<port>/easy-quartz/ (browser prompts for username/password)

8. Attributes & Options

9. Dashboard (English UI)

9.1 Preview

9.2 Pages

⚠️ History is a process-local ring buffer. Overview success/failure counts reflect the current window only (not lifetime totals) and are not shared across nodes.

9.3 Authorization (HTTP Basic Auth)

options.UseEasyCoreQuartzDashboard(dash =>
{
    dash.PathMatch = "/easy-quartz"; // full URL = app base + this path
    dash.Username = "admin";         // required
    dash.Password = "admin123";      // required
});

10. REST API

Base path: api/quartz

11. HTTP Jobs

Create via Dashboard HTTP Jobs or REST:

{
  "jobName": "PingApi",
  "jobGroup": "DEFAULT",
  "url": "https://example.com/demo/ping",
  "method": "GET",
  "cron": "0/30 * * * * ?",
  "headers": { "X-Trace": "demo" },
  "body": "",
  "description": "Health ping"
}

To call a local demo API, allow the host explicitly:

options.HttpJobAllowedHosts.Add("localhost");
options.HttpJobAllowedHosts.Add("127.0.0.1");

12. Database Configuration

All providers use table prefix QRTZ_.

🐬 MySQL

options.UseMySql(mysql =>
{
    mysql.ConnectionString =
        "server=localhost;port=3306;user id=root;password=***;database=EasyCoreQuartz;";
});

🟦 SQL Server

options.UseSqlServer(sql =>
{
    sql.ConnectionString =
        "Server=.;Database=EasyCoreQuartz;User Id=sa;Password=***;TrustServerCertificate=True;";
});

🐘 PostgreSQL

options.UsePostgreSql(pg =>
{
    pg.ConnectionString =
        "Host=localhost;Port=5432;Database=EasyCoreQuartz;Username=postgres;Password=***";
});

🔶 Oracle

options.UseOracle(ora =>
{
    ora.ConnectionString =
        "User Id=quartz;Password=***;Data Source=localhost:1521/ORCL";
});

Production DDL tip

options.AutoCreateSchema = false; // disable auto DDL in production

Apply official Quartz scripts (or freeze scripts generated in staging) through your migration pipeline.

13. Clustering & Concurrency

Configuring any persistent provider enables Quartz clustering.

Prevent overlapping execution:

[EasyCoreDisallowConcurrentExecution]
[EasyCoreCron("0/5 * * * * ?")]
public sealed class ExclusiveJob : IEasyCoreJob { /* ... */ }

14. Demo Projects

Each demo has its own Jobs/SampleJob.cs — open and edit locally, no cross-project reference.

dotnet run --project demo/WebApp.Quartz.InMemory
# open http://localhost:5101/easy-quartz

For DB demos, update ConnectionStrings:Quartz in the corresponding appsettings.json first.

15. Migrating from older versions

8.0.0 is a breaking release (relative to earlier Quarzt* naming):

16. Production Checklist

• Use a strong dashboard password (never ship demo credentials publicly)
• Set AutoCreateSchema = false with reviewed migrations
• Keep connection strings in a secret store
• Monitor logs and History window failure counts (not lifetime totals)
• HTTP jobs: review HttpJobAllowedHosts / egress policy; do not casually disable private-network blocking
• Set MaxConcurrency explicitly under heavy load
• Validate cron expressions before deploy
• Multi-node setups must share the same store and table prefix

17. FAQ

Q: Dashboard returns 401?
A: The browser prompts for Basic Auth. Use the configured Username / Password. Enabling the dashboard without credentials throws at startup.

Q: Does RAM mode include the dashboard?
A: Yes. Reference EasyCore.Quartz.Dashboard and call options.UseEasyCoreQuartzDashboard(...).

Q: Why is History different across nodes?
A: History is a process-local ring buffer; Overview success/failure counts cover the current window only. Use your logging/audit stack for cross-node history.

Q: HTTP job to localhost is rejected?
A: SSRF protection is on by default. Add the host to options.HttpJobAllowedHosts, or disable HttpJobBlockPrivateNetworks only in controlled environments.

Q: Does default Method=GET fail validation?
A: No. Validation is case-insensitive in 8.0.

Q: How do I scan only my business assembly?
A: options.AddAssemblyFrom<YourJob>() or options.AddAssembly(asm).

18. License

MIT — see LICENSE.

🤝 Contributing

1. Fork and create a feature branch
2. Add tests under tests/EasyCore.Quartz.Tests
3. Run dotnet test and dotnet build EasyCore.Quartz.sln
4. Open a pull request

Issues and PRs are welcome 🚀