Magic Square Example: Creating a .NET Component From MATLAB Code

On this page…
makesquare Testing Deployable Component Creation Packaging Your Component (Optional) Copying the Package You Created

MATLAB Programmer

Role	Knowledge Base	Responsibilities
MATLAB programmer	MATLAB expert No IT experience No access to IT systems	Develops models; implements in MATLAB Uses tools to create a component that is used by the .NET developer

The MATLAB programmer usually performs the following tasks.

Key Tasks for the MATLAB Programmer

Task	Reference
Test the MATLAB code to ensure it is suitable for deployment.	makesquare Testing
Create a .NET component by running the deploytool.	Deployable Component Creation
Optionally, use the Packaging Tool to wrap all deliverable files in one bundle.	Packaging Your Component (Optional)
Copy the output so the .NET programmer can work with it further.	Copying the Package You Created

makesquare Testing

In this example, you test a precreated MATLAB file (makesquare.m) containing the predefined MATLAB function magic, in order to have a baseline to compare to the results of the function when it is finally wrappered as a deployable .NET component.

1. Using MATLAB, locate the makesquare.m file at matlabroot\toolbox\dotnetbuilder\Examples\VS8\NET\MagicSquareExample\MagicSquareComp. This file has the following contents:

   function y = makesquare(x)
   %MAKESQUARE Magic square of size x.
   %   Y = MAKESQUARE(X) returns a magic square of size x.
   %   This file is used as an example for the MATLAB 
   %   Builder NE product.
   
   %   Copyright 2001-2011 The MathWorks, Inc.
   
   y = magic(x);

2. At the MATLAB command prompt, enter makesquare(5), and view the results. The output should appear as follows:

   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

For More Information

If you want to...	See...
Perform basic MATLAB Programmer tasks Understand how the deployment products process your MATLAB functions Understand how the deployment products work together Explore guidelines about writing deployable MATLAB code	MATLAB Code Deployment

Back to Top

Deployable Component Creation

You create a .NET component by using the Deployment Tool GUI to build a .NET class that wraps around the sample MATLAB code discussed in makesquare Testing.

Use the following information when creating your component as you work through this example:

Project Name	makeSqr
Class Name	MLTestClass
File to compile	makesquare.m

1. Start MATLAB, if you have not done so already.

2. Type deploytool at the command prompt, and press Enter. The Deployment Project dialog box opens.

   The Deployment Project Dialog Box

   

3. Create a deployment project using the Deployment Project dialog box:

   1. Type the name of your project in the Name field.

   2. Enter the location of the project in the Location field. Alternately, navigate to the location.

   3. Select the target for the deployment project from the Target drop-down menu.

   4. Click OK.

   Tip   You can inspect the values in the Settings dialog before building your project. To do so, click the Action icon ( ) on the toolbar, and then click Settings. Verify where your src and distrib folders will be created because you will need to reference these folders later.

4. On the Build tab:

   • If you are building a COM application, click Add files.

     Click Open to select the file or files.

   • If you are building a .NET application, click Add class. Type the name of the class in the Class Name field, designated by the letter c:

     

     For this class, add MATLAB files you want to compile by clicking Add files then click Open to select the file or files. To add another class, click Add class.

   • You may optionally add supporting files. For examples of these files, see the deploytool Help. To add these files, in the Shared Resources and Helper Files area:

     1. Click Add files/directories

     2. Click Open to select the file or files.

   Note   If you are building a COM component (not a .NET component) and you don't have administrator privileges, you can select the Register the resulting component for you only on the development machine option in the Settings dialog of the Deployment Tool (in the Advanced tab) or use the mcc -u option.

5. When you complete your changes, click the Build button ( ).

What Gets Built?

After you build your add-in with the Deployment Tool, you have the following in the src and distrib subdirectories of your project directory:

These Subdirectories of the Project Directory:	Contain these files:
src	componentName.xml componentName.pdb (if the Debug option is selected)
distrib	componentName.dll componentNameNative.dll Note   See .NET Remoting for more information on using the native .NET API.

For More Information

If you want to...	See...
Perform basic MATLAB Programmer tasks Understand how the deployment products process your MATLAB functions Understand how the deployment products work together Explore guidelines about writing deployable MATLAB code	MATLAB Code Deployment

Back to Top

Packaging Your Component (Optional)

Bundling the .NET component with additional files you can distribute to users is called packaging. You perform this step using the packaging function of deploytool. If you are creating a shared component and want to include additional code with the component, you must perform this step.

The package process zips the following files into a single self-extracting executable, componentName.exe:

• componentName.dll

• componentNameNative.dll

  Note   See .NET Remoting for more information on using the native .NET API.

• componentName.xml

• componentName.pdb (if the Debug option is selected)

• MCR Installer (if the Include MCR option is selected)

• _install.bat (script run by the self-extracting executable)

Tip   Instead of performing the steps below, you can alternately copy the distrib folder and the MCR Installer to a local folder of your choice.

1. On the Package tab, add the MATLAB Compiler Runtime (MCR). To do so, click Add MCR, and choose one of the two options described in the following table.

   Option	What Does This Option Do?	When Should I Use This Option?
   Embed the MCR in the package	This option physically copies the MCR Installer file into the package you create.	You have a limited number of end users who deploy a small number of applications at sporadic intervals Your users have no intranet/network access Resources such as disk space, performance, and processing time are not significant concerns Note   Distributing the MCR Installer with each application requires more resources.
   Invoke the MCR from a network location	This option lets you add a link to an MCR Installer residing on a local area network, allowing you to invoke the installer over the network, as opposed to copying the installer physically into the deployable package. This option sets up a script to install the MCR from a specified network location, saving time and resources when deploying applications.	You have a large number of end users who deploy applications frequently Your users have intranet/network access Resources such as disk space, performance, and processing time are significant concerns for your organization If you choose this option, modify the location of the MCR Installer, if needed. To do so, select the Preferences link in this dialog box, or change the Compiler option in your MATLAB Preferences. Caution   Before selecting this option, consult with your network or systems administrator. Your administrator may already have selected a network location from which to run the MCR Installer.

   For more information about the role the MCR plays in the deployment process, see Installing the MATLAB Compiler Runtime (MCR).

2. Next, add others files you feel may be useful to end users. To package additional files or folders, click Add file/directories, select the file or folder you want to package, and click Open.

3. In the Deployment Tool, click the Packaging button ( ).

4. For Windows, the package is a self-extracting executable. On platforms other than Windows, the package is delivered as a .zip file. Verify that the contents of the distrib folder contains the files you specified.

MATLAB Compiler Runtime (MCR) and the MCR Installer

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:

1. Installs the MCR (if not already installed on the target machine)

2. Installs the component assembly in the folder from which the installer is run

3. Copies the MWArray assembly to the Global Assembly Cache (GAC), as part of installing the MCR

How the MCR Is Shared Among Classes

The builder creates a single MCR instance for each Builder class in an application. All class instances share a single MATLAB workspace and share global variables in the MATLAB files used to build the component. This MCR instance is reused and shared among all subsequent class instances within the component. Such reuse and sharing results in more efficient memory usage and elimination of MCR startup cost in each subsequent class instantiation.

For More Information

If you want to...	See...
Build (compile) a component from your MATLAB code	Deployable Component Creation
Integrate your component into a production environment	Integrating Your Component into a .NET Class Using Microsoft Visual Studio
Perform basic MATLAB Programmer tasks Understand how the deployment products process your MATLAB functions Understand how the deployment products work together Explore guidelines about writing deployable MATLAB code	MATLAB Code Deployment

Back to Top

Copying the Package You Created

Copy the package that you created to the local folder of your choice, or send them directly to the .NET developer.

Back to Top

The Magic Square Example

Magic Square Example: Integrating Your .NET Component In a C# Application

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS