17.8 Predefined Interop Support Attributes

The FCL provides a set of attributes you can use to mark up your objects with information that is used by the CLR marshaling services to alter their default marshaling behavior.

This section describes the most common attributes you need when interoperating with native Win32 DLLs. These attributes all exist in the System.Runtime.InteropServices namespace.

17.8.1 The DllImport Attribute

 [DllImport (dll-name   [, EntryPoint=function-name]?   [, CharSet=charset-enum]?   [, SetLastError=truefalse]?   [, ExactSpelling=truefalse]?   [, PreserveSig=truefalse]?   [, CallingConvention=callconv-enum?)]   (for methods) 

The DllImport attribute annotates an external function that defines a DLL entry point. The parameters for this attribute are as follows :

dll-name

A string specifying the name of the DLL.

function-name

A string specifying the function name in the DLL. This is useful if you want the name of your C# function to be different from the name of the DLL function.

charset-enum

A CharSet enum, specifying how to marshal strings. The default value is CharSet.Auto , which converts strings to ANSI characters on Win98, and to Unicode characters on WinNT.

SetLastError

If true , preserves the Win32 error info . The default is false .

ExactSpelling

If true , the EntryPoint must exactly match the function. If false , name-matching heuristics are used. The default is false .

PreserveSig

If true , the method signature is preserved exactly as it was defined. If false , an HRESULT transformation is performed (see the documentation for "PreserveSigAttribute" in Chapter 36).

callconv-enum

A CallingConvention enum, specifying the mode to use with the EntryPoint. The default is StdCall .

17.8.2 The StructLayout Attribute

 [StructLayout(layout-enum    [, Pack=packing-size]?    [, CharSet=charset-enum]?    [, Size=absolute-size?)]     (for classes, structs) 

The StructLayout attribute specifies how the data members of a class or struct should be laid out in memory. Although this attribute is commonly used when declaring structures that are passed to or returned from native DLLs, it can also define data structures suited to file and network I/O. The parameters for this attribute are as follows:

layout-enum

A LayoutKind enum, which can be sequential (which lays out fields one after the next with a minimum pack size), union (which makes all fields have an offset of 0, so long as they are value types) or explicit (which lets each field have a custom offset).

packing-size

An int specifying whether the packing size is 1, 2, 4, 8, or 16 bytes. The default value is 8.

charset-enum

A CharSet enum, specifying how to marshal strings. The default value is CharSet.Auto , which converts strings to ANSI characters on Win98, and Unicode characters on WinNT.

absolute-size

Specifies the size of the struct or class. This has to be at least as large as the sum of all the members.

17.8.3 The FieldOffset Attribute

 [FieldOffset (byte-offset)]  (for fields) 

The FieldOffset attribute is used within a class or struct that has explicit field layout. This attribute can be applied to a field and specifies the field offset in bytes from the start of the class or struct. Note that these offsets don't have to be strictly increasing and can overlap, thus creating a union data structure.

17.8.4 The MarshalAs Attribute

 [MarshalAs(unmanaged-type)    [, named-parameters]?] (for fields, parameters, return values) 

The MarshalAs attribute overrides the default marshaling behavior the marshaler applies to a parameter or field. The unmanaged-type value is taken from the UnmanagedType enum; see the following list for the permissible values:

Bool	LPStr	VBByRefStr
I1	LPWStr	AnsiBStr
U1	LPTStr	TBStr
I2	ByValTStr	VariantBool
U2	IUnknown	FunctionPtr
I4	IDispatch	LPVoid
U4	Struct	AsAny
I8	Interface	RPrecise
U8	SafeArray	LPArray
R4	ByValArray	LPStruct
R8	SysInt	CustomMarshaler
BStr	SysUInt	NativeTypeMax
Error

For a detailed description of how and when to use each of these enum values, as well as other legal named parameters , see the .NET Framework SDK documentation.

17.8.5 The In Attribute

 [In]  (for parameters) 

The In attribute specifies that data should be marshaled into the caller and can be combined with the Out attribute.

17.8.6 The Out Attribute

 [Out]  (for parameters) 

The Out attribute specifies that data should be marshaled out from the called method to the caller and can be combined with the In attribute.