.NET類別庫「Vanara」：簡單易用的Windows API封裝庫

倉庫位址：https://github.com/dahall/Vanara

翻譯：沙漠盡頭的浪（水平有限，如有條件請盡量查看倉庫位址翻閱）

一系列非常簡單易用，對 Windows API 做了極好封裝的 .NET 類別庫，幾乎不用再寫繁瑣的 Windows API 轉換函式了。

此專案包含各種 .NET 程式集，這些程式集包含來自 Windows 函式庫的 P/Invoke 函式、介面、列舉和結構。每個程式集都與一個或幾個緊密相關的函式庫相關聯。例如，Shlwapi.dll 包含從 Shlwapi.lib 匯出的所有函式；Kernel32.dll 包含 Kernel32.lib 和 kernelbase.lib 的全部。

所有程式集都可透過 NuGet 取得，並提供針對 .NET 2.0、3.5、4.0、4.5、Core 3.0、Core 3.1 和 .NET 5.0（v3.2.20 中新增）的版本，並支援 SourceLink。在相依性不允許的所有情況下，.NET Standard 2.0、.NET Core 2.0 和 2.1 版本也包含在 UWP 和其他 .NET Core 及標準專案中。

在充分測試之後，這個專案每隔幾週釋出一次新版本。新的版本和發行說明一起被編目在 Releases 區段，所有 NuGet 套件都發佈到 nuget.org。每個 GitHub 推送都會觸發 AppVeyor 建置。擁有者感謝他們的免費開源帳戶！文章開頭顯示了專案建置狀態資訊。AppVeyor 來源用於建置 NuGet 套件。

怎麼用？

在 Microsoft 文件中查詢所需的函式。請注意函式位於哪個函式庫或 DLL 中。
檢視下面的支援函式庫表，確認 Vanara 函式庫存在並具有您需要的函式 (Windows API)。按一下程式集連結將帶您深入了解該程式集的覆蓋範圍。找到您的函式，如果有一個匹配的實作，它會出現在右邊。您還可以使用 GitHub 的專案搜尋（頁面左上角）來搜尋函式、方法或常數。確保選擇「在此儲存庫中」。
透過 NuGet 將程式集新增到專案中。
要使用該功能，您可以：

1. 直接呼叫 var bret = Vanara.PInvoke.Kernel32.GetComputerName(sb, ref sbSz);
1. 在 C# 6.0 及更高版本下，使用 static using 指令並呼叫它：

using static Vanara.PInvoke.Kernel32;

var bret = GetComputerName(sb, ref sbSz);

在某些情況下，其中一個[支援程式集]中有一個對應的 helper/wrapper 類別，特別是針對安全性、系統服務、表單和 Shell。前往它們的函式庫頁面（按一下區段中的連結），瀏覽每個函式庫中包含的類別。

設計理念

從單一 DLL 匯入的所有函式都應放置到以 DLL 命名的單一程式集中。
- （例如，程式集 Vanara.PInvoke.Gdi32.dll 承載系統目錄中從 gdi32.dll 匯出的所有函式和支援的列舉、常數和結構。）
任何由許多函式庫使用的結構、巨集或列舉（非函式）都會放入 Vanara.Core 或 Vanara.PInvoke.Shared 函式庫中。
- （例如，巨集 HIWORD 和結構 SIZE 都在 Vanara.PInvoke.Shared 中，簡化互操作呼叫和原生記憶體管理的類別都在 Vanara.Core 中）
在專案中，所有建構都包含在一個以標頭檔（*.h）命名的檔案中，其中這些結構在 Windows API 中定義。
- （例如，在 Vanara.PInvoke.Kernel32 專案目錄中，您將分別找到一個 FileApi.cs、WinBase.cs 和一個 WinNT.cs 檔案，分別表示 FileApi.h、WinBase.h 和 WinNT.h）
如果直接解釋結構或函式會導致記憶體洩漏或誤用，我試圖簡化它的使用。
在結構體總是透過參考傳遞，並且在需要清理記憶體配置的地方，我將結構體變更為實作 IDispoable 的類別。
盡可能，所有控制代碼都已轉換為以 Windows API 控制代碼命名的 SafeHandle 衍生工具。如果這些控制代碼需要呼叫函式以釋放/關閉/銷毀，則存在一個衍生的 SafeHANDLE，該函式將在 disposal 時執行該函式。
- 例如，定義了 HTOKEN。 SafeHTOKEN 在該控制代碼上呼叫 CloseHandle 自動釋放。
盡可能，配置呼叫者釋放記憶體的所有函式都使用安全記憶體控制代碼。
程式集中所有 PInvoke 呼叫都以 Vanara.PInvoke 為前置詞。
如果要將結構體作為常數傳遞到函式中，則使用 in 陳述式封裝該結構體，該陳述式將透過參考傳遞結構體，而不需要 ref 關鍵字。
- Windows API: BOOL MapDialogRect(HWND hDlg, LPRECT LPRECT)
- Vanara: bool MapDialogRect(HWND hDlg, in RECT lpRect);
如果有類別或擴充功能使用 PInvoke 呼叫，則它們位於以 Vanara 前置詞的包裝程式集中，然後後接該功能的邏輯名稱。今天，它們是 Core、Security、SystemServices、Windows.Forms 和 Windows.Shell。