平台调用 (P/Invoke)

项目
05/12/2024

P/Invoke 是可用于从托管代码访问非托管库中的结构、回调和函数的一种技术。大多数 P/Invoke API 包含在以下两个命名空间中：System 和 System.Runtime.InteropServices。使用这两个命名空间可提供用于描述如何与本机组件通信的工具。

我们从最常见的示例着手。该示例在托管代码中调用非托管函数。让我们从命令行应用程序显示一个消息框：

using System;
using System.Runtime.InteropServices;

public partial class Program
{
    // Import user32.dll (containing the function we need) and define
    // the method corresponding to the native function.
    [LibraryImport("user32.dll", StringMarshalling = StringMarshalling.Utf16, SetLastError = true)]
    private static partial int MessageBox(IntPtr hWnd, string lpText, string lpCaption, uint uType);

    public static void Main(string[] args)
    {
        // Invoke the function as a regular managed method.
        MessageBox(IntPtr.Zero, "Command-line message box", "Attention!", 0);
    }
}

上述示例非常简单，但确实演示了从托管代码调用非托管函数所需执行的操作。让我们逐步分析该示例：

第 2 行显示 System.Runtime.InteropServices 命名空间（用于保存全部所需项）的 using 指令。
第 8 行引入 LibraryImportAttribute 属性。此属性将告诉运行时应该加载非托管二进制文件。传入的字符串是包含目标函数的非托管二进制文件。此外，它还指定了要用于封送字符串的编码。最后，它指定此函数调用 SetLastError，且运行时应捕获相应错误代码，以便用户能够通过 Marshal.GetLastPInvokeError() 检索它。
第 9 行显示了 P/Invoke 的关键作用。它定义了一个托管方法，该方法的签名与非托管方法完全相同。声明使用 LibraryImport 特性和 partial 关键字告诉编译器扩展生成代码以调用非托管库。
- 在生成的代码中，在 .NET 7 之前使用的是 DllImport。此声明使用 extern 关键字向运行时指示这是一个外部方法，并且在调用它时，运行时应会在 DllImport 属性中指定的非托管二进制文件中找到它。

该示例的其余部分与调用任何其他托管方法一样调用该方法。

在 macOS 上也可以使用类似的示例。需要更改 LibraryImport 属性中的库名称，因为 macOS 使用不同的方案来命名动态库。下面的示例使用 getpid(2) 函数获取应用程序的进程 ID，然后控制台上列显该 ID：

using System;
using System.Runtime.InteropServices;

namespace PInvokeSamples
{
    public static partial class Program
    {
        // Import the libSystem shared library and define the method
        // corresponding to the native function.
        [LibraryImport("libSystem.dylib")]
        private static partial int getpid();

        public static void Main(string[] args)
        {
            // Invoke the function and get the process ID.
            int pid = getpid();
            Console.WriteLine(pid);
        }
    }
}

它在 Linux 上也是类似的。函数名称相同，因为 getpid(2) 是标准 POSIX 系统调用。

using System;
using System.Runtime.InteropServices;

namespace PInvokeSamples
{
    public static partial class Program
    {
        // Import the libc shared library and define the method
        // corresponding to the native function.
        [LibraryImport("libc.so.6")]
        private static partial int getpid();

        public static void Main(string[] args)
        {
            // Invoke the function and get the process ID.
            int pid = getpid();
            Console.WriteLine(pid);
        }
    }
}

从非托管代码调用托管代码

运行时允许通信流量双向流通，这样，便可以使用函数指针从本机函数回调托管代码。在托管代码中，与函数指针最接近的功能就是委托，正是凭借这个功能，才能从本机代码回调托管代码。

此功能的使用方式类似于上面所述的从托管代码调用本机进程。对于给定的回调，需要定义一个与签名匹配的委托，并将其传入外部方法。运行时将负责处理所有剩余工作。

using System;
using System.Runtime.InteropServices;

namespace ConsoleApplication1
{
    public static partial class Program
    {
        // Define a delegate that corresponds to the unmanaged function.
        private delegate bool EnumWC(IntPtr hwnd, IntPtr lParam);

        // Import user32.dll (containing the function we need) and define
        // the method corresponding to the native function.
        [LibraryImport("user32.dll")]
        private static partial int EnumWindows(EnumWC lpEnumFunc, IntPtr lParam);

        // Define the implementation of the delegate; here, we simply output the window handle.
        private static bool OutputWindow(IntPtr hwnd, IntPtr lParam)
        {
            Console.WriteLine(hwnd.ToInt64());
            return true;
        }

        public static void Main(string[] args)
        {
            // Invoke the method; note the delegate as a first parameter.
            EnumWindows(OutputWindow, IntPtr.Zero);
        }
    }
}

在演练示例之前，最好是回顾一下所要使用的非托管函数的签名。要调用以枚举所有窗口的函数具有以下签名：BOOL EnumWindows (WNDENUMPROC lpEnumFunc, LPARAM lParam);

第一个参数是回调。该回调具有以下签名：BOOL CALLBACK EnumWindowsProc (HWND hwnd, LPARAM lParam);

现在，让我们来演练示例：

示例中的第 9 行定义与非托管代码中回调签名匹配的委托。请注意如何在托管代码中使用 IntPtr 表示 LPARAM 和 HWND 类型。
第 13 和 14 行从 user32.dll 库中引入 EnumWindows 函数。
第 17 - 20 行实现该委托。在这个简单的示例中，我们只要将句柄输出到控制台。
最后，第 24 行调用外部方法并传入委托。

下面显示了 Linux 和 macOS 示例。在这些平台上，我们可以使用 C 库 libc 中的 ftw 函数。此函数用于遍历目录层次结构，它使用指向某个函数的指针作为其参数之一。该函数具有以下签名：int (*fn) (const char *fpath, const struct stat *sb, int typeflag)。

using System;
using System.Runtime.InteropServices;

namespace PInvokeSamples
{
    public static partial class Program
    {
        // Define a delegate that has the same signature as the native function.
        private delegate int DirClbk(string fName, ref Stat stat, int typeFlag);

        // Import the libc and define the method to represent the native function.
        [LibraryImport("libc.so.6", StringMarshalling = StringMarshalling.Utf16)]
        private static partial int ftw(string dirpath, DirClbk cl, int descriptors);

        // Implement the above DirClbk delegate;
        // this one just prints out the filename that is passed to it.
        private static int DisplayEntry(string fName, ref Stat stat, int typeFlag)
        {
            Console.WriteLine(fName);
            return 0;
        }

        public static void Main(string[] args)
        {
            // Call the native function.
            // Note the second parameter which represents the delegate (callback).
            ftw(".", DisplayEntry, 10);
        }
    }

    // The native callback takes a pointer to a struct. This type
    // represents that struct in managed code.
    [StructLayout(LayoutKind.Sequential)]
    public struct Stat
    {
        public uint DeviceID;
        public uint InodeNumber;
        public uint Mode;
        public uint HardLinks;
        public uint UserID;
        public uint GroupID;
        public uint SpecialDeviceID;
        public ulong Size;
        public ulong BlockSize;
        public uint Blocks;
        public long TimeLastAccess;
        public long TimeLastModification;
        public long TimeLastStatusChange;
    }
}

macOS 示例使用相同的函数，唯一的差别在于 LibraryImport 特性的自变量，因为 macOS 将 libc 保留在不同的位置。

using System;
using System.Runtime.InteropServices;

namespace PInvokeSamples
{
    public static partial class Program
    {
        // Define a delegate that has the same signature as the native function.
        private delegate int DirClbk(string fName, ref Stat stat, int typeFlag);

        // Import the libc and define the method to represent the native function.
        [LibraryImport("libSystem.dylib", StringMarshalling = StringMarshalling.Utf16)]
        private static partial int ftw(string dirpath, DirClbk cl, int descriptors);

        // Implement the above DirClbk delegate;
        // this one just prints out the filename that is passed to it.
        private static int DisplayEntry(string fName, ref Stat stat, int typeFlag)
        {
            Console.WriteLine(fName);
            return 0;
        }

        public static void Main(string[] args)
        {
            // Call the native function.
            // Note the second parameter which represents the delegate (callback).
            ftw(".", DisplayEntry, 10);
        }
    }

    // The native callback takes a pointer to a struct. This type
    // represents that struct in managed code.
    [StructLayout(LayoutKind.Sequential)]
    public struct Stat
    {
        public uint DeviceID;
        public uint InodeNumber;
        public uint Mode;
        public uint HardLinks;
        public uint UserID;
        public uint GroupID;
        public uint SpecialDeviceID;
        public ulong Size;
        public ulong BlockSize;
        public uint Blocks;
        public long TimeLastAccess;
        public long TimeLastModification;
        public long TimeLastStatusChange;
    }
}

上面两个示例都依赖于参数，在这两种情况下，参数是作为托管类型提供的。运行时将采取“适当的措施”，在另一个平台上将这些代码处理成等效的代码。类型封送页介绍了如何将类型封送到本机代码。

通过

平台调用 (P/Invoke)

从非托管代码调用托管代码

更多资源

其他资源