如何在C#中使用 Win32和其他库

作者：Microsoft（郁闷） ,
some part changed by xugd

　　C# 用户经常提出两个问题：“我为什么要另外编写代码来使用内置于 Windows 中的功能？在框架中为什么没有相应的内容可以为我完成这一任务？”当框架小组构建他们的 .NET 部分时，他们评估了为使 .NET 程序员可以使用 Win32 而需要完成的工作，结果发现 Win32 API 集非常庞大。他们没有足够的资源为所有 Win32 API 编写托管接口、加以测试并编写文档，因此只能优先处理最重要的部分。许多常用操作都有托管接口，但是还有许多完整的 Win32 部分没有托管接口。
　　平台调用 (P/Invoke) 是完成这一任务的最常用方法。要使用 P/Invoke，您可以编写一个描述如何调用函数的原型，然后运行时将使用此信息进行调用。另一种方法是使用 Managed Extensions to C++ 来包装函数，这部分内容将在以后的专栏中介绍。
　　要理解如何完成这一任务，最好的办法是通过示例。在某些示例中，我只给出了部分代码；完整的代码可以通过下载获得。
　　 简单示例
　　在第一个示例中，我们将调用 Beep() API 来发出声音。首先，我需要为 Beep() 编写适当的定义。查看 MSDN 中的定义，我发现它具有以下原型：
BOOL Beep(
　DWORD dwFreq,　　　// 声音频率
　DWORD dwDuration　 // 声音持续时间
);  
　　要用 C# 来编写这一原型，需要将 Win32 类型转换成相应的 C# 类型。由于 DWORD 是 4 字节的整数，因此我们可以使用 int 或 uint 作为 C# 对应类型。由于 int 是 CLS 兼容类型（可以用于所有 .NET 语言），以此比 uint 更常用，并且在多数情况下，它们之间的区别并不重要。bool 类型与 BOOL 对应。现在我们可以用 C# 编写以下原型：
　　public static extern bool Beep(int frequency, int duration);
　　这是相当标准的定义，只不过我们使用了 extern 来指明该函数的实际代码在别处。此原型将告诉运行时如何调用函数。代码如下：
using System;
using System.Runtime.InteropServices;
namespace Beep
{
class Class1
　{
　　　[DllImport("kernel32.dll")]
　　　public static extern bool Beep(int frequency, int duration);
　　　static void Main(string[] args)
　　　{
　　　　　Random random = new Random();
　　　　　for (int i = 0; i < 10000; i++)
　　　　　{
　　　　　　Beep(random.Next(10000), 100);
　　　　　}
　　　}
　}
}  
　　由于 DllImport 允许您调用 Win32 中的任何代码，因此就有可能调用恶意代码。所以您必须是完全受信任的用户，运行时才能进行 P/Invoke 调用。

　　 枚举和常量
　　Beep() 可用于发出任意声音，但有时我们希望发出特定类型的声音，因此我们改用 MessageBeep()。MSDN 给出了以下原型：
BOOL MessageBeep(
　UINT uType // 声音类型
);  
　　这看起来很简单，但是从注释中可以发现两个有趣的事实。
　　首先，uType 参数实际上接受一组预先定义的常量。
　　其次，可能的参数值包括 -1，这意味着尽管它被定义为 uint 类型，但 int 会更加适合。对于 uType 参数，使用 enum 类型是合乎情理的。MSDN 列出了已命名的常量，但没有就具体值给出任何提示。由于这一点，我们需要查看实际的 API。
　　如果您安装了 Visual Studio? 和 C++，则 Platform SDK 位于 Program FilesMicrosoft Visual Studio .NETVc7PlatformSDKInclude 下。
　　为查找这些常量，我在该目录中执行了一个 findstr。
　　findstr "MB_ICONHAND" *.h
　　它确定了常量位于 winuser.h 中，然后我使用这些常量来创建我的 enum 和原型：
public enum BeepType
{
　 SimpleBeep = -1,
　 IconAsterisk = 0x00000040,
　 IconExclamation = 0x00000030,
　 IconHand = 0x00000010,
　 IconQuestion = 0x00000020,
　 Ok = 0x00000000,
}

[DllImport("user32.dll")]
public static extern bool MessageBeep(BeepType beepType);  
　　现在我可以用下面的语句来调用它： MessageBeep(BeepType.IconQuestion);

　　 处理结构
　　有时我需要确定我笔记本的电池状况。Win32 为此提供了电源管理函数。
　　搜索 MSDN 可以找到 GetSystemPowerStatus() 函数。
BOOL GetSystemPowerStatus(
　LPSYSTEM_POWER_STATUS lpSystemPowerStatus
);  
　　此函数包含指向某个结构的指针，我们尚未对此进行过处理。要处理结构，我们需要用 C# 定义结构。我们从非托管的定义开始：
typedef struct _SYSTEM_POWER_STATUS {
  BYTE　 ACLineStatus;
  BYTE　 BatteryFlag;
  BYTE　 BatteryLifePercent;
  BYTE　 Reserved1;
  DWORD　BatteryLifeTime;
  DWORD　BatteryFullLifeTime;
} SYSTEM_POWER_STATUS, *LPSYSTEM_POWER_STATUS;  
　　然后，通过用 C# 类型代替 C 类型来得到 C# 版本。
struct SystemPowerStatus
{
　 byte ACLineStatus;
　 byte batteryFlag;
　 byte batteryLifePercent;
　 byte reserved1;
　 int batteryLifeTime;
　 int batteryFullLifeTime;
}  
　　这样，就可以方便地编写出 C# 原型：
[DllImport("kernel32.dll")]
public static extern bool GetSystemPowerStatus( ref SystemPowerStatus systemPowerStatus);  
　　在此原型中，我们用“ref”指明将传递结构指针而不是结构值。这是处理通过指针传递的结构的一般方法。
　　此函数运行良好，但是最好将 ACLineStatus 和 batteryFlag 字段定义为 enum：
　　enum ACLineStatus: byte
　　{
　　　Offline = 0,
　　　Online = 1,
　　　Unknown = 255,
　　}
　　enum BatteryFlag: byte
　　{ ...}  
　　请注意，由于结构的字段是一些字节，因此我们使用 byte 作为该 enum 的基本类型。

　　 字符串
　　虽然只有一种 .NET 字符串类型，但这种字符串类型在非托管应用中却有几项独特之处。可以使用具有内嵌字符数组的字符指针和结构，其中每个数组都需要正确的封送处理。
　　在 Win32 中还有两种不同的字符串表示：ANSI,Unicode
　　由于 P/Invoke 的设计者不想让您为所在的平台操心，因此他们提供了内置的支持来自动使用 A 或 W 版本。如果您调用的函数不存在，互操作层将为您查找并使用 A 或 W 版本。
　　通过示例能够很好地说明字符串支持的一些精妙之处。

     简单字符串
　　下面是一个接受字符串参数的函数的简单示例：
BOOL GetDiskFreeSpace(
  LPCTSTR lpRootPathName, 　　　　// 根路径
  LPDWORD lpSectorsPerCluster,　　// 每个簇的扇区数
  LPDWORD lpBytesPerSector,　　　 // 每个扇区的字节数
  LPDWORD lpNumberOfFreeClusters, // 可用的扇区数
  LPDWORD lpTotalNumberOfClusters // 扇区总数
);
　　根路径定义为 LPCTSTR。这是独立于平台的字符串指针。
　　以下是该函数的完整定义，就象我开始定义的那样：
[DllImport("kernel32.dll")]
static extern bool GetDiskFreeSpace(
　[MarshalAs(UnmanagedType.LPTStr)]
　 string rootPathName,
　 ref int sectorsPerCluster,
　 ref int bytesPerSector,
　 ref int numberOfFreeClusters,
　 ref int totalNumberOfClusters);  

　　不幸的是，当我试图运行时，该函数不能执行。问题在于，无论我们在哪个平台上，封送拆收器在默认情况下都试图查找 API 的 Ansi 版本，由于 LPTStr 意味着在 Windows NT 平台上会使用 Unicode 字符串，因此试图用 Unicode 字符串来调用 Ansi 函数就会失败。
    有两种方法可以解决这个问题：一种简单的方法是删除 MarshalAs 属性。如果这样做，将始终调用该函数的 A 版本，如果在您所涉及的所有平台上都有这种版本，这是个很好的方法。但是，这会降低代码的执行速度，因为封送拆收器要将 .NET 字符串从 Unicode 转换为多字节，然后调用函数的 A 版本（将字符串转换回 Unicode），最后调用函数的 W 版本。
　　要避免出现这种情况，可以将 CharSet 设置为 DllImport 属性的一部分：
　　[DllImport("kernel32.dll", CharSet = CharSet.Auto)]
　　对于大多数 Win32 API，都可以对字符串类型设置 CharSet 属性并使用 LPTStr。但是，还有一些不采用 A/W 机制的函数，对于这些函数必须采取不同的方法。

     字符串缓冲区
　　.NET 中的字符串类型是不可改变的类型，这意味着它的值将永远保持不变。对于要将字符串值复制到字符串缓冲区的函数，字符串将无效。这样做至少会破坏由封送拆收器在转换字符串时创建的临时缓冲区；严重时会破坏托管堆，而这通常会导致错误的发生。无论哪种情况都不可能获得正确的返回值。
　　要解决此问题，我们需要使用其他类型。StringBuilder 类型就是被设计为用作缓冲区的，我们将使用它来代替字符串。下面是一个示例：
[DllImport("kernel32.dll", CharSet = CharSet.Auto)]
public static extern int GetShortPathName(
　 [MarshalAs(UnmanagedType.LPTStr)]
　 string path,
　 [MarshalAs(UnmanagedType.LPTStr)]
　 StringBuilder shortPath,
　 int shortPathLength);  

　　使用此函数很简单：
StringBuilder shortPath = new StringBuilder(80);
int result = GetShortPathName(
@"d:/dest.jpg", shortPath, shortPath.Capacity);
string s = shortPath.ToString();
　　请注意，StringBuilder 的 Capacity 传递的是缓冲区大小。

　　 具有内嵌字符数组的结构
　　某些函数接受具有内嵌字符数组的结构。例如，GetTimeZoneInformation() 函数接受指向以下结构的指针：
typedef struct _TIME_ZONE_INFORMATION {
　　LONG　　　 Bias;
　　WCHAR　　　StandardName[ 32 ];
　　SYSTEMTIME StandardDate;
　　LONG　　　 StandardBias;
　　WCHAR　　　DaylightName[ 32 ];
　　SYSTEMTIME DaylightDate;
　　LONG　　　 DaylightBias;
} TIME_ZONE_INFORMATION, *PTIME_ZONE_INFORMATION;  

　　在 C# 中使用它需要有两种结构。一种是 SYSTEMTIME，它的设置很简单：
　 struct SystemTime
　 {
　　　public short wYear;
　　　public short wMonth;
　　　public short wDayOfWeek;
　　　public short wDay;
　　　public short wHour;
　　　public short wMinute;
　　　public short wSecond;
　　　public short wMilliseconds;
　 }  
　　这里没有什么特别之处；另一种是 TimeZoneInformation，它的定义要复杂一些：
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
struct TimeZoneInformation
{
　 public int bias;
　 [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
　 public string standardName;
　 SystemTime standardDate;
　 public int standardBias;
　 [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
　 public string daylightName;
　 SystemTime daylightDate;
　 public int daylightBias;
}  
　　此定义有两个重要的细节。第一个是 MarshalAs 属性：
　 [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
　　查看 ByValTStr 的文档，我们发现该属性用于内嵌的字符数组；另一个是 SizeConst，它用于设置数组的大小。
　　我在第一次编写这段代码时，遇到了执行引擎错误。通常这意味着部分互操作覆盖了某些内存，表明结构的大小存在错误。我使用 Marshal.SizeOf() 来获取所使用的封送拆收器的大小，结果是 108 字节。我进一步进行了调查，很快回忆起用于互操作的默认字符类型是 Ansi 或单字节。而函数定义中的字符类型为 WCHAR，是双字节，因此导致了这一问题。

　　我通过添加 StructLayout 属性进行了更正。结构在默认情况下按顺序布局，这意味着所有字段都将以它们列出的顺序排列。CharSet 的值被设置为 Unicode，以便始终使用正确的字符类型。

　　 指针参数
　　许多 Windows API 函数将指针作为它们的一个或多个参数。指针增加了封送数据的复杂性，因为它们增加了一个间接层。如果没有指针，您可以通过值在线程堆栈中传递数据。有了指针，则可以通过引用传递数据，方法是将该数据的内存地址推入线程堆栈中。然后，函数通过内存地址间接访问数据。使用托管代码表示此附加间接层的方式有多种。
　　在 C# 中，如果将方法参数定义为 ref 或 out，则数据通过引用而不是通过值传递。即使您没有使用 Interop 也是这样，但只是从一个托管方法调用到另一个托管方法。例如，如果通过 ref 传递 System.Int32 参数，则在线程堆栈中传递的是该数据的地址，而不是整数值本身。下面是一个定义为通过引用接收整数值的方法的示例：
void FlipInt32(ref Int32 num){
   num = -num;
}

　　 封送不透明 (Opaque) 指针：一种特殊情况
　　有时在 Windows API 中，方法传递或返回的指针是不透明的，这意味着该指针值从技术角度讲是一个指针，但代码却不直接使用它。相反，代码将该指针返回给 Windows 以便随后进行重用。
　　一个非常常见的例子就是句柄的概念。在 Windows 中，内部数据结构（从文件到屏幕上的按钮）在应用程序代码中都表示为句柄。句柄其实就是不透明的指针或有着指针宽度的数值，应用程序用它来表示内部的 OS 构造。
　　少数情况下，API 函数也将不透明指针定义为 PVOID 或 LPVOID 类型。在 Windows API 的定义中，这些类型意思就是说该指针没有类型。
　　当一个不透明指针返回给您的应用程序（或者您的应用程序期望得到一个不透明指针）时，您应该将参数或返回值封送为 CLR 中的一种特殊类型 — System.IntPtr。当您使用 IntPtr 类型时，通常不使用 out 或 ref 参数，因为 IntPtr 意为直接持有指针。不过，如果您将一个指针封送为一个指针，则对 IntPtr 使用 by-ref 参数是合适的。
　　在 CLR 类型系统中，System.IntPtr 类型有一个特殊的属性。不像系统中的其他基类型，IntPtr 并没有固定的大小。相反，它在运行时的大小是依底层操作系统的正常指针大小而定的。这意味着在 32 位的 Windows 中，IntPtr 变量的宽度是 32 位的，而在 64 位的 Windows 中，实时编译器编译的代码会将 IntPtr 值看作 64 位的值。当在托管代码和非托管代码之间封送不透明指针时，这种自动调节大小的特点十分有用。
　　请记住，任何返回或接受句柄的 API 函数其实操作的就是不透明指针。您的代码应该将 Windows 中的句柄封送成 System.IntPtr 值。
　　您可以在托管代码中将 IntPtr 值强制转换为 32 位或 64 位的整数值，或将后者强制转换为前者。然而，当使用 Windows API 函数时，因为指针应是不透明的，所以除了存储和传递给外部方法外，不能将它们另做它用。这种“只限存储和传递”规则的两个特例是当您需要向外部方法传递 null 指针值和需要比较 IntPtr 值与 null 值的情况。为了做到这一点，您不能将零强制转换为 System.IntPtr，而应该在 IntPtr 类型上使用 Int32.Zero 静态公共字段，以便获得用于比较或赋值的 null 值。

   具有回调的函数
　　当 Win32 函数需要返回多项数据时，通常都是通过回调机制来实现的。开发人员将函数指针传递给函数，然后针对每一项调用开发人员的函数。
　　在 C# 中没有函数指针，而是使用“委托”，在调用 Win32 函数时使用委托来代替函数指针。EnumDesktops() 函数就是这类函数的一个示例：
BOOL EnumDesktops(
　HWINSTA hwinsta,　　　　　　 // 窗口实例的句柄
　DESKTOPENUMPROC lpEnumFunc,　// 回调函数
　LPARAM lParam　　　　　　　　// 用于回调函数的值
);  
　　HWINSTA 类型由 IntPtr 代替，而 LPARAM 由 int 代替。DESKTOPENUMPROC 所需的工作要多一些。下面是 MSDN 中的定义：
BOOL CALLBACK EnumDesktopProc(
　LPTSTR lpszDesktop,　// 桌面名称
　LPARAM lParam　　　　// 用户定义的值
);  
　　我们可以将它转换为以下委托：
delegate bool EnumDesktopProc(
　[MarshalAs(UnmanagedType.LPTStr)]
　 string desktopName,
　 int lParam);  

　　完成该定义后，我们可以为 EnumDesktops() 编写以下定义：
[DllImport("user32.dll", CharSet = CharSet.Auto)]
static extern bool EnumDesktops(
　 IntPtr windowStation,
　 EnumDesktopProc callback,
　 int lParam);  

　　这样该函数就可以正常运行了。
　　在互操作中使用委托时有个很重要的技巧：封送拆收器创建了指向委托的函数指针，该函数指针被传递给非托管函数。但是，封送拆收器无法确定非托管函数要使用函数指针做些什么，因此它假定函数指针只需在调用该函数时有效即可。

　　结果是如果您调用诸如 SetConsoleCtrlHandler() 这样的函数，其中的函数指针将被保存以便将来使用，您就需要确保在您的代码中引用委托。如果不这样做，函数可能表面上能执行，但在将来的内存回收处理中会删除委托，并且会出现错误。

　 　其他高级函数
　　迄今为止我列出的示例都比较简单，但是还有很多更复杂的 Win32 函数。下面是一个示例：
DWORD SetEntriesInAcl(
　ULONG cCountOfExplicitEntries,　　　　　　// 项数
　PEXPLICIT_ACCESS pListOfExplicitEntries, // 缓冲区
　PACL OldAcl,　　　　　　　　　　　　　　 // 原始 ACL
　PACL *NewAcl　　　　　　　　　　　　　　　// 新 ACL
);  
　　前两个参数的处理比较简单：ulong 很简单，并且可以使用 UnmanagedType.LPArray 来封送缓冲区。
　　但第三和第四个参数有一些问题。问题在于定义 ACL 的方式。ACL 结构仅定义了 ACL 标头，而缓冲区的其余部分由 ACE 组成。ACE 可以具有多种不同类型，并且这些不同类型的 ACE 的长度也不同。
　　如果您愿意为所有缓冲区分配空间，并且愿意使用不太安全的代码，则可以用 C# 进行处理。但工作量很大，并且程序非常难调试。而使用 C++ 处理此 API 就容易得多。

　　 属性的其他选项
　　DLLImport 和 StructLayout 属性具有一些非常有用的选项，有助于 P/Invoke 的使用。下面列出了所有这些选项：
　　 DLL Import 属性
　　除了指出宿主 DLL 外，DllImportAttribute 还包含了一些可选属性，其中四个特别有趣：EntryPoint、CharSet、SetLastError 和 CallingConvention。
　　 EntryPoint 在不希望外部托管方法具有与 DLL 导出相同的名称的情况下，可以设置该属性来指示导出的 DLL 函数的入口点名称。当您定义两个调用相同非托管函数的外部方法时，这特别有用。另外，在 Windows 中还可以通过它们的序号值绑定到导出的 DLL 函数。如果您需要这样做，则诸如“#1”或“#129”的 EntryPoint 值指示 DLL 中非托管函数的序号值而不是函数名。
　　 CharSet 对于字符集，并非所有版本的 Windows 都是同样创建的。Windows 9 x 系列产品缺少重要的 Unicode 支持，而 Windows NT 和 Windows CE 系列则一开始就使用 Unicode。在这些操作系统上运行的 CLR 将Unicode 用于 String 和 Char 数据的内部表示。但也不必担心 — 当调用 Windows 9 x API 函数时，CLR 会自动进行必要的转换，将其从 Unicode转换为 ANSI。
　　如果 DLL 函数不以任何方式处理文本，则可以忽略 DllImportAttribute 的 CharSet 属性。然而，当 Char 或 String 数据是等式的一部分时，应该将 CharSet 属性设置为 CharSet.Auto。这样可以使 CLR 根据宿主 OS 使用适当的字符集。如果没有显式地设置 CharSet 属性， 则其默认值为 CharSet.Ansi 。这个默认值是有缺点的，因为对于在 Windows 2000、Windows XP 和 Windows NT? 上进行的 interop 调用，它会消极地影响文本参数封送处理的性能。
　　 SetLastError 错误处理非常重要，但在编程时经常被遗忘。当您进行 P/Invoke 调用时，也会面临其他的挑战 — 处理托管代码中 Windows API 错误处理和异常之间的区别。我可以给您一点建议。
　　如果您正在使用 P/Invoke 调用 Windows API 函数，而对于该函数，您使用 GetLastError 来查找扩展的错误信息，则应该在外部方法的 DllImportAttribute 中将 SetLastError 属性设置为 true。这适用于大多数外部方法。
　　这会导致 CLR 在每次调用外部方法之后缓存由 API 函数设置的错误。然后，在包装方法中，可以通过调用类库的 System.Runtime.InteropServices.Marshal 类型中定义的 Marshal.GetLastWin32Error 方法来获取缓存的错误值。我的建议是检查这些期望来自 API 函数的错误值，并为这些值引发一个可感知的异常。对于其他所有失败情况（包括根本就没意料到的失败情况），则引发在 System.ComponentModel 命名空间中定义的 Win32Exception，并将 Marshal.GetLastWin32Error 返回的值传递给它。
　　 CallingConvention   通过此属性，可以给 CLR 指示应该将哪种函数调用约定用于堆栈中的参数。CallingConvention.Winapi 的默认值是最好的选择，它在大多数情况下都可行。然而，如果该调用不起作用，则可以检查 Platform SDK 中的声明头文件，看看您调用的 API 函数是否是一个不符合调用约定标准的异常 API。
　　通常，本机函数（例如 Windows API 函数或 C- 运行时 DLL 函数）的调用约定描述了如何将参数推入线程堆栈或从线程堆栈中清除。大多数 Windows API 函数都是首先将函数的最后一个参数推入堆栈，然后由被调用的函数负责清理该堆栈。相反，许多 C-运行时 DLL 函数都被定义为按照方法参数在方法签名中出现的顺序将其推入堆栈，将堆栈清理工作交给调用者。
幸运的是，要让 P/Invoke 调用工作只需要让外围设备理解调用约定即可。通常，从默认值 CallingConvention.Winapi 开始是最好的选择。然后，在 C 运行时 DLL 函数和少数函数中，可能需要将约定更改为 CallingConvention.Cdecl。

　　 StructLayout
　　LayoutKind
　　结构在默认情况下按顺序布局，并且在多数情况下都适用。如果需要完全控制结构成员所放置的位置，可以使用 LayoutKind.Explicit，然后为每个结构成员添加 FieldOffset 属性。当您需要创建 union 时，通常需要这样做。

　　CharSet
　　控制 ByValTStr 成员的默认字符类型。

　　Pack
　　设置结构的压缩大小。它控制结构的排列方式。如果 C 结构采用了其他压缩方式，您可能需要设置此属性。

　　Size
　　设置结构大小。不常用；但是如果需要在结构末尾分配额外的空间，则可能会用到此属性。

　　 从不同位置加载
　　您无法指定希望 DLLImport 在运行时从何处查找文件，但是可以利用一个技巧来达到这一目的。
　　DllImport 调用 LoadLibrary() 来完成它的工作。如果进程中已经加载了特定的 DLL，那么即使指定的加载路径不同，LoadLibrary() 也会成功。
　　这意味着如果直接调用 LoadLibrary()，您就可以从任何位置加载 DLL，然后 DllImport LoadLibrary() 将使用该 DLL。
　　由于这种行为，我们可以提前调用 LoadLibrary()，从而将您的调用指向其他 DLL。如果您在编写库，可以通过调用 GetModuleHandle() 来防止出现这种情况，以确保在首次调用 P/Invoke 之前没有加载该库。

　 　P/Invoke 疑难解答
　　如果您的 P/Invoke 调用失败，通常是因为某些类型的定义不正确。以下是几个常见问题：
　　1.long != long。在 C++ 中，long 是 4 字节的整数，但在 C# 中，它是 8 字节的整数。
　　2.字符串类型设置不正确。