Udostępnij za pośrednictwem


Marshaling typów

Marshalling to proces przekształcania typów, gdy muszą one przechodzić między kodem zarządzanym i natywnym.

Marshalling jest wymagany, ponieważ typy w zarządzanym i niezarządzanych kodzie są różne. Na przykład w kodzie zarządzanym stringistnieje ciąg , a ciągi niezarządzane mogą być kodowaniem platformy .NET string (UTF-16), kodowaniem strony kodowej ANSI, kodowaniem strony kodowej UTF-8, zakończonymi wartościami null, ASCII itp. Domyślnie podsystem P/Invoke próbuje wykonać odpowiednie czynności w oparciu o domyślne zachowanie opisane w tym artykule. Jednak w takich sytuacjach, w których potrzebujesz dodatkowej kontroli, można stosować atrybut MarshalAs , aby określić oczekiwany typ po stronie niezarządzanej. Jeśli na przykład chcesz, aby ciąg został wysłany jako ciąg utF-8 zakończony o wartości null, możesz to zrobić w następujący sposób:

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

Jeśli zastosujesz System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute atrybut do zestawu, reguły w poniższej sekcji nie będą stosowane. Aby uzyskać informacje na temat sposobu uwidaczniania wartości platformy .NET w kodzie natywnym po zastosowaniu tego atrybutu, zobacz wyłączone marshalling środowiska uruchomieniowego.

Domyślne reguły marshalingu typowych typów

Ogólnie rzecz biorąc, środowisko uruchomieniowe próbuje wykonać "właściwą rzecz", gdy chcesz wymagać od Ciebie najmniejszej ilości pracy. W poniższych tabelach opisano, jak każdy typ jest domyślnie rozdzielany w przypadku użycia w parametrze lub polu. Typy liczb całkowitych i znaków o stałej szerokości C99/C++11 są używane w celu zapewnienia, że poniższa tabela jest poprawna dla wszystkich platform. Można użyć dowolnego typu natywnego, który ma te same wymagania dotyczące wyrównania i rozmiaru co te typy.

W pierwszej tabeli opisano mapowania dla różnych typów, dla których marshalling jest taki sam zarówno dla P/Invoke, jak i marshallingu pól.

Słowo kluczowe języka C# Typ platformy .NET Typ natywny
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 Albo char albo char16_t w zależności od kodowania P/Invoke lub struktury. Zapoznaj się z dokumentacją zestawu znaków.
System.Char Albo char* albo char16_t* w zależności od kodowania P/Invoke lub struktury. Zapoznaj się z dokumentacją zestawu znaków.
nint System.IntPtr intptr_t
nuint System.UIntPtr uintptr_t
Typy wskaźników .NET (np. void*) void*
Typ pochodzący z System.Runtime.InteropServices.SafeHandle void*
Typ pochodzący z System.Runtime.InteropServices.CriticalHandle void*
bool System.Boolean Typ Win32 BOOL
decimal System.Decimal Struktura MODELU COM DECIMAL
Delegat platformy .NET Wskaźnik funkcji natywnej
System.DateTime Typ Win32 DATE
System.Guid Typ Win32 GUID

Kilka kategorii marshalingu ma różne wartości domyślne, jeśli jesteś marshalling jako parametr lub struktura.

Typ platformy .NET Typ natywny (parametr) Typ natywny (pole)
Tablica .NET Wskaźnik na początek tablicy natywnych reprezentacji elementów tablicy. Niedozwolone bez atrybutu [MarshalAs]
Klasa z wartością LayoutKindSequential lub Explicit Wskaźnik do natywnej reprezentacji klasy Natywna reprezentacja klasy

Poniższa tabela zawiera domyślne reguły marshalingu, które są tylko systemem Windows. Na platformach innych niż Windows nie można marshalingu tych typów.

Typ platformy .NET Typ natywny (parametr) Typ natywny (pole)
System.Object VARIANT IUnknown*
System.Array Interfejs COM Niedozwolone bez atrybutu [MarshalAs]
System.ArgIterator va_list Niedozwolone
System.Collections.IEnumerator IEnumVARIANT* Niedozwolone
System.Collections.IEnumerable IDispatch* Niedozwolone
System.DateTimeOffset int64_t reprezentujący liczbę kleszczy od północy 1 stycznia 1601 r. int64_t reprezentujący liczbę kleszczy od północy 1 stycznia 1601 r.

Niektóre typy można rozmieszać tylko jako parametry, a nie jako pola. Te typy są wymienione w poniższej tabeli:

Typ platformy .NET Typ natywny (tylko parametr)
System.Text.StringBuilder Albo char* albo char16_t* w zależności od CharSet wywołania P/Invoke. Zapoznaj się z dokumentacją zestawu znaków.
System.ArgIterator va_list (tylko w systemie Windows x86/x64/arm64)
System.Runtime.InteropServices.ArrayWithOffset void*
System.Runtime.InteropServices.HandleRef void*

Jeśli te wartości domyślne nie robią dokładnie tego, co chcesz, możesz dostosować sposób działania parametrów. W artykule dotyczącym marshalingu parametrów przedstawiono sposób dostosowywania różnych typów parametrów.

Domyślne marshaling w scenariuszach COM

Podczas wywoływania metod na obiektach COM na platformie .NET środowisko uruchomieniowe platformy .NET zmienia domyślne reguły marshalingu, aby pasować do typowych semantyki COM. W poniższej tabeli wymieniono reguły używane przez środowiska uruchomieniowe platformy .NET w scenariuszach COM:

Typ platformy .NET Typ natywny (wywołania metod COM)
System.Boolean VARIANT_BOOL
StringBuilder LPWSTR
System.String BSTR
Typy delegatów _Delegate* w programie .NET Framework. Niedozwolone w programach .NET Core i .NET 5+.
System.Drawing.Color OLECOLOR
Tablica .NET SAFEARRAY
System.String[] SAFEARRAYz s BSTR

Klasy i struktury marshalling

Innym aspektem marshalingu typu jest sposób przekazywania struktury do metody niezarządzanej. Na przykład niektóre metody niezarządzane wymagają struktury jako parametru. W takich przypadkach należy utworzyć odpowiednią strukturę lub klasę w zarządzanej części świata, aby użyć jej jako parametru. Jednak samo zdefiniowanie klasy nie jest wystarczające, należy również poinstruować marshaller, jak mapować pola w klasie na niezarządzaną strukturę. StructLayout W tym przypadku atrybut staje się przydatny.

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

Poprzedni kod przedstawia prosty przykład wywoływania GetSystemTime() funkcji. Interesujący bit znajduje się w wierszu 4. Atrybut określa, że pola klasy powinny być mapowane sekwencyjnie do struktury po drugiej stronie (niezarządzane). Oznacza to, że nazewnictwo pól nie jest ważne, tylko ich kolejność jest ważna, ponieważ musi odpowiadać niezarządzanej struktury, pokazanej w poniższym przykładzie:

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

Czasami domyślne marshalling struktury nie robi tego, czego potrzebujesz. Artykuł Dostosowywanie struktury marshalling zawiera informacje na temat dostosowywania sposobu działania struktury.