Com.H.Threading.Scheduler 10.0.1

Com.H.Threading.Scheduler

For full documentation, visit the GitHub project page.

An easy-to-use, feature-rich, open-source scheduling framework for building background services as Windows services, Linux daemons, or containerized microservices.

Quick start

Define tasks in an XML configuration file with scheduling rules in <sys> and custom data in any other tags:

scheduler.xml

<?xml version="1.0" encoding="utf-8" ?>
<tasks_list>
  <task>
    <sys>
      <time>11:00</time>
    </sys>
    <greeting_message>Good morning! It's 11:00 AM!</greeting_message>
  </task>
</tasks_list>

Program.cs

using Com.H.Threading.Scheduler;

var configPath = Path.Combine(AppContext.BaseDirectory, "scheduler.xml");
if (!File.Exists(configPath)) throw new FileNotFoundException(configPath);

var scheduler = new HTaskScheduler(configPath);
scheduler.TaskIsDue += async (object sender, HTaskEventArgs e, CancellationToken ct) =>
{
    Console.WriteLine(e["greeting_message"]);
};

Console.WriteLine("Press <ctrl+c> to exit.");
await scheduler.StartAsync();

Interval scheduling

Run every 3 seconds between 9:00 AM and 2:00 PM on specific days:

<sys>
  <time>09:00</time>
  <until_time>14:00</until_time>
  <interval>3000</interval>
  <dow>Monday,Thursday</dow>
</sys>

Scheduling rules

All rules compose — every condition must be true for a task to run.

Retry on error

<sys>
  <interval>10000</interval>
  <retry_attempts_on_error>3</retry_attempts_on_error>
  <sleep_on_error>5000</sleep_on_error>
</sys>

Variables

Built-in placeholders replaced at runtime:

Repeat

Execute a task multiple times with different data per iteration. Supports XML (default), JSON, CSV, and pipe-separated formats:

<sys>
  <interval>60000</interval>
  <repeat content_type="json" delay_interval="500">
    [
      {"id": 1, "name": "alice"},
      {"id": 2, "name": "bob"}
    ]
  </repeat>
</sys>
<message>Processing {var{name}} (ID: {var{id}})</message>

Repeat from external source

Chain content types to fetch and parse: uri > json, uri > csv, uri > xml, etc.

<repeat content_type="uri > json" delay_interval="500">
  https://api.example.com/users
</repeat>

File URIs are also supported:

<repeat content_type="uri > csv" delay_interval="500">
  {dir{uri}}/data/users.csv
</repeat>

External settings

Fetch tag content from URLs with optional caching:

<config content_type="uri" content_cache="once_per_day">
  https://api.example.com/config
</config>

Cache options: none (default), once_per_day / daily, or milliseconds (e.g., 3600000).

Dynamic scheduling with URI — skip holidays

content_type="uri" also works on scheduling rules inside <sys>. Point <enabled> at an API — if the response contains true (case-insensitive), the task runs; otherwise it's skipped:

<sys>
  <time>09:00</time>
  <dow>Monday,Tuesday,Wednesday,Thursday,Friday</dow>
  <enabled content_type="uri">https://api.example.com/is-business-day?date={now{yyyy-MM-dd}}</enabled>
</sys>

Add content_cache="once_per_day" to avoid calling the API on every tick — the result is cached until midnight:

<enabled content_type="uri" content_cache="once_per_day">https://api.example.com/is-business-day?date={now{yyyy-MM-dd}}</enabled>

Custom placeholder markers

Override the default {{ / }} markers on any tag:

<sql open-marker="[%" close-marker="%]" null-value="N/A">
  INSERT INTO users (name, email) VALUES ('[%var{name}%]', '[%var{email}%]')
</sql>

Error handling

scheduler.TaskExecutionError += async (object sender, HTaskExecutionErrorEventArgs e, CancellationToken ct) =>
{
    Console.WriteLine($"Task failed: {e.Exception.Message}");
};

scheduler.TaskLoadingError += async (object sender, HErrorEventArgs e, CancellationToken ct) =>
{
    Console.WriteLine($"Config error: {e.Exception.Message}");
};

Worker service integration

For .NET worker services, use Com.H.Threading.Scheduler.DI for IServiceCollection integration. Installing it automatically includes this library as a dependency.