Custom Synapse Handlers

Synapse Handlers provide techncial capability to the Synapse Workflow Engine. Creating a custom Handler is the primary means of extending Synapse for scenarios.

"Free" Extensibility

Perhaps the easist way to add capability is the through the existing CommandHandler. The CommandHandler can already execute any arbitrary command-line, and has special helper interfaces for scripts and batch files. You can create new "technical modules" as scripts or whole logical processing workflows and integrate via the CommandHandler, as-is. See the CommandHandler Examples (develop branch). You can also read the docs.

Code-based Custom Handlers

If you want more control over your Handler, you may implement a compiled solution. Synapse.Core contains all the interfaces and base classes necessary, so you only need the single dependency. Wanna jump right in? See the Custom Handler Example.


To create a new Handler, create a new Class Library project (dll), and add a reference to Synapse.Core from

At a high level, the implementation flows as:

  1. Initialize: receives the Action Config data, serialized as a string. As an implementer, you must specify what serialization formats you accept (YAML, JSON, and XML). Use this method override to execute any necessary setup code for your Handler.
  2. Execute: receives the Action Parameter data, serialized as a string. As with Config, you must specify what serialization formats you accept. See the full HandlerStartInfo class for details on other members, but take care to implement the IsDryRun member so your Handler supports testing. ExecuteResult is returned from Execute method upon workflow completion.
  3. Progress: Advertises the runtime status of your internal workflow. HandlerProgressCancelEventArgs implements a Cancel member to support external graceful-cancellation requests.
  4. LogMessage: Override to log workflow detail during processing. This is present to support general logging patterns as any application would.
    public interface IHandlerRuntime
        //implmement simple getter/setter; value set by the runtime engine
        string ActionName { get; set; }
        //implmement simple getter/setter; value set by the runtime engine
        string RuntimeType { get; set; }

        IHandlerRuntime Initialize(string config);
        ExecuteResult Execute(HandlerStartInfo startInfo);

        event EventHandler<HandlerProgressCancelEventArgs> Progress;
        event EventHandler<LogMessageEventArgs> LogMessage;


HandlerRuntimeBase provides a default implementation for IHanderRuntime, plus some helper methods for deserialzing Config/Parameters. You may implement IHanderRuntime or inherit from HandlerRuntimeBase as you see fit.

Example Implementation Code

See the examples on GitHub.


In order to test your custom Handler in the Visual Studio debugger, edit the the project properties: click on the project in the Solution Explorer window, and press Alt-Enter on the keyboard. From the Project Properties window, choose the Debug option from the left menu/option-list.

  1. Choose “Start external program” and browse to a copy of synapse.cli.exe (download). It’s typically easiest to locate synapse.cli.exe in the debug output folder location (usually, \bin\Debug).
  2. Under “Start Options,” fill in the “Command line arguments” with a Plan, such as /plan:sample.yaml. You may also choose to add /resultPlan:true, in order to capture the output of the workflow engine.
  3. Press F5 to launch a debug session.

Synapse Handler