Main Content

Type-Safe Interfaces

MATLAB® data types are incompatible with native .NET types. To send data between your application and .NET, you perform these tasks:

  1. Marshal data from .NET input data to a deployed function by creating an MWArray object from native .NET data. The public functions in a deployed component return MWArray objects.

  2. Marshal the output MATLAB data in an MWArray into native .NET data by calling one of the MWArray marshaling methods (ToArray(), for example).

While you can marshal the data manually using MWArray data types, using a type-safe interface simplifies the process.

Manual Data Marshaling Without a Type-Safe Interface

Manually marshaling data adds complexity and potential failure points to the task of integrating deployed components into a .NET application. This is particularly true for these reasons:

  • Your application cannot detect type mismatch errors until run time. For example, you might accidentally create an MWArray from a string and pass the array to a deployed function that expects a number. Because the wrapper code generated by MATLAB Compiler SDK™ expects an MWArray, the .NET compiler is unable to detect this error and the deployed function either throws an exception or returns the wrong answer.

  • Your end users must learn how to use the MWArray data type or alternately mask the MWArray data type behind a manually written (and manually maintained) API. This introduces unwanted training time and places resource demands on a potentially overcommitted staff.

Data Marshaling Without a Type-Safe Interface

A flowchart that depicts .NET data that passes through the MATLAB data constructor to become MATLAB MWArray data, which passes through a wrapper function layer to the MATLAB function. The function outputs MWArray data that passes back through the wrapper function layer and is then converted from MATLAB data to .NET data.

You may find MWArray methods more efficient when passing large data values in loops to one or more deployed functions. In such cases, creating an MWArray object allows you to marshal the data only once, whereas type-safe interfaces marshal inputs on every call.

Simplified Data Marshaling with a Type-Safe Interface

You can avoid performing MWArray data marshaling by using type-safe interfaces. Such interfaces minimize explicit type conversions by hiding the MWArray type from the calling application. Using type-safe interfaces allows .NET developers to work directly with familiar native data types.

Data Marshaling With a Type-Safe Interface

A flowchart that depicts user visible .NET data that passes through a wrapper function layer, which transforms it into the encapsulated MATLAB MWArray data, then passes it to the MATLAB function. The function outputs MWArray data that passes back through the wrapper function layer to become .NET data.

Some of the reasons to implement type-safe interfaces include:

  • You avoid training and coding costs associated with teaching end users to work with the MWArray API.

  • You minimize cost of data you must marshal by either placing MWArray objects in type-safe interfaces or by calling MWArray functions in the deployed MATLAB code.

  • Flexibility — you mix type-safe interfaces with manual data marshaling to accommodate data of varying sizes and access patterns. For example, you may have a few large data objects (images, for example) that would incur excess cost to your organization if managed with a type-safe interface. By mixing type-safe interfaces and manual marshaling, smaller data types can be managed automatically with the type-safe interface and your large data can be managed on an as-needed basis.

For an example on implementing type-safe interfaces, see Implement Type-Safe Interface and Integrate into .NET Application.

How Type-Safe Interfaces Work

Every MATLAB Compiler SDK .NET assembly exports one or more public methods that accept and return data using MWArray objects. Adding a type-safe interface to a MATLAB Compiler SDK assembly creates another set of methods (with the same names) that accept and return native .NET types.

You may create multiple type-safe interface methods for a single MATLAB function. Type-safe interface methods follow the standard .NET methods for overloading.

The following figure illustrates the data paths between the .NET host application and the deployed MATLAB function through a type-safe interface.

Architecture of a deployed component with a type-safe interface

The MATLAB function addOne returns its input plus one. Deploying addOne with a type-safe interface creates two .NET addOne methods:

  • One that accepts and returns .NET double

  • One that accepts and returns MWArray

Notice that the type-safe methods co-exist with the MWArray methods. Your .NET application may mix and match calls to either type of method, as appropriate.

Related Topics