Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

DotNet Connector User Guide

Standard

Overview

The .NET connector lets you execute native .NET code in a Mule ESB application. Supported scenarios include: executing code in an existing binary assembly (DLL) without modification, or new development of .NET code that extends the capability of your integration application.

This connector executes .NET code using the Java Native Interface (JNI), which provides fast interprocess communication between the Java Virtual Machine (JVM) and a native application running in a host operating system.

01ConnectorDotNET

The .NET connector uses JNI to invoke a .NET component running in the Microsoft Common Language Runtime (CLR). The message in a running Mule flow passes between the JVM and the CLR to invoke a .NET method in an existing class.

The connector uses the following strategies to marshall Mule messages between the JVM and the CLR, which mainly depend on the content type associated with the message payload:

  • Primitive types and Java classes are serialized as JSON.

  • JSON or XML data pass directly as strings without data conversion.

  • Binary data passes directly as a byte array without data conversion. 

Invoking Methods Under the Hood

The DotNet connector invokes an instance or static method in an existing class as long as it is public. The properties of the Mule message map to the expected arguments in the .NET method according to name and data type.

The following flow demonstrates how the connector performs mapping:

demoflow

The Set Payload transformer generates the JSON content and sets it as the payload of the Mule message:

Setpayload

For example, for the URL  http://localhost:8081/?name=foo&age=10, the Mule message’s payload is set to: {"name":"foo", "age":10}

The JSON representation contains properties for name and age, which automatically map (by name) to the arguments of the .NET method ExecuteSimple:

public+object

Specify the name of the .NET method you want to invoke:

DOTNET+Method

Advanced Scenarios for Argument Mappings

Mapping with Attributes

The Mule message is the data that passes through an application via one or more flows. The message consists of two main parts:

  • Message header, which contains metadata about the message

  • Message payload, which contains business-specific data

MessageObject

On the .NET side, you can use attributes to indicate from where to map the parameters:

Attribute Uses the

MessagePart.FromQuery

Query strings collection

MessagePart.FromBody

Mule message’s payload

MessagePart.FromInboundProperty

Inbound property collection

MessagePart.FromInvocationProperty

Invocation property collection

MessagePart.FromOutboundProperty

Outbound property collection

MessagePart.FromSessionProperty

Session property collection

These attributes are not mandatory. If no attribute is specified, the .NET connector uses the Mule message’s payload (MessagePart.FromBody). You can combine attributes for more flexibility.

The following is an example of a method using a combination of attributes:

public+object+execute+complex

Method arguments:

  • person: Mapped from the Mule message’s payload, which contains a JSON representation of the type Person

  • id: Mapped from the query string named “id”, such as, http://localhost:8081/?id=1

  • increment: Mapped from the inbound property named “increment”

Mapping XML Data

The DotNet connector automatically maps XML data to an XML document. The connector passes XML data directly as a string without performing serialization. If the invoking .NET method contains an argument of type XmlDocument, then the XML data loads into an XmlDocument and passes to the method.

The following shows a flow that passes XML data to the .NET Connector:

xml+data+tp+dotnet+connector

The .NET connector is configured to invoke the ExecuteXml method. The following shows the method’s signature:

public+object+execute+xml

Note: If the message source in your Mule flow does not set the Content-Type to text/xml, then you must set this manually. If not set, your message is treated as a string and passed to .NET in escaped form. To manually set the Content-Type, add a Property Transformer with the following settings:

set+property-1

Mapping JSON Data

The DotNet connector serializes primitive types and POJOs as JSON. The properties of the JSON data structure are automatically mapped by name to the .NET method arguments.

Executing .NET Code in Full Trust

NET code can be executed in an application domain with restricted privileges to avoid the execution of malware code that can affect the stability of the ESB. These restrictions include limited access to the file system, native code execution, network calls, or registry access to name a few.  

By default the .NET connector is set to use full trust. You can disable it by using the fullTrust attribute shown in the image below:

full+trust

Execution Scope

The DotNet connector supports these scopes:

  • Singleton: Shares the same instance of the .NET component across multiple calls. This is useful for storing a shared state in class instance members across different calls.

  • Transient: Creates a new instance of the .NET component per request.

Use the following scope attribute to set a .NET component’s scope:

execute+scope

Hot Swapping and Deployment

The connector supports deploying a new version of the assembly containing the .NET component without needing to restart the application in the Mule ESB.

When the .NET component executes for first time by the router, a file watcher starts to detect changes in the folder where the assembly with the component deploys. If the component detects a change or a new assembly deploys, the router starts using this new version for successive calls.

Packaged Assemblies

For packaged assemblies, the deployment strategy is a bit different. Replace the existing .NET assembly located under the folder AnypointStudio/.mule/apps/[applicationName]/classes with the new version. Use the new assembly version after redeploying the application in Mule.

Log the following message:

NET assembly location:
[path to Anypoint Studio]/.mule/apps/[applicationName]/classes/[assembly name]

Use this path to deploy the new .NET assembly.

External Assemblies

Replace the old .NET assembly located in the external location with the new one.

Assembly Configuration

For .NET assemblies that you reference from within a Mule flow, you can access configuration settings defined in .NET configuration files using the standard System.Configuration classes such as ConfigurationManager. The naming of configuration files for assemblies follows the convention for class libraries, where the name is in the form: [AssemblyName].dll.config.

If you use a configuration file for your assembly, add the configuration file to the resources folder for the Mule application (src/main/resources). This is the same location to which you deploy the assembly itself if you choose the package deployment model. When referencing an assembly hosted in the Global Assembly Cache (GAC), Mule also checks the resources directory for a matching assembly configuration file: 

transform+dll+config

If you are using an assembly reference path that is external to the Mule application, then locate your assembly configuration file in the same directory as the assembly. 

To reload a configuration:

  • Touch the Mule application .xml file, which causes a hot-reload of the application by the ESB server (you can touch a Windows file using the copy filename+,, command, which updates the last write time on a file).

  • Touch the assembly to which the assembly configuration file belongs. This causes the application domain to reload along with the new configuration.

Advanced Integration Concepts

Assembly References

The .NET connector supports the following deployment types:

  • Package: An assembly embedded as an application resource. Add the assembly as an application resource by copying it to the src/main/resources folder under the application directory:

    assembly+reference

    Specify the assembly’s partial name [Namespace.ClassName], [Assembly] and the name of the assembly as the Assembly Path.

    13

  • External : You can reference an external assembly. Specify the Assembly partial name [Namespace.ClassName], [Assembly] and the absolute path to the external assembly as the Assembly Path.

    14

  • GAC : Assembly installed in the GAC (Global Assembly Cache). To reference an assembly installed in the GAC, use the Assembly Fully Qualified Name: [Assembly], [Version], [Culture], [PublicKey]. For more information, see: http://msdn.microsoft.com/en-us/library/dkkx7f79(v=vs.110).aspx

    dotnet+screenshot

See Also