DotNet Connector User Guide



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.


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:


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


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:


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


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


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

Attribute Uses the


Query strings collection


Mule message’s payload


Inbound property collection


Invocation property collection


Outbound property collection


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:


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:


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


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:


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:


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:


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:


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:


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

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

  • 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:


See Also