使用 MATLAB Data API for .NET 将 MATLAB 类部署到 .NET 应用程序

支持的 .NET 版本：.NET 6.0 或更高版本

数据 API：MATLAB^® Data Array for .NET

此示例说明如何打包 MATLAB 包中包含的 MATLAB 类并将其部署到 C# 应用程序。它使用 .NET 的 MATLAB Data API 来管理 MATLAB 代码和 C# 应用程序之间的数据交换。MATLAB 类可通过前端的 MATLAB 函数访问。该工作流支持 Windows^®、Linux^® 和 macOS。

自 R2023b 起，带有包含 MATLABMATLAB 的 .NET 应用程序可以跨 Windows、Linux 和 macOS 平台开发和发布。这意味着可以在这三种平台中的任一平台上进行开发，然后发布到另外两个平台上。

请注意，虽然开发和发布可以在任何平台上进行，但仍可能存在特定于平台的细微差别和问题。某些库或函数在不同平台上的行为可能会有所不同，开发人员应在目标平台上彻底测试他们的应用程序以确保预期的行为。

前提条件

创建一个对 MATLAB 搜索路径可见的新工作文件夹。此示例使用名为 work 的文件夹。
验证您是否已设置 .NET 开发环境。有关详细信息，请参阅设置 .NET 开发环境。
验证您是否已满足所有 MATLAB .NET 目标要求。有关详细信息，请参阅MATLAB Compiler SDK .NET 目标要求。
最终用户必须安装 MATLAB Runtime 才能运行应用程序。有关详细信息，请参阅下载并安装 MATLAB Runtime。
出于测试目的，您可以使用安装的 MATLAB 来代替 MATLAB Runtime。
验证您是否已安装 .NET 6.0 SDK 或更高版本或 Microsoft^® Visual Studio^® 2022（v17.0 或更高版本）。您可以在系统命令提示符下输入 dotnet --info 来验证 .NET 6.0 是否已安装。您可以从 https://dotnet.microsoft.com/download 下载特定于您的操作系统的 .NET SDK 版本。

数据管理

要在部署的 MATLAB 代码和 .NET 应用程序之间交换数据，请使用适用于 .NET 的 MATLAB Data API。MATLAB 引擎也使用此 API。有关概述，请参阅从 .NET 调用 MATLAB。有关详细信息，请参阅：

文件

每个示例文件的用途

文件	目的
`+shapes`	包含两个类的包：`MyPosition.m` 和 `MyRectangle.m`。
`MyPosition.m`	`+shapes` 包中的类接受一个点的 X 和 Y 坐标并创建一个 `MyPosition` 对象。
`MyRectangle.m`	`+shapes` 包中的类接受指定为 `MyPosition` 对象的两个点并创建一个 `MyRectangle` 对象。
`calculatearea.m`	接受 `MyRectangle` 对象作为输入并计算矩形面积的函数。
`Program.cs`	将 MATLAB 代码打包生成的代码存档（`.ctf` 文件）和 C# 代码（`.cs` 文件）整合在一起的 C# 应用程序代码。

创建 MATLAB 函数和类

检查 MyPosition.m、MyRectangle.m 和 calculatearea.m 的代码。

+shapes 包包含两个 MATLAB 类：MyPosition.m 和 MyRectangle.m。
位于 calculatearea.m 包之外的 +shapes MATLAB 函数接受 MyRectangle 对象作为输入并计算矩形的面积。

+shapes（包）

MyPosition.m（类）

MyRectangle.m（类）

calculatearea.m（函数）

资深 MATLAB 用户可能会发现，在类中看到 properties 模块，在方法或函数中看到 arguments 模块，并且每个块都详细记录数据类型信息，这是很不寻常的。这两个模块都允许您使用等效的 MATLAB 类型表示 C# 数据类型。例如，如果您的 C# 应用程序采用 double 数据类型来表示一个值，那么您现在可以在 MATLAB 中将其表示为 double。您还可以将 MATLAB 对象指定为参量或属性类型。例如，MyRectangle 类将 shapes.MyPosition 指定为其 UpperLeft 和 LowerRight 属性的 MyRectangle。有关详细信息，请参阅C++ 和强类型 MATLAB 代码之间的数据类型映射。

在此示例中，具有数据类型信息的 properties 和 arguments 模块用于阐明细微的差别。但是，请记住，包含类型信息完全是可选的。即使没有它，部署过程仍然保持不变。尽管如此，在 MATLAB 代码中添加类型信息可以大大简化编写 C# 应用程序代码的过程并减少由类型转换引起的错误。这个示例的各个部分强调了这种差异的体现方面。

使用以下代码创建一个名为 runshapes.m 的 MATLAB 脚本，并在 MATLAB 命令提示符下执行它。该脚本说明了类和函数如何交互以生成输出。

runshapes.m

runshapes

Rectangle 1
Point 1 = (10, 5)

Point 2 = (50, 20)

Rectangle (10, 5) -> (50, 20)

Rectangle 2
Point 1 = (0, -5)

Point 2 = (60, 30)

Rectangle (0, -5) -> (60, 30)

Area of rectangle r1 = 600
Area of rectangle r2 = 2100

使用 `compiler.build.dotNETAssembly` 创建 .NET 程序集

要创建 .NET 程序集，请使用 compiler.build.dotNETAssembly 函数。

files = ["calculatearea.m", "+shapes"];
buildResults = compiler.build.dotNETAssembly(files, Interface="matlab-data",...
    AssemblyName="CalculateArea", OutputDir=".\output", Verbose="on")

P:\MATLAB\WORK\OUTPUT
│   CalculateArea.csproj
│   CalculateArea.ctf
│   CalculateArea.deps.json
│   CalculateArea.dll
│   GettingStarted.html
│   includedSupportPackages.txt
│   mccExcludedFiles.log
│   readme.txt
│   requiredMCRProducts.txt
│   unresolvedSymbols.txt
│
└───strongly_typed_interface
        calculatearea.cs
        shapes_MyPosition.cs
        shapes_MyRectangle.cs

该函数生成一套如上所列举的文件，并将它们放在指定的 output 目录中。其中，集成过程中使用的关键文件包括：

CalculateArea.ctf - 包含打包的 MATLAB 代码的代码存档。
calculatearea.cs、shapes_MyPosition.cs 和 shapes_MyRectangle.cs - C# 代码文件。
CalculateArea.dll - .NET 程序集文件。

有关其他文件的信息，请参阅打包 MATLAB 函数后生成的文件。

虽然通过 AssemblyName 属性向 compiler.build.dotNETAssembly 函数提供程序集名称不是强制性的，但强烈建议这样做。这样做会为生成的 .NET 程序集和 C# 文件提供更清晰的命名空间。如果没有它，名为 example 的根命名空间会自动追加到子命名空间，从而导致命名空间结构混乱且可能令人困惑。

要完成集成，您可以选择以下两个选项之一：

将 CalculateArea.ctf 代码存档文件与 calculatearea.cs、shapes_MyPosition.cs 和 shapes_MyRectangle.cs C# 代码文件结合使用。如果您想检查 MATLAB 到 C# 的转换并进行修改，此选项很有用。
将 CalculateArea.ctf 代码存档文件与 CalculateArea.dll 集文件结合使用。如果您想在 .NET 应用程序中利用 MATLAB 代码的功能，而无需深入研究 C# 翻译的具体内容，则此选项很有用。

经检查，您会注意到该函数还生成一个 CalculateArea.csproj 工程文件。该文件是专门为创建相应的 CalculateArea.dll .NET 程序集文件而生成的。但是，它不应被误认为是 .NET 工程的模板，并且不得在该环境中使用。如果您修改了由 compiler.build.dotNETAssembly 生成的 C# 代码文件并且需要创建 .NET 程序集，那么在这种情况下，请通过执行以下命令使用此工程文件：dotnet build CalculateArea.csproj。

此示例采用第一个集成选项来说明类型映射机制。在工作流的相关阶段插入了使用第二种选项的相关指导。

您可以检查以下 C# 代码文件的内容：

calculatearea.cs

有关如何将 MATLAB 类和函数映射到 C# 的深入讨论，请参阅将 MATLAB 类和函数映射到 C#。

注意

生成的组件不包括 MATLAB Runtime 或安装程序。要使用 buildResults 对象创建安装程序，请参阅 compiler.package.installer。

将 MATLAB 代码集成到 .NET 应用程序中

您可以在首选的 C# 开发环境中完成集成过程，包括文本编辑器以及 .NET SDK 命令行 API，或者 Windows 和 Microsoft macOS 上的 Visual Studio 等替代方案。此示例向您说明如何使用两个选项完成集成。有关详细信息，请参阅设置 .NET 开发环境。

使用 .NET SDK 命令行 API 构建应用程序

如果您使用的是 Microsoft Visual Studio，请参阅使用 Microsoft Visual Studio 构建应用程序 (Windows)。

在 Windows 中打开命令提示符并导航到本示例中使用的 work 文件夹。
在命令行中输入：
```
dotnet new console --framework net6.0 --name ShapesConsoleApp
```
此命令创建一个名为 ShapesConsoleApp 的文件夹，其中包含以下内容：
- obj 文件夹
- ShapesConsoleApp.csproj 工程文件
- Program.cs C# 源文件
将由 compiler.build.dotNETAssembly 函数生成的以下文件与 dotnet new C# 应用程序代码文件一起复制到 Program.cs 创建的工程文件夹中：
- 来自 calculatearea.cs 目录的 shapes_MyPosition.cs、shapes_MyRectangle.cs 和 ...\work\output\strongly_typed_interface\ C# 包装器文件。
- 来自 ...\work\output 目录的代码存档 CalculateArea.ctf。

编辑工程文件以添加 MathWorks 集依赖项和 CalculateArea.ctf 代码存档文件。

在文本编辑器中打开工程文件，并使用以下 MathWorks 程序集 <Reference> 标记内的 <ItemGroup> 工程标记：

MathWorks.MATLAB.Runtime.dll
MathWorks.MATLAB.Types.dll

MathWorks 程序集的 Windows 路径

指向 MathWorks 程序集的 Linux 和 macOS 路径

注意

如果您使用由 compiler.build.dotNETAssembly 函数生成的 CalculateArea.dll 程序集文件而不是 C# 代码文件，请将其作为 Reference 包含在同一个 <ItemGroup> 标记。

将 CalculateArea.ctf 代码存档文件作为 Content 文件包含到工程中。
- 将 CalculateArea.ctf 代码存档文件添加为 Content 文件 <ItemGroup> 标记。
- 添加标记 CopyToOutputDirectory 并将其设置为 Always。此步骤确保在构建过程中将 CalculateArea.ctf 文件复制到输出文件夹。这意味着当您构建工程时，该文件与您构建的 .exe 文件位于同一目录中。
- 添加标记 CopyToPublishDirectory 并将其设置为 Always。此步骤确保将 CalculateArea.ctf 文件复制到此工程发布到的跨平台文件夹中。

一旦添加了程序集依赖项并将 CalculateArea.ctf 作为 Content 文件包含，您的工程文件将如下所示：

ShapesConsoleApp.csproj (Windows)

ShapesConsoleApp.csproj (Linux)

ShapesConsoleApp.csproj (macOS)

注意

如果您选择在 C# 代码文件上使用由 compiler.build.dotNETAssembly 生成的 CalculateArea.dll .NET 程序集，请记住取消注释工程文件中 Reference 的 CalculateArea.dll 标记。此更改可确保您的工程正确使用汇编文件。

将 Program.cs C# 文件中的代码替换为以下代码：

Program.cs

using System;
using MathWorks.MATLAB.Runtime;
using MathWorks.MATLAB.Types;
using CalculateArea.shapes;
class Program
{
    static void Main(string[] args)
    {
        string ctfPath = @"CalculateArea.ctf";

       /*
        * If the direct path to the .ctf file does not work, import the 
	* following namespaces and use the following code to construct the 
	* path dynamically:
        * 
        * using System.IO;
        * using System.Reflection;
        * 
        * // Get the directory of the executing assembly
        * string assemblyPath = Assembly.GetExecutingAssembly().Location;
        * string assemblyDirectory = Path.GetDirectoryName(assemblyPath);
        *
        * // Construct the path to the .ctf file
        * string ctfPath = Path.Combine(assemblyDirectory, "CalculateArea.ctf");
        */

        using (dynamic runtime = MATLABRuntime.StartMATLAB(ctfPath))
        {
            // Create point p1
            MyPosition p1 = new MyPosition(runtime);
            p1.X = 10.0;
            p1.Y = 5.0;

            // Create point p2
            MyPosition p2 = new MyPosition(runtime);
            p2.X = 50;
            p2.Y = 20;
            
            // Create rectangle r1
            MyRectangle r1 = new MyRectangle(runtime);
            r1.UpperLeft = p1;
            r1.LowerRight = p2;

            // Use show method to display rectangle coordinates
            Console.WriteLine("Rectangle 1");
            r1.show();
            
            // Create second rectangle by enlarging the first one
            MyRectangle r2 = new MyRectangle(runtime);
            r1.enlarge(10.0, out r2);
            Console.WriteLine("Rectangle 2");
            r2.show();
            
            // Calculate area using MATLAB calculatearea function and display result
            double area1, area2;
            CalculateArea.MATLABFunctions.calculatearea(runtime, r1, out area1);
            CalculateArea.MATLABFunctions.calculatearea(runtime, r2, out area2);
            Console.WriteLine($"Area of rectangle r1 = {area1}");
            Console.WriteLine($"Area of rectangle r1 = {area2}");

            // Call the CalculatePerimeter static method and display result
            double perimeter1, perimeter2;
            perimeter1 = CalculatePerimeter(r1);
            perimeter2 = CalculatePerimeter(r2);
            Console.WriteLine($"Perimeter of rectangle r1 is = {perimeter1}");
            Console.WriteLine($"Perimeter of rectangle r2 is = {perimeter2}");
        }
    }
    static double CalculatePerimeter(MyRectangle rectangle)
    {
        // Get the positions of the upper left and lower right corners
        MyPosition upperLeft = rectangle.UpperLeft;
        MyPosition lowerRight = rectangle.LowerRight;

        // Calculate the width and height of the rectangle
        double width = Math.Abs(lowerRight.X - upperLeft.X);
        double height = Math.Abs(upperLeft.Y - lowerRight.Y);

        // Calculate and return the perimeter
        return 2 * (width + height);
    }
}

注意

在 macOS 系统上开发和操作时，将代码从 Main 方法转换到名为 MainFunc 的新函数。随后，从 MATLABRuntime.SetupMacRunLoopAndRun 方法中调用 Main，并将 MainFunc 与命令行参量一起作为参数传递。MATLABRuntime.SetupMacRunLoopAndRun 对于 macOS 环境来说是不可或缺 MATLABRuntime.SetupMacRunLoopAndRun，因为它允许 MATLAB 与 Core Foundation Run Loop (CFRunLoop) 交互，这是一种特定于 macOS 的机制，用于处理用户输入或计时器事件等事件。有关详细信息，请参阅 MathWorks.MATLAB.Runtime.MATLABRuntime。

在命令行中，输入以下命令来构建您的工程：
```
dotnet build ShapesConsoleApp.csproj
```

运行 C# 应用程序

为了测试目的，您可以从 MATLAB 命令提示符运行该应用程序。这不需要安装 MATLAB Runtime。

在 MATLAB 命令提示符下，导航到 work\ShapesConsoleApp\ShapesConsoleApp\bin\Debug\net6.0 目录并通过键入以下内容运行可执行文件：

!dotnet run

应用程序显示输出。

Rectangle 1
Point 1 = (10, 5)
Point 2 = (50, 20)
Rectangle (10, 5) -> (50, 20)
Rectangle 2
Point 1 = (0, -5)
Point 2 = (60, 30)
Rectangle (0, -5) -> (60, 30)
Area of rectangle r1 = 600
Area of rectangle r1 = 2100
Perimeter of rectangle r1 is = 110
Perimeter of rectangle r2 is = 190

注意

当您准备部署此应用程序时，请确保目标系统已安装 MATLAB Runtime。有关详细信息，请参阅下载并安装 MATLAB Runtime。在 Linux 和 macOS 系统上，必须在运行应用程序之前分别设置 LD_LIBRARY_PATH 和 DYLD_LIBRARY_PATH 运行时路径。有关详细信息，请参阅针对部署设置 MATLAB Runtime 路径。

使用 Microsoft Visual Studio 构建应用程序 (Windows)

打开 Microsoft Visual Studio 并创建一个名为 ShapesConsoleApp 的 C# Console App。
选择 .NET 6.0 (Long-term support) 作为框架。
将 Program.cs 文件中默认生成的源代码替换为此示例页面中的 Program.cs 文件中提供的特定源代码。
通过导航到 Solution Explorer，右键点击工程，然后选择 Add > Existing Item，合并由 compiler.build.dotNETAssembly 函数生成的 calculatearea.cs、shapes_MyPosition.cs 和 shapes_MyRectangle.cs C# 代码文件。使用对话框查找并添加 C# 代码文件。
注意
如果您更喜欢使用由 compiler.build.dotNETAssembly 函数生成的 CalculateArea.dll 程序集文件，请在 Solution Explorer 中右键点击您的解决方案，然后选择 Edit Project File。在这里，您需要在现有文件中添加对 CalculateArea.dll 文件的引用 <ItemGroup> 标记。
请参阅上面列出的工程文件之一以获取指导。

添加以下 MathWorks 集依赖项：

MathWorks.MATLAB.Runtime.dll
MathWorks.MATLAB.Types.dll

MathWorks 程序集的位置

将 CalculateArea.ctf 代码存档文件作为 Content 文件添加到工程中。在 Solution Explorer 中右键点击您的工程，然后选择 Add > Existing Item。在对话框中，浏览文件并添加文件。
在 Solution Explorer 中右键点击 CalculateArea.ctf 文件并选择 Properties。在 Properties 窗口中，将 Build Action 设置为 Content，并将 Copy to Output Directory 设置为 Copy always。
在 Solution Explorer 中右键点击您的工程并选择 Edit Project File。ShapesConsoleApp.csproj 工程文件在编辑器中打开。添加 <CopyToPublishDirectory> 标记正下方 <CopyToOutputDirectory> 标记并将其设置为 Always。ShapesConsoleApp.csproj 工程文件的已编辑部分如下所示：
```
...
<ItemGroup>
    <Content Include="CalculateArea.ctf">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <CopyToPublishDirectory>Always</CopyToPublishDirectory>
    </Content>
</ItemGroup>
...
```
在菜单栏上，选择 Build，然后选择 Build Solution 以在 Visual Studio 中构建应用程序。
编译过程会生成一个名为 ShapesConsoleApp.exe 的可执行文件。
提示
如果您无法从 Visual Studio 运行应用程序，请打开 Developer Command Prompt for Visual Studio，然后输入 devenv /useenv 启动 Visual Studio。然后，打开您的工程并运行您的应用程序。

从 Visual Studio 中运行 C# 应用程序

在 Visual Studio 中执行 C# 应用程序之前，请确保正确设置 PATH 环境变量以引用 MATLAB 或 MATLAB Runtime 安装。以下是在 Visual Studio 中设置 PATH 环境变量的方法：

在 Visual Studio 中，右键点击 Solution Explorer 中的工程，然后点击 Properties。
导航到 Debug > General，然后选择 Open debug launch profiles UI。

在 Launch Profiles 窗口的 Environment variables 下，设置您的 PATH：

对于 MATLAB：

PATH=C:\Program Files\MATLAB\R2025a\runtime\win64

对于 MATLAB Runtime：

PATH=C:\Program Files\MATLAB\MATLAB Runtime\R2025a\runtime\win64

按 Ctrl+F5 从 Visual Studio 运行应用程序。

发布到 Linux 和 macOS

注意

在 R2023a 之前的版本中: 应用程序只能从 Windows 发布到 Linux 和 macOS。

要将应用程序发布到 Linux，请在系统命令提示符下输入以下命令：

dotnet publish --configuration Release --framework net6.0 
  --runtime linux-x64 --self-contained true ShapesConsoleApp.csproj

要将应用程序发布到 macOS，请在一行中输入以下命令：

dotnet publish --configuration Release --framework net6.0 
  --runtime osx.12-x64 --self-contained true ShapesConsoleApp.csproj

要发布到特定平台，请使用适当的运行时标识符 (RID)。有关详细信息，请参阅 https://learn.microsoft.com/en-us/dotnet/core/rid-catalog。

从 Visual Studio 发布

有关如何从 Visual Studio 设置发布的详细信息，请参阅 .NET 文档。设置完成后，编辑您的发布配置文件以包含以下设置：

将 Configuration 设置为 Release | Any CPU。
将 Target framework 设置为 net6.0。
将 Deployment mode 设置为 Self-contained。
将 Target runtime 设置为 linux-x64 或 osx-x64。
保持 Target location 不变或将其设置为您选择的位置。

在 Linux 上运行已发布的应用程序

将 Release 文件夹从 Windows 上的 C:\work\ShapesConsoleApp\bin 复制到 Linux 计算机上的 ~/work。如果尚不存在 work 文件夹，请在 Linux 上创建一个。
在 Linux 计算机上，验证您是否已安装 MATLAB Runtime 并设置了 LD_LIBRARY_PATH 环境变量。有关详细信息，请参阅下载并安装 MATLAB Runtime和针对部署设置 MATLAB Runtime 路径。
打开 Linux 控制台并导航至：
```
~/work/Release/net6.0/linux-x64/publish
```
为 Linux 可执行文件添加执行权限：
```
chmod +x ShapesConsoleApp
```
输入以下命令运行应用程序：
```
./ShapesConsoleApp
```

按照类似的步骤在 macOS 上运行该应用程序。

注意

您可以使用 .NET Framework 4.6.1 或更高版本来实现此示例。但是，您无法跨平台部署该示例。此外，.NET Framework 没有命令行界面。