Avalonia Viewmodels Zafiro

Avalonia ViewModels with Zafiro

This skill provides a set of best practices and patterns for creating ViewModels, Wizards, and managing navigation in Avalonia applications, leveraging the power of ReactiveUI and the Zafiro toolkit.

Core Principles

1. Functional-Reactive Approach: Use ReactiveUI (ReactiveObject, WhenAnyValue, etc.) to handle state and logic. 2. Enhanced Commands: Utilize IEnhancedCommand for better command management, including progress reporting and name/text attributes. 3. Wizard Pattern: Implement complex flows using SlimWizard and WizardBuilder for a declarative and maintainable approach. 4. Automatic Section Discovery: Use the [Section] attribute to register and discover UI sections automatically. 5. Clean Composition: map ViewModels to Views using DataTypeViewLocator and manage dependencies in the CompositionRoot.

Guides

• ViewModels & Commands: Creating robust ViewModels and handling commands.
• Wizards & Flows: Building multi-step wizards with SlimWizard.
• Navigation & Sections: Managing navigation and section-based UIs.
• Composition & Mapping: Best practices for View-ViewModel wiring and DI.

Example Reference

For real-world implementations, refer to the Angor project:

• CreateProjectFlowV2.cs: Excellent example of complex Wizard building.
• HomeViewModel.cs: Simple section ViewModel using functional-reactive commands.

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Composition & Mapping

Ensuring your ViewModels are correctly instantiated and mapped to their corresponding Views is crucial for a maintainable application.

ViewModel-to-View Mapping

Zafiro uses the DataTypeViewLocator to automatically map ViewModels to Views based on their data type.

Integration in App.axaml

Register the DataTypeViewLocator in your application's data templates:

<Application.DataTemplates>
    <DataTypeViewLocator />
    <DataTemplateInclude Source="avares://Zafiro.Avalonia/DataTemplates.axaml" />
</Application.DataTemplates>

Registration

Mappings can be registered globally or locally. Common practice in Zafiro projects is to use naming conventions or explicit registrations made by source generators.

Composition Root

Use a central CompositionRoot to manage dependency injection and service registration.

public static class CompositionRoot
{
    public static IShellViewModel CreateMainViewModel(Control topLevelView)
    {
        var services = new ServiceCollection();
        
        services
            .AddViewModels()
            .AddUIServices(topLevelView);
            
        var serviceProvider = services.BuildServiceProvider();
        return serviceProvider.GetRequiredService<IShellViewModel>();
    }
}

Registering ViewModels

Register ViewModels with appropriate scopes (Transient, Scoped, or Singleton).

public static IServiceCollection AddViewModels(this IServiceCollection services)
{
    return services
        .AddTransient<IHomeSectionViewModel, HomeSectionSectionViewModel>()
        .AddSingleton<IShellViewModel, ShellViewModel>();
}

View Injection

Use the Connect helper (if available) or manual instantiation in OnFrameworkInitializationCompleted:

public override void OnFrameworkInitializationCompleted()
{
    this.Connect(
        () => new ShellView(),
        view => CompositionRoot.CreateMainViewModel(view),
        () => new MainWindow());

    base.OnFrameworkInitializationCompleted();
}

[!TIP]

Use ActivatorUtilities.CreateInstance when you need to manually instantiate a class while still resolving its dependencies from the IServiceProvider.

Navigation & Sections

Zafiro provides powerful abstractions for managing application-wide navigation and modular UI sections.

Navigation with INavigator

The INavigator interface is used to switch between different views or viewmodels.

public class MyViewModel(INavigator navigator)
{
    public async Task GoToDetails()
    {
        await navigator.Navigate(() => new DetailsViewModel());
    }
}

UI Sections

Sections are modular parts of the UI (like tabs or sidebar items) that can be automatically registered.

The [Section] Attribute

ViewModels intended to be sections should be marked with the [Section] attribute.

[Section("Wallet", icon: "fa-wallet")]
public class WalletSectionViewModel : IWalletSectionViewModel
{
    // ...
}

Automatic Registration

In the CompositionRoot, sections can be automatically registered:

services.AddAnnotatedSections(logger);
services.AddSectionsFromAttributes(logger);

Switching Sections

You can switch the current active section via the IShellViewModel:

shellViewModel.SetSection("Browse");

[!IMPORTANT]

The icon parameter in the [Section] attribute supports FontAwesome icons (e.g., fa-home) when configured with ProjektankerIconControlProvider.

ViewModels & Commands

In a Zafiro-based application, ViewModels should be functional, reactive, and resilient.

Reactive ViewModels

Use ReactiveObject as the base class. Properties should be defined using the [Reactive] attribute (from ReactiveUI.SourceGenerators) for brevity.

public partial class MyViewModel : ReactiveObject
{
    [Reactive] private string name;
    [Reactive] private bool isBusy;
}

Observation and Transformation

Use WhenAnyValue to react to property changes:

this.WhenAnyValue(x => x.Name)
    .Select(name => !string.IsNullOrEmpty(name))
    .ToPropertyEx(this, x => x.CanSubmit);

Enhanced Commands

Zafiro uses IEnhancedCommand, which extends ICommand and IReactiveCommand with additional metadata like Name and Text.

Creating a Command

Use ReactiveCommand.Create or ReactiveCommand.CreateFromTask and then Enhance() it.

public IEnhancedCommand Submit { get; }

public MyViewModel()
{
    Submit = ReactiveCommand.CreateFromTask(OnSubmit, canSubmit)
        .Enhance(text: "Submit Data", name: "SubmitCommand");
}

Error Handling

Use HandleErrorsWith to automatically channel command errors to the NotificationService.

Submit.HandleErrorsWith(uiServices.NotificationService, "Submission Failed")
    .DisposeWith(disposable);

Disposables

Always use a CompositeDisposable to manage subscriptions and command lifetimes.

public class MyViewModel : ReactiveObject, IDisposable
{
    private readonly CompositeDisposable disposables = new();

    public void Dispose() => disposables.Dispose();
}

[!TIP]

Use .DisposeWith(disposables) on any observable subscription or command to ensure proper cleanup.

Wizards & Flows

Complex multi-step processes are handled using the SlimWizard pattern. This provides a declarative way to define steps, navigation logic, and final results.

Defining a Wizard

Use WizardBuilder to define the steps. Each step corresponds to a ViewModel.

SlimWizard<string> wizard = WizardBuilder
    .StartWith(() => new Step1ViewModel(data))
        .NextUnit()
        .WhenValid()
    .Then(prevResult => new Step2ViewModel(prevResult))
        .NextCommand(vm => vm.CustomNextCommand)
    .Then(result => new SuccessViewModel("Done!"))
        .Next((_, s) => s, "Finish")
    .WithCompletionFinalStep();

Navigation Rules

• NextUnit(): Advances when a simple signal is emitted.
• NextCommand(): Advances when a specific command in the ViewModel execution successfully.
• WhenValid(): Wait until the current ViewModel's validation passes before allowing navigation.
• Always(): Navigation is always allowed.

Navigation Integration

The wizard is navigated using an INavigator:

public async Task CreateSomething()
{
    var wizard = BuildWizard();
    var result = await wizard.Navigate(navigator);
    // Handle result
}

Step Configuration

• WithCompletionFinalStep(): Marks the wizard as finished when the last step completes.
• WithCommitFinalStep(): Typically used for wizards that perform a final "Save" or "Deploy" action.

[!NOTE]

The SlimWizard handles the "Back" command automatically, providing a consistent user experience across different flows.