主要内容

本页采用了机器翻译。点击此处可查看最新英文版本。

compiler.build.dotNETAssembly

创建 .NET 程序集以在 MATLAB 之外部署

自 R2021a 起

说明

compiler.build.dotNETAssembly(Files) 使用 Files 指定的 MATLAB® 函数创建一个 .NET 程序集。

示例

compiler.build.dotNETAssembly(Files,Name,Value) 使用一个或多个名称-值参量指定附加选项来创建一个 .NET 程序集。选项包括类名、输出目录和要包含的附加文件。

示例

compiler.build.dotNETAssembly(ClassMap) 使用 container.Map 对象 ClassMap 指定的类映射创建一个 .NET 程序集。

示例

compiler.build.dotNETAssembly(ClassMap,Name,Value) 使用 ClassMap 和使用一个或多个名称-值参量指定的附加选项创建一个 .NET 程序集。选项包括程序集名称、输出目录和要包含的附加文件。

示例

compiler.build.dotNETAssembly(opts) 使用 compiler.build.DotNetAssemblyOptions 对象 opts 指定选项创建一个 .NET 程序集。不能使用名称-值参量指定任何其他选项。

示例

results = compiler.build.dotNETAssembly(___) 使用以上语法中的任意输入参量组合以 compiler.build.Results 对象形式返回编译信息。编译信息包括编译类型、编译文件的路径以及编译选项。

示例

示例

全部折叠

使用生成幻方的函数文件在 Windows® 系统上创建 .NET 程序集。

在 MATLAB 中,定位要部署为 .NET 程序集的 MATLAB 函数。对于此示例,使用 matlabroot\extern\examples\compiler 中的文件 magicsquare.m

appFile = which('magicsquare.m');

使用 compiler.build.dotNETAssembly 命令构建 .NET 程序集。

compiler.build.dotNETAssembly(appFile);

该编译函数会在当前工作目录中名为 magicsquaredotNETAssembly 的文件夹中生成以下文件:

  • GettingStarted.html - 包含有关集成您的程序集的信息的 HTML 文件。

  • includedSupportPackages.txt - 列出程序集中包含的所有支持文件的文本文件。

  • magicsquare.dll - 可以使用 mwArray API 访问的动态链接库文件。

  • magicsquare.xml - 包含 mwArray 程序集文档的 XML 文件。

  • magicsquare_overview.html - 包含访问组件和使用 mwArray 类层次结构生成参量的要求的 HTML 文件。

  • magicsquareNative.dll - 可以使用原生 API 访问的动态链接库文件。

  • magicsquareNative.xml - 包含原生程序集文档的 XML 文件。

  • magicsquareVersion.cs - 包含版本信息的 C# 文件。

  • mccExcludedFiles.log - 包含应用程序中未包含的任何工具箱函数列表的日志文件。有关不支持的函数的信息,请参阅 MATLAB Compiler 限制

  • readme.txt - 包含打包和接口信息的文本文件。

  • requiredMCRProducts.txt - 包含 MATLAB Runtime 运行应用程序所需产品的产品 ID 的文本文件。

  • unresolvedSymbols.txt - 包含有关未解析符号的信息的文本文件。

在 Windows 系统上创建 .NET 程序集并使用名称-值参量对其进行自定义。

对于此示例,使用 matlabroot\extern\examples\compiler 中的文件 flames.mflames.mat

appFile = which('flames.m');
MATFile = which('flames.mat');

使用 compiler.build.dotNETAssembly 命令构建 .NET 程序集。使用名称-值参量指定程序集名称和版本,添加 MAT 文件并启用详尽输出。

compiler.build.dotNETAssembly(appFile,'AssemblyName','FlamesComp', ...
'AssemblyVersion','2.0', ...
'AdditionalFiles',MATFile, ...
'Verbose','on');

使用类映射和多个函数文件在 Windows 系统上创建 .NET 程序集。

创建一个 containers.Map 对象,其键是类名,其值是函数文件的位置。

cmap = containers.Map;
cmap('Class1') = {'exampleFcn1.m','exampleFcn2.m'};
cmap('Class2') = {'exampleFcn3.m','exampleFcn4.m'};

使用 compiler.build.dotNETAssembly 命令构建 .NET 程序集。

compiler.build.dotNETAssembly(cmap);

或者,您可以在构建 .NET 程序集时使用名称-值参量指定其他选项。

compiler.build.dotNETAssembly(cmap, ...
'AssemblyName','MyExampleComp', ...
'AssemblyVersion','2.0', ...
'Verbose','on');

使用 compiler.build.DotNETAssemblyOptions 对象在 Windows 系统上创建多个 .NET 程序集。

对于此示例,使用 matlabroot\extern\examples\compiler 中的文件 magicsquare.m

appFile = which('magicsquare.m');

使用 appFile 创建一个 DotNETAssemblyOptions 对象。使用名称-值参量指定一个公共输出目录,单独生成程序集存档,并启用详尽输出。

opts = compiler.build.DotNETAssemblyOptions(appFile, ...
'OutputDir','D:\Documents\MATLAB\work\dotNETBatch', ...
'EmbedArchive','off', ...
'Verbose','on')
opts = 

  DotNETAssemblyOptions with properties:

             AssemblyName: 'example.magicsquare'
                 ClassMap: [1×1 containers.Map]
               DebugBuild: off
           EnableRemoting: off
         FrameworkVersion: '4.0'
    SampleGenerationFiles: {}
        StrongNameKeyFile: ''
          AssemblyVersion: '1.0.0.0'
             EmbedArchive: off
                Interface: 'mwarray'
          AdditionalFiles: {}
      AutoDetectDataFiles: on
    ExternalEncryptionKey: [0×0 struct]
         ObfuscateArchive: off
          SecretsManifest: ''
          SupportPackages: {'autodetect'}
                  Verbose: on
                OutputDir: 'D:\Documents\MATLAB\work\dotNETBatch'

   Class Map Information
         magicsquareClass: {'C:\Program Files\MATLAB\R2025a\extern\examples\compiler\magicsquare.m'}

使用 DotNETAssemblyOptions 对象构建 .NET 程序集。

compiler.build.dotNETAssembly(opts);

要使用具有相同选项的函数文件 hello.m 进行编译,请在再次运行构建函数之前使用点符号修改现有 COMComponentOptions 对象的 ClassMap

remove(opts.ClassMap, keys(opts.ClassMap));
opts.ClassMap('helloClass') = which('hello.m');
compiler.build.dotNETAssembly(opts);

通过修改 ClassMap 参量并重新编译,您可以使用同一个选项对象编译多个组件。

在 Windows 系统上创建一个 .NET 程序集,并将有关构建类型、生成的文件、包含的支持包和构建选项的信息保存到 compiler.build.Results 对象中。

使用文件 magicsquare.m 进行编译。

results = compiler.build.dotNETAssembly('magicsquare.m')
results = 

  Results with properties:

              BuildType: 'dotNETAssembly'
                  Files: {4×1 cell}
IncludedSupportPackages: {}
                Options: [1×1 compiler.build.DotNETAssemblyOptions]
    RuntimeDependencies: [1×1 compiler.runtime.Dependencies]

Files 属性包含以下已编译文件的路径:

  • magicsquare.dll

  • magicsquareNative.dll

  • magicsquare_overview.dll

  • GettingStarted.html

输入参数

全部折叠

实现 MATLAB 函数的文件,指定为字符向量、字符串标量、字符串数组或字符向量元胞数组。文件路径可以是相对于当前工作目录的路径,也可以是绝对路径。文件必须具有以下扩展名之一:.m.p.mlx.mexa64

示例: ["myfunc1.m","myfunc2.m"]

数据类型: char | string | cell

类映射,指定为 containers.Map 对象。映射键是类名,每个值是映射到相应类的文件集合。文件必须具有以下扩展名之一:.m.p.mlx.mexa64

示例: cmap

.NET 程序集构建选项,指定为 compiler.build.DotNETAssemblyOptions 对象。

名称-值参数

全部折叠

Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组,其中 Name 是参量名称,Value 是对应的值。名称-值参量必须出现在其他参量之后,但对各个参量对组的顺序没有要求。

如果使用的是 R2021a 之前的版本,请使用逗号分隔每个名称和值,并用引号将 Name 引起来。

示例: 'Verbose','on'

.NET 程序集中要包含的其他文件和文件夹,指定为字符向量、字符串标量、字符串数组或字符向量元胞数组。路径可以是相对于当前工作目录的路径,也可以是绝对路径。

示例: 'AdditionalFiles',["myvars.mat","data.txt"]

数据类型: char | string | cell

.NET 程序集的名称,指定为字符向量或字符串标量。将 'AssemblyName' 指定为命名空间,它是一个以句点分隔的列表,例如 companyname.groupname.component。生成的库的名称设置为以句点分隔的列表的最后一个条目。名称必须以字母开头,并且只能包含字母字符和句点。

示例: 'AssemblyName','mathworks.dotnet.mymagic'

数据类型: char | string

汇编版本,指定为字符向量或字符串标量。此选项仅与 MWArray API 一起使用。

有关使用 MATLAB Compiler SDK™ 进行版本控制的信息,请参阅版本控制

示例: 'AssemblyVersion','4.0'

数据类型: char | string

自动包含数据文件的标志,指定为 'on''off',或者指定为数值或逻辑 1 (true) 或 0 (false)。值 'on' 等效于 true,值 'off' 等效于 false。因此,可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 如果将此属性设置为 'on',则您作为某些函数(例如 loadfopen)的输入提供的数据文件将自动包含在 .NET 程序集中。

  • 如果将此属性设置为 'off',则必须使用 AdditionalFiles 选项将数据文件添加到程序集。

示例: 'AutoDetectDataFiles','off'

数据类型: logical

.NET 类的名称,指定为字符向量或字符串标量。如果使用 ClassMap 输入,则无法指定此选项。类名称必须符合 .NET 类名称要求。

默认值是 Files 参量中列出的第一个文件的名称加上 Class

示例: 'ClassName','magicsquareClass'

数据类型: char | string

启用调试符号的标志,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true,值 'off' 等效于 false。因此,可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 如果将此属性设置为 'on',则调试符号信息将包含在编译的工件中。此选项还会使 mbuild 将相应的调试标志传递到系统编译器。通过调试选项,您可以回溯到能够确定故障是发生在 MATLAB Runtime 初始化、函数调用还是终止例程中的时间点。此选项不允许您使用外部调试器调试 MATLAB 文件。

  • 如果将此属性设置为 'off',则不会包含调试符号。这是默认选项。

示例: 'DebugBuild','on'

数据类型: logical

嵌入可部署存档的标志,指定为 'on''off',或指定为数值或逻辑 1 (true) 或 0 (false)。值 'on' 等效于 true,值 'off' 等效于 false。因此,可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 如果将此属性设置为 'on',则该函数会将可部署存档嵌入 .NET 程序集中。

  • 如果将此属性设置为 'off',则此函数会将可部署存档生成为单独的文件。

此选项仅与 MWArray API 一起使用。

示例: 'EmbedArchive','off'

数据类型: logical

用于控制程序集的远程处理类型的标志,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true,值 'off' 等效于 false。因此,可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 如果将此属性设置为 'on',则该函数将构建可远程处理的程序集。

  • 如果将此属性设置为 'off',则该函数将构建一个不可远程处理的程序集。

示例: 'EnableRemoting','on'

数据类型: logical

自 R2024b 起

外部 AES 加密密钥和 MEX 密钥加载程序文件的路径,指定为标量结构体,其中恰好有两个分别名为 EncryptionKeyFileRuntimeKeyLoaderFile 的行字符向量或字符串标量字段。两个结构体字段都是必需的。文件路径可以是相对于当前工作目录的路径,也可以是绝对路径。

例如,使用结构体 keyValueStruct 将加密密钥指定为 encrypt.key,将加载程序文件指定为 loader.mexw64

keyValueStruct.EncryptionKeyFile='encrypt.key'; keyValueStruct.RuntimeKeyLoaderFile='loader.mexw64'

加密密钥文件必须采用以下受支持的格式之一:

  • 二进制 256 位 AES 密钥,文件大小为 32 字节

  • 十六进制编码的 AES 密钥,文件大小为 64 字节

MEX 文件加载程序在运行时检索解密密钥,并且必须是具有以下参量的接口:

  • prhs[0] - 输入,指定为静态值 'get' 的字符数组

  • prhs[1] - 输入,指定为 CTF 组件 UUID 的字符数组

  • plhs[0] - 输出,32 字节 UINT8 数字数组或 64 字节十六进制编码字符数组,具体取决于密钥格式

请勿在多个 CTF 之间共享同一个密钥。

示例: 'ExternalEncryptionKey',keyValueStruct

数据类型: struct

指定 '4.0' 以针对从 4.6.2 开始的任意 .NET Framework 版本,无论次要版本增量如何。要针对跨平台 .NET 5.0 或更高版本,请指定 '5.0'

示例: 'FrameworkVersion','5.0'

数据类型: char | string

数据 API 用于处理 .NET 应用程序和部署的 MATLAB 代码之间的数据交换。

  • mwarray - MWArray API。此 API 适用于 .NET Framework。这是 Windows 上的默认界面。

  • matlab-data - MATLAB Data API for .NET。此 API 需要 .NET 5.0 或更高版本。这是 macOS 上的默认界面。

MathWorks® 建议使用 MATLAB Data API for .NET。

示例: 'Interface','matlab-data'

数据类型: char | string

混淆可部署存档的标志,指定为 'on'/1/true'off'/0/false。该值存储为 matlab.lang.onoffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on',则会对最终用户混淆可部署存档中的文件夹结构和文件名,并且 .m.mlapp.p.mat、MLX 文件、SFX 文件和 MEX 文件中包含的用户代码和数据将被放入存档内的用户包中。另外,所有 .m 文件在打包前会转换为 P 文件。

在运行时,系统会从用户包直接解密和加载 MATLAB 代码和数据,而不是将其提取到文件系统。在加载之前,系统会从用户包中临时提取 MEX 文件。

要在用户包中手动包含其他文件类型,请将每种文件类型以单独的扩展标记的形式添加到文件 matlabroot/toolbox/compiler/advanced_package_supported_files.xml 中。

以下内容受支持:

  • ver 函数

  • 调用外部库,例如 DLL

  • 进程外 MATLAB Runtime(用于 MATLAB Data Array 的 C++ 共享库)

  • 进程外 MEX 文件执行(mexhostfevalmatlab.mex.MexHost

  • 在 R2023b 之前的版本中: v7.3 之外的 .mat 文件

启用此选项等效于在指定了 -j-s 的情况下使用 mcc

如果将此属性设置为 'off',则不会混淆可部署存档。这是默认行为。

示例: 'ObfuscateArchive','on'

数据类型: logical

保存编译文件的输出目录的路径,指定为字符向量或字符串标量。该路径可以是相对于当前工作目录的路径,也可以是绝对路径。

构建文件夹的默认名称是程序集名称加上 dotNETAssembly

示例: 'OutputDir','D:\Documents\MATLAB\work\mymagicdotNETAssembly'

数据类型: char | string

MATLAB 示例文件用于为程序集内包含的函数生成示例 .NET 驱动文件,指定为字符向量、字符串标量、字符串数组或字符向量元胞数组。路径可以是相对于当前工作目录的路径,也可以是绝对路径。文件必须具有 .m 扩展名。有关详细信息和限制,请参阅创建示例代码来调用导出函数

示例: 'SampleGenerationFiles',["sample1.m","sample2.m"]

数据类型: char | string | cell

自 R2024b 起

机密清单 JSON 文件的路径,该文件指定要嵌入在可部署存档中的密钥,指定为字符向量或字符串标量。该路径可以是相对于当前工作目录的路径,也可以是绝对路径。

如果您的 MATLAB 代码调用 getSecretgetSecretMetadataisSecret 函数,您必须在 JSON 机密清单文件中指定要嵌入可部署存档的密钥。如果您的代码调用 getSecret 并且您未指定 SecretsManifest 选项,则 MATLABCompiler™ 会发出警告,并在名为 <component_name>_secrets_manifest.json 的输出文件夹中生成一个模板 JSON 文件。通过在嵌入字段中指定密钥名称来修改此文件。

setSecret 函数不可部署。要将密钥嵌入在可部署存档中,您必须在构建存档之前在 MATLAB 中调用 setSecret

有关使用密钥进行部署的详细信息,请参阅处理已部署 App 中的敏感信息

示例: 'SecretsManifest','D:\Documents\MATLAB\work\mycomponent\mycomponent_secrets_manifest.json'

数据类型: char | string

用于签署共享程序集的加密密钥文件的路径,指定为字符向量或字符串标量。如果该值为空,该函数将创建一个私有程序集。文件路径可以是相对于当前工作目录的路径,也可以是绝对路径。

示例: 'StrongNameKeyFile','sgKey.snk'

数据类型: char | string

要包含的支持包,指定为以下选项之一:

  • 'autodetect'(默认值)- 依赖关系分析过程会自动检测并包含所需的支持包。

  • 'none' - 不包括任何支持包。使用此选项可能会导致运行时错误。

  • 字符串标量、字符向量或字符向量元胞数组 - 仅包含指定的支持包。要列出已安装的支持包或特定文件使用的那些支持包,请参阅 compiler.codetools.deployableSupportPackages

示例: 'SupportPackages',{'Deep Learning Toolbox Converter for TensorFlow Models','Deep Learning Toolbox Model for Places365-GoogLeNet Network'}

数据类型: char | string | cell

控制编译详细程度的标志,指定为 'on''off',或者指定为数值或逻辑 1 (true) 或 0 (false)。值 'on' 等效于 true,值 'off' 等效于 false。因此,可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 如果将此属性设置为 'on',则 MATLAB 命令行窗口会显示进度信息,指示编译过程期间的编译器输出。

  • 如果将此属性设置为 'off',则命令行窗口不会显示进度信息。

示例: 'Verbose','on'

数据类型: logical

输出参量

全部折叠

编译结果,以 compiler.build.Results 对象形式返回。Results 对象包括:

  • 编译类型,即 'dotNETAssembly'

  • 以下编译文件的路径:

    • AssemblyName.dll

    • AssemblyNameNative.dll

    • AssemblyName_overview.dll

    • GettingStarted.html

  • 包含的支持包的列表

  • 编译选项,指定为 DotNETAssemblyOptions 对象

  • 必需和可选依赖项的列表,指定为 Dependencies 对象

限制

  • 在 R2023a 中: 除了 Windows 之外,Linux®macOS 操作系统也支持该函数。

版本历史记录

在 R2021a 中推出

全部展开