UXDivers Avalonia Navigation Framework

A powerful and flexible navigation framework for Avalonia applications, featuring scoped dependency injection, modular navigation, and MVVM support.

Overview

The UXDivers Avalonia Navigation Framework provides a comprehensive solution for building scalable Avalonia applications with:

• Scoped Dependency Injection: Hierarchical service scopes that align with your UI structure
• Outlet-Based Navigation: Navigate between views within defined outlets of your application
• MVVM Support: First-class support for ViewModels with automatic resolution and lifecycle management
• Cross-Platform: Works seamlessly across Desktop, Mobile (iOS/Android), and Browser platforms
• Fluent API: Intuitive builder pattern for configuring navigation and scopes

Key Features

Scoped Dependency Injection

• Create isolated service scopes for different parts of your application (windows, views, etc.)
• Automatic scope propagation through the visual tree
• Support for custom scope implementations
• Efficient service resolution with parent scope fallback

Navigation System

• Outlet-based navigation with support for multiple outlets per view
• Modal and non-modal navigation
• Navigation parameters and result handling
• View and ViewModel lifecycle awareness (IActivatable, IInitializeAware)
• Nested outlet support

Flexibility

• Compatible with Microsoft.Extensions.DependencyInjection
• Support for both manual service container setup and .NET Generic Host
• Custom view/ViewModel resolution strategies

Quick Start

1. Install the NuGet Package

dotnet add package UXDivers.Popups.Maui

2. Basic App Setup

In your App.axaml.cs:

public class App : Application
{
    private IServiceProvider? _services;

    public override void Initialize()
    {
        base.Initialize();
        AvaloniaXamlLoader.Load(this);

        // Create and configure services
        var services = new ServiceCollection();
        ConfigureServices(services);
        
        // Build and initialize the service provider
        _services = services.BuildServiceProvider();
        ServiceLocator.Initialize(_services);
    }

    private void ConfigureServices(IServiceCollection services)
    {
        // Add navigation support
        services.AddNavigation(navigationBuilder =>
        {
            navigationBuilder.WithDefaultOutlet("MainOutlet");
            navigationBuilder.WithNavigationRegistry(registry =>
            {
                registry.RegisterView<HomeView>()
                    .WithViewModel<HomeViewModel>()
                    .AsOutletTarget("MainOutlet");
            });
        });
            
        // Register your windows
        services.AddTransient<MainWindow>();
    }
}

3. Define Outlets in XAML

<Window xmlns="https://github.com/avaloniaui"
        xmlns:uxd="https://uxdivers.com"
        x:Class="YourApp.MainWindow">

    <uxd:Shell uxd:NavigationService.OutletName="MainOutlet" />
</Window>

4. Navigate Between Views

public class HomeViewModel : ViewModelBase
{
    private readonly INavigationService _navigationService;

    public HomeViewModel(INavigationService navigationService)
    {
        _navigationService = navigationService;
    }

    private async Task NavigateToDetails()
    {
        await _navigationService.NavigateAsync("MainOutlet", "DetailsView");
    }
}

Documentation

Detailed documentation is available in the docs folder:

• Scopes Guide - Understanding and configuring scopes
• Navigation Guide - Outlet-based navigation patterns
• Outlet Handlers - Extending navigation to support custom controls
• Service Registration - Registering views, ViewModels, and services

Architecture

Core Concepts

1. ServiceLocator: Global access point to the root service provider
2. Scopes: Isolated service containers that can be attached to controls
3. Outlets: Named navigation targets within your UI
4. Navigation Registry: Maps view names to view types and ViewModels
5. Behaviors: Extensible hooks for customizing navigation and outlet behavior

Component Hierarchy

Application
  ├─ ServiceProvider (Global)
  │   └─ IScopeRegistry
  │
  └─ Windows/Views
      └─ Scope (Per Window/View)
          ├─ IOutletManager
          ├─ INavigationService
          └─ INavigationRegistry

Platform Support

• ✅ Windows Desktop
• ✅ macOS Desktop
• ✅ Linux Desktop
• ✅ iOS
• ✅ Android
• ✅ WebAssembly (Browser)

Requirements

• .NET 8.0 or later
• Avalonia 11.0 or later
• Microsoft.Extensions.DependencyInjection

Examples

The repository includes two example applications:

1. UXDivers.Avalonia.TestApp - Manual service container setup
2. UXDivers.Avalonia.TestAppWithHost - Using .NET Generic Host

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For questions and support, please visit our website or open an issue in the repository.