Partager via


Marshaling de types

Le marshaling est le processus qui consiste à transformer les types quand ils doivent naviguer entre du code managé et du code natif.

La raison pour laquelle le marshaling est nécessaire est que les types diffèrent entre le code managé et le code non managé. Dans le code managé, par exemple, vous avez un string, tandis que les chaînes non managées peuvent être l’encodage .NET string (UTF-16), l’encodage de page de codes ANSI, UTF-8, se terminant par null, ASCII, etc. Par défaut, le sous-système P/Invoke tente de prendre la bonne décision en fonction du comportement par défaut, décrit dans cet article. Toutefois, dans les cas où vous avez besoin de plus de contrôle, vous pouvez employer l’attribut MarshalAs pour spécifier le type attendu du côté du code non managé. Par exemple, pour que la chaîne soit envoyée sous forme de chaîne UTF-8 terminée par null, vous pouvez procéder ainsi :

[LibraryImport("somenativelibrary.dll")]
static extern int MethodA([MarshalAs(UnmanagedType.LPStr)] string parameter);

// or

[LibraryImport("somenativelibrary.dll", StringMarshalling = StringMarshalling.Utf8)]
static extern int MethodB(string parameter);

Si vous appliquez l’attribut System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute à l’assembly, les règles de la section suivante ne s’appliquent pas. Pour plus d’informations sur la façon dont les valeurs .NET sont exposées au code natif lorsque cet attribut est appliqué, consultez Marshaling de runtime désactivé.

Règles par défaut de marshaling des types courants

En règle générale, le runtime tente de prendre la bonne décision en matière de marshaling, c’est-à-dire celle qui demande le moins de travail de votre part. Les tableaux suivants indiquent comment chaque type est marshalé par défaut lorsqu’il est utilisé dans un paramètre ou un champ. Les types de caractères et d’entiers de longueur fixe C99/C ++11 garantissent que le tableau suivant est correct pour toutes les plateformes. Vous pouvez utiliser n’importe quel type natif ayant les mêmes exigence d’alignement et de taille que ces types.

La première table décrit les correspondances de différents types pour lesquels le marshaling P/Invoke et le marshaling des champs sont identiques.

Mot clé C# Type .NET Type natif
byte System.Byte uint8_t
sbyte System.SByte int8_t
short System.Int16 int16_t
ushort System.UInt16 uint16_t
int System.Int32 int32_t
uint System.UInt32 uint32_t
long System.Int64 int64_t
ulong System.UInt64 uint64_t
char System.Char char ou char16_t selon l’encodage de P/Invoke ou la structure. Voir la documentation charset.
System.Char char* ou char16_t* selon l’encodage de P/Invoke ou la structure. Voir la documentation charset.
nint System.IntPtr intptr_t
nuint System.UIntPtr uintptr_t
Types pointeur .NET (p. ex. void*) void*
Type dérivé de System.Runtime.InteropServices.SafeHandle void*
Type dérivé de System.Runtime.InteropServices.CriticalHandle void*
bool System.Boolean Type BOOL Win32
decimal System.Decimal Struct DECIMAL COM
Délégué .NET Pointeur de fonction natif
System.DateTime Type DATE Win32
System.Guid Type GUID Win32

Certaines catégories ont des valeurs par défaut différentes pour le marshaling comme paramètre ou comme structure.

Type .NET Type natif (paramètre) Type natif (champ)
Tableau .NET Pointeur vers le début d’un tableau de représentations natives des éléments du tableau Non autorisé sans attribut [MarshalAs]
Classe avec LayoutKind de Sequential ou de Explicit Pointeur vers la représentation native de la classe Représentation native de la classe

Le tableau suivant présente les règles de marshaling par défaut propres à Windows. Sur les autres plateformes, il n’est pas possible de marshaler ces types.

Type .NET Type natif (paramètre) Type natif (champ)
System.Object VARIANT IUnknown*
System.Array Interface COM Non autorisé sans attribut [MarshalAs]
System.ArgIterator va_list Non autorisé
System.Collections.IEnumerator IEnumVARIANT* Non autorisé
System.Collections.IEnumerable IDispatch* Non autorisé
System.DateTimeOffset représentant le nombre de cycles depuis le 1er janvier 1601 à minuit représentant le nombre de cycles depuis le 1er janvier 1601 à minuit

Certains types ne peuvent être marshalés que comme paramètres, et non comme champs :

Type .NET Type natif (paramètre uniquement)
System.Text.StringBuilder char* ou char16_t* selon le CharSet de P/Invoke. Voir la documentation charset.
System.ArgIterator va_list (sur Windows x86/x64/arm64 uniquement)
System.Runtime.InteropServices.ArrayWithOffset void*
System.Runtime.InteropServices.HandleRef void*

Si ces valeurs par défaut ne vous conviennent pas tout à fait, vous pouvez personnaliser la façon dont les paramètres sont marshalés. L’article Marshaling des paramètres explique comment faire, pour différents types de paramètres.

Marshaling par défaut dans les scénarios COM

Quand vous appelez des méthodes sur des objets COM dans .NET, le runtime .NET modifie les règles de marshaling par défaut pour qu’elles correspondent à la sémantique COM courante. Le tableau suivant liste les règles utilisées par les runtimes .NET dans les scénarios COM :

Type .NET Type natif (appels de méthodes COM)
System.Boolean VARIANT_BOOL
StringBuilder LPWSTR
System.String BSTR
Types délégués _Delegate* dans le .NET Framework. Non autorisé dans .NET Core et .NET 5+.
System.Drawing.Color OLECOLOR
Tableau .NET SAFEARRAY
System.String[] SAFEARRAY de BSTRs

Marshaling de classes et de structures

Un autre aspect du marshaling de types consiste à passer une structure à une méthode non managée. Par exemple, certaines des méthodes non managées nécessitent une structure comme paramètre. Il faut dans ce cas créer une classe ou un struct correspondant dans la partie managée de l’environnement pour l’utiliser comme paramètre. Toutefois, il ne suffit pas de définir la classe : il est également nécessaire d’indiquer au marshaleur comment mapper des champs de la classe au struct non managé. C’est ici qu’intervient l’attribut StructLayout.

[LibraryImport("kernel32.dll")]
static partial void GetSystemTime(out SystemTime systemTime);

[StructLayout(LayoutKind.Sequential)]
struct SystemTime
{
    public ushort Year;
    public ushort Month;
    public ushort DayOfWeek;
    public ushort Day;
    public ushort Hour;
    public ushort Minute;
    public ushort Second;
    public ushort Millisecond;
}

public static void Main(string[] args)
{
    SystemTime st = new SystemTime();
    GetSystemTime(st);
    Console.WriteLine(st.Year);
}

Le code précédent illustre de manière simple les appels dans la fonction GetSystemTime(). L’élément digne d’intérêt se trouve sur la ligne 4. L’attribut spécifie que les champs de la classe doivent être mappés séquentiellement à la structure de l’autre côté (non managé). Cela signifie que le nom des champs n’a pas d’importance ; seul leur ordre compte, car il doit correspondre au struct non managé, comme dans l’exemple suivant :

typedef struct _SYSTEMTIME {
  WORD wYear;
  WORD wMonth;
  WORD wDayOfWeek;
  WORD wDay;
  WORD wHour;
  WORD wMinute;
  WORD wSecond;
  WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME;

Il est possible que le marshaling par défaut de votre structure ne vous convienne pas. L’article Personnaliser le marshaling des structures explique comment personnaliser la façon dont les structures sont marshalées.