DP44/enriched-qwen3-coder-next/DataPRO/Users/UserSettings.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Users/UserSettings/OptimizationSettings.cs DataPRO/Users/UserSettings/CategoryAttributeEx.cs DataPRO/Users/UserSettings/DisplayAttributeEx.cs DataPRO/Users/UserSettings/DescriptionAttributeEx.cs DataPRO/Users/UserSettings/PropertyIdAttribute.cs DataPRO/Users/UserSettings/SampleRateConverter.cs DataPRO/Users/UserSettings/UserHistory.cs DataPRO/Users/UserSettings/PropertyEnums.cs	2026-04-16T04:03:26.586662+00:00	Qwen/Qwen3-Coder-Next-FP8	1	1eb9bffd7fe29c43

Documentation: User Settings Module

1. Purpose

This module provides infrastructure for managing user-specific settings in the DataPRO system, including persistence to a database, localization via string resources, and UI integration for property grids. It defines core data structures (OptimizationSettings, UserHistory), attribute classes for metadata annotation (CategoryAttributeEx, DisplayAttributeEx, DescriptionAttributeEx, PropertyIdAttribute), and supporting utilities (SampleRateConverter). The module enables centralized storage and retrieval of user preferences (e.g., last used sample rate, export options, hardware assignments) with fallback to defaults defined in code or the database, while supporting localized display names and descriptions for UI rendering.

2. Public Interface

OptimizationSettings class (Users.UserSettings namespace)

• OptimizationSettings()
  Default constructor; initializes an empty Settings list.

• OptimizationSettings(string xmlOptimizationSettings)
  Constructor that deserializes XML-formatted optimization settings into the Settings list using XmlToObject<OptimizationSettings>.FromXml.

• Settings property (List<Setting>)
  Collection of hardware-specific optimization settings.

  • Setting nested class

    • HardwareType (HardwareTypes): Specifies the hardware type (e.g., SLICE, TDAS).
    • TransferSpeedSampleRateSettings (List<TransferSpeedSampleRate>): List of sample rate configurations for transfer speed ranges.

  • TransferSpeedSampleRate nested class

    • MaxTransferSpeed (float): Upper bound of transfer speed (bytes/sec? units unspecified).
    • MinTransferSpeed (float): Lower bound of transfer speed.
    • SampleRate (double): Sample rate (Hz) to use within the speed range.

CategoryAttributeEx class (DTS.Slice.Users.UserSettings namespace)

• CategoryAttributeEx(PropertyEnums.PropertyCategories category)
  Constructor that initializes the attribute with a category enum value and stores it internally.

• GetCategory() method
  Returns the stored PropertyCategories enum value.

• GetLocalizedString(string value) override
  Looks up value in StringResources.ResourceManager; returns "##ResourceNotFound##" + value if not found.

DisplayAttributeEx class (DTS.Slice.Users.UserSettings namespace)

• DisplayAttributeEx(PropertyEnums.PropertyIds propertyId)
  Constructor for enum-based property ID lookup.

• DisplayAttributeEx(string propertyId)
  Constructor for string-based property ID lookup.

• DisplayName override
  Constructs resource key as "{propertyId}_DisplayName" (using enum or string), looks up in StringResources.ResourceManager; returns "##DisplayNameNotFound##" + propertyId if not found.

DescriptionAttributeEx class (DTS.Slice.Users.UserSettings namespace)

• DescriptionAttributeEx(PropertyEnums.PropertyIds propertyId)
  Constructor for enum-based property ID lookup.

• DescriptionAttributeEx(string propertyId)
  Constructor for string-based property ID lookup.

• Description override
  Constructs resource key as "{propertyId}_Description" (using enum or string), looks up in StringResources.ResourceManager; returns "##DescriptionNotFound##" + propertyId if not found.

PropertyIdAttribute class (DTS.Slice.Users.UserSettings namespace)

• PropertyIdAttribute(PropertyEnums.PropertyIds propertyId)
  Constructor that stores the property ID enum.

• GetPropertyId(PropertyInfo o) static method
  Retrieves the integer property ID from a PropertyInfo's PropertyIdAttribute. Throws NullReferenceException if property or attribute is missing.

• GetPropertyIdEnum(PropertyInfo o) static method
  Retrieves the PropertyIds enum value from a PropertyInfo's PropertyIdAttribute. Throws NullReferenceException if property or attribute is missing.

SampleRateConverter class (DTS.Slice.Users.UserSettings namespace)

• SampleRateConverter()
  Default constructor.

• GetStandardValuesSupported(ITypeDescriptorContext context) override
  Returns true, indicating a standard list of values is available.

• GetStandardValues(ITypeDescriptorContext context) override
  Returns a sorted list of valid sample rates (as double[]) by:

  1. Reading SPSINDEX_COUNT (default 56) from SettingsDB.
  2. Iterating i = 0 to SPSINDEX_COUNT-1, fetching SPSINDEX_{i} from SettingsDB (defaulting to AvailableSampleRatesDefault[i] if i < 27).
  3. Filtering out duplicates and non-positive values. Returns values as StandardValuesCollection.

• AvailableSampleRatesDefault static field (int[])
  Hardcoded default sample rates (Hz): [5, 50, 100, ..., 1000000] (27 values).

UserHistory class (DTS.Slice.Users.UserSettings namespace)

• Static CreateAnyMissingUserHistory() method
  Ensures all properties defined in UserHistory exist in the DefaultProperties database table and creates user-specific entries. Uses reflection to inspect properties, checks DefaultProperties table for existing entries, and inserts missing defaults via DbOperations.

• Instance Properties (all annotated with [CategoryAttributeEx], [PropertyId], [DescriptionAttributeEx], [DisplayAttributeEx], [DefaultValue], [ReadOnly(true)]):

  • UsersCurrentTestSetup (string, default "", ID 401)
  • LastRunTestSetup (string, default "", ID 402)
  • LastUsedSampleRate (double, default 20000.0, ID 403)
  • ApplySensorDataToBlankChannels (bool, default true, ID 404)
  • ApplyHardwareAssignmentInHardwareDisco (bool, default true, ID 434, [Browsable(false)])
  • ShowOptionsWhenApplyingSensorToBlankChannel (bool, default true, ID 405)

PropertyEnums class (DTS.Slice.Users.UserSettings namespace)

• PropertyCategories enum
  Categories for grouping settings in UI (e.g., UserHistory, ExportOptions, RealtimeOptions). Used by CategoryAttributeEx.

• PropertyOrders enum
  Ordered list of property names (used for ordering within categories in UI). Not directly used in the provided source files.

• PropertyIds enum
  Integer-based IDs for properties (e.g., UsersCurrentTestSetup = 401, DefaultSampleRate = 103). Used by PropertyIdAttribute, DisplayAttributeEx, and DescriptionAttributeEx.

3. Invariants

• Database storage format: All settings are stored in invariant (culture-agnostic) form in the database (e.g., numeric sample rates, English string keys).
• Fallback chain: When retrieving a setting, the system falls back in this order: user-specific value → default value in DB → default value in code (via [DefaultValue] or TestSetupDefaults.GetDefaultValueAsString).
• Resource key format: Display names and descriptions use keys of the form "{PropertyId}_DisplayName" and "{PropertyId}_Description" (where PropertyId is the enum or string value).
• Property ID uniqueness: Each PropertyIds enum value maps to a unique integer ID used as the primary key in DefaultProperties table.
• Sample rate list construction: SampleRateConverter.GetStandardValues() always returns a sorted list of unique, positive sample rates derived from SettingsDB and AvailableSampleRatesDefault.
• Attribute consistency: Properties in UserHistory must have exactly one PropertyIdAttribute, and its value must match the enum value used in PropertyIdAttribute/DisplayAttributeEx/DescriptionAttributeEx.

4. Dependencies

Module depends on:

• DTS.Common.Enums.Hardware.HardwareTypes (for OptimizationSettings.Setting.HardwareType)
• DTS.Common.Utilities.Xml.XmlToObject<T> (for XML deserialization in OptimizationSettings)
• DTS.Common.Settings.SettingsDB (for SampleRateConverter to read global settings like SPSINDEX_COUNT)
• DTS.Common.Storage.DbOperations (for database operations in UserHistory.CreateAnyMissingUserHistory)
• System.ComponentModel (for CategoryAttribute, DisplayNameAttribute, DescriptionAttribute, TypeConverter)
• System.Resources.ResourceManager (via StringResources.ResourceManager for localization)
• TestSetupDefaults.GetDefaultValueAsString (for default value retrieval in CreateAnyMissingUserHistory)
• TestSetupDefaults.CreateMissingUserSettingProperties (for user-specific setting creation)

Module is depended on by:

• UI components (e.g., property grids) that use UserHistory properties and attributes for display.
• Settings persistence layer (e.g., DbOperations, SettingsDB) for reading/writing settings.
• Code that consumes OptimizationSettings (e.g., hardware-specific optimization logic).
• Localization infrastructure (via StringResources).

5. Gotchas

• Resource key mismatch: If a property ID is passed as a string to DisplayAttributeEx/DescriptionAttributeEx, the resource key is "{string}_DisplayName" (e.g., "MyProp_DisplayName"), not the enum name. Ensure string-based keys match this pattern.
• Missing enum entries: PropertyOrders enum is defined but not used in the provided source files; its purpose is unclear without additional context.
• Hardcoded defaults: SampleRateConverter uses a hardcoded AvailableSampleRatesDefault array (27 values) as fallback, but SPSINDEX_COUNT defaults to 56. This may cause out-of-bounds access if SPSINDEX_COUNT > 27 and missing DB entries exist.
• Case sensitivity: Resource lookups are case-sensitive (via ResourceManager.GetString), but enum-to-string conversion uses ToString() (case-sensitive per C# conventions).
• No validation in OptimizationSettings: The Setting and TransferSpeedSampleRate classes have no validation (e.g., MinTransferSpeed ≤ MaxTransferSpeed, SampleRate > 0). Invalid data may be deserialized silently.
• ApplyHardwareAssignmentInHardwareDisco is [Browsable(false)]: Though public, this property will not appear in standard property grids.
• SampleRateConverter mutates state: GetStandardValues clears and repopulates _validSampleRateList on each call. Not thread-safe if used concurrently.
• PropertyIdAttribute.GetPropertyId throws on null/missing: No graceful handling; callers must ensure attributes exist before calling.