WinDevicesNet 0.1.3

WinDevicesNet - .NET Wrapper for WinDevices

A modern .NET 8.0 wrapper for the WinDevices USB enumeration library. This library provides a clean, type-safe C# API for enumerating and querying USB devices on Windows.

Features

• Simple API: Clean, idiomatic C# interface
• Type-safe: Strongly-typed device information with nullable reference types
• Exception-based: Proper error handling with custom exceptions
• LINQ-friendly: Query devices with standard LINQ operators
• IDisposable: Proper resource management following .NET best practices
• Well-tested: Comprehensive unit and integration tests
• Thread-safe: Safe to use with multiple DeviceManager instances

Installation

dotnet add package WinDevicesNet

That is the whole story. The package ships the native WinDevices.dll under runtimes/win-x64/native/, so the .NET SDK records it in your deps.json and the runtime loads it from your build output. You do not need to install anything machine-wide, add a HintPath, or copy the native library yourself.

Target net8.0-windows or later. The library wraps the Windows Setup and Device Management APIs and only runs on Windows x64.

<ItemGroup>
  <PackageReference Include="WinDevicesNet" Version="0.1.1" />
</ItemGroup>

Installing the native library machine-wide

install.cmd copies the native library, headers, import library, and CMake package config to C:\Program Files\WinDevices. This is for native C/C++ consumers using find_package(WinDevices). .NET projects do not need it.

install.cmd --config Release

Manual Build

cd dotnet\WinDevicesNet
dotnet build -c Release

The compiled library will be in bin/Release/net8.0-windows/WinDevicesNet.dll

Usage

Quick Start

using WinDevices.Net;

// Create device manager (use using for automatic cleanup)
using var manager = new DeviceManager();

// Enumerate USB devices
manager.EnumerateUsbDevices();

// Print all devices
foreach (var device in manager.GetAllDevices())
{
    Console.WriteLine(device); // Uses ToString() for smart formatting
}

Basic Enumeration

using WinDevices.Net;

using var manager = new DeviceManager();
manager.EnumerateUsbDevices();

var devices = manager.GetAllDevices();

foreach (var device in devices)
{
    Console.WriteLine($"{device.Manufacturer} {device.Product}");
    Console.WriteLine($"Serial Number: {device.SerialNumber}");
    Console.WriteLine($"VID: 0x{device.VendorId:X4}, PID: 0x{device.ProductId:X4}");
    Console.WriteLine();
}

Finding Specific Devices

// Find by serial number
var device = manager.FindDeviceBySerialNumber("ABC123456");

// Find by predicate
var massStorageDevices = manager.FindDevices(d => d.DeviceClass == 0x08);

// Using LINQ
var logitechDevices = manager.GetAllDevices()
    .Where(d => d.VendorId == 0x046D)
    .ToList();

Enumerate by Device Class

using var manager = new DeviceManager();

// Enumerate keyboards only
manager.EnumerateKeyboards();

// Or enumerate disk drives
manager.EnumerateDiskDrives();

// Or USB mass storage devices
manager.EnumerateUsbMassStorage();

foreach (var device in manager.GetAllDevices())
{
    Console.WriteLine($"{device.Product} (VID={device.VendorId:X4}, PID={device.ProductId:X4})");
}

Error Handling

try
{
    using var manager = new DeviceManager();
    manager.EnumerateUsbDevices();

    var device = manager.GetDeviceInfo(0);
    Console.WriteLine($"First device: {device}");
}
catch (WinDevicesException ex) when (ex.ErrorCode == WinDevicesErrorCode.InvalidHandle)
{
    Console.WriteLine("Invalid device manager handle");
}
catch (WinDevicesException ex) when (ex.ErrorCode == WinDevicesErrorCode.InvalidIndex)
{
    Console.WriteLine("Device index out of range");
}
catch (WinDevicesException ex)
{
    Console.WriteLine($"Device enumeration error {ex.ErrorCode}: {ex.Message}");
}

API Reference

DeviceManager Class

Main class for USB device enumeration and management.

Constructor

• DeviceManager() - Creates a new device manager instance

Methods

Static Methods

• GetVersion() - Returns API version string (e.g., "1.0.0")

DeviceInfo Class

Immutable class containing USB device information.

Properties

WinDevicesException Class

Custom exception for device enumeration errors.

Properties

• ErrorCode - The WinDevicesErrorCode enum value
• Message - Human-readable error message

Error Codes

Common Device Class GUIDs

USB Device Classes

Common USB device class codes:

Best Practices

Resource Management

Always use using statements:

// Good - Automatic cleanup
using var manager = new DeviceManager();
manager.EnumerateUsbDevices();

Error Handling

Catch specific error codes when appropriate:

try
{
    var device = manager.GetDeviceInfo(index);
}
catch (WinDevicesException ex) when (ex.ErrorCode == WinDevicesErrorCode.InvalidIndex)
{
    return null;
}

Performance

Enumerate once, query multiple times:

// Good - Single enumeration
manager.EnumerateUsbDevices();
var allDevices = manager.GetAllDevices();
var storage = allDevices.Where(d => d.DeviceClass == 0x08);
var hid = allDevices.Where(d => d.DeviceClass == 0x03);

Troubleshooting

DllNotFoundException

Problem: System.DllNotFoundException: Unable to load DLL 'WinDevices.dll'

Solutions:

1. Ensure WinDevices.dll is installed (run install.cmd)
2. Check that the DLL is in C:\Program Files\WinDevices\dotnet\
3. Install Visual C++ Redistributable 2022

No Devices Found

Problem: GetDeviceCount() returns 0 after enumeration

Solutions:

1. Run application as Administrator (required for some USB operations)
2. Ensure USB devices are actually connected
3. Check Windows Device Manager for driver issues

Access Denied

Problem: Enumeration fails with access errors

Solutions:

1. Run as Administrator
2. Check Windows permissions for USB device access

Requirements

• .NET 8.0 or later
• Windows 10/11
• Visual C++ Redistributable 2022

Testing

cd dotnet\WinDevicesNet.Tests
dotnet test

The test suite includes unit tests, integration tests, and error handling tests.

Related Documentation

• Quick Start Guide
• Code Examples
• Main Project README

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For bug reports or feature requests, please use the GitHub Issues page.