Questo articolo è stato tradotto automaticamente. Per visualizzare l'articolo in inglese, selezionare la casella di controllo Inglese. È possibile anche visualizzare il testo inglese in una finestra popup posizionando il puntatore del mouse sopra il testo.
Traduzione
Inglese

Marshalling predefinito per i tipi di valore

La maggior parte dei tipi valore, quali gli interi e i numeri a virgola mobile, sono copiabili e non richiedono il marshalling. Altri tipi non copiabili hanno rappresentazioni diverse nella memoria gestita e non gestita e richiedono il marshalling. Per altri tipi ancora occorre una formattazione esplicita attraverso il limite di interoperabilità.

In questo argomento sono disponibili le informazioni indicate di seguito sui tipi valore:

Oltre alla descrizione dei tipi formattati, in questo argomento sono specificati i tipi di valore del sistema con un comportamento di marshalling insolito.

Un tipo formattato è un tipo complesso contenente informazioni che controllano in modo esplicito il layout dei membri in memoria. Le informazioni sul layout dei membri vengono fornite mediante l'attributo StructLayoutAttribute. Il layout può assumere uno dei seguenti valori di enumerazione LayoutKind:

  • LayoutKind.Automatic

    Indica che i membri del tipo possono essere riordinati in Common Language Runtime per ragioni di efficienza. Tuttavia, quando un tipo di valore viene passato al codice non gestito, il layout dei membri viene previsto. Il tentativo di eseguire il marshalling di una struttura di questo tipo provoca un'eccezione.

  • LayoutKind.Sequential

    Indica che i membri del tipo devono essere disposti nella memoria non gestita nello stesso ordine in cui appaiono nella definizione del tipo gestito.

  • LayoutKind.Explicit

    Indica che i membri sono disposti in base all'attributo FieldOffsetAttribute fornito con ogni campo.

Nell'esempio riportato di seguito i tipi Point e Rect forniscono informazioni sul layout dei membri mediante StructLayoutAttribute.

using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential)]
public struct Point {
   public int x;
   public int y;
}   

[StructLayout(LayoutKind.Explicit)]
public struct Rect {
   [FieldOffset(0)] public int left;
   [FieldOffset(4)] public int top;
   [FieldOffset(8)] public int right;
   [FieldOffset(12)] public int bottom;
}

Per questi tipi formattati il marshalling nel codice non gestito viene eseguito come strutture di tipo C. Si tratta di un modo semplice per chiamare un'API non gestita con argomenti di struttura. Le strutture POINT e RECT, ad esempio, possono essere passate alla funzione PtInRect dell'API Microsoft Win32 come illustrato di seguito:

BOOL PtInRect(const RECT *lprc, POINT pt);

È possibile passare strutture mediante la definizione di platform invoke riportata di seguito:

class Win32API {
   [DllImport("User32.dll")]
   public static extern Bool PtInRect(ref Rect r, Point p);
}

Il tipo di valore Rect deve essere passato per riferimento, in quanto l'API non gestita prevede che alla funzione venga passato un puntatore a RECT. Il tipo di valore Point viene passato per valore, in quanto l'API non gestita prevede che POINT venga passato sullo stack. Questa sottile differenza è molto importante. I riferimenti vengono passati al codice non gestito come puntatori, mentre i valori vengono passati al codice non gestito sullo stack.

NotaNota

In caso di marshalling di un tipo formattato come struttura, risultano accessibili solo i campi all'interno del tipo. Eventuali metodi, proprietà o eventi del tipo sono inaccessibili dal codice non gestito.

È anche possibile eseguire il marshalling delle classi nel codice non gestito come strutture di tipo C, purché abbiano un layout dei membri fisso. Le informazioni sul layout dei membri per una classe vengono anche fornite con l'attributo StructLayoutAttribute. La differenza principale tra i tipi di valore con layout fisso e le classi con lo stesso layout sta nel modo in cui viene eseguito il marshalling nel codice non gestito. I tipi di valore sono passati sullo stack per valore e, di conseguenza, le eventuali modifiche apportate ai membri del tipo dal chiamato non sono visibili al chiamante. Poiché invece i tipi di riferimento sono passati per riferimento (un riferimento al tipo viene passato sullo stack), tutte le modifiche apportate dal chiamato ai membri di tipo copiabile di un tipo sono visibili al chiamante.

NotaNota

Se un tipo riferimento ha membri di tipi non copiabili, la conversione è necessaria due volte: la prima volta quando si passa un argomento al lato non gestito e la seconda volta in risposta alla chiamata. A causa di questo ulteriore sovraccarico, i parametri In/Out devono essere applicati in modo esplicito a un argomento se il chiamante desidera vedere le modifiche apportate dal chiamato.

Nell'esempio riportato di seguito, la classe SystemTime ha un layout dei membri sequenziale e può essere passata alla funzione GetSystemTime dell'API Win32.

[StructLayout(LayoutKind.Sequential)]
   public class SystemTime {
   public ushort wYear; 
   public ushort wMonth;
   public ushort wDayOfWeek; 
   public ushort wDay; 
   public ushort wHour; 
   public ushort wMinute; 
   public ushort wSecond; 
   public ushort wMilliseconds; 
}

La funzione GetSystemTime è definita come segue:

void GetSystemTime(SYSTEMTIME* SystemTime);

La definizione di platform invoke equivalente per GetSystemTime è la seguente:

class Win32API {
   [DllImport("Kernel32.dll", CharSet=CharSet.Auto)]
   public static extern void GetSystemTime(SystemTime st);
}

Si noti che l'argomento SystemTime non è tipizzato come argomento di riferimento, in quanto SystemTime è una classe, non un tipo di valore. A differenza dei tipi di valore, le classi vengono passate sempre per riferimento.

Nell'esempio di codice riportato di seguito viene mostrata una classe Point diversa che ha un metodo denominato SetXY. Poiché il tipo ha un layout sequenziale, è possibile passarlo al codice non gestito ed eseguirne il marshalling come struttura. Tuttavia, il membro SetXY non può essere chiamato dal codice non gestito, anche se l'oggetto è passato per riferimento.

[StructLayout(LayoutKind.Sequential)]
public class Point {
   int x, y;
   public void SetXY(int x, int y){ 
      this.x = x;
      this.y = y;
   }
}

I tipi formattati possono anche essere passati alle chiamate ai metodi di interoperabilità COM. In realtà, quando esportati in una libreria dei tipi, i tipi di valore vengono convertiti automaticamente in strutture. Come illustrato nell'esempio riportato di seguito, il tipo di valore Point diventa una definizione di tipo (typedef) denominata Point. Tutti i riferimenti al tipo di valore Point in un punto diverso della libreria dei tipi vengono sostituiti dalla definizione typedef Point.

Rappresentazione di libreria dei tipi

typedef struct tagPoint {
   int x;
   int y;
} Point;
interface _Graphics {
   …
   HRESULT SetPoint ([in] Point p)
   HRESULT SetPointRef ([in,out] Point *p)
   HRESULT GetPoint ([out,retval] Point *p)
}

Per il marshalling tramite le interfacce COM valgono le stesse regole del marshalling di valori e riferimenti in platform invoke. Ad esempio, quando un'istanza del tipo di valore Point viene passata da .NET Framework a COM, Point viene passato per valore. Se il tipo di valore Point è passato per riferimento, un puntatore a Point viene passato sullo stack. Il gestore di marshalling di interoperabilità non supporta livelli superiori di riferimenti indiretti (Point **) in entrambe le direzioni.

NotaNota

Le strutture con il valore di enumerazione LayoutKind impostato su Explicit non possono essere utilizzate nell'interoperabilità COM perché la libreria dei tipi esportata non può esprimere un layout esplicito.

Nello spazio dei nomi System sono presenti vari tipi di valore che rappresentano la forma boxed dei tipi primitivi della libreria di runtime. Il tipo di valore della struttura System.Int32 rappresenta ad esempio la forma boxed di ELEMENT_TYPE_I4. Il marshalling di questi tipi non viene eseguito come strutture, allo stesso modo di altri tipi formattati, ma come i tipi primitivi di cui costituiscono la forma boxed. Viene quindi eseguito il marshalling di System.Int32 come ELEMENT_TYPE_I4, anziché come struttura contenente un singolo membro di tipo long. Nella tabella riportata di seguito vengono elencati i tipi di valore dello spazio dei nomi System che rappresentano la forma boxed dei tipi primitivi.

Tipi di valore del sistema

Tipo di elemento

System.Boolean

ELEMENT_TYPE_BOOLEAN

System.SByte

ELEMENT_TYPE_I1

System.Byte

ELEMENT_TYPE_UI1

System.Char

ELEMENT_TYPE_CHAR

System.Int16

ELEMENT_TYPE_I2

System.UInt16

ELEMENT_TYPE_U2

System.Int32

ELEMENT_TYPE_I4

System.UInt32

ELEMENT_TYPE_U4

System.Int64

ELEMENT_TYPE_I8

System.UInt64

ELEMENT_TYPE_U8

System.Single

ELEMENT_TYPE_R4

System.Double

ELEMENT_TYPE_R8

System.String

ELEMENT_TYPE_STRING

System.IntPtr

ELEMENT_TYPE_I

System.UIntPtr

ELEMENT_TYPE_U

Alcuni degli altri tipi di valore dello spazio dei nomi System sono gestiti in modo diverso. Poiché il codice non gestito possiede già formati ben definiti per questi tipi, il gestore di marshalling applica regole speciali. Nella tabella riportata di seguito sono elencati i tipi di valore speciali nello spazio dei nomi System, nonché il tipo non gestito sul quale viene eseguito il marshalling.

Tipi di valore del sistema

Tipo di IDL

System.DateTime

DATE

System.Decimal

DECIMAL

System.Guid

GUID

System.Drawing.Color

OLE_COLOR

Nel codice riportato di seguito viene mostrata la definizione dei tipi non gestiti DATE, GUID, DECIMAL e OLE_COLOR nella libreria dei tipi Stdole2.

0t2cwe11.collapse_all(it-it,VS.110).gifRappresentazione di libreria dei tipi

typedef double DATE;
typedef DWORD OLE_COLOR;

typedef struct tagDEC {
    USHORT    wReserved;
    BYTE      scale;
    BYTE      sign;
    ULONG     Hi32;
    ULONGLONG Lo64;
} DECIMAL;

typedef struct tagGUID {
    DWORD Data1;
    WORD  Data2;
    WORD  Data3;
    BYTE  Data4[ 8 ];
} GUID;

Nel codice che segue vengono mostrate le definizioni corrispondenti nell'interfaccia IValueTypes gestita.

public interface IValueTypes {
   void M1(System.DateTime d);
   void M2(System.Guid d);
   void M3(System.Decimal d);
   void M4(System.Drawing.Color d);
}

0t2cwe11.collapse_all(it-it,VS.110).gifRappresentazione di libreria dei tipi

[…]
interface IValueTypes : IDispatch {
   HRESULT M1([in] DATE d);
   HRESULT M2([in] GUID d);
   HRESULT M3([in] DECIMAL d);
   HRESULT M4([in] OLE_COLOR d);
};
Mostra: