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 implemented in a DLL. Further, 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 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. To show all languages, click the Language Filter button in the upper-left corner of the page. 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 Integer
End Class

To apply the BestFitMapping, CallingConvention, ExactSpelling, PreserveSig, or SetLastError ThrowOnUnmappableChar fields to a Microsoft Visual Basic .NET 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 Integer
   End Function
End Class
[C#]
using System.Runtime.InteropServices;
[DllImport("user32.dll")]
    public static extern int MessageBox(int hWnd, String text, 
                                       String caption, uint type);
[C++]
using namespace System::Runtime::InteropServices;
[DllImport("user32.dll")]
    extern "C" int 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	Toggles off 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

Consuming Unmanaged DLL Functions | Specifying an Entry Point | Specifying a Character Set | Platform Invoke Examples | Identifying Functions in DLLs | Creating a Class to Hold DLL Functions | Calling a DLL Function