C# P/Invoke 非受控型別對應表：Win32 API 參數封送完整速查

呼叫 Windows API (P/Invoke) 時，正確對應非受控型別至 .NET 受控型別至關重要。錯誤對應會導致記憶體損毀、存取違規、資料截斷等難以除錯的問題。本文提供完整對應表，涵蓋基礎型別、指標/字串/結構體/陣列封送、呼叫慣例、32/64 位元差異，並附上常見 Win32 結構體對應範例。

基礎型別對應表

指標/字串/陣列封送

常見 Win32 結構體對應範例

POINT

[StructLayout(LayoutKind.Sequential)]
public struct POINT { public int X; public int Y; }

RECT

[StructLayout(LayoutKind.Sequential)]
public struct RECT { public int Left, Top, Right, Bottom; }

WNDCLASSEX (含字串指標、函數指標、大小欄位)

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
public struct WNDCLASSEX
{
    public uint cbSize;
    public uint style;
    public IntPtr lpfnWndProc;      // 函數指標 -> IntPtr
    public int cbClsExtra;
    public int cbWndExtra;
    public IntPtr hInstance;
    public IntPtr hIcon;
    public IntPtr hCursor;
    public IntPtr hbrBackground;
    [MarshalAs(UnmanagedType.LPTStr)] public string lpszMenuName;
    [MarshalAs(UnmanagedType.LPTStr)] public string lpszClassName;
    public IntPtr hIconSm;
}

呼叫慣例與 CharSet 設定

[DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true, ExactSpelling = false)]
public static extern IntPtr FindWindow(string lpClassName, string lpWindowName);

// CharSet.Auto: 依平台自動選 Ansi/Unicode (建議)
// CharSet.Ansi: 強制 ANSI (EntryPoint="FindWindowA")
// CharSet.Unicode: 強制 Unicode (EntryPoint="FindWindowW")
// SetLastError=true: 允許 Marshal.GetLastWin32Error() 取得錯誤碼
// ExactSpelling=false: 允許運行時依 CharSet 修飾函數名稱 (A/W 後綴)

32/64 位元可攜性核心原則

1. 所有句柄/指標用 IntPtr / nint，絕不使用 `int`/`long`。
2. 結構體大小欄位 (如 `cbSize`) 在建構函式中用 `Marshal.SizeOf()` 動態計算。
3. 避免 `ToInt32()` / `ToInt64()` 硬編碼，使用 `IntPtr.Size` 判斷平台。
4. 編譯目標：專案屬性 → Build → 取消勾選 "Prefer 32-bit"，讓進程隨平台為 64 位元，或明確指定 x86/x64。

現代工具輔助

• pinvoke.net：社群維護的簽章庫，可直接搜尋複製。
• CsWin32 (Microsoft)：Source Generator 從 Windows SDK 標頭自動產生 P/Invoke 簽章，支援 .NET 6+，強型別、無需手寫。
• LibraryImport ( .NET 7+ )：編譯期產生包裝，效能優於 `DllImport`，支援 `StringMarshalling`、`ArrayMarshalling` 等屬性。

結語

P/Invoke 型別對應錯誤是導致「不可重現崩潰」的首要原因。請永遠使用 `IntPtr` 處理句柄/指標、明確指定 `CharSet` 與 `SetLastError`、結構體加上 `StructLayout.Sequential`、優先使用 CsWin32/LibraryImport 自動產生簽章。將此表加入團隊 Wiki，代碼審查時必查項目。