Package MATLAB Function Using .NET Assembly Compiler App

Supported platforms: Windows^®

This example shows how to use the .NET Assembly Compiler app to package MATLAB^® functions into a .NET assembly. The provided .NET application demonstrates passing matrices between the MATLAB functions and the .NET application using the MATLAB Data API.

Before R2025a: Create a .NET assembly using the Library Compiler as shown in Generate .NET Assembly and Build .NET Application (R2024b).

Prerequisites

• Verify that you have a .NET compiler that is compatible with MATLAB Compiler SDK™. For details, see MATLAB Compiler SDK .NET Target Requirements.

• End users must have an installation of MATLAB Runtime to run the application. For details, see Download and Install MATLAB Runtime.

  For testing purposes, you can use an installation of MATLAB instead of MATLAB Runtime.

Create MATLAB Functions

In MATLAB, examine the MATLAB code that you want to package. For this example, create a MATLAB function named magicsquare.m in a new folder named MagicProject.

function y = magicsquare(x)
y = magic(x);

At the MATLAB command prompt, enter magicsquare(5).

The output is a 5-by-5 matrix.

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

Create Project and Compiler Task

Create a compiler task for your .NET assembly using the .NET Assembly Compiler. Compiler tasks allow you to compile files in a project for a specific deployment target.

To open the app, on the Apps tab, expand the Apps gallery. In the Application Deployment section, click .NET Assembly Compiler.

You can also open the app using the dotNetAssemblyCompiler function at the MATLAB Command Window.

After you open the app, the Create Compiler Task dialog box prompts you to add a task to a new or an existing MATLAB project. For this example, select Start a new project and create a compiler task and create a new project named MagicProject in the MagicProject folder. For more information on creating and using MATLAB projects, see Create Projects.

A new compiler task named DotNETAssembly1 opens in the Editor.

You can create more .NET compiler tasks or package code for other deployment targets by opening the Compiler Task Manager or going to the Manage Tasks tab and creating a new compiler task.

Specify Build Options

You can specify options for the .NET assembly and its installer before packaging to customize the building and packaging process. For instance, you can obfuscate the MATLAB code or specify the method of including MATLAB Runtime in the generated installer.

Add the MATLAB function to the .NET assembly. All files must be located in the project root folder to be added to the project. For this example, in the Exported Functions section of the compiler task, click Add Exported Function and select magicsquare.m. In the Project panel, the file now has the labels Design and Exported Function File.

In the .NET Assembly Info section, replace the string MyDotNetAssembly with the name for your .NET assembly, magicsquarelib.

To choose a different output location for the generated files, update the paths in the Output Locations section.

In the .NET API Selection section, choose the API to use for exchanging data between the .NET application and the MATLAB functions. For this example, select the MATLAB Data API. For more information, see Choose .NET Deployment Option.

Create Sample Code (Optional)

MATLAB Compiler SDK can generate sample .NET code that demonstrates how to call your MATLAB exported function. You can use samples to implement your own application or to test the compiled artifact. If you write your own .NET application code, you can move it to the appropriate directory after the MATLAB functions are packaged. For more information, see Create Sample Code to Call Exported Function.

To create a sample MATLAB file, click Create new sample in the Samples section. Select the file magicsquare.m. A MATLAB live script opens for you to edit. Under Edit Sample Inputs, enter the value 5 and save the file. The file sampleFiles\magicsquareSample1.mlx is added to the Samples section of the task.

View Code and Package .NET Assembly

To view code that contains instructions on building and packaging your component, click the arrow next to Export Build Script and select Show Code. On the right, a window displays a deployment script with the compiler.build.dotNETAssembly and compiler.package.installer functions that corresponds to your build options. You can convert this code to a MATLAB script file by clicking the Export Build Script button. Running the generated build script is equivalent to clicking the Build and Package button.

To create the .NET assembly and an installer, click Build and Package. To create only the .NET assembly, click the arrow next to Build and Package and select Build.

The compiler generates files in the <compiler_task_name>/output folder in your project folder. The key files utilized during the integration process are the code archive (.ctf file) containing the MATLAB code. For information on the other files, see Files Generated After Packaging MATLAB Functions.

If you created an installer, the package subfolder contains the installer for your shared library files along with MATLAB Runtime.

Caution

The generated installer does not include a .NET application executable. You must compile your .NET application after packaging. Then, manually distribute the application file along with MATLAB Runtime or include the executable in an installer using the AdditionalFiles option of compiler.package.installer. For more information, see Distribute MATLAB Compiler SDK Files to Application Developers.

Integrate MATLAB Code Archive into .NET Application

After creating the .NET assembly, write source code for a .NET application in your preferred .NET development environment. For details, see Set Up .NET Development Environment.

If you created sample code before packaging, MATLAB Compiler SDK generates a sample C# .NET application named magicsquareSample1.cs in the samples folder.

 magicsquareSample1.cs

using System;

using MathWorks.MATLAB.Runtime;
using MathWorks.MATLAB.Types;

/// <summary>
/// Sample driver code that integrates a compiled MATLAB function
/// generated by MATLAB Compiler SDK.
///
/// Refer to the MATLAB Compiler SDK documentation for more
/// information.
/// </summary>
class magicsquareSample1 {
    /// <summary>
    /// Example of using the magicsquare function.
    /// </summary>
    public static int magicsquareSample(Object args) {
        string ctfPathLocation = @"magicsquarelib.ctf";
        using (dynamic matlab = MATLABRuntime.StartMATLAB(ctfPathLocation)) {
            double xIn = 5.0;
            var yOut = (double[,])matlab.magicsquare(new RunOptions(nargout: 1), xIn);
        }
        return 0;
    }

    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    static void Main(string[] args) {
        try {
            // If being run on Mac a call to SetupMacRunLoopAndRun is
            // required, if run on Windows magicsquareSample can be
            // called directly
            magicsquareSample(null);
            //MATLABRuntime.SetupMacRunLoopAndRun(magicsquareSample, null);
        } catch (Exception e) {
            Console.WriteLine(e);
            Environment.Exit(1);
        }
    }
}

The matrix application performs these actions:

• Uses a try-catch block to handle exceptions.

• Creates an MWNumericArray array to store the input data.

• Instantiates the Class1 object results.

• Calls the magicsquare method, where the first parameter specifies the number of output arguments and the subsequent parameters are passed to the function in order as input arguments.

• Writes the function output to the console.

After you write source code, build and run your .NET application.

At the system command prompt, navigate to your project folder and create a .NET project file using the dotnet command.

dotnet new console --name magicsquarelib

This command creates a folder named magicsquarelib that contains:

• obj folder

• magicsquarelib.csproj project file

• Program.cs C# source file, which you should replace with magicsquareSample1.cs

Copy and paste the generated code archive magicsquarelib.ctf from the output folder and the sample application magicsquareSample1.cs from the samples folder into the new magicsquarelib folder that contains your .NET project.

Delete the Program.cs file.

Open the project file magicsquarelib.csproj in a text editor and include these assemblies using a <Reference> tag within the <ItemGroup> tag of the project:

• MathWorks.MATLAB.Runtime.dll

• MathWorks.MATLAB.Types.dll

Add the magicsquarelib.ctf code archive file as a content file within the <ItemGroup> tag.

Add the tag CopyToPublishDirectory and set it to Always. This step ensures that the magicsquarelib.ctf file is copied to the cross-platform folder to which this project is published.

After you add the references, your project file resembles this file.

 magicsquarelib.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  
  <ItemGroup>
    <Reference Include="MathWorks.MATLAB.Runtime">
      <HintPath>C:\Program Files\MATLAB\MATLAB Runtime\R2025a\extern\dotnet\netstandard2.0\MathWorks.MATLAB.Runtime.dll</HintPath>
    </Reference>
    <Reference Include="MathWorks.MATLAB.Types">
      <HintPath>C:\Program Files\MATLAB\MATLAB Runtime\R2025a\extern\dotnet\netstandard2.0\MathWorks.MATLAB.Types.dll</HintPath>
    </Reference>    
    
    <Content Include="magicsquarelib.ctf">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
  </ItemGroup>
</Project>

At the command line, build your project by entering this command:

dotnet build magicsquarelib.csproj

Run the application from the system command prompt. For instance, on Windows, navigate to the folder that contains the executable and enter this command:

dotnet run

To test your application in MATLAB before deployment, run the application using the bang (!) operator. For instance, !dotnet run.

The application returns the same output as the sample MATLAB code you created during packaging.

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

To run the .NET application outside of MATLAB, you must install MATLAB Runtime. For details, see Download and Install MATLAB Runtime. If you created an installer using Build and Package, the installer contains a version of MATLAB Runtime that matches the version of MATLAB used to compile the .NET assembly.

To deploy the .NET application, distribute the executable file to the end user.