Handle Data Returned from .NET Objects

When you call a .NET method or function from MATLAB®, MATLAB automatically converts returned .NET scalar data into a MATLAB type. If the .NET function returns array data, you can explicitly convert the data into MATLAB types.

For information about passing MATLAB data to .NET methods instead, see Pass MATLAB Data to .NET Functions.

Return .NET Scalar Data to MATLAB

When a .NET function returns scalar data, MATLAB automatically converts the .NET object into these MATLAB types. This table shows how MATLAB maps C# .NET types to MATLAB types.

C# .NET TypeMATLAB Type
System.Int16int16 scalar
System.UInt16uint16 scalar
System.Int32int32 scalar
System.UInt32uint32 scalar
System.Int64int64 scalar
System.UInt64uint64 scalar
System.Singlesingle scalar
System.Doubledouble scalar
System.Booleanlogical scalar
System.Byteuint8 scalar
System.Enumenum
System.Charchar
System.DecimalSystem.Decimal
System.ObjectSystem.Object
System.IntPtrSystem.IntPtr
System.UIntPtrSystem.UIntPtr
System.StringSystem.String
System.Collections.Generic.IDictionary<,>System.Collections.Generic.IDictionary<,>
See Convert .NET Dictionary to MATLAB Dictionary.
System.Nullable<ValueType>System.Nullable<ValueType>
See Pass System.Nullable Arguments.
System.__ComObject

See How MATLAB Handles System.__ComObject

class nameclass name
struct namestruct name
dynamic typesSystem.Object

Convert Arrays of Primitive .NET Type to MATLAB Type

When a .NET function returns array data, you can explicitly convert the .NET array to an equivalent MATLAB array calling these MATLAB functions.

C# .NET TypeMATLAB Conversion Function
System.Int16

int16

System.UInt16uint16
System.Int32int32
System.UInt32uint32
System.Int64int64
System.UInt64uint64
System.Singlesingle
System.Doubledouble
System.Booleanlogical
System.Byteuint8
System.Array

See Use MATLAB Arrays with .NET Functions

Convert System.String to MATLAB String or Character Vector

When a .NET function returns a System.String object, MATLAB does not automatically convert the data to a MATLAB type. However, MATLAB displays the string value of System.String objects, instead of the standard object display. For example:

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

a = 
test
b = 
test hello world

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

str = System.String("My System.String");
mlstr = string(str)
mlchar = char(str)

mlstr = 

    "My System.String"


mlchar =

    'My System.String'

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

How MATLAB Handles System.Decimal

To use a System.Decimal type in MATLAB, call the System.Decimal.ToDouble function. Create a System.Decimal variable:

xdec = System.Decimal(100.1)
xdec = 
  Decimal with properties:
       Scale: 1
        Zero: [1×1 System.Decimal]
         One: [1×1 System.Decimal]
    MinusOne: [1×1 System.Decimal]
    MaxValue: [1×1 System.Decimal]
    MinValue: [1×1 System.Decimal]

Convert to a MATLAB double:

xdouble = System.Decimal.ToDouble(xdec)
xdouble =
  100.1000

How MATLAB Handles System.Byte

Suppose that you have C# library function that returns an image as a System.Byte array. To use the data in MATLAB, see How to convert raw byte data from a C# library to an image?

Convert .NET Dictionary to MATLAB Dictionary

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 Return .NET Scalar Data to MATLAB.

Create MATLAB dictionary from 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 MATLAB dictionary from 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 MATLAB dictionary from 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 this signature.

Return TypeNameArguments
NetDocTest.TestType RetValGetTestType(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 this 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. This 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, this C# method exampleMethod has a dynamic input argument d and returns a dynamic output value:

public dynamic exampleMethod(dynamic d)

This table shows the corresponding MATLAB function signature.

Return TypeNameArguments
System.Object RetValexampleMethod(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.

See Also

Topics