Handle Data Returned from .NET Objects

These tables show how MATLAB^® maps C# .NET types to MATLAB types. For information about passing MATLAB data types to .NET methods, see Pass Data to .NET Objects.

.NET Type to MATLAB Type Mapping

MATLAB automatically converts data from a .NET object into these MATLAB types. These values are displayed in a method signature.

C# .NET Type	MATLAB Type
`System.Int16`	`int16` scalar
`System.UInt16`	`uint16` scalar
`System.Int32`	`int32` scalar
`System.UInt32`	`uint32` scalar
`System.Int64`	`int64` scalar
`System.UInt64`	`uint64` scalar
`System.Single`	`single` scalar
`System.Double`	`double` scalar
`System.Boolean`	`logical` scalar
`System.Byte`	`uint8` scalar
`System.Enum`	`enum`
`System.Char`	`char`
`System.Decimal`	`System.Decimal`
`System.Object`	`System.Object`
`System.IntPtr`	`System.IntPtr`
`System.UIntPtr`	`System.UIntPtr`
`System.String`	`System.String`
`System.Nullable<ValueType>`	`System.Nullable<ValueType>`
`System.Array`	See Use Arrays with .NET Applications
`System.__ComObject`	See How MATLAB Handles System.__ComObject
`class name`	`class name`
`struct name`	`struct name`

Convert Arrays of Primitive .NET Type to MATLAB Type

To convert elements of a .NET array to an equivalent MATLAB array, call these MATLAB functions. For an example, see Convert Primitive .NET Arrays to MATLAB Arrays.

C# .NET Type	MATLAB Conversion Function
`System.Int16`	`int16`
`System.UInt16`	`uint16`
`System.Int32`	`int32`
`System.UInt32`	`uint32`
`System.Int64`	`int64`
`System.UInt64`	`uint64`
`System.Single`	`single`
`System.Double`	`double`
`System.Boolean`	`logical`
`System.Byte`	`uint8`

How MATLAB Handles System.String

To convert a System.String object to a MATLAB string, use the string function. To convert a System.String object to a MATLAB character array, use the char function. For example:

str = System.String('create a System.String');
mlstr = string(str)
mlchar = char(str)

mlstr = 

    "create a System.String"


mlchar =

    'create a System.String'

MATLAB displays the string value of System.String objects, instead of the standard object display. For example, type:

a = System.String('test')
b = System.String.Concat(a,' hello',' world')

a = 
test
b = 
test hello world

The System.String class illustrates how MATLAB handles fields and properties, as described in Call .NET Properties That Take an Argument. To see reference information about the class, search for the term System.String in the documentation for a .NET class library, as described in To Learn More About .NET.

The string function converts String.String arrays (String.String[], String.String[,], etcetera) to MATLAB string arrays with the same dimensions and sizes. Conversion of jagged arrays, for example String.String[][], is not supported.

How MATLAB Handles .NET Dictionary Objects

You can convert objects which implement the System.Collections.Generic.IDictionary<,> interface to a MATLAB dictionary type by calling the dictionary function of the object. The syntax is:

d = dictionary(netDict)

where netDict is a .NET object whose type implements the IDictionary<> interface. The keys and values of d are determined by the default conversion rules described in .NET Type to MATLAB Type Mapping.

Create a MATLAB dictionary from a generic .NET dictionary mapping `System.Int32` to `System.Double`

Instantiate a .NET Dictionary that maps System.Int32 to System.Double.

netDict = NET.createGeneric( "System.Collections.Generic.Dictionary", ...
    {"System.Int32", "System.Double"} );

Add three elements to the .NET Dictionary.

netDict.Add(1, 1.1);
netDict.Add(2, 2.2);
netDict.Add(3, 3.3);
netDict

netDict =
  Dictionary<System*Int32,System*Double> with properties:
 
    Comparer: [1×1 System.Collections.Generic.GenericEqualityComparer<System*Int32>]
       Count: 3
        Keys: [1×1 System.Collections.Generic.Dictionary*KeyCollection<System*Int32,System*Double>]
      Values: [1×1 System.Collections.Generic.Dictionary*ValueCollection<System*Int32,System*Double>]

Convert the .NET Dictionary to a MATLAB dictionary, where System.Int32 maps to int32 and System.Double maps to double.

d = dictionary(netDict)

d =
  dictionary (int32 ⟼ double) with 3 entries:
    1 ⟼ 1.1
    2 ⟼ 2.2
    3 ⟼ 3.3

Create MATLAB dictionaries from a generic .NET `ConcurrentDictionary` mapping `System.Char` to `System.String`

Instantiate a .NET ConcurrentDictionary that maps System.Char to System.String.

netDict = NET.createGeneric( "System.Collections.Concurrent.ConcurrentDictionary", ...
    {"System.Char", "System.String"} );

Add three elements to the .NET ConcurrentDictionary.

netDict.Add('a', "aaa");
netDict.Add('b', "bbb");
netDict.Add('c', "ccc");
netDict

netDict =
  ConcurrentDictionary<System*Char,System*String> with properties:
 
    Comparer: [1×1 System.Collections.Concurrent.GenericEqualityComparer<System*Char>]
       Count: 3
        Keys: [1×1 System.Collections.Concurrent.ConcurrentDictionary*KeyCollection<System*Char,System*String>]
      Values: [1×1 System.Collections.Concurrent.ConcurrentDictionary*ValueCollection<System*Char,System*String>]

Convert the .NET ConcurrentDictionary to a MATLAB dictionary, where System.Char maps to char (which converts to string in dictionaries) and System.String maps to System.String.

d = dictionary(netDict)

d =
  dictionary (string ⟼ System.String) with 3 entries:
    "a" ⟼ "aaa"
    "b" ⟼ "bbb"
    "c" ⟼ "ccc"

Change the type of the dictionary values to a MATLAB string.

d = dictionary( keys(d), string(values(d, "cell")) )

d =
  dictionary (string ⟼ string) with 3 entries:
    "a" ⟼ "aaa"
    "b" ⟼ "bbb"
    "c" ⟼ "ccc"

Create a MATLAB dictionary from a generic .NET `SortedDictionary` mapping `System.Type` to `System.Double[]`

Instantiate a .NET SortedDictionary that maps System.Type to System.Double[].

netDict = NET.createGeneric( "System.Collections.Generic.SortedDictionary", ...
    {"System.Type", "System.Double[]"} );

Add three elements to the .NET SortedDictionary.

netDict.Add( System.Type.GetType("System.Int32"),  [1 2 3] );
netDict.Add( System.Type.GetType("System.Double"), [4 5] );
netDict.Add( System.Type.GetType("System.String"), [] );
netDict

netDict =
  ConcurrentDictionary<System*Type,System*Double[]> with properties:
 
    Comparer: [1×1 System.Collections.Generic.GenericEqualityComparer<System*Type>]
       Count: 3
        Keys: [1×1 System.Collections.Generic.SortedDictionary*KeyCollection<System*Type,System*Double[]>]
      Values: [1×1 System.Collections.Generic.SortedDictionary*ValueCollection<System*Type,System*Double[]>]

Convert the .NET SortedDictionary to a MATLAB dictionary, where System.Type maps to System.Type and System.Double[] maps to System.Double[].

d = dictionary(netDict)

d =
  dictionary (System.Type ⟼ System.Double[]) with 3 entries:
    System.Type ⟼ System.Double[]
    System.Type ⟼ System.Double[]
    System.Type ⟼ System.Double[]

Create a MATLAB dictionary from a generic .NET dictionary mapping `System.Double` to `System.Object`

Instantiate a .NET Dictionary that maps System.Double to System.Object.

netDict = NET.createGeneric( "System.Collections.Generic.Dictionary", ...
    {"System.Double", "System.Object"} );

Add three elements to the .NET Dictionary.

netDict.Add(1, 1);
netDict.Add(2, [1 2 3 4]);
netDict.Add(3, System.DateTime.Now);
netDict

netDict = 
  Dictionary<System*Double,System*Object> with properties:

    Comparer: [1×1 System.Collections.Generic.GenericEqualityComparer<System*Double>]
       Count: 3
        Keys: [1×1 System.Collections.Generic.Dictionary*KeyCollection<System*Double,System*Object>]
      Values: [1×1 System.Collections.Generic.Dictionary*ValueCollection<System*Double,System*Object>]

Convert the .NET Dictionary to a MATLAB dictionary, where System.Double maps to double and System.Object maps to cell.

d = dictionary(netDict)

d =

  dictionary (double ⟼ cell) with 3 entries:

    1 ⟼ {[1]}
    2 ⟼ {1×1 System.Double[]}
    3 ⟼ {1×1 System.DateTime}

How MATLAB Handles System.__ComObject

The System.__ComObject type represents a Microsoft^® COM object. It is a non-visible, public class in the mscorlib assembly with no public methods. Under certain circumstances, a .NET object returns an instance of System.__ComObject. MATLAB handles the System.__ComObject based on the return types defined in the metadata.

MATLAB Converts Object

If the return type of a method or property is strongly typed, and the result of the invocation is System.__ComObject, MATLAB automatically converts the returned object to the appropriate type.

For example, suppose that your assembly defines a type, TestType, and provides a method, GetTestType, with the following signature.

Return Type	Name	Arguments
`NetDocTest.TestType RetVal`	`GetTestType`	`(NetDocTest.MyClass this)`

The return type of GetTestType is strongly typed and .NET returns an object of type System.__ComObject. MATLAB automatically converts the object to the appropriate type, NetDocTest.TestType, shown in the following pseudo-code:

cls = NetDocTest.MyClass;
var = GetTestType(cls)

var = 

  TestType handle with no properties.

Casting Object to Appropriate Type

If the return type of a method or property is System.Object, and the result of the invocation is System.__ComObject, MATLAB returns System.__ComObject. To use the returned object, cast it to a valid class or interface type. Use your product documentation to identify the valid types for this object.

To call a member of the new type, cast the object using the MATLAB conversion syntax:

objConverted = namespace.classname(obj)

where obj is a System.__ComObject type.

For example, an item in a Microsoft Excel^® sheet collection can be a chart or a worksheet. The following command converts the System.__ComObject variable mySheet to a Chart or a Worksheet object newSheet:

newSheet = Microsoft.Office.Interop.Excel.interfacename(mySheet);

where interfacename is Chart or Worksheet. For an example, see Work with Microsoft Excel Spreadsheets Using .NET.

Pass a COM Object Between Processes

If you pass a COM object to or from a function, lock the object so that MATLAB does not automatically release it when the object goes out of scope. To lock the object, call the NET.disableAutoRelease function. Then unlock the object, using the NET.enableAutoRelease function, after you are through using it.

How MATLAB Handles System.Nullable

If .NET returns a System.Nullable type, MATLAB returns the corresponding System.Nullable type.

A System.Nullable type lets you assign null values to types, such as numeric types, that do not support null value. To use a System.Nullable object in MATLAB, first decide how to handle null values.

If you want to process null values differently from <ValueType> values, use the HasValue property.
If you want every value to be of the underlying <ValueType>, use the GetValueOrDefault method. This method assigns a default value of type <ValueType> to null values.

Use a variable of the object's underlying type where appropriate in any MATLAB expression. For examples, see Pass System.Nullable Arguments.

How MATLAB Handles dynamic Type

MATLAB handles dynamic types as System.Object. For example, the following C# method exampleMethod has a dynamic input argument d and returns a dynamic output value:

public dynamic exampleMethod(dynamic d)

The following table shows the corresponding MATLAB function signature.

Return Type	Name	Arguments
`System.Object RetVal`	`exampleMethod`	`(namespace.classname this, System.Object d)`

How MATLAB Handles Jagged Arrays

You must convert a .NET jagged array before using it in a MATLAB command. To convert:

If the shape of the array is rectangular, use the corresponding MATLAB numeric function.
If the array is not rectangular, use the cell function.

If the jagged array is multidimensional, you must individually convert the arrays in each dimension.