Creating Custom Adapters

Adapters are Enterprise Application Integration (EAI) components that are hosted in the Neuron ESB server process and integrate natively with the Neuron messaging system.

Neuron provides several supported prebuilt adapters but sometimes you may need to create your own adapter when interacting with a system that does not have a prebuilt adapter. You create your own adapter by leveraging the Neuron Adapter Framework.

Always handle exceptions in a Custom Adapter. An unhandled exception in an adapter will cause the Neuron ESB process to terminate.

Creating a Publication Adapter

Publication adapters are responsible for publishing messages to Neuron from an external system. To create a publication adapter:

1. Add references to the standard Neuron DLLs (Neuron.dll, Neuron.Esb.dll, Neuron.Scripting.dll and Neuron.Pipelines.dll).
2. Create a class that derives from Neuron.Esb.Adapters.ESBAdapterBase.
3. In the constructor of the class, initialize the adapter capabilities and adapter modes:
   AdapterModes = new Neuron.Esb.Adapters.AdapterMode[]
{
new Neuron.Esb.Adapters.AdapterMode("Publish", Neuron.Esb.Adapters.MessageDirection.DatagramReceiver)
};
Capabilities = new Neuron.Esb.Adapters.ESBAdapterCapabilities()
{
AdapterName = "My Adapter"
};
   
   DatagramReceiver is used for implementations where the external system will push messages onto the bus and does not expect a reply. RequestReplyReceiver is used when the external system initiates the process and expects a reply.
4. Implement the Connect and Disconnect methods. The connect method will be passed the name of the mode in which the adapter has been configured to run.
5. Implement SendToEndpoint if your Publication Adapter also implements DataGramSender or RequestReplySender. This method is invoked when receiving messages from the bus. For Publication only adapters this may be left blank.
6. Implement a custom method / thread that will call the base class method RaiseReceiveFromEndpointEvent when it receives a message. The mechanisms for receiving the message are inherently custom. For example your implementation may use a Timer for polling or use a Socket for a legacy binary protocol.

Creating a Subscription Adapter

Subscription adapters are responsible for publishing messages from Neuron to an external system.

1. Add references to the standard Neuron DLLs (Neuron.dll, Neuron.Esb.dll, Neuron.Scripting.dll and Neuron.Pipelines.dll).
2. Create a class that derives from Neuron.Esb.Adapters.ESBAdapterBase.
3. In the constructor of the class, initialize the adapter capabilities and adapter modes:
   AdapterModes = new Neuron.Esb.Adapters.AdapterMode[]
{
new Neuron.Esb.Adapters.AdapterMode("Subscribe", Neuron.Esb.Adapters.MessageDirection.DatagramSender)
};
Capabilities = new Neuron.Esb.Adapters.ESBAdapterCapabilities()
{
AdapterName = "My Adapter"
};
4. Implement the Connect and Disconnect methods. The connect method will be passed the name of the mode in which the adapter has been configured to run.
5. Implement the SendToEndpointMethod. If your Adapter supports RequestReplySender then use RaiseReceiveFromEndpointEvent in the body of this method to return the response.

Adapter Properties

Many adapters require information such as connection strings to be configured. The adapter framework allows custom properties to be exposed by Neuron Explorer. Be default, any public property exposed by the adapter will be saved. All properties to be saved must be convertible to and from string format. To exclude a property from being saved, add the NameValuePairIgnore attribute to the property definition. The DisplayName, Category, and Description attributes can be used to customize the information displayed in the adapter property grid.

Tracing and Logging

The adapter framework exposes the following logging methods to communicate status with the bus.

void RaiseAdapterInfo(ErrorLevel errorLevel, string message)

void RaiseAdapterError(ErrorLevel errorLevel, string message, Exception ex)

These methods will log according to the trace options in use by the bus. For additional information refer to the Neuron API Reference [link] and Configuring Logging and Tracing [link].

Deploying an Adapter

To make an adapter available to Neuron, copy the adapter DLL and any supporting DLLs to the “Adapters” folder under the Neuron installation folder. The adapter can now be made available to adapter endpoints by adding a reference to the adapter in the connection methods section of Neuron Explorer:

After adding a reference in the connection methods section of Neuron Explorer, individual adapter endpoints can now be configured: