简介：这份资源面向具备一定C#基础的.NET开发者与USB上位机开发初学者，围绕libusbDotNet库讲解如何在C#中完成USB设备的枚举、打开、读写与异常处理，帮助解决.NET环境下访问USB设备接口不便的问题。压缩包共236个文件，约4.05MB，以132个dll动态库、24个xml文档、17个txt说明、7个nupkg包及5个cs源码文件为主，另含sln解决方案、csproj工程与config配置，构成可直接运行的完整示例工程。资源中通过Manager类枚举设备、按VendorId与ProductId筛选目标，并演示WriteEndpoint与ReadEndpoint的读写流程及超时处理，覆盖控制、批量、中断等传输模式，便于读者对照代码理解USB通信链路。目前已有4798人学习下载，适合需要快速搭建USB读写程序、排查设备通信问题的开发者参考借鉴。
1. 为什么我宁愿用 LibUsbDotNet 也不直接调 WinUSB
去年帮一个做工业采集的朋友调一套 C# 上位机，设备插上后系统能识别，但厂商只给了一份模糊的寄存器手册，没有现成 DLL。他一开始想用 WinUSB 的 P/Invoke 硬啃，结果 SetupAPI 那套设备枚举加接口绑定写了三百多行，换台机器就翻车。后来我让他换成 LibUsbDotNet，同样的读写逻辑压到几十行，跨 Windows 和 Linux 的调试成本也降下来了。
LibUsbDotNet 是 libusb 的 .NET 封装，把设备枚举、接口声明、批量传输、控制传输这些底层操作包装成 C# 对象。它解决的核心问题是：当你面对一个没有官方 SDK 的 USB 设备，又不想被操作系统驱动模型绑死时，能用一个统一的 API 完成打开、配置、读写、释放。适合做嵌入式调试工具、产线测试上位机、自定义 HID 扩展设备的开发者。前提是你得知道端点地址、传输类型和协议格式，否则再好的库也读不出数据。
2. 环境搭建与设备枚举：从 NuGet 包到拿到设备句柄
2.1 安装与项目配置
新建一个 .NET 控制台项目，目标框架选 net6.0 或 net48 都行，LibUsbDotNet 对两者都兼容。通过 NuGet 安装：
dotnet add package LibUsbDotNet如果你用的是传统 .NET Framework 项目，在包管理器控制台执行：
Install-Package LibUsbDotNet装完后检查输出目录，应该能看到 LibUsbDotNet.dll 和对应的原生 libusb-1.0.dll。这里有个容易忽略的点：原生 DLL 的平台位数必须和你的进程匹配。AnyCPU 在 64 位系统上默认跑 64 位进程，如果你手头只有 32 位的 libusb-1.0.dll，就会在运行时抛DllNotFoundException。我一般直接把项目平台目标设成 x64，然后把 64 位原生 DLL 放到输出目录，省得后面排查。
2.2 枚举设备与识别目标
LibUsbDotNet 提供两种枚举方式：按 VID/PID 精确匹配，或者遍历所有设备后按描述符过滤。产线工具里我倾向后者，因为同一款设备可能烧录了不同 PID 做区分。
using LibUsbDotNet; using LibUsbDotNet.Main; // 获取所有已连接 USB 设备 UsbRegDeviceList allDevices = UsbDevice.AllDevices; foreach (UsbRegistry deviceReg in allDevices) { // 读取 VID、PID 和产品字符串 int vid = deviceReg.Vid; int pid = deviceReg.Pid; string product = deviceReg.Device.Info.ProductString; Console.WriteLine($"VID=0x{vid:X4} PID=0x{pid:X4} Product={product}"); // 假设目标设备 VID=0x1234 PID=0x5678 if (vid == 0x1234 && pid == 0x5678) { // 尝试打开设备 if (deviceReg.Open(out IUsbDevice usbDevice)) { Console.WriteLine("设备打开成功"); // 后续操作使用 usbDevice } else { Console.WriteLine("设备打开失败，可能被其他驱动占用"); } } }这段代码的逻辑是：先拿到系统里所有 USB 设备的注册表信息，再逐个比对 VID/PID。UsbRegistry对象里还包含Device.Info，能读到厂商字符串、序列号等描述符。参数方面，Vid和Pid是十六进制整数，写的时候注意别把0x1234写成十进制1234，这是新手最常见的低级错误。
如果设备已经被系统自带的 HID 或厂商驱动接管，Open会返回 false。这时候要么在设备管理器里把驱动换成 WinUSB/libusb，要么用 libusb 的过滤驱动做绑定。具体换驱动的方法取决于设备类型，常见做法是用 Zadig 工具把接口驱动替换成 WinUSB，但这一步有风险，换错驱动可能导致设备无法恢复，建议在虚拟机或备用机上先验证。
2.3 接口声明与端点确认
打开设备后，必须声明要使用的接口，否则读写会直接失败。USB 设备通常有多个接口，每个接口下挂若干端点。端点地址决定了数据方向：0x81表示端点 1 的 IN 方向（设备到主机），0x01表示端点 1 的 OUT 方向（主机到设备）。
// 假设设备只有一个接口，编号 0 if (usbDevice is IUsbDevice wholeDevice) { // 声明接口，第二个参数表示是否强制声明 wholeDevice.SetConfiguration(1); wholeDevice.ClaimInterface(0); }SetConfiguration(1)是激活设备的第一个配置，绝大多数单配置设备写 1 就行。ClaimInterface(0)告诉系统这个接口归我管，其他进程不能再抢。如果设备有多个接口，比如一个用于控制一个用于数据，就要分别 Claim 对应的接口号。忘记 Claim 接口的典型症状是读写返回UsbError.DeviceNotFound或直接抛异常，排查时先看这一步有没有漏。
3. 批量传输与控制传输：读写循环怎么写才不丢包
3.1 批量端点读写
批量传输是 USB 数据采集最常用的方式，适合大量、对时间不敏感但要求不丢数据的场景。下面是一个完整的批量读循环：
// 定义端点：0x81 为 IN 端点，0x01 为 OUT 端点 byte[] readBuffer = new byte[64]; // 缓冲区大小与端点最大包长一致 byte[] writeBuffer = new byte[64]; // 创建端点读写器 UsbEndpointReader reader = usbDevice.OpenEndpointReader(ReadEndpointID.Ep01); UsbEndpointWriter writer = usbDevice.OpenEndpointWriter(WriteEndpointID.Ep01); // 写入数据 int bytesWritten; UsbError writeErr = writer.Write(writeBuffer, 1000, out bytesWritten); if (writeErr != UsbError.None) { Console.WriteLine($"写失败: {writeErr}"); } // 循环读取 while (true) { int bytesRead; // 超时设为 500ms，避免死等 UsbError readErr = reader.Read(readBuffer, 500, out bytesRead); if (readErr == UsbError.None && bytesRead > 0) { // 处理数据，例如打印十六进制 Console.WriteLine(BitConverter.ToString(readBuffer, 0, bytesRead)); } else if (readErr == UsbError.Timeout) { // 超时不算错误，继续下一轮 continue; } else { Console.WriteLine($"读失败: {readErr}"); break; } }Read方法的第二个参数是超时毫秒数，设 0 表示无限等待，设 -1 表示立即返回。产线工具里我一般设 500 到 1000，既能及时响应停止指令，又不会因为频繁轮询吃满 CPU。缓冲区大小要和端点的MaximumPacketSize对齐，如果端点最大包长是 64 字节，你给 32 字节的缓冲区，一次传输就会被拆成多个包，处理起来更麻烦。
Write方法返回的UsbError枚举能区分多种失败原因：Timeout表示设备没在指定时间内响应，Pipe表示端点方向搞反了，Io表示底层传输错误。写的时候如果一直返回Pipe，先检查WriteEndpointID是不是写成了Ep01而实际设备用的是Ep02。
3.2 控制传输与参数配置
控制传输用于发送标准请求或厂商自定义命令，比如设置采样率、读取设备状态。LibUsbDotNet 把控制传输封装成ControlTransfer方法：
// 厂商自定义请求：bRequest=0x01，设置采样率 byte[] setupData = new byte[] { 0xE8, 0x03 }; // 1000 的小端表示 int transferred; UsbSetupPacket setupPacket = new UsbSetupPacket( (byte)(UsbCtrlFlags.Direction_Out | UsbCtrlFlags.RequestType_Vendor | UsbCtrlFlags.Recipient_Device), 0x01, // bRequest 0x0000, // wValue 0x0000, // wIndex (short)setupData.Length ); UsbError ctrlErr = usbDevice.ControlTransfer(ref setupPacket, setupData, setupData.Length, out transferred); if (ctrlErr != UsbError.None) { Console.WriteLine($"控制传输失败: {ctrlErr}"); }UsbSetupPacket的四个关键字段对应 USB 协议里的 bmRequestType、bRequest、wValue、wIndex。bmRequestType由方向、请求类型、接收者三部分按位或组成。厂商自定义请求通常用RequestType_Vendor，标准请求用RequestType_Standard。如果设备手册里写的是“发送命令 0x01，参数 1000”，那 bRequest 就是 0x01，数据段放 1000 的二进制表示。控制传输的数据阶段长度必须和wLength一致，否则设备可能直接 STALL。
3.3 异步读写与事件驱动
同步读写适合简单场景，但如果你的上位机还要刷新界面，同步阻塞会卡死 UI 线程。LibUsbDotNet 支持事件驱动的异步模式：
// 注册数据接收事件 reader.DataReceived += (sender, e) => { if (e.Count > 0) { byte[] data = new byte[e.Count]; Array.Copy(e.Buffer, data, e.Count); // 在事件里做轻量处理，重活丢给线程池 ThreadPool.QueueUserWorkItem(_ => ProcessData(data)); } }; // 开始异步读，缓冲区大小 64，超时 0 表示持续监听 reader.ReadFlush(); reader.DataReceivedEnabled = true;DataReceivedEnabled设为 true 后，底层会起一个后台线程持续读端点，收到数据就触发事件。注意事件回调里不要做耗时操作，否则会阻塞后续数据接收。我一般只做数据拷贝，解析和入库丢到线程池。停止监听时先设DataReceivedEnabled = false，再调ReadFlush清空缓冲区，顺序反了可能丢最后一包数据。
4. 避坑排查：设备打开失败、传输超时、驱动冲突怎么定位
4.1 现象：Open 返回 false，设备管理器显示黄色感叹号
原因：设备被系统默认驱动接管，或者 VID/PID 匹配到了但接口被占用。Windows 对 HID 类设备会自动加载 hidusb.sys，这时候 libusb 拿不到控制权。
解决：先在设备管理器里查看设备属性，确认驱动提供商。如果是厂商驱动，尝试卸载后重新插拔，让系统加载 WinUSB。如果设备是 HID 类，可以用 libusb 的 HID 兼容模式，但功能会受限。更稳妥的做法是联系设备方提供 libusb 兼容固件，或者在 INF 文件里指定 WinUSB 驱动。
4.2 现象：Read 一直返回 Timeout，但设备确实在发数据
原因：端点地址写错，或者接口没有正确 Claim。还有一种可能是设备固件在等待主机先发命令才启动数据流。
解决：先用 USB 分析仪或 Wireshark 的 USBPcap 抓包，确认设备是否真的有 IN 数据。如果没有，检查是否需要先发启动命令。如果抓到了数据但程序读不到，核对ReadEndpointID是否和描述符里的 bEndpointAddress 一致。注意 LibUsbDotNet 的ReadEndpointID.Ep01对应地址 0x81，Ep02对应 0x82，别把端点号和地址搞混。
4.3 现象：Write 返回 Pipe 错误
原因：端点方向反了。WriteEndpointID只能用于 OUT 端点，如果你把 IN 端点传进去，底层会直接报 Pipe。
解决：查看设备描述符里的端点地址，最高位为 1 的是 IN，为 0 的是 OUT。WriteEndpointID.Ep01对应地址 0x01，ReadEndpointID.Ep01对应 0x81。如果设备只有一个双向端点（某些自定义设备会这么设计），需要根据协议切换读写方向，LibUsbDotNet 不支持同一个端点同时读写。
4.4 现象：程序运行一段时间后报“设备未找到”
原因：USB 设备被拔出或复位，或者系统电源管理把设备挂起了。
解决：在读写循环里捕获UsbError.DeviceNotFound，然后重新枚举设备并重新打开。更彻底的做法是监听 Windows 的设备变更消息（WM_DEVICECHANGE），在设备重新插入时自动重连。另外在设备管理器里把 USB 根集线器的电源管理选项“允许计算机关闭此设备以节约电源”取消勾选，能减少意外挂起。
4.5 现象：换一台电脑就报 DllNotFoundException
原因：原生 libusb-1.0.dll 没有随程序发布，或者位数不匹配。
解决：在项目里把 libusb-1.0.dll 的属性设为“如果较新则复制”，确保输出目录里有这个文件。如果目标机器是 32 位系统，而你的程序编译成了 64 位，也会报这个错。统一用 x64 或 x86 编译，别用 AnyCPU 碰运气。
5. 进阶技巧：用设备过滤器做多设备并发与热插拔
单设备读写跑通后，下一步通常是支持多台同型号设备同时工作。LibUsbDotNet 提供了UsbDeviceFinder和UsbRegDeviceList的组合用法，但直接遍历会有一个问题：每台设备打开后都占着接口，如果枚举和打开的逻辑写在一起，拔掉一台再插上，句柄就乱了。
我的做法是维护一个设备字典，键用序列号，值是对应的IUsbDevice和读写器。序列号从deviceReg.Device.Info.SerialString读，如果设备没烧序列号，就用 USB 端口路径代替。下面是一个简化的管理类骨架：
public class UsbDeviceManager { private Dictionary<string, UsbSession> _sessions = new(); public void ScanAndAttach() { var devices = UsbDevice.AllDevices; foreach (UsbRegistry reg in devices) { if (reg.Vid != 0x1234 || reg.Pid != 0x5678) continue; string key = reg.Device.Info.SerialString; if (string.IsNullOrEmpty(key)) key = reg.Device.Info.DevicePath; // 无序列号时用路径 if (_sessions.ContainsKey(key)) continue; // 已打开则跳过 if (reg.Open(out IUsbDevice dev)) { dev.SetConfiguration(1); dev.ClaimInterface(0); var session = new UsbSession(dev); _sessions[key] = session; session.StartRead(); } } } public void Detach(string key) { if (_sessions.TryGetValue(key, out var session)) { session.Stop(); session.Device.Close(); _sessions.Remove(key); } } }UsbSession里封装端点读写器和异步事件，StartRead启动后台读循环，Stop负责取消事件并释放接口。热插拔的触发可以靠定时扫描（比如每 2 秒调一次ScanAndAttach），也可以监听系统消息。定时扫描实现简单，代价是插拔响应有延迟，产线工具里 2 秒完全够用。
还有一个容易踩的坑：多台设备同时打开时，ClaimInterface可能会因为系统枚举顺序不同而随机失败。解决办法是在打开前先调UsbDevice.ForceLibUsbWinBack，强制走 libusb 的后端而不是 WinUSB，能减少驱动层的竞争。这个调用在程序启动时执行一次即可。
验证多设备并发是否稳定，我一般会写一个压力脚本：同时开 4 台设备，每台每秒发 100 包数据，跑 30 分钟，看有没有丢包或句柄泄漏。丢包率超过万分之一就要检查缓冲区大小和线程调度。句柄泄漏用任务管理器的句柄数观察，如果持续上涨，多半是Close没调到或者事件没解绑。
从那以后我每次做 USB 上位机，都强制先跑一遍枚举加打开加读写的冒烟测试，确认驱动和端点没问题再写业务逻辑。希望帮到你。
本文还有配套的精品资源，点击获取
