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:

Difference in Generated Artifacts

When you feed a MATLAB function or class to the compiler.build.dotNETAssembly function or the .NET Assembly Compiler, 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
    
    % Calculate 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.

% .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;