Avalonia.Markup.Declarative

For features where the view and its reactive state are tightly coupled, use a self-contained declarative component. This pattern involves inheriting from ViewBase<TState> and defining a nested State class (typically using CommunityToolkit.Mvvm.ComponentModel.ObservableObject).

To compose views that require constructor injection, use ViewFactory.Create<T>(). If you are using Dependency Injection, register UseComponentControlFactory(...) on your AppBuilder.

using Avalonia.Data;
using CommunityToolkit.Mvvm.ComponentModel;

public class CounterComponent() : ViewBase<CounterComponent.State>(new State())
{
    public sealed partial class State : ObservableObject
    {
        [ObservableProperty]
        [NotifyPropertyChangedFor(nameof(CounterLabel))]
        public partial decimal? Counter { get; set; } = 0;

        [ObservableProperty]
        public partial string StatusText { get; set; } = "Hello world";

        public string CounterLabel => $"Counter: {Counter}";
    }

    protected override object Build(State state) =>
        new StackPanel()
            .Children(
                new TextBlock()
                    .Text(state, x => x.StatusText),
                new TextBlock()
                    .Text(state, x => x.CounterLabel),
                new NumericUpDown()
                    .Value(state, x => x.Counter, BindingMode.TwoWay),
                new Button()
                    .Content("Increment")
                    .OnClick(_ => state.Counter++)
            );
}

Compiled-binding setters in Avalonia.Markup.Declarative support automatic conversion for common primitive and nullable mismatches.

• Recommended approach: Use plain member access like x => x.Property. This avoids manual casts for types like int -> double or bool -> bool?.
• Unsupported: Value-converting casts such as x => (double)x.Counter are rejected by the expression parser.
• Supported: Type casts that reach a member of a derived type, such as x => ((DerivedType)x).Property, are supported.
• Note on TwoWay bindings: For lossy numeric TwoWay bindings, the convert-back operation truncates toward zero.

// Prefer this (automatic conversion works for int -> double)
Button().Bind(Button.CommandProperty, x => x.MyCommand)

// This is supported (casting to derived type)
Button().Bind(Button.CommandProperty, x => ((DerivedViewModel)x).MyCommand)

// This is REJECTED (direct value cast)
// Button().Bind(Button.CommandProperty, x => (double)x.Counter)

The inspector captures several types of errors to provide actionable feedback to agents:

• Build errors: ViewBuildingException (including rich binding/setter error messages) are stored in a thread-safe ring buffer.
• Binding & Converter errors: Captured via a custom ILogSink decorator on Avalonia's Logger.Sink, specifically filtering for LogArea.Binding and LogArea.Property.
• Runtime errors: Unhandled exceptions on the UI dispatcher and unobserved task exceptions are captured by RuntimeErrorSink. This is a pure observer; it records the exception (including the throw site) but does not mark it as handled, so the application's original error behavior remains unchanged.
• Structured ViewModel errors: When set_view_model or invoke_command fails due to a bad path, the error message includes the failing segment, the runtime type of the object, available members, and a "did you mean" suggestion.

To expose application-specific logic (like sprite editing or state inspection) to an agent, implement custom tool classes and register them using WithTools<T>() during inspector setup.

Implementation Steps:

1. Define a Tool Class: Mark the class with [McpServerToolType]. Use [McpServerTool] on methods to expose them.
2. Provide Documentation: Use the [Description] attribute on methods. This is the only documentation the agent receives to decide how to call the tool.
3. Dependency Injection: Tool instances are built once from your application's Services. You can inject your app's state or services into the constructor.
4. Gating Interaction: To prevent accidental state changes, mark state-modifying tool classes with [AgentInteractionTools]. These will only be registered if EnableInteraction is set to true in the inspector configuration.

Example Implementation

[McpServerToolType]
public sealed class SpriteTools
{
    private readonly AppState _state;

    public SpriteTools(AppState state) => _state = state;

    [McpServerTool(Name = "get_sprite_info", ReadOnly = true), Description(
        "Returns the open sprite's size, frame count and the selected layer.")]
    public string GetSpriteInfo() =>
        $"{_state.Sprite.Size}, {_state.Sprite.Frames.Count} frame(s), layer '{_state.SelectedLayer.Name}'";
}

// Registration
.UseAgentInspector(o =>
{
    o.EnableInteraction = true;
    o.Services = serviceProvider;
    o.WithTools<SpriteTools>();
})

The library has moved away from reflection-based Bind(...) and custom onChanged callbacks. You should now use compiled bindings which provide better type safety and performance.

Patterns:

• Two-way binding: Instead of .Value(() => property, val => property = val), use .Value(state, x => x.Property, BindingMode.TwoWay).
• Standard binding: Instead of .Text(Bind(Message)), use .Text(state, x => x.Message).
• Styles: Instead of string-based or Binding object styles, use compiled style setters: .IsEnabled(default(TViewModel)!, x => x.IsPropertyEnabled).

// Two-way input
new NumericUpDown()
    .Value(state, x => x.Counter, BindingMode.TwoWay);

// Compiled binding
new TextBox()
    .Text(state, x => x.Message, BindingMode.TwoWay);

// Compiled style binding
new Style<TabItem>()
    .IsEnabled(default(TabVm)!, x => x.Enabled)
    .Foreground(Brushes.YellowGreen);