Choosing .NET Deployment Option

MATLAB^® Compiler SDK™ provides two ways to deploy MATLAB functions within .NET applications:

Deploy to .NET Applications using MATLAB Data API for .NET (since R2022b)
Deploy to .NET Applications using MWArray API

Since MATLAB Compiler SDK provides two .NET application APIs to interact with deployed MATLAB functions, the two deployment options are distinguished based on the APIs used for exchanging data between the .NET application and the deployed MATLAB functions.

Choosing a .NET deployment option comes down to understanding the capabilities of each option and recognizing how those capabilities line up with your development requirements. Both options provide a comprehensive set of APIs for handling both application management and data manipulation.

Advantages of MATLAB Data API for .NET Over `MWArray` API

MathWorks^® recommends deploying to .NET applications using the more modern MATLAB Data API for .NET over the MWArray API. The advantages of using the MATLAB Data API for .NET over the MWArray API are:

You can program with native .NET types by specifying a mapping between C# and MATLAB data types using arguments blocks with type information within MATLAB code. This eliminates the need to manage MATLAB data types in C#.
The MATLAB Runtime instance can run either in-process or out-of-process with respect to the .NET application, and deployed MATLAB functions can be executed either synchronously or asynchronously.
Thread-safe design facilitates concurrent data creation and consumption across multiple threads without the need for locking. This leads to improved performance, particularly when there's extensive manipulation of MATLAB data in multiple threads.
MATLAB class methods are now exposed, enabling direct invocations on the class object.
Transitioning between .NET based MATLAB Engine applications and deployed MATLAB applications can now be accomplished with minimal effort.
Support for cross-platform development and deployment. Since R2023a, .NET applications with packaged MATLAB code can be developed and published across Windows^®, Linux^®, and macOS platforms. This means it's possible to develop on any one of these platforms and publish to any of the other two.

Difference in Generated Artifacts

When you feed a MATLAB function or class to the compiler.build.dotNETAssembly function or the Library Compiler app, the main products generated are different for the two deployment options.

Assuming you have a MATLAB function called calculateDistance stored in a file named calculateDistance.m, and you aim to deploy it into a .NET application, let's examine the resulting outcomes of the two deployment alternatives:

function distance = calculateDistance(p1, p2)
    % This function calculates the Euclidean distance between two points
    % Inputs:
    %   p1 - a two-element vector [x, y]
    %   p2 - a two-element vector [x, y]
    % Output:
    %   distance - the Euclidean distance between p1 and p2
    
    % Use arguments block to map C# type to corresponding MATLAB type
    % Int64 [] <--> (1,2) int64 {mustBeReal}
    
    arguments (Input)
        p1 (1,2) int64 {mustBeReal}
        p2 (1,2) int64 {mustBeReal}
    end

    arguments (Output)
        distance (1,1) int64 {mustBeReal}
    end
    
    % Calculte Euclidean distance
    diff = p1 - p2;
    diffSq = diff.^2;
    sumSq = sum(diffSq);
    distance = sqrt(sumSq);
end

When you feed the calculateDistance.m file into the compiler.build.dotNETAssembly function, the MWArray API is the default choice. To use the MATLAB Data API, you need to explicitly specify the interface type using the name-value pair Interface="matlab-data".

buildResults = compiler.build.dotNETAssembly( ...
    "calculateDistance.m",...
    Verbose="on", OutputDir=".\output_mwa", ...
    AssemblyName="CalculateDistance")

buildResults = compiler.build.dotNETAssembly( ...
    "calculateDistance.m", Interface="matlab-data",...
    Verbose="on", OutputDir=".\output_mda", ...
    AssemblyName="CalculateDistance")

The function generates corresponding files for the two APIs in the specified folder:

P:\MATLAB\WORK\OUTPUT_MWA
    CalculateDistance.dll
    CalculateDistance.xml
    calculateDistanceClass.cs
    calculateDistanceClassNative.cs
    CalculateDistanceNative.dll
    CalculateDistanceNative.xml
    CalculateDistanceVersion.cs
    CalculateDistance_overview.html
    GettingStarted.html
    includedSupportPackages.txt
    mccExcludedFiles.log
    readme.txt
    requiredMCRProducts.txt
    unresolvedSymbols.txt

No subfolders exist

P:\MATLAB\WORK\OUTPUT_MDA
│   CalculateDistance.csproj
│   CalculateDistance.ctf
│   CalculateDistance.deps.json
│   CalculateDistance.dll
│   GettingStarted.html
│   includedSupportPackages.txt
│   mccExcludedFiles.log
│   readme.txt
│   requiredMCRProducts.txt
│   unresolvedSymbols.txt
│
└───strongly_typed_interface
        calculateDistance.cs

In the MWArray API case, two sets of artifacts are generated. The first set consists of a C# wrapper file and a corresponding assembly file, both utilizing MWArray classes for arguments and return values. This configuration mirrors intrinsic MATLAB data structures.

Simultaneously, compiler.build.dotNETAssembly generates a second set of corresponding artifacts that use native .NET System.Object types for method parameters and returns. This variation provides a more .NET centric perspective of the MATLAB function, replacing MWArray with standard .NET Object instances.

In the MATLAB Data API case, the compiler.build.dotNETAssembly function generates three essential components. First, it creates a code archive (.ctf file), which encapsulates the MATLAB functions to be deployed. Second, it crafts corresponding C# wrapper files that establish a mapping between MATLAB and C# input and output data types, and allow MATLAB functions to be called as .NET methods. Lastly, it generates a .NET assembly that can be used in place of the C# wrapper files.

Support for Strong Types Using MATLAB Data API

You have the option to specify a mapping between MATLAB and C# data types when you use the MATLAB Data API.

When deploying a MATLAB function, an arguments block is needed to specify type information for input and output arguments. If deploying a MATLAB class, utilize a properties block to detail the type information of class properties, and use an arguments block to provide type information for the arguments of class methods.

MATLAB Function

For example, should your C# application utilize an Int64 data type to signify input types for the MATLAB function, you can employ a MATLAB arguments block to designate the corresponding type. The resulting MATLAB code, the associated C# wrapper file, and the C# application code are as follows:

% .m file
arguments (Input)
        p1 (1,2) int64 {mustBeReal}
        p2 (1,2) int64 {mustBeReal}
    end
arguments (Output)
        distance (1,2) int64 {mustBeReal}
    end

// .cs wrapper file
   
    public static void calculateDistance(
        MATLABProvider _matlab, 
        Int64 [] p1, Int64 [] p2,  
        out Int64 distance){

// .cs application file
  
Int64[] p1 = new Int64[2] { 0, 0 };
Int64[] p2 = new Int64[2] { 3, 4 };
...

Int64 distance;

MATLAB Class

If you are deploying a MATLAB class, use a properties block and arguments block within the MATLAB class.

MATLAB data types are mapped to C# data types based on type specification in arguments and properties blocks.
MATLAB packages are mapped to C# sub-namespaces of the same name. The root namespace corresponds to the name of the assembly.
MATLAB classes are mapped to C# structs of the same name. The C# code file is generated with the following naming pattern: <MatlabPackageName>_<MatlabClassName>.cs.
Public methods of MATLAB classes map to public methods of the C# struct of the same name.
Properties of a MATLAB class are mapped to properties of the same name in the C# struct.
Limitations
In R2023b: MATLAB handle class , and functions varargin, and varargout are not supported.