Getting Started with .NET

On this page…
What is an Assembly? .NET Terminology Simplifying .NET Class Names Loading .NET Assemblies into MATLAB Handling Exceptions Working With Nested Classes

What is an Assembly?

Assemblies are the building blocks of .NET Framework applications; they form the fundamental unit of deployment, version control, reuse, activation scoping, and security permissions. An assembly is a collection of types and resources built to work together and form a logical unit of functionality.

To work with a .NET application, you need to make its assemblies visible to MATLAB. How you do this depends on how the assembly is deployed, either privately or globally.

• A global assembly is shared among applications and installed in a common directory, called the Global Assembly Cache (GAC).

• A private assembly is used by a single application.

To load a global assembly into MATLAB, use the short name of the assembly, which is the file name without the extension. To load a private assembly, you need the full path (folder and file name with extension) of the assembly. This information is in the your product's vendor documentation for the assembly. Refer to the vendor documentation for everything you need to know to use your product.

The following assemblies from the .NET Framework class library are available at startup. MATLAB dynamically loads them the first time you type "NET." or "System.".

• mscorlib.dll

• system.dll

To use any other .NET assembly, load the assembly using the NET.addAssembly command. After loading the assembly, you can work with the classes defined by the assembly.

For an example showing you how to find the information you need to work with assemblies, see:

• Access a Simple .NET Class

For detailed information, see:

• Loading .NET Assemblies into MATLAB

• Using a .NET Object

Back to Top

.NET Terminology

A namespace is a way to group identifiers. A namespace can contain other namespaces. In MATLAB, a namespace is a package. In MATLAB, a .NET type is a class.

The syntax namespace.ClassName is known as a fully qualified name.

.NET Framework System Namespace

System is the root namespace for fundamental types in the .NET Framework. This namespace also contains classes (for example, System.String and System.Array) and second-level namespaces (for example, System.Collections.Generic). The mscorlib and system assemblies, which MATLAB loads at startup, contain many, but not all System namespaces. For example, to use classes in the System.Xml namespace, load the system.xml assembly using the NET.addAssembly command. Refer to the Microsoft .NET Framework Class Library Reference to learn what assembly to use for a specific namespace.

Reference Type Versus Value Type

Objects created from .NET classes (for example, the System.Reflection.Assembly class) appear in MATLAB as reference types, or handle objects. Objects created from .NET structures (for example, the System.DateTime structure) appear as value types. You use the same MATLAB syntax to create and access members of classes and structures.

However, handle objects are different from value objects. When you copy a handle object, only the handle is copied and both the old and new handles refer to the same data. When you copy a value object, the object's data is also copied and the new object is independent of changes to the original object. For more information about these differences, see Copying Objects.

Do not confuse an object created from a .NET structure with a MATLAB structure array (see Structures). You cannot pass a structure array to a .NET method.

Back to Top

Simplifying .NET Class Names

In a MATLAB command, you can refer to any class by its fully qualified name, which includes its package name. A fully qualified name might be long, making commands and functions, such as constructors, cumbersome to edit and to read. You can refer to classes by the class name alone (without a package name) if you first import the fully qualified name into MATLAB. The import function adds all classes that you import to a list called the import list. You can see what classes are on that list by typing import, without any arguments.

For example, to eliminate the need to type System. before every command in the Access a Simple .NET Class example, type:

import System.*
import System.DateTime.*

To create the object, type:

dateObj = DateTime.Today;

To use a static method, type:

DaysInMonth(dateObj.Year, dateObj.Month)

Using import in MATLAB Functions

If you use the import command in a MATLAB function, you must add the corresponding .NET assembly before calling the function. For example, the following function getPrinterInfo calls methods in the System.Drawing namespace.

function ptr = getPrinterInfo
import System.Drawing.Printing.*;
ptr = PrinterSettings;
end

To call the function, type:

NET.addAssembly('System.Drawing');
printer = getPrinterInfo;

You cannot add the command NET.addAssembly('System.Drawing') to the getPrinterInfo function. MATLAB processes the getPrinterInfo.m code before executing the NET.addAssembly command. In that case, PrinterSettings is not fully-qualified and MATLAB does not recognize the name.

Likewise, the scope of the import command is limited to the getPrinterInfo function. At the command line, type:

ptr = PrinterSettings;

Undefined function or variable 'PrinterSettings'.

Back to Top

Loading .NET Assemblies into MATLAB

If MATLAB does not automatically load your assembly, use the NET.addAssembly function. The syntax is:

asmInfo = NET.addAssembly('assemblyName');

You need to know if the assembly is global or private, as explained in What is an Assembly? Your vendor documentation has this information.

You cannot unload an assembly from MATLAB.

Back to Top

Handling Exceptions

MATLAB catches exceptions thrown by .NET and converts them into a NET.NetException object, which is derived from the MException class. The default display of NetException contains the Message, Source and HelpLink fields of the System.Exception class that caused the exception. For example:

try
  NET.addAssembly('C:\Work\invalidfile.dll')
catch e
  e.message
  if(isa(e,'NET.NetException'))
    e.ExceptionObject
  end
end

Back to Top

Working With Nested Classes

In MATLAB, you cannot directly instantiate a nested class but here is how to do it through reflection. The following C# code defines InnerClass nested in OuterClass:

namespace MyClassLibrary
{
  public class OuterClass
  {
      public class InnerClass
      {
          public String strmethod(String x)
          {
              return "from InnerClass " + x;
          }
       }
   }
}

If the MyClassLibrary assembly is in your c:\work folder, load the file:

a = NET.addAssembly('C:\Work\MyClassLibrary.dll');
a.Classes

ans = 
    'MyClassLibrary.OuterClass'
    'MyClassLibrary.OuterClass+InnerClass'

To call strmethod, type:

t = a.AssemblyHandle.GetType('MyClassLibrary.OuterClass+InnerClass');
obj = System.Activator.CreateInstance(t);
strmethod(obj,'hello')

ans = 
from InnerClass hello

Back to Top

Overview Using .NET from MATLAB

Using a .NET Object

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