Building Custom Adapters 3.7
- 2. Building Custom Adapters • Understand how to build custom adapters using the Adapter Framework • Understand how to use custom adapters inside a Neuron ESB solution Goals
- 3. Building Custom Adapters • Adapter Framework • Creating custom metadata • Building a custom adapter • Integrating custom adapters into the Neuron Explorer • Debugging adapters at both design-time and run-time Lesson Plan
- 4. Building Custom Adapters The Neuron ESB adapter framework is a Visual Studio project, that provides a template for building adapters to be leveraged inside of the Neuron ESB Explorer Solution: • ESB-Name-Adapter • Classes • Adapter.cs • Inherits from ESBAdapterBase • Contains base method overrides • Framework helper code • CertificateConverter.cs • Used by a sample property to show how to perform type conversion • Sample demonstrates how to access design time Neuron ESB Configuration • NameAdapter.cs • The class you edit when creating a new adapter; contains methods and properties to support the UI property grid and adapter functionality. Adapter Framework Architecture
- 5. Two existing constants: • MetadataPrefix • Used within the Neuron ESB Explorer to identify properties specific to the adapter • Properties registered with this prefix in the adapters constructor will appear in the Set Property process step • AdapterName • Defines the “user friendly” name that will appear in the Adapter Registration screen Building Custom Adapters Adapter Framework Architecture : Constants and Types
- 6. • Defined properties are visible on the property grid at design-time • Properties can be set to either be hidden or visible based on the values of other properties • Type convertors can be used for defined properties • Defined properties are displayed in the Bindings Dialog, but can be declared as not bindable, if desired Building Custom Adapters Adapter Framework Architecture : Properties
- 7. • Define modes your adapter will support • Subscriber • Publisher • RequestReply • SolicitResponse • Define the ESBAdapterCapabilities • AdapterName • MetadataPrefix • MetadataFieldInfo • Any properties registered in the constructor will appear in the Set Property process step Building Custom Adapters Adapter Framework Architecture : Constructor
- 8. These methods are called from within base adapter class methods: ConnectAdapter Validation logic and initialization of resources used by custom adapter DisconnectResources Clean up all resources used by custom adapter SendToDataSource Called when adapter is in any subscriber based mode (Subscribe, Solicit Response etc..) ReceiveFromDataSource Called when adapter is in any publisher based mode (Publish, RequestReply etc..) InitializeRequestReplyListener Setup of the reply listener as well as handling the retrieval of data, as well as creating the ESB reply message Building Custom Adapters Adapter Framework Architecture : Base Methods
- 9. These methods are used in the various subscribe based modes (Subscriber, Query, SolicitResponse etc) SendToDataSource One way send to a back end system, protocol, transport etc (Subscribe) QueryDataSource Used in a Query or SolicitResponse mode to query information from the a back end system and publish the resulting data retrieval to the Bus Building Custom Adapters Adapter Framework Architecture : Send Methods
- 10. • These methods are used in the various publisher based modes (Publish, RequestReply etc) • PublishMessageFromSource • Implement logic to reach out to data source and then publish the resulting data to the Bus Building Custom Adapters Adapter Framework Architecture : Publish Methods
- 11. • Custom Metadata can be added to an ESBMessage using the IncludeMetadata property, which is configured on the General tab of an adapter endpoint in the Neuron ESB Explorer • Custom Metadata are provided with every message sent or received from Neuron ESB • Metadata is added to a message using the following syntax • MessageProperties.Add(new NameValuePair(“PropertyName", PropertyValue)); Building Custom Adapters Adapter Framework Architecture : Custom Metadata
- 12. • Compile into .NET assembly • Copy to Adapters folder: <install directory>Neuron ESB v3<instance name>Adapters • Ensure dependencies are installed in Adapters folder or Neuron install folder Building Custom Adapters Register with the Neuron ESB Explorer
- 13. Building Custom Adapters : Demo Purpose Familiarize users with the Neuron ESB Adapter Framework Objectives Acquaint users with following aspects custom adapters • How to build a custom adapter • How to integrate and deploy custom adapters
- 14. Building Custom Adapters Design Time • Attach debugger to neuronexplorer.exe from visual studio • Supports debugging of the adapter as well as the property grid Debugging Custom Adapters Image will be added when demo video is created as I will have access to exact pictures used in the demo
- 15. Building Custom Adapters Run time • Attach the debugger to the <endpoint host>.exe of the endpoint host that is hosting the adapter or hosting the business process that the adapter is being called from • Attach the debugger to <endpoint host>.exe that is hosting the workflow endpoint in order to debug the adapter workflow activity Debugging Custom Adapters Image will be added when demo video is created as I will have access to exact pictures used in the demo
- 16. Debugging Custom Adapters : Demo Purpose Familiarize users with how to debug custom adapters Objectives • Debug custom adapters using Visual Studio
- 17. Building Custom Adapters : Lab Purpose To acquaint users with building a custom adapter and registering it with Neuron ESB Objectives • Use the Adapter Framework to build a custom adapter • Copy the custom adapter DLL to Neuron’s Directories
- 18. Building Custom Adapters Review • Custom adapters are used to integrate third party systems for which Neuron ESB does not come with a pre-built adapter. • Custom adapters are created using the Adapter Framework • The modes the adapter is capable of running in is configurable • SendToDataSource is the base method used by a Subscribe mode adapter • ReceiveFromDataSource is the base method used by a Publish mode adapter • Custom adapters are registered with the Neuron ESB Explorer by copying the compiled DLL into the adapters directory
Editor's Notes
- #3: The goals of this lesson are to familiarize users with how to build custom adapters using the Neuron ESB adapter framework, and how to use those custom adapters inside of a Neuron ESB solution.
- #4: This lesson has been broken into five sections to make the information presented easier to understand. The sections we will be covering are Adapter Framework Creating custom metadata Building a custom adapter Integrating custom adapters into the Neuron Explorer Debugging adapters at both design-time and run-time
- #5: The Neuron ESB adapter framework is a Visual Studio project, that provides a template for building adapters to be leveraged inside of the Neuron ESB Explorer. The solution for the Adapter Framework Project is divided into two parts ESB-Name-Adapter Classes Adapter.cs Inherits from ESBAdapterBase Contains base method overrides Framework helper code CertificateConverter.cs Used by a sample property to show how to perform type conversion Sample demonstrates how to access design time Neuron ESB Configuration NameAdapter.cs The class you edit when creating a new adapter; contains methods and properties to support the UI property grid and adapter functionality.
- #6: There are two existing constants in the NameAdapter class MetadataPrefix Used within the Neuron ESB Explorer to identify properties specific to the adapter. Properties registered with this prefix in the adapters constructor will appear in the Set Property process step AdapterName Defines the “user friendly” name that will appear in the Adapter Registration screen
- #7: Public properties defined in the NameAdapter class are visible on the property grid at design-time Properties can be set to either be hidden or visible based on the values of other properties Type convertors can be used for defined properties Defined properties are displayed in the Bindings Dialog, but can be declared as not bindable, if desired
- #8: In the constructor of the NameAdapter class you will find the AdapterModes. If you are not going use some of the modes, it is recommended to comment them out, so that they can be reinstated at a different time should you wish to extend the abilities of your adapter. You will also find the ESBAdapterCapabilities to which the adapter name, metadata prefix and metadata field info is added. Any properties registered with the capabilities in the constructor will appear in the Set Property process step
- #9: The NameAdapter class also contains the methods for interacting with Neuron ESB. ConnectAdapter Validation logic and initialization of resources used by custom adapter DisconnectResources Clean up all resources used by custom adapter SendToDataSource Called when adapter is in any subscriber based mode (Subscribe, Solicit Response etc..) ReceiveFromDataSource Called when adapter is in any publisher based mode (Publish, RequestReply etc..) InitializeRequestReplyListener Setup of the reply listener as well as handling the retrieval of data, as well as creating the ESB reply message
- #10: The send methods are those methods that are used in the various subscribe modes (Subscribe, Query, SolicitResponse) SendToDataSource One way send to a back end system, protocol, transport etc (Subscribe) QueryDataSource Used in a Query or SolicitResponse mode to query information from the a back end system and publish the resulting data retrieval to the Bus
- #11: The publish methods are those used by the various publish modes (Publish, RequestReply) PublishMessageFromSource Implement logic to reach out to data source and then publish the resulting data to the Bus
- #12: Custom Metadata can be added to an ESBMessage using the IncludeMetadata property, which is configured on the General tab of an adapter endpoint in the Neuron ESB Explorer Custom Metadata are provided with every message sent or received from Neuron ESB. Metadata is added to a message using the following syntax MessageProperties.Add(new NameValuePair(“PropertyName", PropertyValue));
- #13: Once you have finished your development of your custom adapter you will need to compile it into a .NET assembly and copy that assembly to the adapters folder <install directory>\Neuron ESB v3\<instance name>\Adapters. Make sure that all dependencies for your adapter are installed in the same folder or the Neuron install directory.
- #15: To debug custom adapters you need to attach the visual studio debugger to the neuronesplorer.exe. This supports the debugging of the property grid as well.
- #16: To debug a custom adapter at runtime attach the debugger to the <endpoint host>.exe of the endpoint host that is hosting the adapter or hosting the business process that the adapter is being called from. If the custom adapter is being called from a workflow definition attach the debugger to <endpoint host>.exe that is hosting the workflow endpoint in order to debug the adapter workflow activity