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
folder
in your project folder. The <compiler_task_name>
/outputbuild
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.
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
objectresults
.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®.
Open Microsoft Visual Studio and create a C# Console App (.NET Framework) called
MainApp
.Remove any source code files that were created within your project, if necessary.
Add the sample C# application code
magicsquareSample1.cs
that was generated in thesamples
folder to the project.In Visual Studio, add a reference to your assembly file
magicsquarelib.dll
located in the folder where you generated or installed the assembly.Add a reference to the
MWArray
API. The file is located at
, where<matlabroot>
\toolbox\dotnetbuilder\bin\win64\<framework_version>
\MWArray.dll<matlabroot>
is the location of your MATLAB or MATLAB Runtime installation.Go to Build, then Configuration Manager, and change the platform from Any CPU to x64.
After you finish adding your code and references, build the application with Visual Studio.
The build process generates an executable named
magicsquareSample1.exe
.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.
See Also
compiler.build.dotNETAssembly
| compiler.package.installer