.NETCompute node
Use the .NETCompute node on Windows integration nodes to construct output messages and interact with Microsoft .NET Framework (.NET) or Component Object Model (COM) applications.
- Developer
- Application Integration Suite
- Standard
- Advanced
- Express
- Scale
- Adapter
This topic contains the following sections:
Purpose
The output messages that you create in the .NETCompute node can be created by modifying the information that is provided in the input message, or by using information that can be taken from other sources, such as .NET or COM applications. Elements of the input message (for example, headers, header fields, and body data), and its associated Environment, LocalEnvironment, and ExceptionList, can be used to create the output message.
The .NETCompute node uses any Common Language Runtime (CLR) compliant language to create or modify the message, such as C#, Visual Basic (VB), F#, and C++/CLI (Common Language Infrastructure).
Use the .NETCompute node to complete the following tasks:
- Build messages.
- Interact with .NET or COM applications.
- Transform messages from one format to another.
- Copy messages between parsers.
- Use a .NET programming language to examine an incoming message and, depending on the message content, propagate it unchanged to one of the .NETCompute node output terminals. The node behaves in a similar way to a Filter node, but uses .NET languages instead of ESQL to determine which output terminal to use.
- Use .NET to change part of an incoming message and propagate the changed message to one of the output terminals.
- Use .NET to create and build an output message that is independent of the input message.
The .NETCompute node is contained in the .NET drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:
The .NETCompute node runs only on Windows integration nodes. An error occurs if you attempt to deploy a message flow that contains a .NETCompute node to an integration node that is running on a non-Windows system. Ensure that the integration node is running on Windows before you deploy your message flow.
.NET configuration files, which can be used in your .NETCompute node, are supported in the IBM Integration Toolkit.
Using this node in a message flow
The .NETCompute node can be used in any message flow that is deployed to an integration node that is running on Windows. The .NETCompute node is often used in a scenario where the message that is built is required to interact with other .NET applications to store data from the message, or retrieve data to augment the message.
Only one instance of a given .NETCompute node is created, regardless of the number of threads that are running against the message flow. Either as a result of additional instances, or multiple input nodes. Therefore, all of your user .NET code must be thread-safe and reentrant. For more information about making a node thread-safe and ensuring that the functions implemented and started by user-defined extensions are reentrant, see User-defined extensions execution model and Threading considerations for user-defined extensions.
Updates that are made using the .NET languages do not participate in IBM Integration Bus transactions.
The .NETCompute node must be configured with a .NET assembly that contains the code of the node. The code consists of a class that is derived from the abstract NBComputeNode class that is provided in the IBM.Broker.Plugin.dll assembly.
Using an existing .NET assembly
If the assembly is provided as a compiled .dll file from a vendor or other third party, you must choose the assembly by using the Browse option that is provided for the Assembly Name .NETCompute node property. Alternatively, you can drag the assembly directly onto the node. If you are not provided with an assembly, you must create a node assembly.
Creating a .NET assembly
The integration node can integrate with Microsoft Visual Studio 2010 or 2012 to create a .NET assembly that represents the node. To start Microsoft Visual Studio directly from the node, ensure that Microsoft Visual Studio 2010 or 2012 is installed, and double-click the .NETCompute node. Alternatively, right-click the node and select Open Microsoft Visual Studio. If a Microsoft Visual Studio project or solution name is provided on the Visual Studio panel, the project or solution automatically loads when Microsoft Visual Studio is opened.
From within Microsoft Visual Studio, select New Project. You can then select an Integration Bus project, which is located underneath your language of choice, for example; Visual Basic.
- Create an IBM Integration message
- Filter an IBM Integration message
- Modify an IBM Integration message
The project generates skeleton code that matches the selected type. This skeleton code then displays in the corresponding .NET language editor, for example; Visual Basic.
The NBComputeNode class
contains a method that must be overridden, and two optional additional
methods that you can choose to override if necessary. The Evaluate() method
must always be overridden and is automatically implemented by the Message
Broker Project template, if the template is used to generate
the skeleton code. The optional methods are OnInitialize() and OnDelete().
If you want the node to perform any initialization or cleanup operations,
provide an implementation of one or both of these methods.
The OnDelete() method
is called by the integration node immediately before the method deletes
the node. The OnInitialize() method is called by
the broker when the node is constructed, after the node attributes
are set. The OnInitialize() method is called during
deployment, but before the deployment is committed. Downstream nodes
can still throw exceptions during initialization, causing the deployment
to fail. For this reason, any user application code that relies on
the deployed state of the message flow must be placed within the Evaluate() method.
Configuring the .NETCompute node
When you put an instance of the .NETCompute node into a message flow, you must configure it; see Configuring a message flow node. To configure the node, you can drag an assembly file from a file explorer to the node. The properties of the node are displayed in the Properties view.
All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.
Specifying .NET code
You can code statements to customize the behavior of the .NETCompute node by using the Microsoft Visual Studio Integration Bus Compute Node project code skeletons as a template. For example, you can customize the node to create an output message, or a number of messages, by using an input message or data from an external source. A particular scenario might be that you want to modify a value from the input message, which you can do by adding one or more values that are obtained from the .NET interface of an external application and storing the result in the output message.
To debug a .NETCompute node that is running inside the integration server, place the .pdb file for the assembly that implements the node in the same directory as the assembly for the node, and attach Microsoft Visual Studio to the DataFlowEngine.exe process. You can then place breakpoints in your code and examine variables, for example; when the breakpoint is hit.
For more information about creating .NET code for a .NETCompute node, you can access the .NET API documentation included with your installation of IBM Integration Bus from the Start Menu location in Windows.
Validating messages
Set the validation properties to define how the message that is produced by the .NETCompute node is to be validated. These properties do not cause the input message to be validated. It is expected that if such validation is required, the input node or a preceding validation node has already performed validation.
For more information, see Validating messages and Validation properties.
Terminals and properties
The .NETCompute node terminals are described in the following table.
| Terminal | Type | Description |
|---|---|---|
| In | Input data | The input terminal that takes data from a remote source. |
| Out | Output data | The output terminal that sends data to a downstream node. |
| Failure | Output data | The output terminal to which the input message is routed if an unhandled exception occurs during the computation. |
| * (dynamic) | Output data | Zero or more dynamic output terminals can be created to support message routing. |
You can define additional dynamic output terminals on the .NETCompute node.
The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file for deployment).
The .NETCompute node Description properties are described in the following table.
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Node name | No | No | The node type | The name of the node. |
| Short description | No | No | A brief description of the node. | |
| Long description | No | No | Text that describes the purpose of the node in the message flow. |
The .NETCompute node Basic properties are described in the following table.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| Assembly name | Yes | Yes | The assembly that implements the node. Use the Browse option to select an assembly, alternatively you can drop an assembly .dll file onto the node to automatically complete this property. | AssemblyName | |
| Class name | No | Yes | The name of the class that implements the node. A value for this property is required only if two or more nodes are exposed from the same assembly, or to explicitly name a subclass as the implementing node. | AssemblyNodeClassName |
The Microsoft Visual Studio properties for the .NETCompute node are described in the following table.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| Visual Studio project name | No | No | The Microsoft Visual Studio project or solution that contains the code for the node. |
The .NETCompute node Advanced properties are described in the following table.
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| AppDomain name | No | Yes | The .NET AppDomain that hosts the node. Note: If
a DotNetAppDomain configurable service is defined with the
same name as the AppDomain name, the configurable service
properties take precedence when the assembly is loaded.
For more information, see DotNetAppDomain configurable service.
|
AppDomain | |
| Version | No | Yes | The Assembly Version. | AssemblyVersion | |
| Culture | No | Yes | The Assembly Culture. | AssemblyCulture | |
| Public key token | No | Yes | The Assembly Public Key Token. | AssemblyPublicKeyToken |
The Validation properties of the .NETCompute node are described in the following table.
For a full description of these properties, see Validation properties.| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| Validate | No | Yes | None | This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. | validateMaster |
| Failure action | No | No | Exception | This property controls what happens if a validation failure occurs. You can set this property only if Validate is set to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List. |
| Property | M | C | Default | Description |
|---|---|---|---|---|
| Events | No | No | None | Events that you have defined for the node are
displayed on this tab. By default, no monitoring events are defined
on any node in a message flow. Use Add, Edit,
and Delete to create, change or delete monitoring
events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |
| Property | M | C | Default | Description | mqsiapplybaroverride command property |
|---|---|---|---|---|---|
| <User provided name> | No | No | The node provides a table in which the user can Add, Edit, or Delete rows each providing a Name: Value pair. |