Neuron COM Interoperability
Neuron ESB is completely written using the Microsoft .NET Framework. Neuron ESB is deployed as a server solution, but also offers a distributable .NET Neuron ESB Client API that allow users to effectively host the Enterprise Service Bus (ESB) within their own .NET Applications, remote from the central Neuron ESB Server. The Neuron ESB Client API can communicate either with Topics via the central Neuron ESB Server, or directly to other hosted Neuron ESB clients. These hosted Neuron ESB Clients can be easily distributed across the network where Business Processes can be associated with them and executed within the environment they are hosted in.
Using .NET COM Interoperability features, the Neuron ESB Client API may be exposed as a COM library that can be used within scripting environments such as VBScript and WScript or, within development environments like Microsoft Office VBA applications, PowerBuilder or Foxpro.
Microsoft Visual Studio .NET Solution
This sample demonstrates early and late binding COM interoperability using a Neuron ESB COM Type Library. A Visual Studio .NET Solution is provided as part of this sample that can be compiled to create the COM Type Library. The VS.NET Solution (Neuron.Excel.Interop.sln) contains the Party class as well as the IParty and IPartyEvents interfaces.
The Party class exposes the following methods and events that can be used in scripting or VBA enabled applications:
|Connect||Method||Uses inputs such as zone, port, server and party id to connect to the Neuron ESB environment.|
|Disconnect||Method||Disconnects the party id from the Neuron ESB environment.|
|Send||Method||Publishes a message using the Multicast Semantic to the Neuron ESB Topic.|
|SendRequest||Method||Publishes a message using the Request Semantic to the Neuron ESB Topic. A Response message will be returned.|
|StopReceive||Method||Disconnects the Receive event from the subscribing Party.|
|StartReceive||Method||Starts/Connects the Receive event for the subscribing Party.|
|OnMessageReceive||Event||Activates when a message is received by the Party. StartReceive must be called first.|
|OnDisconnect||Event||Activates when Disconnect is called.|
|OnConnect||Event||Activates when Connect is called.|
Registration BAT file
A registration batch file (regcom.bat) is included which demonstrates how to register the outputs of the Visual Studio solution so that COM enabled applications can use the COM Type Library.
The Assembly Registration tool (Regasm.exe) reads the metadata within an assembly and adds the necessary entries to the registry, which allows COM enabled clients to create .NET Framework classes transparently. Once a class is registered, any COM client can use it as though the class were a COM class. The class is registered only once, when the assembly is installed. Instances of classes within the assembly cannot be created from COM until they are actually registered.
Microsoft Excel Macro enabled Workbook
The Microsoft Excel 2010 Macro enabled Workbook (Neuron.Excel.Interop.xlsm) demonstrates how to use the Neuron ESB COM Type library from Visual Basic for Applications. Sheet1 of the Workbook as 6 command buttons that are bound to macros that call their respective functions:
|Connect||Connect||Uses inputs such as zone, port, server and party id to connect to the Neuron ESB environment.|
|Disconnect||Disconnect||Disconnects the party id from the Neuron ESB environment.|
|Send Multicast||Send||Publishes a message using the Multicast Semantic to the Neuron ESB Topic.|
|Send Request||SendRequest||Publishes a message using the Request Semantic to the Neuron ESB Topic. A Response message will be returned.|
|Stop Receive||StopReceive||Disconnects the Receive event from the subscribing Party.|
|Start Receive||StartReceive||Starts/Connects the Receive event for the subscribing Party.|
The Connect, Send Multicast and Send Request all require user entered parameters on the spreadsheet corresponding with their labels:
|Connect||Party ID – Defaults to FinancePublisherServer – Defaults to localhostPort – Defaults to 50000Zone – Defaults to Enterprise|
|Send Multicast||Topic – Defaults to FinanceMessage To Send – Defaults to <xml>hello</xml>|
|Send Request||Topic – Defaults to FinanceMessage To Send – Defaults to <xml>hello</xml>|
Users enter Neuron configuration parameters and the message to send in the column adjacent to the labels (column B).
There is an included VBScript (vba_sample_code.vbs) file that contains sample WScript code sample that demonstrates how to use the exposed Neuron ESB COM object model, including events, in scripting enabled environments. On execution the Connect() function is executed which connects to the bus using the FinancePublisher party id, sends a message and listens for any messages using the OnMessageReceive event:
Connect() Sub Connect() 'Create an instance of a subscriber and connect to ESB. 'This uses WScript.CreateObject to connect to the events. Alternatively, ' CreateObject("Neuron.ESB.Excel.Interop.Party") ' can be used, instead of the WScript.CreateObject from WScript Dim o 'Set o = CreateObject("Neuron.ESB.Excel.Interop.Party") 'WScript.ConnectObject o,"Neuron_" Set o = WScript.CreateObject("Neuron.ESB.Excel.Interop.Party","Neuron_") ' Connect to the bus o.Connect "FinancePublisher", "Enterprise", "localhost", "50000" Wscript.Sleep 200 ' Send a test message o.Send "Finance", "<xml>hi from vbscript</xml>" MsgBox "Sent Message" ' Wait to receive a message, if one is sent o.StartReceive Wscript.Sleep 15000 'Stop receiving and Disconnect from the bus o.StopReceive o.Disconnect End Sub
Below are all the events. All Defined events on the Neuron Party must be preceded with “Neuron_” to be recognized by the VBScript Parser
Sub Neuron_OnConnect(partyId, zone, server, port) MsgBox "Connected Event: " & partyId End Sub Sub Neuron_OnDisconnect(partyId) MsgBox "Disconnected Event: " & partyId End Sub Sub Neuron_OnMessageReceive(message) MsgBox "Receive Event: " & message End Sub
Neuron ESB Solution Configuration
The accompanying Neuron ESB Configuration file named, NeuronCOMSample.esb, is configured to support the Neuron ESB COM Interoperability sample described in this paper. The configuration file can be opened within the Neuron ESB Explorer. Within it are the following elements:
There is one Topic (Finance) that has been configured to support publishing the original request message to the bus, as well as routing messages to one or more subscribers.
Neuron ESB Parties are used to communicate to, and receive messages from the Neuron ESB Publishing Services. Every Topic represents an instance of a Neuron ESB Publishing Service. What messages a Neuron ESB Party is allowed to send, and what messages they can receive is determined by what subscriptions are assigned to them. Subscriptions are generally defined by using Topics with the optional addition of Message Patterns.
Neuron ESB Parties can be defined as either a Publisher, Subscriber or both. How they are defined is a function of the Topic subscription rights assigned to them, Send, Receive or both.
To support this sample, the following Publisher is configured under the Messaging:Topics:Publishers section of the Neuron ESB Explorer:
Name: FinancePublisher Subscriptions: Finance Send/Receive
The following Subscriber is configured under the Messaging:Topics:Subscribers section of the Neuron ESB Explorer:
Name: FinanceSubscriber Subscriptions: Finance Send/Receive
Running the Sample
Open the Sample
To open this sample, see the topic Using the Neuron Samples and select the COM Interop to ESB using Excel sample.
- Navigate to the NeuronCOM folder located under the \Neuron ESB v3\Samples\Scenarios directory tree.
Before running this sample, follow these instructions:
- In the Visual Studio project that opens, add a reference to Neuron.Esb.dll and build the solution in release mode.
- Open a Visual Studio command prompt as administrator. Change the folder location to the NeuronCOM directory (<Program Files>\Neudesic\Neuron ESB v3\Samples\Scenarios\NeuronCOM). Run the regcom.bat batch file. This file may have to be edited to reflect the proper location of the Neuron.Excel.Interop assemblies and type libraries if the project was moved.
- Open the Microsoft Excel Workbook, Neuron.Excel.Interop.xlsm. If Macros are not enabled, enable them.
- The Samples Launcher opens 1 Neuron Test Client. Connect one client to the FinanceSubscriber party. Navigate to the Receive tab.
Run the Sample
- From the Excel Workbook, click on the Connect button located on Sheet1. This should display the following message box on success:
- From the Excel Workbook, click the Send Multicast button located on Sheet1. This will publish the hello message to the bus
- Navigate to the open/connected Test Client. The message, <xml>hello</xml>, should be displayed in the Receive tabs Message field indicating that the message was successfully published from Excel and received by the test client.
- Navigate back to the Excel Workbook and click the Start Receive button located on Sheet1. This will activate the OnMessageReceive event for the workbook.
- Navigate to the Test Clients Send tab. Ensure that the Semantic drop down at the bottom of the client is set to Multicast. Type any message text into the Message field and click the Send button located at the lower left hand corner of the Test Client, 3 times.
- Navigate to the Excel Workbook. You should see the message repeated down 3 cells, starting at B15
- Navigate to the vbs_sample_code.vbs VBScript in <Program Files>\Neudesic\Neuron ESB v3\Samples\Scenarios\NeuronCOM and execute it by double clicking on it. Two message boxes should be displayed indicating a successful connection and that a message was sent.
- Navigate to the open/connected Test Client. The message, <xml>hi from vbscript</xml>, should be displayed in the Receive tabs Message field indicating that the message was successfully published from Excel and received by the test client.
- Navigate to the Test Clients Send tab. Ensure that the Semantic drop down at the bottom of the client is set to Multicast. Type any message text into the Message field and click the Send button located at the lower left hand corner of the Test Client.
- A message box with the text of the Message sent should appear from the running vbscript.