GitHub - hugoj0s3/NaturalCron: Human-readable recurrence expressions for .NET – easier than Cron!

NaturalCron is a human-readable scheduling engine for .NET. It lets you write schedules in a clear and intuitive way instead of memorizing cryptic cron strings.

Why? Because memorizing 0 18 * * 1-5 is harder than understanding every day between monday and friday at 6:00pm.

Readable schedules reduce mistakes, write expressions that you can understand at a glance.

Note: NaturalCron is not a cron converter. It is a self-contained scheduling engine with its own expressive syntax. If you need a classic cron string for an external system, the optional NaturalCron.CronConverter package can translate expressions — but be aware that some NaturalCron features have no cron equivalent.

💡 Why use NaturalCron?

• Readable syntax: every 30 minutes in [jan, jun] between 09:00 and 18:00
• Fluent Builder API: Strongly typed for .NET developers.
• No online generators needed.
• Features:
  • Ranges
  • Weekday list
  • Closest weekday, first/last day handling
  • Time zone support with IANA TZ names

🚀 Quick Start

Using an Expression

using System;
using NaturalCron;

// Define an advanced expression
string expression = "every 30 minutes in [jan, jun] between 09:00 and 18:00";

// Parse and calculate next occurrence (local time)
NaturalCronExpr schedule = NaturalCronExpr.Parse(expression);
DateTime next = schedule.GetNextOccurrence(DateTime.Now);

Console.WriteLine($"Next occurrence: {next}");

Using Fluent Builder

using System;
using NaturalCron;
using NaturalCron.Builder;

NaturalCronExpr schedule = NaturalCronBuilder
.Every(30).Minutes()
.In(NaturalCronMonth.Jan)
.Between("09:00", "18:00")
.Build();

DateTime next = schedule.GetNextOccurrenceInUtc(DateTime.UtcNow);

Console.WriteLine($"Next occurrence in UTC: {next}");

⚡ Try it online: Run on .NET Fiddle

🆚 Cron vs NaturalCron

📝 Syntax Overview

Examples:

every 5 minutes
every day at 18:00
every 30 minutes in [jan, jun] between 09:00 and 18:00
every day at 10:00 on [monday, wednesday, friday]

📦 Installation

dotnet add package NaturalCron

📖 Documentation

• Expression Syntax — Learn how to write human-readable recurrence rules.
• Fluent Builder Guide — Build expressions easily with type safety and IntelliSense.
• API Reference — Full API details and usage examples.
• Cron Converter — Translate NaturalCron expressions to classic cron strings, and what is not supported.

🔌 JobMaster Integration (Alpha)

Looking for a complete job scheduling solution with NaturalCron support? Check out JobMaster — a powerful .NET job scheduling library that natively integrates with NaturalCron for human-readable scheduling.

🤝 Contributing

Contributions, bug reports, and feature requests are welcome!

Please open an issue or submit a pull request.