Custom Synapse Controller Interface

Synapse.Controller accepts configuration specifying custom ApiController libraries, thereby allowing you apply custom data processing models, URIs, and RBAC implentations. We consider this a "normal" integration pattern such that Synapse can feel like part of your application, not an adjunct entity.


The easiest way to implement a custom ApiController is to create a new Class Library project (dll), and add a reference to Synapse.Server.Extensibility from This will add all the necessary Web Api dependencies, and Synapse.Server.Extensibility contains a few helper utilities to aid in your dev. See a Custom ApiController using Synapse.Server.Extensibility on

Native ApiControllers

You may choose to implement a regular .NET ApiController, and Synapse will load it just fine. The Synapse.Server.Extensibility library mentioned above is simply a helper lib. Working sans Synapse.Server.Extensibility just means you need to bridge into Synapse.Controller on your own, whereas Synapse.Server.Extensibility provides a utility helper class to do so for you.

Declare your Custom Controller Interface

After you implement the custom interface, specify it in Synapse.Server.config.yaml in the Controller->Assemblies section, as shown below. The syntax is simply to list the assembly name, as opposed to assembly:{namepsace.}class, as in Handler declaration. Synapse Controller will discover all classes that inherit from System.Web.Http.ApiController (MSDN).

# Configure the 'Assemblies' node of Synapse.Server.config.yaml

  Name: Synapse.Controller
  DisplayName: Synapse Controller
  Role: Server
  Host: localhost
  Port: 20000
  IsSecure: false
    Scheme: Anonymous
  KeyContainerName: DefaultContainerName
  CspProviderFlags: NoFlags
  NodeUrl: http://localhost:20001/synapse/node
  SignPlan: false
  - Synapse.CustomController0
  - Synapse.CustomController1
  - Synapse.CustomController2

Synapse.Server.Extensibility Example


In order to test your custom ApiController 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. Download the latest build of Synapse.Server and extraxt it to the .\bin folder of your custom controller (note: not the .\bin\Debug folder, or, if you're using a custom build location, extract local to that folder).
  2. Choose “Start external program” and browse to either 1) synapse.controller.cli.exe, or 2) synapse.server.exe in the extract location from step 1.
    • If using synapse.controller.cli.exe, then under “Start Options,” fill in the “Command line arguments” with a service run.
    • Use synapse.controller.cli.exe to debug against only a Controller instance, and use synapse.server.exe if you want a Controller and and Node option (making sure to configure synapse.server.config.yaml appropriately (detail).
  3. See Configuration Options for assembly resolution, and add the Debug & Release folders to the .exe.config probing privatePath setting.
  4. Press F5 to launch a debug session.

Synapse Handler