Overview
Avalonia provides powerful debugging capabilities including built-in DevTools, IDE integration, and platform-specific debugging options. This guide covers the essential debugging techniques for Avalonia applications.Avalonia DevTools
Avalonia includes built-in developer tools similar to browser DevTools, providing visual tree inspection, property viewing, and performance monitoring.Enabling DevTools
Add DevTools to your application inProgram.cs:
Opening DevTools
Once enabled, press F12 while your application is running to open the DevTools window.DevTools Features
Visual Tree Inspector
Visual Tree Inspector
Browse the live visual tree of your application, similar to browser element inspection. Click on elements to see their properties, styles, and data context.
- Navigate parent-child relationships
- View applied styles and templates
- Inspect attached properties
- Monitor property changes in real-time
Property Editor
Property Editor
View and modify property values at runtime:
- Edit any property on selected elements
- See inherited and local values
- Test different property values without recompiling
- Track property value sources (styles, bindings, local values)
Events Monitor
Events Monitor
Track routed events as they bubble and tunnel through the visual tree:
- View event routing paths
- Inspect event arguments
- Monitor event timing
- Debug event handling issues
Performance Metrics
Performance Metrics
Monitor rendering performance and identify bottlenecks:
- Frame rate monitoring
- Layout passes
- Render time
- Memory usage
IDE Debugging
Visual Studio
Setup
- Install the Avalonia for Visual Studio extension
- Open your Avalonia solution
- Set breakpoints in your code
- Press F5 to start debugging
XAML Designer
The Visual Studio extension provides a XAML previewer:- Real-time preview of AXAML files
- Design-time data context
- IntelliSense support
- Error highlighting
Troubleshooting Visual Studio
Error: MSB4062 GenerateAvaloniaResourcesTask
Error: MSB4062 GenerateAvaloniaResourcesTask
Manually build the
Avalonia.Build.Tasks project at least once, or build the solution with Nuke:JetBrains Rider
JetBrains Rider provides excellent built-in support for Avalonia.Features
- Code completion for AXAML
- Inspections and refactorings
- XAML previewer (via AvaloniaRider plugin)
- Full debugging support
Install XAML Previewer
- Go to Settings → Plugins → Marketplace
- Add plugin repository:
https://plugins.jetbrains.com/plugins/dev/14839 - Search for and install AvaloniaRider
- Restart Rider
Debugging
- Set breakpoints by clicking in the gutter
- Press F5 or click the Debug button
- Use the debugger toolbar to step through code
VS Code
Use VS Code with the C# extension for debugging:- Install C# extension
- Install Avalonia for VS Code
- Open your project folder
- Press F5 to start debugging
Logging and Diagnostics
Enable Trace Logging
Avalonia usesSystem.Diagnostics.Trace for logging. Enable it in your application:
Configure Log Verbosity
Control logging levels through environment variables or configuration:Custom Logging
Implement custom logging for diagnostic purposes:Debugging Specific Scenarios
Data Binding Issues
Enable binding trace output:Layout and Rendering
Enable layout and rendering diagnostics:Memory Leaks
Detect memory leaks using diagnostic overlays:Debugger Attachment
Wait for Debugger
Pause application startup to attach a debugger:Conditional Breakpoints
Use conditional breakpoints for targeted debugging:Designer Support and Previewing
Design-Time Properties
Set design-time data for XAML previewing:Remote Designer
Avalonia’s designer support uses a remote previewer architecture:- PreviewerWindowImpl: Provides the window implementation for the previewer
- RemoteDesignerEntryPoint: Entry point for remote designer instances
- FileWatcherTransport: Monitors file changes for live preview updates
Platform-Specific Debugging
Windows
DXGI Debugging
Enable Direct3D debugging for graphics issues:Linux
X11 Debugging
Enable X11-specific debugging:Framebuffer Debugging
For embedded Linux systems:DRM Debugging
Direct Rendering Manager debugging:macOS
Metal API Debugging
Enable Metal framework debugging through Xcode.WebAssembly
Browser Debugging
Enable debugging in browser:Headless Testing
Run automated UI tests without a display:VNC Preview
View headless applications through VNC:localhost:5901 with a VNC client.
Performance Profiling
Rendering Overlays
Enable visual debugging overlays:Composition Debugging
Debug the composition pipeline:Vulkan Debugging
Enable Vulkan validation layers:Common Issues and Solutions
Issue: XAML not hot-reloading
Issue: XAML not hot-reloading
Ensure you have:
- Latest Avalonia extension installed
- XAML file saved
- Designer infrastructure initialized
Issue: Binding not working
Issue: Binding not working
Check:
- Property implements
INotifyPropertyChanged - Property name matches exactly (case-sensitive)
- DataContext is set correctly
- Enable binding trace logs:
Issue: Application freezes
Issue: Application freezes
Likely causes:
- Long-running operation on UI thread
- Deadlock in async code
- Infinite layout loop
Issue: High memory usage
Issue: High memory usage
Use profiling tools:
- Visual Studio Diagnostic Tools
- dotMemory (JetBrains)
- PerfView (Windows)
- Event handler leaks
- Unclosed streams
- Large image caching
Testing and Integration
For comprehensive testing approaches, see:- Unit Tests: Located in
tests/directory, categorized by assembly - Integration Tests: Located in
tests/Avalonia.IntegrationTests.Appium/using Appium - Render Tests: Located in
tests/Avalonia.RenderTests/for visual testing
Additional Resources
DevTools Documentation
Complete DevTools guide and features
Testing Guide
Unit testing and integration testing
Best Practices
Development best practices
Contributing
Contributing guidelines including testing
Next Steps
Now that you understand debugging:- Enable DevTools in your applications
- Configure appropriate logging levels
- Set up your IDE for optimal debugging
- Learn platform-specific debugging techniques
- Implement comprehensive testing strategies