Marshaling de types

Le marshaling est le processus de transformation des types lorsqu’ils doivent passer d’un code managé à un code natif.

Le marshaling est nécessaire, car les types dans le code managé et non managé sont différents. 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 faire la bonne chose en fonction du comportement par défaut, décrit dans cet article. Toutefois, pour les situations où vous avez besoin d’un contrôle supplémentaire, vous pouvez utiliser l’attribut MarshalAs pour spécifier le type attendu du côté non managé. Par exemple, si vous souhaitez que la chaîne soit envoyée en tant que chaîne UTF-8 terminée par null, vous pouvez le faire comme suit :

[LibraryImport("somenativelibrary.dll")]
static extern int MethodA([MarshalAs(UnmanagedType.LPUTF8Str)] 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 le marshaling du 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 décrivent comment chaque type est marshalé par défaut lorsqu’il est utilisé dans un paramètre ou un champ. Les types entiers et caractères de largeur fixe C99/C++11 sont utilisés pour s’assurer que le tableau suivant est correct pour toutes les plateformes. Vous pouvez utiliser n’importe quel type natif qui a les mêmes exigences 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.

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

Le tableau suivant inclut les règles de marshaling par défaut qui sont uniquement pour Windows. Sur les autres plateformes, il n’est pas possible de marshaler ces types.

Certains types peuvent uniquement être marshalés en tant que paramètres et non en tant que champs. Ces types sont répertoriés dans le tableau suivant :

Si ces valeurs par défaut ne font pas exactement ce que vous voulez, vous pouvez personnaliser la façon dont les paramètres sont marshalés. L’article de marshaling de paramètres vous guide tout au long de la façon dont différents types de paramètres sont marshalés.

Marshaling par défaut dans les scénarios COM

Lorsque 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 répertorie les règles que les runtimes .NET utilisent dans les scénarios COM :

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 un struct en tant que paramètre. Dans ces cas, vous devez créer un struct correspondant ou une classe dans une partie gérée du monde pour l’utiliser comme paramètre. Toutefois, la définition de la classe n’est pas suffisante, vous devez également indiquer au marshaller comment mapper les champs de la classe au struct non managé. Ici, l’attribut StructLayout devient utile.

using System;
using System.Runtime.InteropServices;

Win32Interop.GetSystemTime(out Win32Interop.SystemTime systemTime);

Console.WriteLine(systemTime.Year);

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

    [StructLayout(LayoutKind.Sequential)]
    internal ref 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;
    }
}

Le code précédent montre un exemple simple d'appel d'une fonction GetSystemTime(). La partie intéressante se trouve à la ligne 13. L’attribut spécifie que les champs de la classe doivent être mappés séquentiellement au struct de l’autre côté (non managé). Cela signifie que le nommage des champs n’est pas important, seul son ordre est important, car il doit correspondre au struct non managé, illustré 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, *LPSYSTEMTIME;

Il est possible que le marshaling par défaut de votre structure ne vous convienne pas. L’article Personnalisation de l'assemblage de structure vous apprend à personnaliser la manière dont votre structure est assemblée.