Exception Handling

Overview

This sample demonstrates how you can wrap the Neuron Process steps inside an Exception step. An Exception step is comprised of three execution blocks: Try, Catch and Finally. Encapsulating process steps inside an Exception step allows for further processing in the event of any errors. In this example the exception thrown will be compared with a known type and an attempt to fix the issue will be performed in a Code process step. If the exception is not of a known type then it will be re-thrown so that the process can abort execution.

Process Components Demonstrated:

• Exception (Try/Catch/Finally)
• Decision
• Code
• Rethrow

Solution

The Try Set Custom Property process depicted in Figure 2 has an Exception step that is used as a container for all other steps in the process. Any number of process steps can be placed in each of the execution blocks of the Exception step.

Within the Try execution block of the Exception step is a C# Code process step named Set Custom Property. This step will be used in the sample to purposely cause an error so that the Exception step can be demonstrated. The C# Code process step can be used to access the incoming message to set the value of any of the ESB Message properties as well as to set the value of custom context properties. For example, at runtime, the context.Data.Header.Topic property could be changed on the published message to redirect publication of the message to an entirely different topic.

In this example an attempt will be made to set a custom message property with a prefix of my and a name of property to the value invalid value. To demonstrate the Exception process step, an Exception of type SetPropertyPipelineException is purposely thrown.

Note: It is always recommended that custom context properties always be specified in prefix.name pairs such as my.property

Within the Catch execution block is a Decision process step with one branch named If and another named Else. All Decision process steps have at least one If and one Else branch. Other conditional evaluative branches can be added and placed after the first If branch if necessary and are identified as Else If. A code property (which displays the Code Editor) is used in all evaluative branches (If and Else If) to specify the condition by which that branch will be executed. The Else branch does not have any condition associated with it and that branch will be taken if no other branch condition evaluates to true. The evaluation order in a Decision process step is from left to right starting with the If branch.

The code associated with the If branch of the Decision process step will check the type of exception that was encountered in the Try execution block. If the type of exception is of type SetPropertyPipelineException then the process steps in the If branch will be executed. If the exception is of any other type then steps in the Else branch will be executed.

The If branch contains a Code process step named Fix Custom Property. In this step an attempt will be made to re-set the same custom property as specified in the C# Code process step named Set Custom Property within the Try execution block.

The Else branch contains an Execute Process process step named Process Exception which contains a sample Code process step and a Rethrow process step with the default name of Rethrow. The Code process step contains commented-out sample code that would enrich the exception with more details. The code in this step is shown in Figure 3. The Rethrow process step will re-throw the original exception that occurred due to the error in the Set Property process step located within the Try execution block. Re-throwing the original exception allows Neuron to abort the process normally and prevent the errant message from continuing on in the bus.

Running the Sample

Open the Sample

To open this sample, see the topic Using the Neuron Samples and select the Exception Handling sample.

Run the Sample

1. The sample launcher opens 2 Neuron Test Clients. Connect one to the TestMessagePublisher party and the other to the TestSubscriber party.
2. Select the Send tab on the TestMessagePublisher test client and make sure that the topic Test is selected in the Topic Dropdown list above the message field.
3. Enter a message in the clients Send tab message field such as <test>hello world</test> and click the Send button.
4. On the test client connected to the TestSubscriber select the Receive tab and click the View Custom Properties hyperlink located above the message field. The following dialog (Figure 4) is displayed showing the custom properties associated with the message.

Re-throw the Exception

1. Navigate to the Processes section of Neuron Explorer and select the Try Set Custom Property process in the list located in the left panel of the designer.
2. Select the If branch (mouse click on the Decision steps If branch).
3. In the property grid on the bottom right of the designer click the ellipsis button next to the (Set Condition) property. This will open the code editor show on Figure 5.

4. Alter the lines of code (outlined in red) to that shown in Figure 5 and click the Save button on the Code Editor dialog.
   
   Note: The original code is shown in Figure 9 at the end of this document for comparison.
5. Save the process by clicking the Apply toolbar button located in the upper left corner of the Process Designer panel.

6. Save the configuration file by selecting File -> Save from the menu and Restart the Neuron ESB Service using the Server Status dropdown menu item.
7. Follow steps 2-4 listed above in the Run the Sample section. Ensure that the Test topic is selected in the TestMessagePublisher test client before sending the message.
8. When the process runs this time the Decision process step sends execution down the Else branch instead of the If branch because the condition no longer evaluated to true. There is a Rethrow step in the Else branch that re-throws the exception created in the Set Properties process step. The message box shown in Figure 7 will be displayed indicating the process failed.

Configuration Notes

All processes with the exception of the Code process step are configured by selecting and setting their properties in the property grid located at the bottom right of the process designer. The Code process step is configured by selecting the Edit option from the short cut menu that is available when right-clicking the Code step in the process designer. See the process documentation for more information.

Appendix

Adding an Audit Database

1. In Neuron ESB Explorer, click on the Deployment tab, then click Databases from the left-hand navigation.
2. Click the New button.

3. In the properties for creating a new database, set the server name to your SQL Server name, set the appropriate Authentication settings, and enter SampleAuditing as the database name.

4. Click the Test/Create Database button to test the connection settings. If the database does not exist, you will receive this message:

5. Click the Yes button to create the database.

6. When the database has been successfully created, click the OK button.
7. Click the Test/Create Database button again to test the connection. This time you will receive this message:

8. Click the OK button.
9. Click on the Deployment tab, then click Deployment Groups from the left-hand navigation.
10. Select the Dev deployment from the list.
11. From the Database dropdown, select the SampleAuditing database.

12. Click the Apply button.
13. Save the configuration file by selecting File -> Save from the menu and Restart the Neuron ESB Service using the Server Status dropdown menu item.
14. Your ESB solution is now configured to use an Auditing database.