DeviceId

In version 6, instead of calling general methods directly on the builder, use platform-specific wrappers to ensure compatibility and access relevant components. This prevents runtime errors on unsupported platforms.

Common mapping examples:

// Example of platform-specific component selection in v6
builder.OnWindows(x => x.AddMachineGuid())
       .OnLinux(x => x.AddMachineId())
       .OnMac(x => x.AddPlatformSerialNumber());

Upgrading from version 5 to version 6 involves several breaking changes:

1. Package Splitting: DeviceId is now split into platform-specific packages. You must add references to the packages required for your target platforms (e.g., DeviceId.Windows, DeviceId.Windows.Wmi, DeviceId.Linux).
2. Formatter Changes: The default formatter has changed. To revert to the version 5 formatting style, use .UseFormatter(DeviceIdFormatters.DefaultV5).
3. Method Renaming and Platform Restrictions: Many methods have been moved into platform-specific extension methods (e.g., .OnWindows(), .OnLinux(), .OnMac()). Some components are no longer available on certain platforms.

If a specific component from v5 is missing in v6, you can re-implement it using a custom component.

// Reverting to v5 formatter in v6
string deviceId = new DeviceIdBuilder()
    .UseFormatter(DeviceIdFormatters.DefaultV5)
    .ToString();

If you have updated your device ID generation logic but need to remain backwards compatible with older identifiers (e.g., stored in license files), use DeviceIdManager. It allows you to register multiple builders, each associated with a version number. The manager will attempt to validate the input against the builders.

Example: Validating against multiple versions

var deviceIdManager = new DeviceIdManager()
    .AddBuilder(1, builder => builder
        .AddMachineName()
        .AddUserName()
        .AddMacAddress())
    .AddBuilder(2, builder => builder
        .AddMacAddress()
        .AddFileToken(TokenFilePath));

var savedDeviceIdFromLicenseFile = ReadDeviceIdFromLicenseFile();

// Validates the saved ID against the registered builders
var isLicenseValid = deviceIdManager.Validate(savedDeviceIdFromLicenseFile);

var deviceIdManager = new DeviceIdManager()
    .AddBuilder(1, builder => builder.AddMachineName())
    .AddBuilder(2, builder => builder.AddMacAddress());

bool isValid = deviceIdManager.Validate(savedId);

Use UseFormatter to control how the collected components are represented in the final string.

Custom Hash Formatter:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .UseFormatter(new HashDeviceIdFormatter(() => SHA256.Create(), new Base32ByteArrayEncoder()))
    .ToString();

Reverting to Version 5 format in Version 6:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .UseFormatter(DeviceIdFormatters.DefaultV5)
    .ToString();

Available Formatters (IDeviceIdFormatter)

• StringDeviceIdFormatter: Formats as a string containing each component ID using a specified encoding.
• HashDeviceIdFormatter: Formats as a hash string using a specified hash algorithm and byte array encoding.
• XmlDeviceIdFormatter: Formats as an XML document.

Available Encoders (IDeviceIdComponentEncoder / IByteArrayEncoder)

• PlainTextDeviceIdComponentEncoder: Plain text encoding.
• HashDeviceIdComponentEncoder: Hash string encoding.
• HexByteArrayEncoder: Hex string encoding.
• Base32UrlByteArrayEncoder: Base64 URL-encoded string.
• Base64ByteArrayEncoder: Base64 string.
• Base64UrlByteArrayEncoder: Base64 URL-encoded string.

Use the DeviceIdBuilder class to construct a device identifier by chaining component methods. The builder supports cross-platform components and platform-specific extensions (Windows, Linux, Mac) via lambda expressions.

Example: Windows-specific ID

string deviceId = new DeviceIdBuilder()
    .OnWindows(windows => windows.AddWindowsDeviceId())
    .ToString();

Example: Cross-platform ID

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .AddFileToken("example-device-token.txt")
    .ToString();

Example: Complex multi-platform ID

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .OnWindows(windows => windows
        .AddProcessorId()
        .AddMotherboardSerialNumber()
        .AddSystemDriveSerialNumber())
    .OnLinux(linux => linux
        .AddMotherboardSerialNumber()
        .AddSystemDriveSerialNumber())
    .OnMac(mac => mac
        .AddSystemDriveVolumeUUID()
        .AddPlatformSerialNumber())
    .ToString();

Example: SQL Server Database ID

using SqlConnection connection = new SqlConnection(connectionString);
connection.Open();
string databaseId = new DeviceIdBuilder()
    .AddSqlServer(connection, sql => sql
        .AddServerName()
        .AddDatabaseName()
        .AddDatabaseId())
    .ToString();

The following extension methods can be used with DeviceIdBuilder to include specific hardware or software attributes in the identifier. Availability depends on the installed package.

From DeviceId (Cross-platform)

• AddUserName(): Current user's username.
• AddMachineName(): Machine name.
• AddOsVersion(): Current OS version (uses Environment.OSVersion).
• AddMacAddress(): MAC address.
• AddFileToken(string path): A unique token stored in a file. Fails silently if no permissions.

From DeviceId.Windows

• AddWindowsDeviceId(): Windows Device ID (Machine ID/Advertising ID).
• AddWindowsProductId(): Windows Product ID.
• AddRegistryValue(string key): A specified registry value.
• AddMachineGuid(): Machine GUID from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography.

From DeviceId.Windows.Wmi / WmiLight / Mmi

• AddMacAddressFromWmi() / AddMacAddressFromMmi(): MAC address using improved query functionality.
• AddProcessorId(): Processor ID (falls back to Manufacturer/Name/Cores on ARM64).
• AddSystemDriveSerialNumber(): System drive's serial number.
• AddMotherboardSerialNumber(): Motherboard serial number.
• AddSystemUuid(): System UUID.

From DeviceId.Linux

• AddSystemDriveSerialNumber(): System drive's serial number.
• AddMotherboardSerialNumber(): Motherboard serial number (falls back to Device Tree on ARM).
• AddMachineId(): Machine ID from /var/lib/dbus/machine-id or /etc/machine-id.
• AddProductUuid(): Product UUID from /sys/class/dmi/id/product_uuid (falls back to Device Tree on ARM).
• AddCpuInfo(): CPU info from /proc/cpuinfo.
• AddDockerContainerId(): Docker container ID from /proc/1/cgroup.
• AddDeviceTreeSerialNumber(): Device Tree serial number (common on ARM).
• AddDeviceTreeModel(): Device Tree model (common on ARM).

From DeviceId.Mac

• AddSystemDriveVolumeUUID(): System drive's Volume UUID.
• AddPlatformSerialNumber(): IOPlatformSerialNumber.

From DeviceId.SqlServer

• AddServerName(): SQL Server name.
• AddDatabaseName(): Database name.
• AddDatabaseId(): Database ID.
• AddServerProperty(string name): Specified server property.
• AddServerProperty(string name, string value): Specified extended property.