Neuron COM Interoperability

Overview

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.

Solution components:

Solution

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:

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:

The Connect, Send Multicast and Send Request all require user entered parameters on the spreadsheet corresponding with their labels:

Users enter Neuron configuration parameters and the message to send in the column adjacent to the labels (column B).

VBScript/WScript Sample

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:

Neuron Topics

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 Parties

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.

1. Navigate to the NeuronCOM folder located under the \Neuron ESB v3\Samples\Scenarios directory tree.

Setup Instructions

Before running this sample, follow these instructions:

1. In the Visual Studio project that opens, add a reference to Neuron.Esb.dll and build the solution in release mode.
2. 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.

3. Open the Microsoft Excel Workbook, Neuron.Excel.Interop.xlsm. If Macros are not enabled, enable them.
4. The Samples Launcher opens 1 Neuron Test Client. Connect one client to the FinanceSubscriber party. Navigate to the Receive tab.

Run the Sample

1. From the Excel Workbook, click on the Connect button located on Sheet1. This should display the following message box on success:

2. From the Excel Workbook, click the Send Multicast button located on Sheet1. This will publish the hello message to the bus
3. 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.

4. Navigate back to the Excel Workbook and click the Start Receive button located on Sheet1. This will activate the OnMessageReceive event for the workbook.
5. 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.
6. Navigate to the Excel Workbook. You should see the message repeated down 3 cells, starting at B15

7. 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.

8. 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.
9. 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.
10. A message box with the text of the Message sent should appear from the running vbscript.