init

enriched-qwen3-coder-next/Common/DTS.Common.Licensing/SystemInformation.md

@@ -0,0 +1,91 @@
+---
+source_files:
+  - Common/DTS.Common.Licensing/SystemInformation/MachineInfo.cs
+  - Common/DTS.Common.Licensing/SystemInformation/ComputerSystemInfo.cs
+  - Common/DTS.Common.Licensing/SystemInformation/MainBoardInfo.cs
+  - Common/DTS.Common.Licensing/SystemInformation/ProcessorInfo.cs
+  - Common/DTS.Common.Licensing/SystemInformation/SystemInformationXSD.cs
+generated_at: "2026-04-16T03:29:41.596274+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "3f95f5cfcf14dbc2"
+---
+
+# SystemInformation
+
+## Documentation: System Information Module (`DTS.Common.Licensing.SystemInformation`)
+
+---
+
+### 1. **Purpose**
+
+This module provides static accessors to retrieve hardware-identifying information from the local Windows machine using WMI (Windows Management Instrumentation) and .NET environment APIs. It is part of the licensing subsystem and is intended to supply stable, hardware-based identifiers (e.g., motherboard serial, CPU ID, system UUID) for machine fingerprinting or license validation. The module is read-only and defensive: all property getters return empty strings on failure instead of throwing exceptions, ensuring robustness in constrained or non-standard environments.
+
+---
+
+### 2. **Public Interface**
+
+All types are `static` classes; no instantiation is required.
+
+| Type | Member | Signature | Behavior |
+|------|--------|-----------|----------|
+| `MachineInfo` | `MachineName` | `public static string MachineName { get; }` | Returns the network name of the machine via `Environment.MachineName`. Returns `""` on any exception. |
+| `ComputerSystemInfo` | `SystemID` | `public static string SystemID { get; }` | Returns the UUID of the computer system product (from `Win32_ComputerSystemProduct.UUID`). Returns `""` on any exception. |
+| `MainBoardInfo` | `SerialNumber` | `public static string SerialNumber { get; }` | Returns the serial number of the baseboard (motherboard) (from `Win32_BaseBoard.SerialNumber`). Returns `""` on any exception. |
+| `ProcessorInfo` | `ProcessorID` | `public static string ProcessorID { get; }` | Returns the `ProcessorID` field of the first processor (from `Win32_Processor.ProcessorID`). Returns `""` on any exception. |
+| `SystemInformationXSD` | `XSD` | `public static string XSD { get; }` | Returns a hardcoded XML Schema Definition (XSD) string for validating a `SysInfo` XML document containing the above fields. |
+
+> **Note**: All getters are *eagerly evaluated* on first access and cached internally (via static field initialization or static property getter logic). Subsequent accesses reuse the result unless the underlying WMI query is re-executed (see *Gotchas*).
+
+---
+
+### 3. **Invariants**
+
+- **Non-null return values**: All public properties return either a non-empty string (if WMI/Environment data is successfully retrieved) or `""` (empty string) on failure. **No property ever returns `null`.**
+- **No side effects**: Property getters are idempotent *per call*, but due to static `ManagementObjectSearcher` fields, repeated access may reuse cached WMI results (see *Gotchas*).
+- **Windows-only dependency**: All WMI-based properties (`SystemID`, `SerialNumber`, `ProcessorID`) assume Windows and rely on `System.Management`. Behavior on non-Windows platforms is undefined (but likely to return `""` due to exception handling).
+- **Schema consistency**: The `XSD` string defines a fixed schema for a `SysInfo` XML element containing exactly four child elements (`MainBoardSerialNumber`, `ProcessorID`, `SystemID`, `MachineName`) and two attributes (`Version`, `SystemInformationGuid`). The order of child elements is fixed.
+
+---
+
+### 4. **Dependencies**
+
+| Dependency | Usage |
+|------------|-------|
+| `System.Environment` (mscorlib) | Used by `MachineInfo.MachineName` to fetch machine name. |
+| `System.Management` (System.Management.dll) | Required for all WMI-based properties (`ComputerSystemInfo.SystemID`, `MainBoardInfo.SerialNumber`, `ProcessorInfo.ProcessorID`). |
+| `System.Linq` (System.Core.dll) | Used via LINQ extension methods (`OfType<T>()`, `FirstOrDefault()`) to safely extract WMI results. |
+| `System.Collections.Generic` (System.Core.dll) | Used for `ManagementObjectSearcher.Get()` result enumeration. |
+
+**Depended on by**:  
+This module is part of `DTS.Common.Licensing`, implying it is consumed by licensing validation logic (e.g., to generate or verify machine fingerprints). No direct reverse dependencies are visible in the provided source.
+
+---
+
+### 5. **Gotchas**
+
+- **WMI query execution is not lazy per access**:  
+  `ManagementObjectSearcher` instances are *static fields*, initialized once at type initialization. Each property getter calls `systemSearcher.Get()` (or equivalent) *on every access*, meaning repeated calls to `ProcessorInfo.ProcessorID` will re-execute the WMI query each time. This is inefficient and may cause performance issues if called frequently. Consider caching the first result (e.g., via `Lazy<T>` or a static field) if repeated access is expected.
+
+- **`Win32_*` WMI classes are Windows-specific**:  
+  On non-Windows platforms (e.g., via .NET Core on Linux/macOS), `System.Management` may not be available or may throw exceptions. All properties will return `""`, but this behavior is not guaranteed across all environments.
+
+- **`ProcessorID` may be empty or non-unique**:  
+  The `Win32_Processor.ProcessorID` field is *not guaranteed* to be populated on all systems (e.g., virtual machines, some OEM hardware). It may be empty or fall back to a placeholder value. The code does not validate uniqueness or consistency across processors.
+
+- **`SystemID` vs. `UUID` ambiguity**:  
+  The WMI class `Win32_ComputerSystemProduct.UUID` is used for `SystemID`. While commonly stable, UUIDs can be reset (e.g., BIOS reset, VM cloning) or duplicated in some virtualized environments.
+
+- **No validation of WMI field presence**:  
+  The code assumes the WMI properties (`UUID`, `SerialNumber`, `ProcessorID`) exist and are non-null. If a property is missing from the WMI result (e.g., due to driver issues), `["FieldName"]` may throw a `NullReferenceException`, which is caught and returns `""`. This is safe but obscures the root cause.
+
+- **`SystemInformationXSD.XSD` is hardcoded and immutable**:  
+  The schema string is constant at compile time. There is no mechanism to update or version the schema dynamically. The `Version` and `SystemInformationGuid` attributes are defined in the schema but not used by any code in this module.
+
+- **No thread-safety guarantees**:  
+  While `ManagementObjectSearcher` is generally thread-safe for concurrent reads, the module does not document or enforce thread-safety. Concurrent access to these properties is *likely* safe but not guaranteed by design.
+
+- **No cleanup of WMI resources**:  
+  `ManagementObjectSearcher` implements `IDisposable`, but none of the searchers are disposed. This may lead to resource leaks in long-running processes (e.g., services), though `ManagementObjectSearcher` internally manages native handles and may mitigate this.
+
+> **Recommendation for future refactoring**: Cache results on first access using `Lazy<string>` and ensure proper disposal of WMI resources if repeated access is common.