Agrupamento de tipo

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

O marshalling é necessário porque os tipos no código gerenciado e não gerenciado são diferentes. No código gerenciado, por exemplo, você tem um string, enquanto as cadeias de caracteres não gerenciadas podem ser codificação .NET string (UTF-16), codificação ANSI Code Page, UTF-8, null-terminated, 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 aquelas 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ê pode fazê-lo da seguinte forma:

[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 aplicar o atributo System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute ao assemblage, as regras na secção a seguir não se aplicarão. Para obter informações sobre como os valores .NET são expostos ao código nativo quando esse atributo é aplicado, consulte Empacotamento de tempo de execução desabilitado.

Regras supletivas para o agrupamento de tipos comuns

Geralmente, o tempo de execução tenta fazer a "coisa certa" ao organizar para exigir o mínimo de trabalho de você. As tabelas a seguir descrevem como cada tipo é organizado por padrão quando usado em um parâmetro ou campo. Os tipos de inteiro e caractere de largura fixa 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 para tipos para os quais o marshalling é o mesmo para P/Invoke e marshalling de campo.

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

A tabela a seguir inclui as regras de empacotamento padrão que são somente para Windows. Em plataformas que não sejam Windows, não é possível organizar esses tipos.

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

Se esses padrões não fizerem exatamente o que você deseja, você poderá personalizar como os parâmetros são organizados. O artigo de interligação de parâmetros orienta o leitor sobre como personalizar a forma como diferentes tipos de parâmetros são transferidos.

Empacotamento padrão em cenários COM

Quando se está a chamar métodos em objetos COM no .NET, o tempo de execução do .NET altera as regras de intermediação padrão para corresponder à semântica COM comum. A tabela a seguir lista as regras que os tempos de execução do .NET usam em cenários de COM:

Classes e estruturas de agrupamento

Outro aspeto do tipo marshalling é como passar uma struct para um método não gerido. Por exemplo, alguns dos métodos não gerenciados exigem um struct como parâmetro. Nesses casos, você precisa criar uma struct correspondente ou uma classe na parte gerenciada do mundo para usá-la como parâmetro. No entanto, apenas definir a classe não é suficiente; é necessário instruir o marshaller sobre como mapear os campos da classe para a estrutura não gerida. Aqui o StructLayout atributo torna-se ú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 para 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 precisa corresponder à struct não gerenciada, mostrada 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 Customizing structure marshalling ensina como personalizar como sua estrutura é organizada.