Prerequisites

Create MATLAB Function

Create a MATLAB file named calculateDistance.m with the following code:

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

Established MATLAB users may find the presence of an arguments block unconventional. The arguments block lets you represent C# data types with an equivalent MATLAB type. For instance, if your C# application employs an Int64 data type representing a value, you can now represent that in MATLAB as an int64. This option is useful in situations where a C# application has strict type requirements. For details, see Data Type Mappings Between .NET and Strongly Typed MATLAB Code.

In this example, an arguments block with specified type information is used to illuminate subtle nuances. However, remember that incorporating an arguments block is entirely optional. The deployment process remains unchanged even without it. Various parts of this example underscore the areas where this difference manifests. So, if data types aren't crucial, the specification of type information using an arguments block is not necessary.

Test the MATLAB function at the command prompt.

p1 = int64([0, 0])
p2 = int64([3 4])
distance = calculateDistance(p1,p2)

p1 =
  1×2 int64 row vector
   0   0
p2 =
  1×2 int64 row vector
   3   4
distance =
  int64
   5

Create .NET Assembly Using compiler.build.dotNETAssembly

Create a code archive (.ctf file), from the MATLAB function using the compiler.build.dotNETAssembly function.

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

Although supplying an assembly name via the AssemblyName property isn't mandatory, it's highly recommended. Doing so results in a cleaner namespace for the generated .NET assembly and C# file. In its absence, a root namespace named example is automatically appended to the sub-namespace, leading to a cluttered and potentially confusing namespace structure.

The function produces a suite of files, as enumerated below, and places them in the specified output directory. Among these, the key files utilized during the integration process are the code archive (.ctf file) containing the MATLAB code, a C# (.cs) code file, and a .NET assembly (.dll file). For information on the other files, see Files Generated After Packaging MATLAB Functions.

P:\MATLAB\WORK\OUTPUT
│   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

To finalize integration, you can choose one of two options:

Upon inspection, you notice that the function also generates a CalculateDistance.csproj project file. This file is generated specifically to create the corresponding CalculateDistance.dll .NET assembly file. However, it should not be mistaken as a template for your .NET project and must not be used in that context.

This example employs the first integration option to illustrate type mapping mechanics. Relevant guidance for using the second option is interjected at pertinent stages of the workflow.

You can inspect the content of the C# code file below:

 calculateDistance.cs

using System;
using MathWorks.MATLAB.Types;
using MathWorks.MATLAB.Exceptions;
namespace CalculateDistance
{
    public static partial class MATLABFunctions
    {
        public static void calculateDistance(
            MATLABProvider _matlab, Int64[] p1, Int64[] p2)
        {
            dynamic _dynMatlab = _matlab;
            _dynMatlab.calculateDistance(new RunOptions(nargout: 0), p1, p2);
        }
        public static void calculateDistance(
            MATLABProvider _matlab, Int64[] p1, Int64[] p2, out Int64 distance)
        {
            dynamic _dynMatlab = _matlab;
            distance = (Int64)_dynMatlab.calculateDistance(
                new RunOptions(nargout: 1), p1, p2);
        }
    }
}

In the calculateDistance.cs C# code file, the MATLAB function's int64 argument specification mirrors its C# equivalent, Int64.

    arguments (Input)
        p1 (1,2) int64 {mustBeReal}
        p2 (1,2) int64 {mustBeReal}
    end

   
Int64[] p1, 
Int64[] p2 )

    arguments (Output)
        distance (1,1) int64 {mustBeReal}
    end

public static void calculateDistance(
            MATLABProvider _matlab, Int64[] p1, Int64[] p2, out Int64 distance)
        {
            dynamic _dynMatlab = _matlab;
            distance = (Int64)_dynMatlab.calculateDistance(
                new RunOptions(nargout: 1), p1, p2);
        }

When an arguments block detailing type information is not included in your MATLAB function, it results in the production of the following C# code file:

 calculateDistance.cs (Type Agnostic)

using System;
using MathWorks.MATLAB.Types;
using MathWorks.MATLAB.Exceptions;
namespace CalculateDistance
{
    public static partial class MATLABFunctions
    {
        public static void calculateDistance(
            MATLABProvider _matlab, dynamic p1, dynamic p2)
        {
            dynamic _dynMatlab = _matlab;
            _dynMatlab.calculateDistance(new RunOptions(nargout: 0), p1, p2);
        }
        public static void calculateDistance(
            MATLABProvider _matlab, dynamic p1, dynamic p2, out dynamic distance)
        {
            dynamic _dynMatlab = _matlab;
            distance = (MATLABArray)_dynMatlab.calculateDistance(
                new RunOptions(nargout: 1), p1, p2);
        }
    }
}

The primary difference between the C# code files rests in the type specification for input and output variables. When an arguments block is used with type information specified, the inputs and outputs are categorized as Int64. Conversely, when an arguments block with type information is absent:

The process of specifying input and output types often involves a considerable amount of referencing and educated guessing. Consequently, employing an arguments block containing type information can eliminate this ambiguity, thereby streamlining the development of C# applications that incorporate packaged MATLAB functions.

Integrate MATLAB Code into .NET Application

You can finalize the integration process in your preferred C# development environment, including a text editor along with the .NET SDK Command Line API, or alternatives such as Microsoft Visual Studio on Windows and macOS. This example shows you how to complete the integration using both options. For details, see Set Up .NET Development Environment.

!dotnet run

Euclidean distance between [0, 0] and [3, 4] is: 5

Publish to Linux and macOS

To publish to a specific platform, use the appropriate Runtime Identifier (RID). For details, see https://learn.microsoft.com/en-us/dotnet/core/rid-catalog.

Run Published Application on Linux

Follow similar steps to run the application on macOS.