Bagikan melalui

Mengawal jenis

  • Artikel

Pengawalan adalah proses transformasi jenis ketika mereka harus menyeberang di antara kode terkelola dan kode asli.

Pengawalan diperlukan karena jenis dalam kode terkelola dan tidak terkelola berbeda. Dalam kode terkelola, misalnya, Anda memiliki string, sementara string yang tidak dikelola dapat berupa pengodean .NET string (UTF-16), pengodean Halaman Kode ANSI, UTF-8, dihentikan secara null, ASCII, dll. Secara default, subsistem P/Invoke mencoba melakukan hal yang benar berdasarkan perilaku default, yang dijelaskan dalam artikel ini. Namun, untuk situasi di mana Anda membutuhkan kontrol ekstra, Anda dapat menggunakan atribut MarshalAs untuk menentukan apa jenis yang diharapkan di sisi yang tidak dikelola. Misalnya, jika Anda ingin string dikirim sebagai string UTF-8 yang dihentikan null, Anda dapat melakukannya seperti ini:

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

Jika Anda menerapkan atribut System.Runtime.CompilerServices.DisableRuntimeMarshallingAttribute ke rakitan ini, aturan di bagian berikut tidak berlaku. Untuk informasi tentang bagaimana nilai .NET diekspos ke kode asli saat atribut ini diterapkan, lihat pengawalan runtime yang dinonaktifkan.

Aturan default untuk pengawalan jenis umum

Umumnya, runtime mencoba melakukan "hal yang benar" ketika mengawal membutuhkan jumlah pekerjaan paling sedikit dari Anda. Tabel berikut ini menjelaskan bagaimana setiap jenis dikawal secara default saat digunakan dalam parameter atau bidang. Bilangan bulat lebar-tetap C99/C++11 dan jenis karakter digunakan untuk memastikan bahwa tabel berikut ini benar untuk semua platform. Anda dapat menggunakan jenis asli apa pun yang memiliki persyaratan penyelarasan dan ukuran yang sama dengan jenis ini.

Tabel pertama ini menjelaskan pemetaan untuk berbagai jenis yang pengawalannya sama baik untuk P/Invoke maupaun pengawalan bidang.

Kata kunci C# Jenis .NET Jenis Asli
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 Baik char atau char16_t tergantung pada pengodean P/Invoke atau struktur. Lihat dokumentasi tataan karakter.
System.Char Baik char* atau char16_t* tergantung pada pengodean P/Invoke atau struktur. Lihat dokumentasi tataan karakter.
nint System.IntPtr intptr_t
nuint System.UIntPtr uintptr_t
Jenis Pointer .NET (mis. void*) void*
Jenis yang berasal dari System.Runtime.InteropServices.SafeHandle void*
Jenis yang berasal dari System.Runtime.InteropServices.CriticalHandle void*
bool System.Boolean Jenis Win32 BOOL
decimal System.Decimal Struktur COM DECIMAL
Delegasi .NET Penunjuk fungsi asli
System.DateTime Jenis Win32 DATE
System.Guid Jenis Win32 GUID

Beberapa kategori pengawalan memiliki default yang berbeda jika Anda melakukan pengawalan sebagai parameter atau struktur.

Jenis .NET Jenis Asli (Parameter) Jenis Asli (Bidang)
Array .NET Penunjuk ke awal array representasi asli dari elemen array. Tidak diizinkan tanpa atribut [MarshalAs]
Kelas dengan LayoutKind dari Sequential atau Explicit Penunjuk ke representasi asli dari kelas tersebut Representasi asli dari kelas tersebut

Tabel berikut ini menyertakan aturan pengawalan default yang hanya-Windows. Pada platform non-Windows, Anda tidak dapat mengawal jenis ini.

Jenis .NET Jenis Asli (Parameter) Jenis Asli (Bidang)
System.Object VARIANT IUnknown*
System.Array Antarmuka COM Tidak diizinkan tanpa atribut [MarshalAs]
System.ArgIterator va_list Tidak diizinkan
System.Collections.IEnumerator IEnumVARIANT* Tidak diizinkan
System.Collections.IEnumerable IDispatch* Tidak diizinkan
System.DateTimeOffset int64_t mewakili jumlah kutu sejak tengah malam pada 1 Januari 1601 int64_t mewakili jumlah kutu sejak tengah malam pada 1 Januari 1601

Beberapa jenis hanya dapat dikawal sebagai parameter dan bukan sebagai bidang. Jenis-jenis ini tercantum dalam tabel berikut:

Jenis .NET Jenis Asli (Hanya Parameter)
System.Text.StringBuilder Baik char* atau char16_t* tergantung pada CharSet dari P/Invoke. Lihat dokumentasi tataan karakter.
System.ArgIterator va_list (hanya pada Windows x86/x64/arm64)
System.Runtime.InteropServices.ArrayWithOffset void*
System.Runtime.InteropServices.HandleRef void*

Jika default ini tidak melakukan apa yang Anda inginkan, Anda dapat menyesuaikan bagaimana parameter dikawal. Artikel pengawalan parameter memandu Anda cara menyesuaikan bagaimana berbagai jenis parameter dikawal.

Pengawalan default dalam skenario COM

Ketika Anda memanggil metode pada objek COM di .NET, runtime .NET mengubah aturan pengawalan default agar sesuai dengan semantik COM umum. Tabel berikut mencantumkan aturan yang digunakan runtime bahasa umum .NET dalam skenario COM:

Jenis .NET Jenis Asli (panggilan metode COM)
System.Boolean VARIANT_BOOL
StringBuilder LPWSTR
System.String BSTR
Jenis delegasi _Delegate* dalam .NET Framework. Tidak diizinkan dalam .NET Core dan .NET 5+.
System.Drawing.Color OLECOLOR
Array .NET SAFEARRAY
System.String[] SAFEARRAY dari banyak BSTR

Pengawalan kelas dan struktur

Aspek lain dari pengawalan jenis adalah cara meneruskan struct ke metode yang tidak dikelola. Misalnya, beberapa metode yang tidak dikelola memerlukan struct sebagai parameter. Dalam kasus ini, Anda perlu membuat struktur yang sesuai atau kelas di bagian terkelola dunia untuk menggunakannya sebagai parameter. Namun, hanya mendefinisikan kelas tidak cukup, Anda juga perlu menginstruksikan pengawal cara memetakan bidang di kelas ke struktur yang tidak dikelola. Di sini atribut StructLayout menjadi berguna.

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

Kode sebelumnya menunjukkan contoh sederhana panggilan ke dalam fungsi GetSystemTime(). Bit yang menarik ada di baris 4. Atribut menentukan bahwa bidang kelas harus dipetakan secara berurutan ke struktur di sisi lain (yang tidak terkelola). Artinya penamaan bidang tidak penting, hanya urutannya yang penting, karena harus sesuai dengan struktur yang tidak dikelola, yang ditunjukkan dalam contoh berikut:

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

Terkadang pengawalan default untuk struktur Anda tidak melakukan apa yang Anda perlukan. Artikel Menyesuaikan pengawalan struktur mengajarkan Anda cara menyesuaikan bagaimana struktur Anda dikawal.