Crear prototipos en código administrado

Artículo
08/23/2008

Actualización: noviembre 2007

En este tema se describe la forma de obtener acceso a las funciones no administradas y se presentan varios campos de atributo que anotan la definición de métodos en código administrado. Para obtener ejemplos que muestren cómo construir declaraciones .NET que se utilizan con la invocación de plataforma, vea Calcular referencias de datos con invocación de plataforma.

Para poder tener acceso a una función no administrada de un archivo DLL desde el código administrado, es necesario conocer el nombre de la función y el del archivo DLL que la exporta. Con esta información, se puede empezar a escribir la definición administrada de una función no administrada que se implemente en una DLL. Además, se puede ajustar el modo en que la invocación de plataforma crea la función y calcula las referencias a los datos desde la función y hacia la función.

Nota:
Las funciones de la API de Win32 que asignan una cadena le permiten liberar la cadena utilizando un método como LocalFree. La invocación de plataforma controla estos parámetros de forma distinta. Para las llamadas de invocación de plataforma, haga que el parámetro sea de tipo IntPtr en lugar de String. Utilice los métodos proporcionados por la clase System.Runtime.InteropServices.Marshal para convertir el tipo en una cadena y liberarla manualmente.

Las funciones de la API de Win32 que asignan una cadena le permiten liberar la cadena utilizando un método como LocalFree. La invocación de plataforma controla estos parámetros de forma distinta. Para las llamadas de invocación de plataforma, haga que el parámetro sea de tipo IntPtr en lugar de String. Utilice los métodos proporcionados por la clase System.Runtime.InteropServices.Marshal para convertir el tipo en una cadena y liberarla manualmente.

Conceptos básicos de declaración

Las definiciones administradas de funciones no administradas dependen del lenguaje, tal y como se puede observar en los siguientes ejemplos. Para obtener ejemplos de código más completos, vea Ejemplos de invocación de plataforma.

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

Para aplicar los campos BestFitMapping, CallingConvention, ExactSpelling, PreserveSig, SetLastError o ThrowOnUnmappableChar a una declaración Microsoft Visual Basic 2005, debe utilizar el atributo DllImportAttribute en lugar de la instrucción Declare.

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);

Ajustar la definición

Los campos de atributo, tanto si se establecen de forma explícita como si no, se encargan de definir el comportamiento del código administrado. La invocación de plataforma funciona según los valores predeterminados establecidos en varios campos que existen en forma de metadatos en un ensamblado. Es posible modificar este comportamiento predeterminado ajustando los valores de uno o varios campos. En muchos casos, se puede utilizar DllImportAttribute para establecer un valor.

En la siguiente tabla se enumeran todos los campos de atributo relacionados con la invocación de plataforma. Para cada campo, la tabla incluye el valor predeterminado y un vínculo a la información sobre la forma de utilizar los campos para definir funciones no administradas de archivos DLL.

Campo	Descripción
BestFitMapping	Habilita o deshabilita la asignación de ajuste perfecto.
CallingConvention	Especifica las convenciones de llamada utilizadas al pasar argumentos de método. El valor predeterminado es WinAPI, que corresponde a __stdcall en las plataformas de 32 bits de Intel.
CharSet	Controla la mutilación de nombres y la forma en que se deben calcular las referencias a los argumentos de cadena en la función. El valor predeterminado es CharSet.Ansi.
EntryPoint	Especifica el punto de entrada del archivo DLL que se va a llamar.
ExactSpelling	Controla si un punto de entrada debe modificarse para que se corresponda con el juego de caracteres. El valor predeterminado cambia según el lenguaje de programación.
PreserveSig	Controla si el prototipo administrado del método debería transformarse en un prototipo no administrado que devuelva un resultado HRESULT y que pueda tener un argumento adicional [out, retval] para el valor devuelto. El valor predeterminado es true (la firma no debe transformarse).
SetLastError	Habilita el llamador para usar la función API Marshal.GetLastWin32Error con el fin de determinar si se produjo un error mientras se ejecutaba el método. En Visual Basic, el valor predeterminado es true; en C# y C++, es false.
ThrowOnUnmappableChar	Controla el inicio de una excepción en un carácter Unicode que no se puede asignar y que se convierte en un carácter ANSI "?".