|
|
|
| R2011b Documentation → MATLAB Builder NE | |
Learn more about MATLAB Builder NE |
|
| Contents | Index |
The following tasks are usually performed by the .NET developer.
.NET Developer
| Role | Knowledge Base | Responsibilities |
|---|---|---|
 .NET
Developer |
|
|
Key Tasks for the .NET Developer
| Task | Reference |
|---|---|
| Ensure you have the needed files from the MATLAB programmer. | Gathering Files Needed for Deployment |
| Install your application on target computers without MATLAB (installing the MCR). | Installing the MATLAB Compiler Runtime (MCR) |
| Integrate classes generated by the MATLAB Builder NE product into existing .NET applications. | Integrating Your Component into a .NET Class Using Microsoft Visual Studio |
| Verify your .NET application works as expected in your end user's deployment environment. | Building and Testing the .NET Application with Microsoft Visual Studio |
Before beginning, verify you have the files the MATLAB programmer packaged, listed in Packaging Your Component (Optional).
The package is a self-extracting executable. Paste it in a folder on the development machine and run it. If you are using a .zip file bundled with WinZip, unzip and extract the contents to the development machine.
On target computers without MATLAB, install the MCR, if it is not already present on the deployment machine.
The MATLAB Compiler Runtime (MCR) is an execution engine made up of the same shared libraries MATLAB uses to enable the execution of MATLAB files on systems without an installed version of MATLAB.
In order to deploy a component, you package the MCR along with it. Before you utilize the MCR on a system without MATLAB, run the MCR Installer.
The installer does the following:
Installs the MCR (if not already installed on the target machine)
Installs the component assembly in the folder from which the installer is run
Copies the MWArray assembly to the Global Assembly Cache (GAC), as part of installing the MCR
Since installing the MCR requires write access to the system registry, ensure you have administrator privileges to run the MCR Installer.
The version of the MCR that runs your application on the target computer must be compatible with the version of MATLAB Compiler that built the component.
Avoid installing the MCR in MATLAB installation directories.
Include the MCR in your deployment by using the Deployment Tool.
On the Package tab of the deploytool interface, click Add MCR.
Note For more information about additional options for including the MCR Installer (embedding it in your package or locating the installer on a network share), see Packaging (Optional) in the MATLAB Compiler User's Guide or in your respective Builder User's Guide. |
When you test with the MCR, keep in mind that the MCR is an instance of MATLAB. Given this, it is not possible to load the MCR into MATLAB.
For example, if you build a generic COM component with the Deployment Tool from MATLAB Builder NE, you generate a DLL.
If you then try to test the component with an application such as actxserver, which loads its process into MATLAB, you are effectively loading the MCR into MATLAB, producing an error such as this:
mwsamp.mymagic(3,[],[]) ??? Invoke Error, Dispatch Exception: Source: tmw1.Class1.1_0 Description: MCR instance is not available
Therefore, understand the behaviors of third-party processes before attempting to test them with the MCR.
If you are uncertain about the behavior of these processes, contact your developer or systems administrator.
To install the MCR, perform the following tasks on the target machines:
If you added the MCR during packaging, open the package to locate the installer. Otherwise, run the command mcrinstaller to display the locations where you can download the installer.
If you are running on a platform other than Windows, set the system paths on the target machine. Setting the paths enables your application to find the MCR.
Windows paths are set automatically. On Linux and Mac, you can use the run script to set paths. See Using Run Script to Set MCR Paths in the appendix Using MATLAB Compiler on UNIX in the MATLAB Compiler User's Guide for more information.
Where to find the MWArray API. The MCR also includes MWArray.dll, which contains an API for exchanging data between your applications and the MCR. You can find documentation for this API in the Help folder of the installation.
On target machines where the MCR
Installer is run, the MCR Installer puts the MWArray assembly
in installation_folder\toolbox\dotnetbuilder\
bin\architecture\framework_version.
See Supported Microsoft .NET Framework Versions for a list of supported framework versions.
Tip Learn about creating type-safe interfaces for .NET components, in order to avoid data conversion tasks with MWArray. See Type-Safe Interfaces, WCF, and MEF for details. |
Sample Directory Structure of the MCR Including MWArray.dll
To create a Microsoft Visual Studio project:
Open Microsoft Visual Studio
Click File > New > Project.
In the New Project dialog, select the project type and template you want to use.
For example, if you want to create a C# Console Application, select Windows in the Visual C# branch of the Project Type pane, and select the Console Application template from the Templates pane.
Type the name of the project in the Name field (MainApp, for example).
Create a reference in your code to the component that you just built.
To do so, in Microsoft Visual Studio, perform the following steps:
In the Solution Explorer pane within Microsoft Visual Studio (usually on the right side), select the name of your project, highlighting it.
Right-click and select Add Reference.
In the Add Reference dialog box, select the Browse tab. Locate the distrib folder using this dialog box. When you are finished the path to your distrib folder should be in the File Name: field. Click OK when done to open the distrib folder.
After you access the folder, select your component's executable file (in the case of the standalone example, a .dll file). Click OK.
You also need to reference MWArray.dll, which has already been registered with the Global Assembly Cache (GAC) (if you installed the MCR). The GAC is a machine-wide .NET assembly cache for Microsoft's CLR platform.
To create the reference, in Microsoft Visual Studio, perform the following steps:
In the Solution Explorer pane within Microsoft Visual Studio (usually on the right side), select the name of your project, and highlight it.
Right-click and select Add Reference.
Add a reference as follows, based on the version of Visual Studio you are running:
Microsoft Visual Studio 2005 or 2008: In the Add Reference dialog box, select the .NET tab. Locate MathWorks, .NET MWArray API, and select it. Click OK
Microsoft Visual Studio 2010: Browse for MWArray in this location: matlabroot\toolbox\dotnetbuilder\bin\arch\version\ and click Open.
.
Tip If you cannot locate the MathWorks, .NET MWArray API, it is likely the MCR was not installed correctly. See Installing the MATLAB Compiler Runtime (MCR) for more information. |
Make pertinent namespaces available to your application by adding the following using statements to your C#/.NET code:
using com.component_name; using MathWorks.MATLAB.NET.Arrays; using MathWorks.MATLAB.NET.Utility;
Tip When you add these statements to your code, use these best-practices:
|
Specifying Component Assembly and Namespace. To use the component assembly generated using the MATLAB Builder NE product from the client application, you must
Reference the MATLAB data conversion assembly and specify the namespace in your application, as shown:
using MathWorks.MATLAB.NET.Arrays;
Reference the namespace for the builder assembly generated for your particular component and specify the namespace in your application, for example:
using MyComponentName;
Suppose you named the component you created MyComponentName and you want to use it in a program named MyApp.cs. Here are the statements to use at the beginning of MyApp.cs:
using System; using MathWorks.MATLAB.NET.Arrays; using MyComponentName;
As a best practice, initialize your classes before you use them.
For example, you start by initializing an abstract class, MLTestClass, and then writing the code as follows.
Initializing Classes
In this example, you perform the following initializations:
Initializing classes to handle all input and output arguments (MWNumericArray input = null and MWNumericArray output = null). MWNumericArray is an interface to MATLAB's numeric type.
Initializing a class to handle MWArrays that the program returns (MWArray[] result = null — an array of MWArrays).
After your classes have been initialized, you write code to create objects (instances of the class) using instantiation (creating an instance of a class). Instantiating a class requires use of the new keyword.
In this example, you instantiate MLTestClass with obj = new MLTestClass();:
Instantiating a Class
Creating an Instance of a Class. As with any .NET class, you need to create an instance of the classes you create with the MATLAB Builder NE product before you can use them in your program.
Suppose you build a component with a class named MyComponentClass. Here is an example of creating an instance of that class:
MyComponentClass classInstance = new MyComponentClass();
See How the MCR Is Shared Among Classes for additional information about what happens when you instantiate classes.
After you complete the tasks of initializing and instantiating the classes you are working with, invoke the makeSqr component you built with MATLAB Builder NE in Deployable Component Creation.
Invoke the component method using a signature containing both the number of output arguments expected and the number of input arguments the MATLAB function requires. In this example, using makeSqr, the number of input arguments is 1 and the number of output arguments is 5:
obj.makeSqr(1, 5);
Using Implicit Conversion. Make use of implicit conversion, from .NET types to MATLAB types, by passing the native C# value directly to makeSqr using the input argument, as follows:
input = new MWNumericArray(5); obj.makeSqr(1, input);
Using Implicit Constructors. You can exploit implicit constructors supplied with MWArray classes to save writing code.
For example, in this example, you can directly define your input as 5 (input being identified previously as MATLAB numeric type MWNumericArray).
Defining Input Using an Implicit Constructor
Handling Output from MWArray. The makeSqr method returns an array of MWArrays
Extract the Magic Square you created from the first indice of result and print the output, as follows:
output = (MWNumericArray)result[0]; Console.WriteLine(output);
Because class instantiation and method invocation make their exceptions at run-time, you enclose your code in a try-catch block to handle errors.
Using a Try-Catch Block
| If you want to... | See... |
|---|---|
| Perform advanced integration tasks | Component Integration |
| Convert native data types to MATLAB data types | Manual Data Conversion from Native Types to MATLAB Types |
| Learn about creating type-safe interfaces, in order to avoid data conversion tasks with MWArray. | Type-Safe Interfaces, WCF, and MEF |
| Automatic casting to MATLAB data types | Automatic Casting to MATLAB Types |
| Learn more about building your component | Component Building |
| MATLAB Code Deployment |
After you finish writing your code, you build and run it with Microsoft Visual Studio:
To build the application, select Build > Build Solution.
To run the application, select Debug > Start Without Debugging.
| If you want to... | See... |
|---|---|
| Perform advanced integration tasks | Component Integration |
| Convert native data types to MATLAB data types | Manual Data Conversion from Native Types to MATLAB Types |
| Learn about creating type-safe interfaces, in order to avoid data conversion tasks with MWArray. | Type-Safe Interfaces, WCF, and MEF |
| Automatic casting to MATLAB data types | Automatic Casting to MATLAB Types |
| Learn more about building your component | Component Building |
| MATLAB Code Deployment |
Write source code for an application that uses the .NET component created in Deployable Component Creation.
The C# source code for the sample application for this example is in MagicSquareExample\MagicSquareCSApp\MagicSquareApp.cs.
Tip Although MATLAB Builder NE generates C# code for the MagicSquare component and the sample application is in C#, applications that use the component do not need to be coded in C#. You can access the component from any CLS-compliant .NET language. For C#, as well as Microsoft® Visual Basic® examples, see Component Integration. |
Build the application using Visual Studio® .NET.
Note In the project file for this example, the MWArray assembly and the magic square component assembly have been prereferenced. Any references preceded by an exclamation point require you to remove the reference and rereference the affected assembly. |
Open the project file for the Magic Square example (MagicSquareCSApp.csproj) in Visual Studio .NET.
Add a reference to the MWArray component
in matlabroot\toolbox\dotnetbuilder\bin\
architecture\framework_version.
See Supported Microsoft .NET Framework Versions for a list of supported framework versions.
If necessary, add a reference to the Magic Square component (MagicSquareComp), which is in the distrib subfolder.
 | Magic Square Example: Creating a .NET Component From MATLAB Code | Next Steps |  |
Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.
| © 1984-2012- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |
