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 MWArray 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 your working 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 mwArray 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 build subfolder contains the .NET assembly and the package subfolder contains an installer for your assembly along with MATLAB Runtime. To choose a different output location for the generated files, update the paths in the Output Locations section.

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 .NET Assembly 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 System.Collections.Generic;
using System.Text;
using MathWorks.MATLAB.NET.Arrays;
using MathWorks.MATLAB.NET.Utility;
using magicsquarelib;

/// <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 {
    static Class1 Class1Instance;

    static void Setup() {
        Class1Instance = new Class1();
    }

    /// <summary>
    /// Example of using the var function.
    /// </summary>
    public static void magicsquareSample() {
        double xInData = 5.0;
        MWNumericArray yOut = null;
        Object[] results = null;
        try {
            MWNumericArray xIn = new MWNumericArray(xInData);
            results = Class1Instance.magicsquare(1, xIn);
            if (results[0] is MWNumericArray) {
                yOut = (MWNumericArray) results[0];
            }
            Console.WriteLine(yOut);
        } catch (Exception e) {
            Console.WriteLine(e);
        }
    }

    /// <summary>
    /// The main entry point for the application.
    /// </summary>
    static void Main(string[] args) {
        try {
            Setup();
        } catch (Exception e) {
            Console.WriteLine(e);
            Environment.Exit(1);
        }
        try {
            magicsquareSample();
        } catch (Exception e) {
            Console.WriteLine(e);
            Environment.Exit(1);
        }
    }
}

The 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 following parameters are passed to the function in order as input arguments.

• Writes the function output to the console.

For more details on using the MWArray API, see Data Marshaling with MWArray API.

After you write source code, build and run your .NET application using Microsoft^® Visual Studio^®.

1. Open Microsoft Visual Studio and create a C# Console App (.NET Framework) called MainApp.

2. Remove any source code files that were created within your project, if necessary.

3. Add the sample C# application code magicsquareSample1.cs that was generated in the samples folder to the project.

4. In Visual Studio, add a reference to your assembly file magicsquarelib.dll located in the folder where you generated or installed the assembly.

5. Add a reference to the MWArray API. The file is located at <matlabroot>\toolbox\dotnetbuilder\bin\win64\<framework_version>\MWArray.dll, where <matlabroot> is the location of your MATLAB or MATLAB Runtime installation.

6. Go to Build, then Configuration Manager, and change the platform from Any CPU to x64.

7. After you finish adding your code and references, build the application with Visual Studio.

   The build process generates an executable named magicsquareSample1.exe.

8. Run the application from Visual Studio, in a command window, or by double-clicking the generated executable.

   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 more information, see About 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 code archive and the executable .exe file to the end user.