Маршалинг типов
Маршалинг — это процесс преобразования типов при переходе от управляемого кода к машинному.
Необходимость в маршалинге вызвана различием типов в управляемом и неуправляемом коде. Например, в управляемом коде есть stringнеуправляемые строки, в то время как неуправляемые строки могут быть кодировкой .NET string (UTF-16), кодировкой кодов ANSI, кодировкой UTF-8, null-terminated, ASCII и т. д. По умолчанию подсистема P/Invoke пытается выполнить правильные действия на основе поведения по умолчанию, описанного в этой статье. Однако в ситуациях, когда требуется дополнительный контроль, можно применить атрибут MarshalAs, чтобы указать ожидаемый тип на стороне неуправляемого кода. Например, если вы хотите, чтобы строка была отправлена в виде строки, завершаемой значением NULL, UTF-8, это можно сделать следующим образом:
[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);
Если атрибут применяется System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute к сборке, правила в следующем разделе не применяются. Сведения о том, как значения .NET предоставляются машинным кодом при применении этого атрибута, см. в разделе "Отключено маршалирование среды выполнения".
Правила маршалинга общих типов
Обычно среда выполнения пытается маршалировать типы "правильно", чтобы от пользователя не потребовалось каких-либо действий. В приведенных ниже таблицах показано, как при использовании в параметре или поле каждый тип данных маршалируется по умолчанию. Чтобы проверить правильность данных в приведенных ниже таблицах для всех платформ, используются символьные и целочисленные (фиксированной ширины) типы данных C99/C++11. Используйте любой собственный тип, который имеет такое же выравнивание и требования к размеру, как эти типы данных.
В первой таблице представлены сопоставления различных типов, для которых маршалинг выполняется одинаково — как для P/Invoke, так и для поля.
| Ключевое слово C# | Тип .NET | Собственный тип |
|---|---|---|
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 в char16_t зависимости от кодировки P/Invoke или структуры. См. дополнительные сведения в документации по кодировке. |
System.Char |
Либо char* в char16_t* зависимости от кодировки P/Invoke или структуры. См. дополнительные сведения в документации по кодировке. |
|
nint |
System.IntPtr |
intptr_t |
nuint |
System.UIntPtr |
uintptr_t |
Типы указателей .NET (например) void* |
void* |
|
Тип, производный от System.Runtime.InteropServices.SafeHandle |
void* |
|
Тип, производный от System.Runtime.InteropServices.CriticalHandle |
void* |
|
bool |
System.Boolean |
Тип Win32 BOOL |
decimal |
System.Decimal |
Структура COM DECIMAL |
| Делегат .NET | Собственный указатель функции | |
System.DateTime |
Тип Win32 DATE |
|
System.Guid |
Тип Win32 GUID |
Если вы маршалируете тип как параметр или структуру, несколько категорий маршалинга будут иметь разные значения по умолчанию.
| Тип .NET | Собственный тип (параметр) | Собственный тип (поле) |
|---|---|---|
| Массив .NET | Указатель на начало массива в собственном представлении элементов массива. | Нельзя использовать без атрибута [MarshalAs] |
Класс, где для LayoutKind задано значение Sequential или Explicit |
Указатель на собственное представление класса | Собственное представление класса |
В приведенной ниже таблице содержатся правила маршалинга, применяемые по умолчанию только для Windows. На других платформах (не Windows) эти типы нельзя маршалировать.
| Тип .NET | Собственный тип (параметр) | Собственный тип (поле) |
|---|---|---|
System.Object |
VARIANT |
IUnknown* |
System.Array |
Интерфейс COM | Нельзя использовать без атрибута [MarshalAs] |
System.ArgIterator |
va_list |
Не разрешенный |
System.Collections.IEnumerator |
IEnumVARIANT* |
Не разрешенный |
System.Collections.IEnumerable |
IDispatch* |
Не разрешенный |
System.DateTimeOffset |
int64_t — число тактов начиная с полуночи 1 января 1601 года. |
int64_t — число тактов начиная с полуночи 1 января 1601 года. |
Некоторые типы можно маршалировать только как параметры и нельзя — как поля. Эти типы перечислены в следующей таблице.
| Тип .NET | Собственный тип (только параметр) |
|---|---|
System.Text.StringBuilder |
Тип char* или char16_t* в зависимости от кодировки CharSet P/Invoke. См. дополнительные сведения в документации по кодировке. |
System.ArgIterator |
va_list (только в Windows x86/x64/arm64) |
System.Runtime.InteropServices.ArrayWithOffset |
void* |
System.Runtime.InteropServices.HandleRef |
void* |
Если эти значения по умолчанию вам не подходят, вы можете настроить маршалинг параметров. В статье о маршалинге параметров описана настройка маршалинга различных типов параметров.
Маршалирование по умолчанию в сценариях COM
При вызове методов в COM-объектах в .NET среда выполнения .NET изменяет правила маршаллинга по умолчанию в соответствии с общей семантикой COM. В следующей таблице перечислены правила, которые среда выполнения .NET использует в сценариях COM:
| Тип .NET | Собственный тип (вызовы метода COM) |
|---|---|
System.Boolean |
VARIANT_BOOL |
StringBuilder |
LPWSTR |
System.String |
BSTR |
| Типы делегатов | _Delegate* в .NET Framework. Не разрешены в .NET Core и .NET 5 и более поздних версий. |
System.Drawing.Color |
OLECOLOR |
| Массив .NET | SAFEARRAY |
System.String[] |
SAFEARRAYBSTR |
Маршалинг классов и структур
Другим аспектом маршалинга типов является способ передачи структуры в неуправляемый метод. Например, некоторые неуправляемые методы требуют указания структуры в качестве параметра. В таких случаях необходимо создать соответствующую структуру или соответствующий класс в управляемом коде и использовать в качестве параметра. Однако просто определение класса недостаточно, вам также нужно указать маршаллеру, как сопоставить поля в классе с неуправляемой структурой. Здесь пригодится атрибут 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);
}
В приведенном выше примере представлен код вызова функции GetSystemTime(). Интерес представляет строка 4. Атрибут указывает, что поля класса должны последовательно сопоставляться со структурой на другой (неуправляемой) стороне. Это означает, что имена полей не важны, важен только их порядок, так как он должен соответствовать неуправляемой структуре, которая показана в приведенном ниже примере:
typedef struct _SYSTEMTIME {
WORD wYear;
WORD wMonth;
WORD wDayOfWeek;
WORD wDay;
WORD wHour;
WORD wMinute;
WORD wSecond;
WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME;
Иногда маршалинг по умолчанию не решает задачу для вашей структуры. В статье по настройке структуры маршаллинга вы узнаете, как настроить способ маршаллирования структуры.
