Triggers

Starting workflows from schedules, events, and file changes

A trigger decides when a workflow runs. Every trigger implements ITrigger through the shared TriggerBase, which provides identity, enabled/active state, activation counts, and error reporting.

Table of Contents

Built-in Triggers

TriggerFires whenKey configuration
ManualTriggerThe host (or user) starts the workflow directly; the trigger only tracks active stateOptional activation payload
ScheduleTriggerA fixed interval elapsesInterval (must be greater than zero)
EventTriggerAn application event is raisedEvent name and optional filter
FileWatchTriggerA file matching a filter is created, changed, deleted, or renamedPath, Filter, IncludeSubdirectories

Lifecycle

Triggers are validated, started, and stopped explicitly, and they report failures instead of throwing at you:

Validate, start, observe, dispose

var trigger = new FileWatchTrigger
{
    Path = @"C:\dropbox\incoming",
    Filter = "*.csv",
    IncludeSubdirectories = false,
    WorkflowId = "nightly"
};

var validation = await trigger.ValidateAsync();   // e.g. "Directory does not exist"
if (!validation.IsValid) { /* surface it */ }

trigger.Triggered += (s, e) => Console.WriteLine($"fired with {e.TriggerData?.Count} field(s)");
await trigger.StartAsync();

// ... later
trigger.Dispose();   // stops the trigger and releases its watcher/timer
Triggers are IDisposable. Disposing a running trigger stops it and releases the underlying FileSystemWatcher or background loop, so hosts that discard a trigger cannot leak operating system handles. Disposal is idempotent and safe on an already-stopped trigger, and a stopped trigger can be restarted.

Each trigger exposes IsActive, IsEnabled, LastActivated and ActivationCount for monitoring, plus Triggered and ErrorOccurred events. The Triggered event carries TriggerId, TriggerType and a TriggerData payload; failures arrive through ErrorOccurred with the exception and message.

TriggerBase Members

MemberTypeDescription
IdstringShort unique id assigned at construction.
Name / DescriptionstringDisplay identity of the trigger.
TriggerTypeTriggerTypeManual, Scheduled, WebHook, DataChange, Event, Email, FileSystem or API.
IsActive / IsEnabledboolRunning state and a separate enable switch.
WorkflowIdstringThe workflow this trigger starts.
ConfigurationDictionary<string, object>Free-form settings, mirrored by GetConfigurationSchema().
LastActivated / ActivationCountDateTime? / longActivation telemetry.
InitializeAsync / ValidateAsync / StartAsync / StopAsyncTaskLifecycle, all cancellation-aware.

Example: a schedule that feeds a workflow

var engine = new WorkflowEngine();
await engine.LoadWorkflowAsync(savedWorkflow);

using var trigger = new ScheduleTrigger { Interval = TimeSpan.FromMinutes(15) };
trigger.Triggered += async (s, e) =>
{
    var result = await engine.ExecuteWorkflowAsync(savedWorkflow.Id);
    Console.WriteLine($"scheduled run finished: {result.Status}");
};

await trigger.StartAsync();

Related