封送處理類型
當類型需要跨越受控碼和機器碼之間的界限時，封送處理便是轉換類型的程序。
之所以需要進行封送處理，是因受控碼和非受控碼中的類型並不相同。 例如，在 Managed 程式碼中，您有 ， String 而 Unmanaged 世界字串中可以是 Unicode (「wide」) 、非 Unicode、null 終止、ASCII 等。根據預設，P/Invoke 子系統會根據本文所述的預設行為，嘗試執行正確的動作。 不過，在您需要進行額外控制的情況下，您可以運用 MarshalAs 屬性來指定非受控端的預期類型。 比方說，如果您想要用以 null 終止的 ANSI 字串形式來傳送字串，您可以下列方式執行它︰
[DllImport("somenativelibrary.dll")]
static extern int MethodA([MarshalAs(UnmanagedType.LPStr)] 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 或結構的 CharSet。 請參閱字元集文件。 |
System.Char |
char* 或 char16_t*，取決於 P/Invoke 或結構的 CharSet。 請參閱字元集文件。 |
|
nint |
System.IntPtr |
intptr_t |
nuint |
System.UIntPtr |
uintptr_t |
.NET 指標類型 (例如 void*) |
void* |
|
衍生自 System.Runtime.InteropServices.SafeHandle 的類型 |
void* |
|
衍生自 System.Runtime.InteropServices.CriticalHandle 的類型 |
void* |
|
System.Boolean |
Win32 BOOL 類型 |
|
decimal |
System.Decimal |
COM DECIMAL 結構 |
| .NET 委派 | 原生函式指標 | |
System.DateTime |
Win32 DATE 類型 |
|
System.Guid |
Win32 GUID 類型 |
如果您是以參數或結構的形式進行封送處理，有幾個封送處理類別具有不同的預設值。
| .NET 類型 | 原生類型 (參數) | 原生類型 (欄位) |
|---|---|---|
| .NET 陣列 | 針對陣列元素原生表示法之陣列開頭的指標。 | 需要有 [MarshalAs] 屬性，否則不允許 |
具有 Sequential 或 Explicit之 LayoutKind 的類別 |
針對類別之原生表示法的指標 | 類別的原生表示法 |
下表包含僅限 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 代表從 1601 年 1 月 1 日午夜起的刻度數目 |
int64_t 代表從 1601 年 1 月 1 日午夜起的刻度數目 |
某些類型只能以參數 (而非欄位) 的形式進行封送處理。 這些類型已列於下表中：
| .NET 類型 | 原生類型 (僅限參數) |
|---|---|
System.Text.StringBuilder |
char* 或 char16_t*，取決於 P/Invoke 的 CharSet。 請參閱字元集文件。 |
System.ArgIterator |
va_list (僅限 Windows x86/x64/arm64) |
System.Runtime.InteropServices.ArrayWithOffset |
void* |
System.Runtime.InteropServices.HandleRef |
void* |
如果這些預設值無法達成您的目的，您可以自訂對參數進行封送處理的方式。 參數封送處理一文會引導您了解如何自訂對不同參數類型進行封送處理的方式。
COM 案例中的預設封送處理
當您在 .NET 中的 COM 物件上呼叫方法時，.NET 執行時間會變更預設封送處理規則，以符合常見的 COM 語意。 下表列出 .NET 執行階段在 COM 案例中使用的規則：
| .NET 類型 | 原生類型 (COM 方法呼叫) |
|---|---|
System.Boolean |
VARIANT_BOOL |
StringBuilder |
LPWSTR |
System.String |
BSTR |
| 委派型別 | .NET Framework 中的 _Delegate*。 .NET Core 和 .NET 5+ 中不允許。 |
System.Drawing.Color |
OLECOLOR |
| .NET 陣列 | SAFEARRAY |
System.String[] |
BSTR 的 SAFEARRAY |
封送處理類別和結構
封送處理類型的另一個層面是如何將結構傳遞給 Unmanaged 方法。 比方說，有些 Unmanaged 方法需要結構以作為參數。 在這些情況下，您需要在世界的受控部分建立對應的結構或類別，以將它作為參數。 不過，只要定義類別就不夠，您也需要指示封送器如何將類別中的欄位對應至 Unmanaged 結構。 在這裡，StructLayout 屬性將會變得很有用。
[DllImport("kernel32.dll")]
static extern void GetSystemTime(SystemTime systemTime);
[StructLayout(LayoutKind.Sequential)]
class SystemTime {
public ushort Year;
public ushort Month;
public ushort DayOfWeek;
public ushort Day;
public ushort Hour;
public ushort Minute;
public ushort Second;
public ushort Milsecond;
}
public static void Main(string[] args) {
SystemTime st = new SystemTime();
GetSystemTime(st);
Console.WriteLine(st.Year);
}
上述程式碼示範針對 GetSystemTime() 函式進行呼叫的簡單範例。 請注意第 4 行。 此屬性會指定類別的欄位應該循序對應至 Unmanaged 這一端上的結構。 這表示欄位的命名並不重要，只有其順序才重要，因為它需要對應至非受控結構，如下列範例所示︰
typedef struct _SYSTEMTIME {
WORD wYear;
WORD wMonth;
WORD wDayOfWeek;
WORD wDay;
WORD wHour;
WORD wMinute;
WORD wSecond;
WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME;
有時候，針對您的結構進行預設的封送處理並無法帶來您所需的結果。 自訂結構封送處理一文會教導您如何自訂如何封送處理您的結構。