Marshalling dos tipos

O marshalling é o processo de transformação de tipos quando eles precisam se cruzar entre código gerenciado e nativo.

O marshalling é necessário porque os tipos são diferentes, no código gerenciado e não gerenciado. No código gerenciado, por exemplo, você tem uma string, enquanto cadeias de caracteres não gerenciadas podem ser de codificação .NET string (UTF-16), codificação de página de código ANSI, UTF-8, terminadas em nulo, ASCII, etc. Por padrão, o subsistema P/Invoke tenta fazer a coisa certa com base no comportamento padrão, descrito neste artigo. No entanto, para as situações em que você precisa de controle extra, você pode empregar o atributo MarshalAs para especificar qual é o tipo esperado no lado não gerenciado. Por exemplo, se você quiser que a cadeia de caracteres seja enviada como uma cadeia de caracteres UTF-8 terminada em nulo, você poderá fazer isso da seguinte maneira:

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

Se você aplicar o atributo System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute à montagem, as regras na seção a seguir não se aplicarão. Para obter informações sobre como os valores do .NET são expostos ao código nativo quando esse atributo é aplicado, confira marshalling de runtime desabilitado.

Regras padrão para tipos comuns de marshalling

Geralmente, o runtime tenta fazer a "coisa certa" ao realizar marshal para exigir a menor quantidade de trabalho de você. As tabelas a seguir descrevem como cada tipo é processado por padrão quando usado em um parâmetro ou campo. Os tipos de inteiro e caractere de largura fixa do C99/C++11 são usados para garantir que a tabela a seguir esteja correta para todas as plataformas. Você pode usar qualquer tipo nativo que tenha os mesmos requisitos de alinhamento e tamanho que esses tipos.

Esta primeira tabela descreve os mapeamentos de tipos para os quais o registro é o mesmo para P/Invoke e registro de campo.

Algumas categorias de marshalling têm padrões diferentes se você estiver realizando marshaling como um parâmetro ou estrutura.

A tabela a seguir inclui as regras de marshalling padrão que são somente do Windows. Em plataformas que não são Windows, você não pode realizar marshal desses tipos.

Alguns tipos só podem ser empacotados como parâmetros e não como campos. Esses tipos são listados na tabela a seguir:

Se esses padrões não fizerem exatamente o que você deseja, personalize como os parâmetros têm o marshal realizado. O artigo sobre processamento de parâmetro explica como personalizar o modo como diferentes tipos de parâmetros são empacotados.

Marshalling padrão em cenários COM

Quando você está chamando métodos em objetos COM no .NET, o runtime do .NET altera as regras de marshalling padrão para corresponder à semântica COM comum. A tabela a seguir lista as regras que os runtimes do .NET usam em cenários COM:

Marshalling de classes e structs

Outro aspecto do marshalling de tipos é como passar um struct para um método não gerenciado. Por exemplo, alguns dos métodos não gerenciados exigem um struct como um parâmetro. Nesses casos, você precisa criar um struct correspondente ou uma classe em parte gerenciada do mundo para usá-lo como parâmetro. No entanto, apenas definir a classe não é suficiente, você também precisa instruir o marshaller como mapear campos na classe para o struct não gerenciado. Aqui, o StructLayout atributo se torna útil.

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

O código anterior mostra um exemplo simples de chamada à GetSystemTime() função. A parte interessante está na linha 13. O atributo especifica que os campos da classe devem ser mapeados sequencialmente para o struct no outro lado (não gerenciado). Isso significa que a nomenclatura dos campos não é importante, apenas sua ordem é importante, pois ela precisa corresponder ao struct não gerenciado, mostrado no exemplo a seguir:

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

Às vezes, o marshalling padrão para sua estrutura não faz o que você precisa. O artigo Personalizando o marshalling de estrutura ensina como personalizar a forma como é feito o marshalling de sua estrutura.