Creating Prototypes in Managed Code

This topic describes how to access unmanaged functions and introduces several attribute fields that annotate method definition in managed code. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see Marshaling Data with Platform Invoke.

Before you can access an unmanaged DLL function from managed code, you need to know the name of the function and the name of the DLL that exports it. With this information, you can begin to write the managed definition for an unmanaged function that is implemented in a DLL. Furthermore, you can adjust the way that platform invoke creates the function and marshals data to and from the function.

Note
Win32 API functions that allocate a string enable you to free the string by using a method such as LocalFree. Platform invoke handles such parameters differently. For platform invoke calls, make the parameter an IntPtr type instead of a String type. Use methods that are provided by the System.Runtime.InteropServices.Marshal class to convert the type to a string manually and free it manually.

Declaration Basics

Managed definitions to unmanaged functions are language-dependent, as you can see in the following examples. For more complete code examples, see Platform Invoke Examples.

Imports System.Runtime.InteropServices
Public Class Win32
    Declare Auto Function MessageBox Lib "user32.dll" _
       (ByVal hWnd As Integer, _
        ByVal txt As String, ByVal caption As String, _
        ByVal Typ As Integer) As IntPtr
End Class

To apply the BestFitMapping, CallingConvention, ExactSpelling, PreserveSig, SetLastError, or ThrowOnUnmappableChar fields to a Microsoft Visual Basic 2005 declaration, you must use the DllImportAttribute attribute instead of the Declare statement.

Imports System.Runtime.InteropServices
Public Class Win32
   <DllImport ("user32.dll", CharSet := CharSet.Auto)> _
   Public Shared Function MessageBox (ByVal hWnd As Integer, _
        ByVal txt As String, ByVal caption As String, _
        ByVal Typ As Integer) As IntPtr
   End Function
End Class

using System.Runtime.InteropServices;
[DllImport("user32.dll")]
    public static extern IntPtr MessageBox(int hWnd, String text, 
                                       String caption, uint type);

using namespace System::Runtime::InteropServices;
[DllImport("user32.dll")]
    extern "C" IntPtr MessageBox(int hWnd, String* pText,
    String* pCaption unsigned int uType);

Adjusting the Definition

Whether you set them explicitly or not, attribute fields are at work defining the behavior of managed code. Platform invoke operates according to the default values set on various fields that exist as metadata in an assembly. You can alter this default behavior by adjusting the values of one or more fields. In many cases, you use the DllImportAttribute to set a value.

The following table lists the complete set of attribute fields that pertain to platform invoke. For each field, the table includes the default value and a link to information on how to use these fields to define unmanaged DLL functions.

Field	Description
BestFitMapping	Enables or disables best-fit mapping.
CallingConvention	Specifies the calling convention to use in passing method arguments. The default is WinAPI, which corresponds to __stdcall for the 32-bit Intel-based platforms.
CharSet	Controls name mangling and the way that string arguments should be marshaled to the function. The default is CharSet.Ansi.
EntryPoint	Specifies the DLL entry point to be called.
ExactSpelling	Controls whether an entry point should be modified to correspond to the character set. The default value varies by programming language.
PreserveSig	Controls whether the managed method signature should be transformed into an unmanaged signature that returns an HRESULT and has an additional [out, retval] argument for the return value. The default is true (the signature should not be transformed).
SetLastError	Enables the caller to use the Marshal.GetLastWin32Error API function to determine whether an error occurred while executing the method. In Visual Basic, the default is true; in C# and C++, the default is false.
ThrowOnUnmappableChar	Controls throwing of an exception on an unmappable Unicode character that is converted to an ANSI "?" character.

For detailed reference information, see DllImportAttribute Class.

See Also

Concepts

Consuming Unmanaged DLL Functions

Specifying an Entry Point

Specifying a Character Set

Platform Invoke Examples

Platform Invoke Security Considerations

Identifying Functions in DLLs

Creating a Class to Hold DLL Functions

Other Resources

Calling a DLL Function