beyhan/ClassicAssist.Avalonia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0aa63a7e5e6e04f0a01a8a644755ec1c9f5866e9
ClassicAssist.Avalonia/.qoder/repowiki/en/content/Development Tools/Debug Console.md
T
Beyhan Oğur d5f52cc3d3 first commit
2026-09-03 04:45:36 +03:00

438 lines
18 KiB
Markdown
Raw Blame History

# Debug Console
<cite>
**Referenced Files in This Document**
- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
- [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
</cite>
## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
10. [Appendices](#appendices)
## Introduction
This document explains the Debug Console in ClassicAssist.Avalonia, focusing on how it receives, displays, and manages diagnostic information from various subsystems. It covers:
- Console output system and log viewing capabilities
- Diagnostic information display for packets, chat, and macros
- Configuring logging levels, filtering messages, and exporting debug data
- Real-time streaming and search functionality
- Message formatting options and interpreting outputs
- Performance implications across logging levels
- Best practices for development vs production
- Extending the console with custom sources and formats
## Project Structure
The Debug Console is implemented as an Avalonia view with a corresponding ViewModel that binds to shared services and network filters. The key files are:
- View layer (Avalonia): DebugWindow.axaml and DebugWindow.axaml.cs
- View model: DebugViewModel.cs
- Shared services and filters: ChatManager, Packet Filters, Packet Handlers
- Application bootstrap: App.axaml.cs and Engine.cs
```mermaid
graph TB
subgraph "UI Layer"
DW["DebugWindow.axaml"]
DWC["DebugWindow.axaml.cs"]
DVM["DebugViewModel.cs"]
end
subgraph "Shared Services"
CM["ChatManager.cs"]
SMTW["SystemMessageTextWriter.cs"]
end
subgraph "Networking"
IPF["IncomingPacketFilters.cs"]
OPF["OutgoingPacketFilters.cs"]
PF["PacketFilter.cs"]
PFI["PacketFilterInfo.cs"]
IPH["IncomingPacketHandlers.cs"]
OPH["OutgoingPacketHandlers.cs"]
end
subgraph "Bootstrap"
APP["App.axaml.cs"]
ENG["Engine.cs"]
end
DW --> DWC
DWC --> DVM
DVM --> CM
DVM --> IPF
DVM --> OPF
DVM --> PF
DVM --> PFI
DVM --> IPH
DVM --> OPH
APP --> ENG
ENG --> DVM
```
**Diagram sources**
- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
- [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs)
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
**Section sources**
- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
## Core Components
- Debug Window (View): Provides UI elements for displaying logs, searching, filtering, and exporting.
- Debug View Model: Binds UI to shared services and network filters; exposes commands for filtering, clearing, and exporting.
- Chat Manager: Centralizes chat message handling and can be integrated into the console for unified diagnostics.
- System Message Text Writer: Bridges macro/system messages into the console pipeline.
- Packet Filters and Handlers: Provide real-time packet inspection and routing, enabling detailed network diagnostics.
Key responsibilities:
- Receive and aggregate logs from multiple sources
- Render logs in real time with optional auto-scrolling
- Support filtering by level, source, or keyword
- Allow export of filtered logs to external files
- Maintain performance by throttling high-volume streams
**Section sources**
- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
## Architecture Overview
The Debug Console integrates with shared services and networking layers to provide centralized diagnostics. The flow typically involves:
- Subsystems emitting logs/messages via shared services
- Debug View Model subscribing to events and updating bound collections
- UI rendering entries in real time with filtering and search
- Export functionality writing selected entries to disk
```mermaid
sequenceDiagram
participant Subsystem as "Subsystem"
participant Service as "Shared Service"
participant VM as "DebugViewModel"
participant UI as "DebugWindow"
participant Exporter as "Exporter"
Subsystem->>Service : Emit log/message
Service-->>VM : Event/Notification
VM->>VM : Apply filter/format
VM-->>UI : Update collection
UI->>UI : Render entry (real-time)
UI->>Exporter : Export filtered logs
Exporter-->>UI : Save file path/status
```
**Diagram sources**
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
## Detailed Component Analysis
### Debug Window (View)
- Purpose: Hosts the console UI, including log list, search box, filter controls, and export actions.
- Behavior: Binds to properties exposed by DebugViewModel; supports keyboard shortcuts and context menu operations.
- Integration: Uses Avalonia data binding to reflect changes from the ViewModel efficiently.
```mermaid
classDiagram
class DebugWindow {
+InitializeComponent()
+OnLoaded()
+BindDataContext()
+ExportLogs()
+ClearConsole()
+SearchText
+SelectedLogLevel
+AutoScrollEnabled
}
```
**Diagram sources**
- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
**Section sources**
- [DebugWindow.axaml](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
### Debug View Model
- Purpose: Aggregates logs, applies filters, formats messages, and exposes commands for UI interaction.
- Responsibilities:
- Subscribe to shared services (e.g., ChatManager) and packet filters
- Maintain a bounded collection of log entries to prevent memory growth
- Implement filtering by level, source, and text search
- Provide export functionality to write logs to files
- Manage auto-scroll behavior and thread-safe updates
```mermaid
classDiagram
class DebugViewModel {
+ObservableCollection~LogEntry~ Logs
+string SearchText
+LogLevel SelectedLogLevel
+bool AutoScroll
+void AddLog(source, level, message)
+void ClearLogs()
+IEnumerable~LogEntry~ GetFilteredLogs()
+void ExportLogs(path)
+void ToggleAutoScroll()
}
class LogEntry {
+DateTime Timestamp
+string Source
+LogLevel Level
+string Message
}
DebugViewModel --> LogEntry : "creates/manages"
```
**Diagram sources**
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
**Section sources**
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
### Chat Integration
- Purpose: Route chat messages into the console for unified diagnostics.
- Mechanism: Subscribe to ChatManager events and append formatted entries to the log collection.
```mermaid
sequenceDiagram
participant Client as "Game Client"
participant CM as "ChatManager"
participant VM as "DebugViewModel"
participant UI as "DebugWindow"
Client->>CM : Chat event
CM-->>VM : OnChatMessage(args)
VM->>VM : Format message
VM-->>UI : Append to Logs
UI->>UI : Render new entry
```
**Diagram sources**
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
**Section sources**
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
### Macro System Messages
- Purpose: Capture macro/system messages and route them to the console.
- Mechanism: Use SystemMessageTextWriter to bridge macro outputs into the logging pipeline.
```mermaid
flowchart TD
Start(["Macro Execution"]) --> Write["SystemMessageTextWriter.Write(message)"]
Write --> Filter{"Filter by Level/Source?"}
Filter --> |Yes| Append["Append to DebugViewModel.Logs"]
Filter --> |No| Drop["Discard Entry"]
Append --> Render["UI Renders Entry"]
Drop --> End(["End"])
Render --> End
```
**Diagram sources**
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
**Section sources**
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
### Packet Diagnostics
- Purpose: Inspect incoming and outgoing packets for network troubleshooting.
- Mechanism: Use IncomingPacketFilters and OutgoingPacketFilters to capture and format packet data; integrate with DebugViewModel for display.
```mermaid
sequenceDiagram
participant Net as "Network Stack"
participant IPF as "IncomingPacketFilters"
participant OPF as "OutgoingPacketFilters"
participant VM as "DebugViewModel"
participant UI as "DebugWindow"
Net->>IPF : Incoming packet
IPF-->>VM : OnIncoming(packet)
VM->>VM : Format packet info
VM-->>UI : Append to Logs
Net->>OPF : Outgoing packet
OPF-->>VM : OnOutgoing(packet)
VM->>VM : Format packet info
VM-->>UI : Append to Logs
```
**Diagram sources**
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
- [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
**Section sources**
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
- [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
### Bootstrap and Initialization
- Purpose: Initialize the application and ensure the Debug Console is wired to shared services.
- Mechanism: App.axaml.cs and Engine.cs set up DI, register services, and start the main window.
```mermaid
flowchart TD
Boot["App Startup"] --> Register["Register Services"]
Register --> InitVM["Initialize DebugViewModel"]
InitVM --> BindUI["Bind DebugWindow DataContext"]
BindUI --> Ready["Console Ready"]
```
**Diagram sources**
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
**Section sources**
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
## Dependency Analysis
The Debug Console depends on shared services and network filters to aggregate and display diagnostics. Key dependencies include:
- ChatManager for chat integration
- Packet filters for network diagnostics
- SystemMessageTextWriter for macro outputs
- UI components for rendering and user interaction
```mermaid
graph TB
DVM["DebugViewModel.cs"] --> CM["ChatManager.cs"]
DVM --> IPF["IncomingPacketFilters.cs"]
DVM --> OPF["OutgoingPacketFilters.cs"]
DVM --> PF["PacketFilter.cs"]
DVM --> PFI["PacketFilterInfo.cs"]
DVM --> SMTW["SystemMessageTextWriter.cs"]
DW["DebugWindow.axaml.cs"] --> DVM
```
**Diagram sources**
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
- [PacketFilterInfo.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilterInfo.cs)
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
**Section sources**
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [DebugWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/Debug/DebugWindow.axaml.cs)
## Performance Considerations
- Logging Levels:
- High verbosity (Trace/Debug) can significantly impact performance due to increased I/O and UI updates.
- Recommended levels:
- Development: Debug or Trace for comprehensive diagnostics
- Production: Warning or Error to minimize overhead
- Filtering:
- Enable server-side filtering where possible to reduce payload size before reaching the console.
- Use keyword and level filters to limit displayed entries.
- Throttling:
- Implement rate limiting for high-frequency logs (e.g., packet dumps).
- Batch UI updates to avoid excessive re-renders.
- Memory Management:
- Use bounded collections to cap log history size.
- Periodically purge old entries to prevent memory growth.
- Export Strategy:
- Stream exports instead of loading entire logs into memory.
- Compress exported files if large volumes are expected.
[No sources needed since this section provides general guidance]
## Troubleshooting Guide
Common issues and resolutions:
- Console not receiving logs:
- Verify service registration during app startup.
- Ensure subscriptions to ChatManager and packet filters are active.
- Slow UI when many logs:
- Reduce logging level or enable filtering.
- Disable auto-scroll if not needed.
- Missing packet diagnostics:
- Confirm packet filters are enabled and correctly configured.
- Check handler registrations for incoming/outgoing packets.
- Export failures:
- Validate file path permissions and available disk space.
- Ensure asynchronous export to avoid blocking UI.
**Section sources**
- [DebugViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/DebugViewModel.cs)
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
## Conclusion
The Debug Console in ClassicAssist.Avalonia provides a centralized, extensible platform for diagnosing game interactions, network traffic, and macro execution. By leveraging shared services and packet filters, it offers real-time insights with configurable filtering and export capabilities. Proper configuration of logging levels and performance optimizations ensures effective debugging in development while maintaining stability in production.
[No sources needed since this section summarizes without analyzing specific files]
## Appendices
### Configuration Options
- Logging Levels:
- Trace: Most verbose, includes detailed internal states
- Debug: Useful for feature-level diagnostics
- Info: General operational messages
- Warning: Potential issues requiring attention
- Error: Critical failures
- Filters:
- Level-based filtering
- Source-based filtering (e.g., chat, packets, macros)
- Keyword search across message content
- Export Formats:
- Plain text with timestamps and levels
- JSON for structured analysis
- CSV for spreadsheet processing
[No sources needed since this section provides general guidance]
### Extending the Console
- Custom Log Sources:
- Implement a publisher that emits log events to DebugViewModel.
- Register the publisher during application initialization.
- Custom Output Formats:
- Extend the exporter to support additional formats.
- Integrate with external tools via API endpoints or file watchers.
[No sources needed since this section provides general guidance]
Reference in New Issue View Git Blame Copy Permalink