XAvalonia.Controls 0.3.0

XAvalonia

A plugin-based, extensible desktop shell framework built on Avalonia UI — inspired by Gemini for WPF, reimagined for cross-platform .NET.

What is XAvalonia?

XAvalonia is a shell framework for building extensible desktop applications on top of Avalonia UI. It provides the plumbing — docking layout, menus, status bar, panels, documents — so that each feature of your application lives in an isolated, self-describing plugin.

The architecture is directly inspired by the Eclipse/Gemini model:

• The shell owns the window, the dock, and the service bus.
• Plugins discover each other at runtime, register services, and contribute UI via a clean contribution API.
• Your Program.cs is a single line.

[STAThread]
public static void Main(string[] pArgs) => ShellApplication.Run(pArgs);

Features

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        XAvalonia.SampleApp                      │
│                     (entry point — 1 line)                      │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                      XAvalonia.Bootstrap                        │
│   ShellApplication · PluginLoader · PluginManager · Services    │
└──────────────────────────┬──────────────────────────────────────┘
                           │ depends on
┌──────────────────────────▼──────────────────────────────────────┐
│               XAvalonia.Shell.Abstractions                      │
│   IPlugin · IMenuService · IDocumentService · IToolPanelService │
│   IStatusBarService · IMainWindowService · ILogService …        │
└─────────────────────────────────────────────────────────────────┘
                           ▲
              ┌────────────┼────────────┐
              │            │            │
    ┌─────────┴──┐  ┌──────┴─────┐  ┌──┴──────────┐
    │ MainWindow │  │PluginBrowser│  │  YourPlugin  │
    │  Plugin    │  │   Plugin    │  │   (future)   │
    └────────────┘  └────────────┘  └─────────────-┘

Plugins only ever reference XAvalonia.Shell.Abstractions — zero coupling to the framework internals.

Default layout

┌─────────────────────────────────────────────────────┐
│  File   View   Help                                 │  ← Menu bar
├──────────┬──────────────────────────┬───────────────┤
│          │  [ Doc 1 ] [ Doc 2 ] …  │               │
│          ├──────────────────────────┤               │
│ Explorer │   Document content…      │  Properties   │
│          ├──────────────────────────┤               │
│          │  Output                  │               │
│          │  [INFO] Application …    │               │
├──────────┴──────────────────────────┴───────────────┤
│  Ready          No file open                  Ln 1  │  ← Status bar
└─────────────────────────────────────────────────────┘

Getting Started

Prerequisites

• .NET 8 SDK

Run the sample app

git clone https://github.com/your-org/xavalonia.git
cd xavalonia
dotnet run --project XAvalonia.SampleApp

Writing a Plugin

A plugin is a class library that references only XAvalonia.Shell.Abstractions.

1. Implement IPlugin

public sealed class HelloPlugin : IPlugin
{
    public string Id          => "com.example.hello";
    public string Name        => "Hello Plugin";
    public string Description => "A minimal XAvalonia plugin.";
    public Version CurrentVersion    => new(1, 0, 0);
    public string? NuGetPackageId    => null;
    public IReadOnlyList<Type> ProvidedServices => [];

    public void RegisterServices(IServiceCollection pServices)
    {
        pServices.AddSingleton<HelloDocumentViewModel>();
    }

    public void Initialize(IPluginServiceManager pServiceManager)
    {
        IMenuService lMenus = pServiceManager.RequestService<IMenuService>();
        IDocumentService lDocs = pServiceManager.RequestService<IDocumentService>();

        lMenus.RegisterMenuItem("menu.file", new MenuItemContribution
        {
            Id      = "menu.file.hello",
            Header  = "_Hello World",
            Order   = 100,
            Command = ReactiveCommand.Create(() =>
                lDocs.RegisterDocument(new DocumentContribution
                {
                    Id        = "doc.hello",
                    Title     = "Hello",
                    ViewModel = pServiceManager.RequestService<HelloDocumentViewModel>()
                }))
        });
    }
}

2. Drop the DLL into the plugins directory

Point pluginsDirectory in technical_configuration.json to the folder containing your plugin's output. XAvalonia scans all assemblies at startup — no manual registration required.

{
  "pluginsDirectory": "C:\\MyApp\\Plugins"
}

3. Follow the View convention

The ViewLocator resolves views by naming convention:

Project Structure

XAvalonia/
├── XAvalonia.Shell.Abstractions/   ← Plugin contract (no UI deps)
├── XAvalonia.Bootstrap/            ← Framework core & services
├── XAvalonia.Controls/             ← Shared controls (PropertyInspector)
├── XAvalonia.MainWindow/           ← Default dock layout plugin
├── XAvalonia.SampleApp/            ← Minimal entry-point app
└── Plugins/
    ├── XAvalonia.PluginBrowser/    ← Browse & update plugins
    ├── XAvalonia.LogViewer/        ← Output panel
    ├── XAvalonia.UserSettings/     ← Settings editor (user configuration)
    └── XAvalonia.Splashscreen/     ← Startup splash screen

Key Dependencies

Roadmap

• Add a screenshot / GIF demo
• NuGet package for XAvalonia.Shell.Abstractions
• Theming API (light / dark / custom)
• Plugin marketplace integration
• Persistent user layout per plugin

Acknowledgements

Inspired by Gemini — the excellent WPF shell framework by @tgjones. XAvalonia brings the same plugin-first philosophy to cross-platform desktop development via Avalonia UI.

License

MIT — see LICENSE.