Interoperability - The ComAliasName attribute

Interoperability

The attributes described in this chapter are used for creating programs that interoperate with COM programs.

The ComAliasName attribute

namespace System.Runtime.InteropServices

public string Value }
}
}

The ComImport attribute

When placed on a class, the ComImport attribute marks the class as an externally implemented Com class. Such a class declaration enables the use of a C# name to refer to a COM class.

namespace System.Runtime.InteropServices

}
}

A class that is decorated with the ComImport attribute is subject to the following restrictions:

It must also be decorated with the Guid attribute, which specifies the CLSID for the COM class being imported. A compile-time error occurs if a class declaration includes the ComImport attribute but fails to include the Guid attribute.

It must not have any members. (A public constructor with no parameters is automatically provided.)

It must not derive from a class other than object.

The example

using System.Runtime.InteropServices;

[ComImport, Guid('00020810-0000-0000-C000-000000000046')]
class Worksheet

class Test

}

declares a class Worksheet as a class imported from COM that has a CLSID of "00020810-0000-0000-C000-000000000046". Instantiating a Worksheet instance causes a corresponding COM instantiation.

The ComRegisterFunction attribute

The presence of the ComRegisterFunction attribute on a method indicates that the method should be called during the COM registration process.

namespace System.Runtime.InteropServices

}
}

The ComSourceInterfaces attribute

The ComSourceInterfaces attribute is used to list the source interfaces on the imported coclass.

namespace System.Runtime.InteropServices

public string Value }
}
}

The ComUnregisterFunction attribute

The presence of the ComUnregisterFunction attribute on a method indicates that the method should be called when the assembly is unregistered for use in COM.

namespace System.Runtime.InteropServices

}
}

The ComVisible attribute

The ComVisible attribute is used to specify whether or not a class or interface is visible in COM.

namespace System.Runtime.InteropServices

public bool Value }
}
}

The DispId attribute

The DispId attribute is used to specify an OLE Automation DISPID. A DISPID is an integral value that identifies a member in a dispinterface.

namespace System.Runtime.InteropServices

public int Value }
}
}

The DllImport attribute

The DllImport attribute is used to specify the dll location that contains the implementation of an extern method.

namespace System.Runtime.InteropServices

public CallingConvention CallingConvention;

public CharSet CharSet;

public string EntryPoint;

public bool ExactSpelling;

public bool PreserveSig;

public bool SetLastError;

public string Value }

}
}

Specifically, the DllImport attribute has the following behaviors:

It can only be placed on method declarations.

It has a single positional parameter: a dllName parameter that specifies name of the dll in which the imported method can be found.

It has five named parameters:

The CallingConvention parameter indicates the calling convention for the entry point. If no CallingConvention is specified, a default of CallingConvention.Winapi is used.

The CharSet parameter indicates the character set used in the entry point. If no CharSet is specified, a default of CharSet.Auto is used.

The EntryPoint parameter gives the name of the entry point in the dll. If no EntryPoint is specified, then the name of the method itself is used.

The ExactSpelling parameter indicates whether EntryPoint must exactly match the spelling of the indicated entry point. If no ExactSpelling is specified, a default of false is used.

The PreserveSig parameter indicates whether the signature of the method should be preserved or transformed. When a signature is transformed, it is transformed to one having an HRESULT return value and an additional out parameter named retval for the return value. If no PreserveSig value is specified, a default of true is used.

The SetLastError parameter indicates whether the method preserves the Win32 "last error". If no SetLastError is specified, a default of false is used.

It is a single-use attribute class.

In addition, a method that is decorated with the DllImport attribute must have the extern modifier.

The FieldOffset attribute

The FieldOffset attribute is used to specify the layout of fields for the struct.

namespace System.Runtime.InteropServices

public int Value }
}
}

The FieldOffset attribute may not be placed on a field declarations that is a member of a class.

The Guid attribute

The Guid attribute is used to specify a globally unique identifier (GUID) for a class or an interface. This information is primarily useful for interoperability with COM.

namespace System.Runtime.InteropServices

public string Value }
}
}

The format of the positional string argument is verified at compile-time. It is an error to specify a string argument that is not a syntactically valid GUID.

The HasDefaultInterface attribute

If present, the HasDefaultInterface attribute indicates that a class has a default interface.

namespace System.Runtime.InteropServices

}
}

The ImportedFromTypeLib attribute

The ImportedFromTypeLib attribute is used to specify that an assembly was imported from a COM type library.

namespace System.Runtime.InteropServices

public string Value }

}
}

The In and Out attributes

The In and Out attributes are used to provide custom marshalling information for parameters. All combinations of these marshalling attributes are permitted.

namespace System.Runtime.InteropServices

}

[AttributeUsage(AttributeTargets.Parameter)]
public class OutAttribute: System.Attribute

}
}

If a parameter is not decorated with either marshalling attribute, then it is marshalled based on the its parameter-modifiers, as follows. If the parameter has no modifiers then the marshalling is [In]. If the parameter has the ref modifier then the marshalling is [In, Out]. If the parameter has the out modifier then the marshalling is [Out].

Note that out is a keyword, and Out is an attribute. The example

class Class1

}

shows that the use of out as a parameter-modifier and the use of Out in an attribute.

The IndexerName attribute

Indexers are implemented in some systems using indexed properties. If no IndexerName attribute is present for an indexer, then the name Item is used by default. The IndexerName attribute enables a developer to override this default and specify a different name.

namespace System.Runtime.CompilerServices.CSharp

public string Value }
}
}

The InterfaceType attribute

When placed on an interface, the InterfaceType attribute specifies the manner in which the interface is treated in COM.

namespace System.Runtime.InteropServices

public ComInterfaceType Value }
}
}

The MarshalAs attribute

The MarshalAs attribute is used to describe the marshalling format for a field, method, or parameter.

namespace System.Runtime.InteropServices

public UnmanagedType ArraySubType;

public string MarshalCookie;

public string MarshalType;

public VarEnum SafeArraySubType;

public int SizeConst;

public short SizeParamIndex;

public int SizeParamMultiplier;
}
}

The NoIDispatch attribute

The presence of the NoIDispatch attribute indicates that the class or interface should derive from IUnknown rather than IDispatch when exported to COM.

namespace System.Runtime.InteropServices

}
}

The PreserveSig attribute

The PreserveSig attribute is used to indicate that the HRESULT/retval signature transformation that normally takes place during interoperability calls should be suppressed.

namespace System.Runtime.InteropServices

public bool Value }
}
}

The StructLayout attribute

The StructLayout attribute is used to specify the layout of fields for the struct.

namespace System.Runtime.InteropServices

public CharSet CharSet;

public bool CheckFastMarshal;

public int Pack;

public LayoutKind Value }
}
}

If LayoutKind.Explicit is specified, then every field in the struct must have the FieldOffset attribute. If LayoutKind.Explicit is not specified, then use of the FieldOffset attribute is prohibited.

The TypeLibFunc attribute

The TypeLibFunc attribute is used to specify typelib flags, for interoperability with COM.

namespace System.Runtime.InteropServices

public TypeLibFuncFlags Value }
}
}

The TypeLibType attribute

The TypeLibType attribute is used to specify typelib flags, for interoperability with COM.

namespace System.Runtime.InteropServices

public TypeLibTypeFlags Value }
}
}

The TypeLibVar attribute

The TypeLibVar attribute is used to specify typelib flags, for interoperability with COM.

namespace System.Runtime.InteropServices

public TypeLibVarFlags Value }
}
}

Supporting enums

namespace System.Runtime.InteropServices

public enum CharSet

public enum ComInterfaceType

public enum LayoutKind

public enum TypeLibFuncFlags

public enum TypeLibTypeFlags

public enum TypeLibVarFlags

public enum UnmanagedType

}