Atc.XamlToolkit.WinUI 1.5.81

ATC.Net WPF, WinUI, and Avalonia

This is a base libraries for building WPF, WinUI, or Avalonia application with the MVVM design pattern.

📑 Table of Contents

• Key Features
  • MVVM Foundation
  • Commands
  • Messaging System
  • Behaviors
  • Value Converters
  • Source Generators
  • Performance Optimizations
  • Utilities
• Quick Start
• Requirements
• NuGet Packages
• Documentation
• Complete Feature List
• Why Choose Atc.XamlToolkit?
• How to Contribute

🎁 Key Features

🏗️ MVVM Foundation

• ViewModelBase - Base class with INotifyPropertyChanged
• MainWindowViewModelBase - Main window lifecycle management
• ViewModelDialogBase - Dialog-specific ViewModels
• ObservableObject - Lightweight observable pattern

⚡ Commands

• RelayCommand / RelayCommand<T> - Synchronous commands with CanExecute support
• RelayCommandAsync / RelayCommandAsync<T> - Async/await commands for responsive UIs with cancellation token support
  • IDisposable support - Async command interfaces inherit from IDisposable for proper resource cleanup
  • Auto-generated DisposeCommands() - Source generator creates helper method for disposing all cancellable commands
• Automatic CanExecute refresh - Commands automatically update UI state
• Error handling support - Built-in IErrorHandler interface for graceful error management

🔔 Messaging System

Decouple your ViewModels with a powerful messaging infrastructure:

• Messenger - Central message bus for app-wide communication
• GenericMessage<T> - Send typed messages between components
• NotificationMessage - Simple notifications with optional callbacks
• PropertyChangedMessage<T> - Broadcast property changes across ViewModels

Perfect for scenarios like:

• Cross-ViewModel communication without direct references
• Event aggregation patterns
• Plugin architectures
• Loosely-coupled component communication

// Send a message
Messenger.Default.Send(new GenericMessage<User>(currentUser));

// Receive a message
Messenger.Default.Register<GenericMessage<User>>(this, msg =>
{
    var user = msg.Content;
    // Handle the user...
});

Learn more: Messaging System Documentation

🎭 Behaviors

Attach declarative behaviors to UI elements without code-behind. All behaviors work seamlessly across WPF, WinUI, and Avalonia platforms.

EventToCommandBehavior

Execute commands in response to any UI event, eliminating the need for code-behind event handlers.

• Works with any routed or standard .NET event
• Optional CommandParameter for passing custom data
• PassEventArgsToCommand to access event details
• Perfect for maintaining clean MVVM architecture

<Button Content="Save">
    <i:Interaction.Behaviors>
        <behaviors:EventToCommandBehavior 
            EventName="Click"
            Command="{Binding SaveCommand}" />
    </i:Interaction.Behaviors>
</Button>

Learn more about EventToCommandBehavior

AnimationBehavior

Provides simple, declarative animations for UI elements without writing animation code.

• 8 animation types: FadeIn, FadeOut, SlideInFromLeft/Right/Top/Bottom, ScaleIn, ScaleOut
• Trigger-based or auto-start animations
• Customizable duration
• GPU-accelerated for smooth performance

<Border Background="LightBlue" Padding="20">
    <i:Interaction.Behaviors>
        <behaviors:AnimationBehavior 
            AnimationType="FadeIn"
            Duration="1000"
            AutoStart="True" />
    </i:Interaction.Behaviors>
    <TextBlock Text="I fade in automatically!" />
</Border>

Learn more about AnimationBehavior

FocusBehavior

Manages focus for UI elements declaratively through XAML properties.

• HasInitialFocus - Set focus when element loads
• IsFocused - Two-way bindable focus state
• SelectAllOnFocus - Automatically select text in TextBox
• FocusTrigger - Trigger focus from ViewModel

<TextBox Width="300">
    <i:Interaction.Behaviors>
        <behaviors:FocusBehavior 
            IsFocused="{Binding IsFieldFocused, Mode=TwoWay}"
            SelectAllOnFocus="True" />
    </i:Interaction.Behaviors>
</TextBox>

Learn more about FocusBehavior

KeyboardNavigationBehavior

Enables custom keyboard navigation with arrow keys, Enter, Escape, and Tab through declarative command bindings.

• Arrow key navigation (Up, Down, Left, Right)
• Action keys (Enter, Escape, Tab)
• Enable/disable toggle
• Perfect for grids, lists, and custom controls

<Border Focusable="True">
    <i:Interaction.Behaviors>
        <behaviors:KeyboardNavigationBehavior
            UpCommand="{Binding NavigateUpCommand}"
            DownCommand="{Binding NavigateDownCommand}"
            LeftCommand="{Binding NavigateLeftCommand}"
            RightCommand="{Binding NavigateRightCommand}"
            EnterCommand="{Binding SelectCommand}" />
    </i:Interaction.Behaviors>
</Border>

Learn more about KeyboardNavigationBehavior

Complete Behaviors Documentation: Behaviors Overview

🎨 Value Converters

Extensive collection of ready-to-use XAML converters for WPF, WinUI, and Avalonia:

Bool Converters

• BoolToInverseBoolValueConverter
• BoolToVisibilityCollapsedValueConverter
• BoolToVisibilityVisibleValueConverter
• BoolToWidthValueConverter
• MultiBoolToBoolValueConverter (AND/OR logic)
• MultiBoolToVisibilityVisibleValueConverter

String Converters

• StringNullOrEmptyToBoolValueConverter
• StringNullOrEmptyToInverseBoolValueConverter
• StringNullOrEmptyToVisibilityVisibleValueConverter
• StringNullOrEmptyToVisibilityCollapsedValueConverter
• ToLowerValueConverter / ToUpperValueConverter

Null Converters

• NullToVisibilityCollapsedValueConverter
• NullToVisibilityVisibleValueConverter

See detailed Value Converters documentation

⚙️ Source Generators

Eliminate boilerplate with powerful code generation:

• [ObservableProperty] - Auto-generate properties with change notification
• [ComputedProperty] - Auto-detect dependencies for computed properties and generate automatic notifications
• [RelayCommand] - Auto-generate command properties from methods
  • SupportsCancellation = true generates cancel methods and DisposeCommands() helper for proper resource cleanup
• [ObservableDtoViewModel] - Auto-generate ViewModel wrappers for DTOs/POCOs with:
  • IsDirty tracking for change detection
  • InnerModel access to underlying DTO
  • Support for readonly properties
  • Method proxy generation
  • Selective generation with IgnorePropertyNames and IgnoreMethodNames
  • Automatic validation attribute copying with EnableValidationOnPropertyChanged and EnableValidationOnInit
  • Support for [ComputedProperty] with automatic dependency tracking
• [DependencyProperty] (WPF & WinUI 3) - Auto-generate dependency properties
• [StyledProperty] (Avalonia) - Auto-generate styled properties
• [AttachedProperty] (WPF, WinUI 3 & Avalonia) - Auto-generate attached properties
• [RoutedEvent] (WPF only) - Auto-generate routed events

Note: Classes using [DependencyProperty], [AttachedProperty], [StyledProperty], or [RoutedEvent] must either inherit from UserControl/DependencyObject/FrameworkElement, or have a class name ending with "Attach", "Behavior", or "Helper" (e.g., DragBehavior, CheckBoxHelper).

Learn more about each generator:

• SourceGenerators for AttachedProperties
• SourceGenerators for DependencyProperties
• SourceGenerators for RoutedEvents
• SourceGenerators for ViewModel

🚀 Performance Optimizations

• BooleanBoxes - Cached boolean boxing for reduced memory allocations
• WeakAction/WeakFunc - Memory-leak prevention for event handlers and callbacks
• PropertyDefaultValueConstants - Shared default values for common property types

🔧 Utilities

• DesignModeHelper - Detect design-time vs runtime for better designer experience
• Base Converter Classes - ValueConverterBase and MultiValueConverterBase for creating custom converters
• Error Handling - IErrorHandler interface for centralized command error management

🚀 Quick Start

Installation

Install via NuGet Package Manager or .NET CLI:

For WPF:

dotnet add package Atc.XamlToolkit.Wpf

For WinUI:

dotnet add package Atc.XamlToolkit.WinUI

For Avalonia:

dotnet add package Atc.XamlToolkit.Avalonia

Basic Usage

// Create a ViewModel with source-generated properties and commands
public partial class MainViewModel : ViewModelBase
{
    [ObservableProperty]
    private string userName;

    [ObservableProperty]
    private bool isLoading;

    [RelayCommand]
    private async Task LoadDataAsync()
    {
        IsLoading = true;
        // Load data...
        IsLoading = false;
    }
}

📖 Read the full Getting Started Guide for a complete walkthrough.

Requirements

• .NET >= 9.0.202 - SDK
• .NET 9 - Runtime for Avalonia
• .NET 9 - Desktop Runtime for WPF
• .NET 9 - Desktop Runtime for WinUI 3

NuGet Packages Provided in this Repository

Nuget package	Description	Dependencies
	Base package with ViewModelBase, ObservableObject	Atc & Atc.XamlToolkit.SourceGenerators
	RelayCommand, MainWindowViewModelBase for WPF	Atc.XamlToolkit.SourceGenerators
	RelayCommand, MainWindowViewModelBase for WinUI	Atc.XamlToolkit
	RelayCommand, MainWindowViewModelBase for Avalonia	Atc.XamlToolkit

📚 Documentation

Get Started

• Getting Started Guide - Complete walkthrough for beginners

Core Concepts

• MVVM Framework - ViewModels, Commands, and MVVM patterns
• Async Command Cancellation - CancellationToken support for async commands
• Messaging System - Decoupled communication between components
• Behaviors - EventToCommandBehavior and declarative behaviors
• Source Generators - Eliminate boilerplate code

Advanced Topics

• Value Converters - Complete converter reference
• Performance Optimizations - BooleanBoxes, WeakAction, and more
• Utilities and Helpers - DesignModeHelper, base classes, and utilities

Platform-Specific (WPF Only)

• Dependency Properties - Auto-generate dependency properties
• Attached Properties - Auto-generate attached properties
• Routed Events - Auto-generate routed events

Source Generator Examples

Example for ViewModel classes with source generation:

For more details, see the MVVM section.

🎯 Complete Feature List

Core MVVM Components

Commands

All commands support:

• ✅ CanExecute with automatic refresh
• ✅ Error handling via IErrorHandler
• ✅ Auto-generation via [RelayCommand] attribute
• ✅ Cancellation token support for async commands

Messaging System

Source Generators

Note on Routed Events: Routed events are a WPF-exclusive feature that uses EventManager.RegisterRoutedEvent() and supports event bubbling/tunneling through the visual tree. WinUI 3 and Avalonia use different event systems and do not support custom routed events. See the RoutedEvents documentation for detailed platform comparison.

Value Converters

Bool Converters (WPF, WinUI & Avalonia):

• BoolToInverseBoolValueConverter
• BoolToVisibilityCollapsedValueConverter
• BoolToVisibilityVisibleValueConverter
• BoolToWidthValueConverter
• MultiBoolToBoolValueConverter
• MultiBoolToVisibilityVisibleValueConverter

String Converters (WPF, WinUI & Avalonia):

• StringNullOrEmptyToBoolValueConverter
• StringNullOrEmptyToInverseBoolValueConverter
• StringNullOrEmptyToVisibilityVisibleValueConverter
• StringNullOrEmptyToVisibilityCollapsedValueConverter
• ToLowerValueConverter
• ToUpperValueConverter

Null Converters (WPF, WinUI & Avalonia):

• NullToVisibilityCollapsedValueConverter
• NullToVisibilityVisibleValueConverter

Performance Optimizations

Utilities

🌟 Why Choose Atc.XamlToolkit?

• ✅ Modern - Built for .NET 9 with latest C# features
• ✅ Cross-platform - Supports WPF, WinUI 3, and Avalonia
• ✅ High Performance - Optimized for minimal allocations
• ✅ Source Generators - Eliminate boilerplate code
• ✅ Well Documented - Comprehensive documentation and examples
• ✅ Battle Tested - Used in production applications
• ✅ Open Source - MIT licensed and community-driven

How to contribute

Contribution Guidelines

Coding Guidelines