Beyhan Oğur
22 KiB
22 KiB
Configuration Management
**Referenced Files in This Document** - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs) - [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs) - [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs) - [ShortcutKeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/ShortcutKeys.cs) - [Crypter.cs](file://ClassicAssist.Shared/Data/Crypter.cs) - [NewProfileWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml.cs) - [NewProfileViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/NewProfileViewModel.cs) - [HotkeysTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/HotkeysTabControl.axaml.cs) - [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs) - [GeneralControl.axaml.cs](file://ClassicAssist.Avalonia/Views/GeneralControl.axaml.cs) - [GeneralControlViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/GeneralControlViewModel.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document explains the configuration management system used by ClassicAssist.Avalonia. It covers profile creation and switching, settings migration, backup and restore, hotkey management (including conflict resolution and global hotkeys), theme and appearance customization, persistence mechanisms and file formats, programmatic access to options, dynamic option changes, migration strategies for version compatibility, and security considerations for sensitive data.
Project Structure
Configuration-related code is primarily located in:
- Shared data models and managers under ClassicAssist.Shared/Data
- UI views and view models under ClassicAssist.Avalonia/Views and ClassicAssist.Shared/UI/ViewModels
- Application bootstrap and engine initialization under ClassicAssist.Avalonia
graph TB
subgraph "Shared"
O["Options.cs"]
AO["AssistantOptions.cs"]
HKM["HotkeyManager.cs"]
HKE["HotkeyEntry.cs"]
SK["ShortcutKeys.cs"]
CRY["Crypter.cs"]
end
subgraph "Avalonia UI"
NPF["NewProfileWindow.axaml.cs"]
HPVM["HotkeysTabViewModel.cs"]
HTCA["HotkeysTabControl.axaml.cs"]
GCVM["GeneralControlViewModel.cs"]
GCA["GeneralControl.axaml.cs"]
APP["App.axaml.cs"]
ENG["Engine.cs"]
end
APP --> ENG
ENG --> O
ENG --> AO
ENG --> HKM
NPF --> AO
HPVM --> HKM
HPVM --> O
HTCA --> HPVM
GCVM --> O
GCVM --> AO
HKM --> HKE
HKM --> SK
AO --> CRY
Diagram sources
- Options.cs
- AssistantOptions.cs
- HotkeyManager.cs
- HotkeyEntry.cs
- ShortcutKeys.cs
- Crypter.cs
- NewProfileWindow.axaml.cs
- HotkeysTabViewModel.cs
- HotkeysTabControl.axaml.cs
- GeneralControlViewModel.cs
- GeneralControl.axaml.cs
- App.axaml.cs
- Engine.cs
Section sources
- Options.cs
- AssistantOptions.cs
- HotkeyManager.cs
- HotkeyEntry.cs
- ShortcutKeys.cs
- Crypter.cs
- NewProfileWindow.axaml.cs
- HotkeysTabViewModel.cs
- HotkeysTabControl.axaml.cs
- GeneralControlViewModel.cs
- GeneralControl.axaml.cs
- App.axaml.cs
- Engine.cs
Core Components
- Options and AssistantOptions: Define the application’s configuration schema and provide serialization/deserialization helpers. They are central to profile storage and migration.
- HotkeyManager and HotkeyEntry: Manage hotkey registration, conflict detection, and dispatching. ShortcutKeys provides helper utilities for key representation.
- Crypter: Provides encryption utilities for sensitive configuration values.
- Profile UI: NewProfileWindow and its ViewModel orchestrate profile creation and initial defaults.
- Hotkeys UI: HotkeysTabControl and HotkeysTabViewModel expose binding and user interaction for hotkey configuration.
- General UI: GeneralControl and GeneralControlViewModel host general options including theme and appearance settings.
- App and Engine: Initialize configuration at startup, load active profile, and apply runtime options.
Section sources
- Options.cs
- AssistantOptions.cs
- HotkeyManager.cs
- HotkeyEntry.cs
- ShortcutKeys.cs
- Crypter.cs
- NewProfileWindow.axaml.cs
- NewProfileViewModel.cs
- HotkeysTabControl.axaml.cs
- HotkeysTabViewModel.cs
- GeneralControl.axaml.cs
- GeneralControlViewModel.cs
- App.axaml.cs
- Engine.cs
Architecture Overview
The configuration architecture follows a layered approach:
- Data layer: Options and AssistantOptions define schemas and persistence helpers; Crypter secures sensitive fields.
- Service layer: HotkeyManager orchestrates hotkey lifecycle and conflict resolution.
- UI layer: ViewModels bind to Options/AssistantOptions and invoke services to update state.
- Bootstrap: App and Engine initialize configuration, load profiles, and apply them at runtime.
sequenceDiagram
participant Boot as "App.axaml.cs"
participant Eng as "Engine.cs"
participant Opt as "Options.cs"
participant AOpt as "AssistantOptions.cs"
participant HK as "HotkeyManager.cs"
participant VM as "HotkeysTabViewModel.cs"
participant UI as "HotkeysTabControl.axaml.cs"
Boot->>Eng : "Initialize()"
Eng->>Opt : "Load current profile"
Eng->>AOpt : "Load assistant options"
Eng->>HK : "Register hotkeys from options"
UI->>VM : "Bind to hotkey list"
VM->>HK : "Update bindings on change"
HK-->>VM : "Conflict warnings / events"
Diagram sources
- App.axaml.cs
- Engine.cs
- Options.cs
- AssistantOptions.cs
- HotkeyManager.cs
- HotkeysTabViewModel.cs
- HotkeysTabControl.axaml.cs
Detailed Component Analysis
Profile System
Profiles encapsulate all user settings. The system supports:
- Creation: New profiles are created via the NewProfile window and ViewModel, which set default values and persist them.
- Migration: When loading options, the system can detect older versions and migrate fields to the current schema.
- Backup and Restore: Users can export/import or copy profile directories to back up and restore configurations.
Key responsibilities:
- Default value provisioning during profile creation
- Version-aware deserialization and migration logic
- File-based persistence with optional encryption for sensitive sections
flowchart TD
Start(["Create Profile"]) --> Defaults["Apply default settings"]
Defaults --> Validate["Validate required fields"]
Validate --> Valid{"Valid?"}
Valid --> |No| Prompt["Prompt user to fix"]
Prompt --> Validate
Valid --> |Yes| Persist["Persist profile to disk"]
Persist --> Done(["Profile Ready"])
Diagram sources
Section sources
Hotkey Management
Hotkey management includes:
- Key binding configuration through the Hotkeys tab
- Conflict detection and resolution feedback
- Global hotkey support when enabled
Implementation highlights:
- HotkeyEntry represents individual bindings
- HotkeyManager registers/unregisters keys and raises change events
- ShortcutKeys provides parsing/formatting utilities
- UI binds to HotkeyEntry collections and updates manager on edits
classDiagram
class HotkeyEntry {
+string Name
+string Keys
+bool IsGlobal
+bool IsValid()
}
class HotkeyManager {
+Register(entry) void
+Unregister(entry) void
+HasConflicts(keys) bool
+OnHotkeyPressed(event)
}
class ShortcutKeys {
+Parse(text) Keys
+ToString(keys) string
}
HotkeyManager --> HotkeyEntry : "manages"
HotkeyManager --> ShortcutKeys : "uses"
Diagram sources
sequenceDiagram
participant User as "User"
participant UI as "HotkeysTabControl.axaml.cs"
participant VM as "HotkeysTabViewModel.cs"
participant HK as "HotkeyManager.cs"
User->>UI : "Edit hotkey"
UI->>VM : "Update bound entry"
VM->>HK : "Register new binding"
HK-->>VM : "Conflict detected? Warn"
VM-->>UI : "Show validation message"
Diagram sources
Section sources
Theme and Appearance Customization
Appearance settings include color schemes, fonts, and layout preferences. These are exposed via the General control and ViewModel, which bind to Options/AssistantOptions. Changes are applied at runtime where supported and persisted on save.
flowchart TD
Open["Open General Control"] --> Bind["Bind to Options/AssistantOptions"]
Bind --> Edit["Edit theme/font/layout"]
Edit --> Apply["Apply changes at runtime"]
Apply --> Save["Persist updated options"]
Save --> Close["Close dialog"]
Diagram sources
Section sources
Options Persistence and Configuration File Formats
- Persistence mechanism: Options and AssistantOptions handle serialization/deserialization to files. Paths are resolved relative to the active profile directory.
- File formats: JSON-based structures defined by the model classes. Sensitive fields may be encrypted using Crypter before writing.
- Versioning: Deserialization routines check version metadata and run migrations if needed.
sequenceDiagram
participant App as "App.axaml.cs"
participant Eng as "Engine.cs"
participant Opt as "Options.cs"
participant AOpt as "AssistantOptions.cs"
participant C as "Crypter.cs"
App->>Eng : "Start"
Eng->>Opt : "Deserialize profile"
Eng->>AOpt : "Deserialize assistant options"
Opt->>C : "Decrypt sensitive fields"
AOpt->>C : "Encrypt sensitive fields on save"
Eng-->>App : "Ready with loaded config"
Diagram sources
Section sources
Programmatic Access and Dynamic Option Changes
- Reading/writing: ViewModels and services read from and write to Options/AssistantOptions instances.
- Runtime updates: Some options are applied immediately (e.g., hotkeys, certain UI behaviors). Others require restart or reinitialization.
- Event-driven updates: HotkeyManager emits events when bindings change; UI reacts accordingly.
sequenceDiagram
participant VM as "GeneralControlViewModel.cs"
participant Opt as "Options.cs"
participant HK as "HotkeyManager.cs"
VM->>Opt : "Set property"
Opt-->>VM : "Notify change"
VM->>HK : "Re-register affected hotkeys"
HK-->>VM : "Confirm success or conflicts"
Diagram sources
Section sources
Migration Strategies and Version Compatibility
- On load, the system inspects stored version information and applies incremental migrations to bring the configuration to the current schema.
- Migrations preserve user data while updating deprecated fields or adding new ones with safe defaults.
- If migration fails, the system should log errors and fall back to defaults or prompt the user to reset.
flowchart TD
Load["Load Options"] --> CheckVer["Check stored version"]
CheckVer --> UpToDate{"Up to date?"}
UpToDate --> |Yes| Use["Use current schema"]
UpToDate --> |No| Migrate["Run migration steps"]
Migrate --> Validate["Validate migrated data"]
Validate --> Ok{"Valid?"}
Ok --> |Yes| Save["Save updated schema"]
Ok --> |No| Fallback["Fallback to defaults and warn"]
Save --> Use
Fallback --> Use
[No diagram sources since this is a conceptual flow]
Section sources
Security Considerations for Sensitive Data
- Encryption: Sensitive configuration values (e.g., passwords, tokens) are encrypted using Crypter before being written to disk.
- Decryption: Values are decrypted only when needed at runtime.
- Best practices: Avoid logging sensitive values; ensure secure temporary handling and clear memory after use.
Section sources
Dependency Analysis
The following diagram shows core dependencies among configuration components:
graph LR
Opt["Options.cs"] --> CRY["Crypter.cs"]
AOpt["AssistantOptions.cs"] --> CRY
HKM["HotkeyManager.cs"] --> HKE["HotkeyEntry.cs"]
HKM --> SK["ShortcutKeys.cs"]
VMH["HotkeysTabViewModel.cs"] --> HKM
VMG["GeneralControlViewModel.cs"] --> Opt
VMG --> AOpt
NPF["NewProfileViewModel.cs"] --> AOpt
APP["App.axaml.cs"] --> ENG["Engine.cs"]
ENG --> Opt
ENG --> AOpt
ENG --> HKM
Diagram sources
- Options.cs
- AssistantOptions.cs
- Crypter.cs
- HotkeyManager.cs
- HotkeyEntry.cs
- ShortcutKeys.cs
- HotkeysTabViewModel.cs
- GeneralControlViewModel.cs
- NewProfileViewModel.cs
- App.axaml.cs
- Engine.cs
Section sources
- Options.cs
- AssistantOptions.cs
- Crypter.cs
- HotkeyManager.cs
- HotkeyEntry.cs
- ShortcutKeys.cs
- HotkeysTabViewModel.cs
- GeneralControlViewModel.cs
- NewProfileViewModel.cs
- App.axaml.cs
- Engine.cs
Performance Considerations
- Minimize I/O: Batch writes and avoid frequent saves; persist on explicit actions or periodic intervals.
- Lazy initialization: Defer heavy option processing until needed.
- Hotkey registration: Register only changed bindings to reduce overhead.
- Avoid blocking UI: Perform file operations asynchronously where possible.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Hotkey conflicts: The UI will show warnings when two entries share the same key combination. Resolve by editing one of the conflicting entries.
- Missing or corrupted profile: If deserialization fails, the system falls back to defaults. Reset or recreate the profile if necessary.
- Sensitive data not saved: Ensure encryption is enabled for the relevant fields and that the profile path is writable.
- Appearance changes not applied: Some options require restarting the application or reloading specific subsystems.
Section sources
Conclusion
ClassicAssist.Avalonia’s configuration system centers around strongly typed Options and AssistantOptions, backed by robust persistence and optional encryption. Profiles enable isolated settings per user scenario, while HotkeyManager provides reliable global hotkey support with conflict detection. The UI layers expose intuitive controls for customization, and the bootstrap process ensures consistent initialization and migration across versions.
Appendices
- Profile directory structure: Each profile contains its own configuration files and assets. Back up entire profile folders to preserve all settings.
- Recommended workflow: Create a new profile for experiments; keep a stable baseline profile. Export/import profiles as needed.
[No sources needed since this section provides general guidance]