betacart/cron-expression-descriptor

A .NET library that converts cron expressions into human readable descriptions.

Cron Expression Descriptor

 Would you take a quick second and ⭐️ my repo?

A .NET library that converts cron expressions into human readable descriptions.

CronExpressionDescriptor.ExpressionDescriptor.GetDescription("* * * * *");
> "Every minute"

Author: Brady Holt (http://www.geekytidbits.com) License: MIT

Features

• Supports all cron expression special characters including * / , - ? L W, #
• Supports 5, 6 (w/ seconds or year), or 7 (w/ seconds and year) part cron expressions
• Localization with support for 26 languages
• Provides casing options (Sentence case, Title Case, lowercase, etc.)
• Supports Quartz Enterprise Scheduler .NET cron expressions

Demo

https://bradymholt.github.io/cron-expression-descriptor

Download

Cron Expression Descriptor releases can be installed with NuGet.

Package Manager (Visual Studio)

Install-Package CronExpressionDescriptor

.NET CLI

dotnet add package CronExpressionDescriptor

Visit the NuGet Package page for more info.

View Releases for release version history.

Quick Start

CronExpressionDescriptor.ExpressionDescriptor.GetDescription("* * * * *");
> "Every minute"

Options

A CronExpressionDescriptor.Options object can be passed to GetDescription. The following options are available:

• bool ThrowExceptionOnParseError - If exception occurs when trying to parse expression and generate description, whether to throw or catch and output the Exception message as the description. (Default: true)
• bool Verbose - Whether to use a verbose description (Default: false)
• bool DayOfWeekStartIndexZero - Whether to interpret cron expression DOW 1 as Sunday or Monday. (Default: true)
• ?bool Use24HourTimeFormat - If true, descriptions will use a 24-hour clock (Default: false but some translations will default to true)
• string Locale - The locale to use (Default: "en")

Example usage:

ExpressionDescriptor.GetDescription("0-10 11 * * *", new Options(){
    DayOfWeekStartIndexZero = false,
    Use24HourTimeFormat = true,
    Locale = "fr"
});

i18n

The following language translations are available.

• English - en (Brady Holt)
• Chinese Simplified - zh-Hans (zh-CN) (Star Peng)
• Chinese Traditional - zh-Hant (zh-TW) (Ricky Chiang)
• Danish - da (Rasmus Melchior Jacobsen)
• Dutch - nl (TotalMace)
• Finnish - fi (Mikael Rosenberg)
• French - fr (Arnaud TAMAILLON)
• German - de (Michael Schuler)
• Hebrew - he (Ariel Deil)
• Hungarian - hu (Varga Miklós)
• Italian - it (rinaldihno)
• Japanese - ja (Alin Sarivan)
• Korean - ko (Ion Mincu)
• Norwegian - nb (Siarhei Khalipski)
• Persian (Farsi) - fa (A. Bahrami)
• Polish - pl (foka)
• Portuguese (Brazil) - pt-BR (Renato Lima)
• Romanian - ro (Illegitimis)
• Russian - ru (LbISS)
• Slovenian - sl-SI (Jani Bevk)
• Spanish - es (Ivan Santos)
• Spanish (Mexico) - es-MX (Ion Mincu)
• Swedish - sv (roobin)
• Vietnamese - vi (Nguyen Duc Son)
• Turkish - tr (Mustafa SADEDİL)
• Ukrainian - uk (Taras)

To use one of these translations, pass in the Locale option to GetDescription. For example, to get the description of 0-10 11 * * * in German:

ExpressionDescriptor.GetDescription("0-10 11 * * *", new Options(){ Locale = "de" });
> "Jede Minute zwischen 11:00 und 11:10"

Alternatively, you can call ExpressionDescriptor.SetDefaultLocale("es"); first to set the default locale and then every usage will use this locale by default.

ExpressionDescriptor.SetDefaultLocale("es");

ExpressionDescriptor.GetDescription("*/45 * * * * *");
> "Cada 45 segundos"

ExpressionDescriptor.GetDescription("0-10 11 * * *");
> "Cada minuto entre las 11:00 AM y las 11:10 AM"

CurrentUICulture

If you are targeting a platform that supports .NET Standard >= 2.0, Thread.CurrentUICulture is supported for determining the default locale, without explicitly passing it in with the Locale option, so the following will work:

// .NET Standard >= 2.0 only
CultureInfo myCultureInfo = new CultureInfo("it-IT");
Thread.CurrentThread.CurrentUICulture = myCultureInfo;
ExpressionDescriptor.GetDescription("* * * * *");
> "Ogni minuto"

.NET Platform Support

Beginning with version 2.0.0, the NuGet package will contain a library targeting .NET Standard 1.1 and 2.0. This allows the library to be consumed by applications running on the following .NET platforms:

• .NET Core >= 1.0
• .NET Framework >= 4.5
• Mono >= 4.6
• (More)

If your application is targeting an earlier version of .NET Framework (i.e. 4.0 or 3.5), you can use version 1.21.2 as it has support back to .NET Framework 3.5. To install this version, run Install-Package CronExpressionDescriptor -Version 1.21.2.

Strong Name Signing

If you need an assembly that is signed with a strong name, you can use version 1.21.2 as it is currently the latest version signed with a strong name.

Ports

This library has been ported to several other languages.

• JavaScript - https://github.com/bradymholt/cRonstrue
• Java - https://github.com/RedHogs/cron-parser
• Java - https://github.com/voidburn/cron-expression-descriptor
• Ruby - https://github.com/alpinweis/cronex
• Python - https://github.com/Salamek/cron-descriptor
• PHP - https://github.com/panlatent/cron-expression-descriptor
• Go - https://github.com/lnquy/cron
• Rust - https://github.com/cflockhart/cron-descriptor-rust

Frequently Asked Questions

The cron expression I am passing in is not valid and this library is giving strange output. What should I do?

This library does not do full validation of cron expressions and assumes the expression passed in is valid. If you need to validate an expression consider using a library like Cronos.

Does this library support showing the "next" scheduled date?

No, this is not supported.

Examples

ExpressionDescriptor.GetDescription("* * * * *");

"Every minute"

ExpressionDescriptor.GetDescription("*/1 * * * *");

"Every minute"

ExpressionDescriptor.GetDescription("0 0/1 * * * ?");

"Every minute"

ExpressionDescriptor.GetDescription("0 0 * * * ?");

"Every hour"

ExpressionDescriptor.GetDescription("0 0 0/1 * * ?");

"Every hour"

ExpressionDescriptor.GetDescription("0 23 ? * MON-FRI");

"At 11:00 PM, Monday through Friday"

ExpressionDescriptor.GetDescription("* * * * * *");

"Every second"

ExpressionDescriptor.GetDescription("*/45 * * * * *");

"Every 45 seconds"

ExpressionDescriptor.GetDescription("*/5 * * * *");

"Every 5 minutes"

ExpressionDescriptor.GetDescription("0 0/10 * * * ?");

"Every 10 minutes"

ExpressionDescriptor.GetDescription("0 */5 * * * *");

"Every 5 minutes"

ExpressionDescriptor.GetDescription("30 11 * * 1-5");

"At 11:30 AM, Monday through Friday"

ExpressionDescriptor.GetDescription("30 11 * * *");

"At 11:30 AM"

ExpressionDescriptor.GetDescription("0-10 11 * * *");

"Every minute between 11:00 AM and 11:10 AM"

ExpressionDescriptor.GetDescription("* * * 3 *");

"Every minute, only in March"

ExpressionDescriptor.GetDescription("* * * 3,6 *");

"Every minute, only in March and June"

ExpressionDescriptor.GetDescription("30 14,16 * * *");

"At 02:30 PM and 04:30 PM"

ExpressionDescriptor.GetDescription("30 6,14,16 * * *");

"At 06:30 AM, 02:30 PM and 04:30 PM"

ExpressionDescriptor.GetDescription("46 9 * * 1");

"At 09:46 AM, only on Monday"

ExpressionDescriptor.GetDescription("23 12 15 * *");

"At 12:23 PM, on day 15 of the month"

ExpressionDescriptor.GetDescription("23 12 * JAN *");

"At 12:23 PM, only in January"

ExpressionDescriptor.GetDescription("23 12 ? JAN *");

"At 12:23 PM, only in January"

ExpressionDescriptor.GetDescription("23 12 * JAN-FEB *");

"At 12:23 PM, January through February"

ExpressionDescriptor.GetDescription("23 12 * JAN-MAR *");

"At 12:23 PM, January through March"

ExpressionDescriptor.GetDescription("23 12 * * SUN");

"At 12:23 PM, only on Sunday"

ExpressionDescriptor.GetDescription("*/5 15 * * MON-FRI");

"Every 5 minutes, between 03:00 PM and 03:59 PM, Monday through Friday"

ExpressionDescriptor.GetDescription("* * * * MON#3");

"Every minute, on the third Monday of the month"

ExpressionDescriptor.GetDescription("* * * * 4L");

"Every minute, on the last Thursday of the month"

ExpressionDescriptor.GetDescription("*/5 * L JAN *");

"Every 5 minutes, on the last day of the month, only in January"

ExpressionDescriptor.GetDescription("30 02 14 * * *");

"At 02:02:30 PM"

ExpressionDescriptor.GetDescription("5-10 * * * * *");

"Seconds 5 through 10 past the minute"

ExpressionDescriptor.GetDescription("5-10 30-35 10-12 * * *");

"Seconds 5 through 10 past the minute, minutes 30 through 35 past the hour, between 10:00 AM and 12:00 PM"

ExpressionDescriptor.GetDescription("30 */5 * * * *");

"At 30 seconds past the minute, every 05 minutes"

ExpressionDescriptor.GetDescription("0 30 10-13 ? * WED,FRI");

"At 30 minutes past the hour, between 10:00 AM and 01:00 PM, only on Wednesday and Friday"

ExpressionDescriptor.GetDescription("10 0/5 * * * ?");

"At 10 seconds past the minute, every 05 minutes"

ExpressionDescriptor.GetDescription("2-59/3 1,9,22 11-26 1-6 ?");

"Every 03 minutes, minutes 2 through 59 past the hour, at 01:00 AM, 09:00 AM, and 10:00 PM, between day 11 and 26 of the month, January through June"

ExpressionDescriptor.GetDescription("0 0 6 1/1 * ?");

"At 06:00 AM"

ExpressionDescriptor.GetDescription("0 5 0/1 * * ?");

"At 05 minutes past the hour"

ExpressionDescriptor.GetDescription("* * * * * * 2013");

"Every second, only in 2013"

ExpressionDescriptor.GetDescription("* * * * * 2013");

"Every minute, only in 2013"

ExpressionDescriptor.GetDescription("* * * * * 2013,2014");

"Every minute, only in 2013 and 2014"

ExpressionDescriptor.GetDescription("23 12 * JAN-FEB * 2013-2014");

"At 12:23 PM, January through February, 2013 through 2014"

ExpressionDescriptor.GetDescription("23 12 * JAN-MAR * 2013-2015");

"At 12:23 PM, January through March, 2013 through 2015"