Creazione di prototipi nel codice gestito

Articolo
08/11/2011

In questo argomento viene descritto come accedere alle funzioni non gestite e vengono illustrati diversi campi di attributi che caratterizzano la definizione di metodi nel codice gestito. Per esempi della costruzione di dichiarazioni basate su .NET da utilizzare con platform invoke, vedere Marshalling dei dati con platform invoke.

Prima di poter accedere a una funzione di DLL non gestita da codice gestito, è necessario conoscere il nome della funzione e il nome della DLL che la esporta. Una volta in possesso di queste informazioni, si potrà iniziare a scrivere la definizione gestita di una funzione non gestita implementata in una DLL. È inoltre possibile intervenire sul modo in cui viene creata la funzione e viene eseguito il marshalling dei dati da e verso la funzione con pInvoke.

Nota
Le funzioni dell'API Win32 con cui viene allocata una stringa consentono di liberare la stringa utilizzando un metodo quale LocalFree.Platform invoke gestisce tali parametri in maniera differente.Per le chiamate pInvoke, utilizzare come parametro un tipo IntPtr anziché un tipo String.Utilizzare i metodi forniti dalla classe System.Runtime.InteropServices.Marshal per convertire manualmente il tipo in una stringa e liberarla manualmente.

Le funzioni dell'API Win32 con cui viene allocata una stringa consentono di liberare la stringa utilizzando un metodo quale LocalFree.Platform invoke gestisce tali parametri in maniera differente.Per le chiamate pInvoke, utilizzare come parametro un tipo IntPtr anziché un tipo String.Utilizzare i metodi forniti dalla classe System.Runtime.InteropServices.Marshal per convertire manualmente il tipo in una stringa e liberarla manualmente.

Nozioni di base sulla dichiarazione

Le definizioni gestite delle funzioni non gestite sono dipendenti dal linguaggio, come si vede negli esempi che seguono. Per esempi di codice più completi, vedere Esempi di platform invoke.

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

Per applicare i campi BestFitMapping, CallingConvention, ExactSpelling, PreserveSig, SetLastError o ThrowOnUnmappableChar a una dichiarazione di Microsoft Visual Basic 2005, è necessario utilizzare l'attributo DllImportAttribute anziché l'istruzione 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);

Modifica della definizione

Indipendentemente dal fatto che vengano impostati in modo esplicito o meno, i campi di attributi definiscono il comportamento del codice gestito. Il funzionamento di platform invoke dipende dai valori predefiniti impostati in diversi campi inclusi come metadati in un assembly. È possibile modificare tale comportamento predefinito modificando i valori di uno o più campi. In molti casi utilizzare il campo DllImportAttribute per impostare un valore.

Nella tabella riportata di seguito viene elencato l'insieme completo dei campi di attributi relativi a platform invoke. La tabella include, per ciascun campo, il valore predefinito e un rimando a informazioni su come utilizzare i campi per definire le funzioni di DLL non gestite.

Campo	Descrizione
BestFitMapping	Attiva o disabilita il mapping per adattamento.
CallingConvention	Specifica la convenzione di chiamata da utilizzare per passare gli argomenti del metodo. Il valore predefinito è WinAPI, che corrisponde a __stdcall per le piattaforme Intel a 32 bit.
CharSet	Controlla l'alterazione dei nomi e il modo in cui deve essere effettuato il marshalling degli argomenti stringa passati alla funzione. Il valore predefinito è CharSet.Ansi.
EntryPoint	Specifica il punto di ingresso della DLL da chiamare.
ExactSpelling	Controlla se è opportuno modificare un punto di ingresso sulla base del set di caratteri. Il valore predefinito cambia a seconda del linguaggio di programmazione.
PreserveSig	Controlla se è opportuno trasformare la firma gestita del metodo in una firma non gestita che restituisce un HRESULT e dispone di un argomento [out, retval] aggiuntivo per il valore restituito. L'impostazione predefinita è true, in base alla quale la firma non deve essere trasformata.
SetLastError	Consente al chiamante di utilizzare la funzione API Marshal.GetLastWin32Error per determinare se si è verificato un errore durante l'esecuzione del metodo. In Visual Basic, l'impostazione predefinita è true, mentre in C# e in C++ è false.
ThrowOnUnmappableChar	Controlla la generazione di un'eccezione per un carattere Unicode di cui non è possibile eseguire il mapping e che viene convertito in un carattere "?" ANSI.