DP44/enriched-qwen3-coder-next/DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Users.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Users/IUIItems.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Users/ITagAware.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Users/Tags.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Users/User.cs	2026-04-16T04:58:34.034818+00:00	Qwen/Qwen3-Coder-Next-FP8	1	d08339a454aa8af1

Users

Documentation: DatabaseExport.Users Module (Version 57)

---

1. Purpose

This module provides data models and utilities for representing and persisting user account information in a legacy database export context (specifically for database version 57). It defines core abstractions for users (User), tag-aware entities (TagAwareBase), UI item identification (IUIItems), and centralized tag management (Tags). Its primary role is to enable serialization of user data—including permissions, visibility settings, and tags—into XML-compatible formats, while leveraging an in-memory cache of tags for efficient lookup. It supports default system users (e.g., Admin, Guest) and enforces immutability constraints on default users’ roles.

---

2. Public Interface

Interface: IUIItems

• string GetName()
  Returns a unique string identifier for a UI item (e.g., tab or module name). Used as the key in permission/visibility dictionaries.

Abstract Class: TagAwareBase

• byte[] TagsBlobBytes { get; set; }
  Serializes/deserializes the TagIDs array to/from a byte array using Buffer.BlockCopy. Setter includes a try/catch that silently discards exceptions (no logging in source).
• int[] TagIDs { get; set; }
  Stores the list of tag IDs associated with the entity. Setter replaces with empty array if null.
• string GetTagsCommaSeperatedString()
  Returns a comma-separated string of tag text values (e.g., "Role:Admin,Version:1"), derived from TagIDs via GetTagsArray().
• virtual string[] GetTagsArray()
  Converts TagIDs to human-readable tag strings using Tags.GetTagTextFromIDs(). Overridable.

Class: Tags

• class Tag
  Represents a single tag with ID, Text, and IsObsolete fields. Includes:
  • const int INVALID_ID = -1
  • Constructor from DataRow (populates fields from DB columns; exceptions silently ignored).
  • Clone() implementation (returns a new Tag instance with copied values).
• static Tags TagsInstance { get; }
  Singleton accessor (lazy-initialized on first access).
• static string GetTagTextFromID(int tagID)
  Returns the tag text for a given ID from the in-memory cache. Returns null if tagID < 0, INVALID_ID, or not found.
• static string[] GetTagTextFromIDs(int[] tagID)
  Converts an array of tag IDs to an array of tag texts, skipping INVALID_ID and null/whitespace results.
• private void UpdateList()
  Populates/refreshes the _tagsLookup dictionary by querying the database (SELECT * FROM [Tags table]). Uses lock(MyLock) for thread safety.

Class: User

• Nested Enums
  • DefaultRoles: Administrator, PowerUser, User, Guest
  • UserPermissionLevels: Deny, Read, ReadAndExecute, Edit, Admin
  • Tags: Enumerates tag names used for user metadata (e.g., Role, UserName, Password)
  • XmlFields: Enumerates XML element names for serialization (e.g., ID, UserName, IUIItemPermissions)
• Constants
  • DEFAULT_LAST_MODIFIED_BY = "---"
  • DEFAULT_ADMIN_USERNAME = "Admin", DEFAULT_GUEST_USERNAME = "Guest", etc.
  • INVALID_ID = -1
• Properties
  • bool IsADefaultUser → true if UserName matches GetDefaultUserName(Role).
  • string Name, string UserName, int Id, DefaultRoles Role, int Version, DateTime LastModified, string LastModifiedBy, bool LocalOnly
  • private readonly Dictionary<IUIItems, UserPermissionLevels> _tabPermissions
  • private readonly Dictionary<IUIItems, bool> _showTabs
• Methods
  • public override ConstraintHelper[] GetConstraints()
    Returns a constraint for UserName (used for uniqueness validation).
  • public override string LookupTable => DbOperations.Users.USERS_TABLE
    Specifies the database table name.
  • public User(DataRow row)
    Constructor that initializes all properties from a database DataRow.
  • public string GetPermissionSerialized()
    Serializes _tabPermissions as "UIItemName=PermissionLevelInt,..." (thread-safe via lock(TabPermissionsLock)).
  • public static string GetDefaultUserName(DefaultRoles role)
    Maps DefaultRoles to default usernames (e.g., Administrator → "Admin").
  • public string GetVisibilitySerialized()
    Serializes _showTabs as "UIItemName=1/0,...".
  • public Dictionary<string, string> GetValues()
    Returns a dictionary of XML field names to values for serialization, including:
    • Basic fields (ID, UserName, DisplayName, Password, Role, etc.)
    • Serialized permissions (IUIItemPermissions)
    • Serialized visibility (IUIItemVisibility)
    • Tag string (UserTags via GetTagsCommaSeperatedString())

---

3. Invariants

• TagIDs must be non-null: The TagIDs setter replaces null with new int[0].
• INVALID_ID = -1 is excluded from tag lookups: GetTagTextFromID and GetTagTextFromIDs explicitly skip INVALID_ID.
• Default users are immutable by role: Setting Role on a User where IsADefaultUser == true throws NotSupportedException if the role changes.
• Tag text lookup is case-sensitive and text-based: _tagsLookup uses Tag.Text as the dictionary key (in UpdateList()), but GetTagTextFromId searches by Tag.ID (linear scan).
• TagsInstance is a singleton: Initialized once on first access; _tagsLookup is populated only at construction and via UpdateList() (not auto-refreshed).
• TagsBlobBytes size must be divisible by sizeof(int): The setter assumes value.Length % sizeof(int) == 0; otherwise, Buffer.BlockCopy may throw (caught silently).

---

4. Dependencies

• Imports/Usings:
  • System, System.Text, System.Collections.Generic, System.Linq, System.Data
• External Types Referenced (from source):
  • DbOperations.Tags (static class with TagFields enum and Table property)
  • DbOperations.Users (static class with UserFields enum and USERS_TABLE property)
  • DbOperations.Connection (provides QueryDataSet)
  • DbOperations.GetCommand() (returns IDbCommand)
  • DbTimeStampBase (base class of TagAwareBase; not shown, assumed to provide timestamp fields)
  • ConstraintHelper (used in GetConstraints())
• Depended Upon By:
  • User is used by export/serialization logic (e.g., GetValues() implies integration with XML export).
  • Tags.TagsInstance is used by TagAwareBase.GetTagsArray() and User.GetValues().
  • IUIItems is used as a key in User’s permission/visibility dictionaries (implementations not in this source).

---

5. Gotchas

• Silent exception handling: Multiple catch (Exception) blocks (in TagAwareBase.TagsBlobBytes, Tag constructor, Tags.UpdateList) log nothing—only commented-out logging stubs exist. Errors may go unnoticed.
• Inefficient tag lookup: GetTagTextFromId performs a linear scan over _tagsLookup to find by ID, despite _tagsLookup being keyed by Text. This is O(n) per lookup.
• TagsBlobBytes setter is fragile: Assumes input byte array length is divisible by sizeof(int); otherwise, Buffer.BlockCopy throws (caught silently).
• TagsInstance not thread-safe during initialization: _tagsInstance is assigned without double-checked locking (only null == _tagsInstance check), risking multiple instantiations in multi-threaded scenarios.
• IsADefaultUser is role-dependent but role change is restricted: A user’s default status is computed at runtime, but changing the role of a default user is blocked—this may cause confusion if default usernames are reassigned.
• GetTagsCommaSeperatedString() has typo: Method name uses "Seperated" (missing 'a'), consistent with legacy naming.
• TagsBlobBytes and TagIDs are redundant: TagsBlobBytes is a byte-level serialization of TagIDs, but only TagIDs is used in GetTagsArray(). TagsBlobBytes may be legacy or for external compatibility.
• No validation of UserName uniqueness: While GetConstraints() defines a uniqueness constraint, enforcement is external (e.g., in DB or caller), and the User class does not validate this itself.

None identified beyond these.