Avalonia Zafiro Development

Avalonia Zafiro Development

This skill defines the mandatory conventions and behavioral rules for developing cross-platform applications with Avalonia UI and the Zafiro toolkit. These rules prioritize maintainability, correctness, and a functional-reactive approach.

Core Pillars

1. Functional-Reactive MVVM: Pure MVVM logic using DynamicData and ReactiveUI. 2. Safety & Predictability: Explicit error handling with Result types and avoidance of exceptions for flow control. 3. Cross-Platform Excellence: Strictly Avalonia-independent ViewModels and composition-over-inheritance. 4. Zafiro First: Leverage existing Zafiro abstractions and helpers to avoid redundancy.

Guides

• Core Technical Skills & Architecture: Fundamental skills and architectural principles.
• Naming & Coding Standards: Rules for naming, fields, and error handling.
• Avalonia, Zafiro & Reactive Rules: Specific guidelines for UI, Zafiro integration, and DynamicData pipelines.
• Zafiro Shortcuts: Concise mappings for common Rx/Zafiro operations.
• Common Patterns: Advanced patterns like RefreshableCollection and Validation.

Procedure Before Writing Code

1. Search First: Search the codebase for similar implementations or existing Zafiro helpers. 2. Reusable Extensions: If a helper is missing, propose a new reusable extension method instead of inlining complex logic. 3. Reactive Pipelines: Ensure DynamicData operators are used instead of plain Rx where applicable.

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.

Avalonia, Zafiro & Reactive Rules

Avalonia UI Rules

• Strict Avalonia: Never use System.Drawing; always use Avalonia types.
• Pure ViewModels: ViewModels must never reference Avalonia types.
• Bindings Over Code-Behind: Logic should be driven by bindings.
• DataTemplates: Prefer explicit DataTemplates and typed DataContexts.
• VisualStates: Avoid using VisualStates unless absolutely required.

Zafiro Guidelines

• Prefer Abstractions: Always look for existing Zafiro helpers, extension methods, and abstractions before re-implementing logic.
• Validation: Use Zafiro's ValidationRule and validation extensions instead of ad-hoc reactive logic.

DynamicData & Reactive Rules

The Mandatory Approach

• Operator Preference: Always prefer DynamicData operators (Connect, Filter, Transform, Sort, Bind, DisposeMany) over plain Rx operators when working with collections.
• Readable Pipelines: Build and maintain pipelines as a single, readable chain.
• Lifecycle: Use DisposeWith for lifecycle management.
• Minimal Subscriptions: Subscriptions should be minimal, centralized, and strictly for side-effects.

Forbidden Anti-Patterns

• Ad-hoc Sources: Do NOT create new SourceList / SourceCache on the fly for local problems.
• Logic in Subscribe: Do NOT place business logic inside Subscribe.
• Operator Mismatch: Do NOT use System.Reactive operators if a DynamicData equivalent exists.

Canonical Patterns

Validation of Dynamic Collections:

this.ValidationRule(
        StagesSource
            .Connect()
            .FilterOnObservable(stage => stage.IsValid)
            .IsEmpty(),
        b => !b,
        _ => "Stages are not valid")
    .DisposeWith(Disposables);

Filtering Nulls: Use WhereNotNull() in reactive pipelines.

this.WhenAnyValue(x => x.DurationPreset).WhereNotNull()

Core Technical Skills & Architecture

Mandatory Expertise

The developer must possess strong expertise in:

• C# and modern .NET: Utilizing the latest features of the language and framework.
• Avalonia UI: For cross-platform UI development.
• MVVM Architecture: Maintaining strict separation between UI and business logic.
• Clean Code & Clean Architecture: Focusing on maintainability and inward dependency flow.
• Functional Programming in C#: Embracing immutability and functional patterns.
• Reactive Programming: Expertise in DynamicData and System.Reactive.

Architectural Principles

• Pure MVVM: Mandatory for all UI code. Logic must be independent of UI concerns.
• Composition over Inheritance: Favor modular building blocks over deep inheritance hierarchies.
• Inward Dependency Flow: Abstractions must not depend on implementations.
• Immutability: Prefer immutable structures where practical to ensure predictability.
• Stable Public APIs: Design APIs carefully to ensure long-term stability and clarity.

Naming & Coding Standards

General Standards

• Explicit Names: Favor clarity over cleverness.
• Async Suffix: Do NOT use the Async suffix in method names, even if they return Task.
• Private Fields: Do NOT use the _ prefix for private fields.
• Static State: Avoid static state unless explicitly justified and documented.
• Method Design: Keep methods small, expressive, and with low cyclomatic complexity.

Error Handling

• Result & Maybe: Use types from CSharpFunctionalExtensions for flow control and error handling.
• Exceptions: Reserved strictly for truly exceptional, unrecoverable situations.
• Boundaries: Never allow exceptions to leak across architectural boundaries.

Common Patterns in Angor/Zafiro

Refreshable Collections

The RefreshableCollection pattern is used to manage lists that can be refreshed via a command, maintaining an internal SourceCache/SourceList and exposing a ReadOnlyObservableCollection.

Implementation

var refresher = RefreshableCollection.Create(
        () => GetDataTask(), 
        model => model.Id)
    .DisposeWith(disposable);

LoadData = refresher.Refresh;
Items = refresher.Items;

Benefits

• Automatic Loading: Handles the command execution and results.
• Efficient Updates: Uses EditDiff internally to update items without clearing the list.
• UI Friendly: Exposes Items as a ReadOnlyObservableCollection suitable for binding.

Mandatory Validation Pattern

When validating dynamic collections, always use the Zafiro validation extension:

this.ValidationRule(
        StagesSource
            .Connect()
            .FilterOnObservable(stage => stage.IsValid)
            .IsEmpty(),
        b => !b,
        _ => "Stages are not valid")
    .DisposeWith(Disposables);

Error Handling Pipeline

Instead of manual Subscribe, use HandleErrorsWith to pipe errors directly to the user:

LoadProjects.HandleErrorsWith(uiServices.NotificationService, "Could not load projects");

Zafiro Reactive Shortcuts

Use these Zafiro extension methods to replace standard, more verbose Reactive and DynamicData patterns.

General Observable Helpers

Result & Maybe Extensions

Lifecycle Management

Command & Interaction

[!TIP]

Always check Zafiro.Reactive.ObservableMixin and Zafiro.CSharpFunctionalExtensions.ObservableExtensions before writing custom Rx logic.