Oakrey.Applications.Base 4.0.3

Oakrey.Applications.Base

A foundational .NET library for building modular WPF applications. It provides application lifecycle management, structured logging and telemetry, MVVM ViewModel resolution, service preloading with error diagnostics, and a set of WPF utilities.

Main features

• Application base class � OakreyApplication extends System.Windows.Application and wires up DI, logging, telemetry, and all unhandled-exception handlers in one place.
• Application metadata � IApplicationInfo / AppInfoBase expose name, version, log paths, settings paths, deployment URL, and application logo.
• ViewModel resolution � ViewModelProvider is a XAML markup extension that resolves ViewModels from the DI container, creates a scoped lifetime per FrameworkElement, and disposes it on Unloaded.
• Service preloading � IPreLoadable contract with observable error propagation. Sequential (TryPreloadServices) and parallel (TryPreloadServicesParallel) strategies. Aggregates errors and shuts down gracefully if preloading fails.
• Logging and telemetry � integrates Oakrey.Log (file + WPF queue loggers) and Oakrey.Telemetry tracing. Debug builds automatically lower the log threshold to Trace.
• WPF behaviors and extensions � BindableSelectedItemBehavior for two-way binding of TreeView.SelectedItem; KeyboardExtension for detecting keyboard shortcut combinations.
• Path helpers � PathsAndNames centralises assembly name, default settings directory, and per-user %AppData% settings path resolution.

Architecture

classDiagram
    class OakreyApplication {
        +IServiceProvider Services
        +GetService~T~()
        #App_Startup()
        #AppStartup(CancellationToken) Task
        #SetLoggers()
        #TryPreloadServices(CancellationToken, Type[]) Task
        #TryPreloadServicesParallel(CancellationToken, Type[]) Task
    }

    class IApplicationInfo {
        +Name : string
        +Version : string
        +LogFilePath : FileInfo
        +LogDirectoryPath : DirectoryInfo
        +UserSettingsPath : string
        +DefaultSettingsPath : string
        +DeploymentUrl : string
        +Logo : BitmapImage
    }

    class AppInfoBase {
        <<abstract>>
    }

    class IPreLoadable {
        <<interface>>
        +Preload(CancellationToken) Task
    }

    class ViewModelProvider {
        <<MarkupExtension>>
        +ViewModelType : Type
        +ProvideValue() object
    }

    class PreLoadingException {
        +Details : string
    }

    OakreyApplication --> IApplicationInfo : resolves
    OakreyApplication --> IPreLoadable : preloads
    OakreyApplication ..> PreLoadingException : observes
    AppInfoBase ..|> IApplicationInfo
    IPreLoadable ..> PreLoadingException : publishes
    ViewModelProvider --> IServiceProvider : resolves from

Requirements

• .NET 10 or higher
• Windows (WPF target: net10.0-windows)

Installation

NuGet Package Manager

1. Open Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
2. Search for Oakrey.Applications.Base and click Install.

.NET CLI

dotnet add package Oakrey.Applications.Base

Package Manager Console

Install-Package Oakrey.Applications.Base

Usage

1. Implement application metadata

public class MyAppInfo : AppInfoBase, IApplicationInfo
{
    public override string DeploymentUrl => "https://deploy.example.com/";
}

2. Register services and subclass OakreyApplication

public partial class App : OakreyApplication
{
    public App() : base(ConfigureServices) { }

    private static void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<IApplicationInfo, MyAppInfo>();
        services.AddSingleton<WpfQueueLogger>();
        // register your own services here
    }

    protected override async Task AppStartup(CancellationToken cancellationToken)
    {
        await TryPreloadServices(cancellationToken, typeof(IMyPreloadable));
        Current.MainWindow = new MainWindow();
        Current.MainWindow.Show();
    }
}

In App.xaml set x:Class="MyApp.App" and remove the default StartupUri. Wire the startup event:

<local:App x:Class="MyApp.App"
           xmlns:local="clr-namespace:MyApp"
           Startup="App_Startup">
</local:App>

3. Resolve ViewModels in XAML

<Window xmlns:app="clr-namespace:Oakrey.Applications;assembly=Oakrey.Applications.Base"
        DataContext="{app:ViewModelProvider viewModelType={x:Type local:MainViewModel}}">

The ViewModel is resolved from the DI container in a new scope. The scope is disposed automatically when the Window unloads.

4. Implement a preloadable service

public class MyStartupService : IPreLoadable
{
    private readonly Subject<PreLoadingException> _errors = new();

    public IDisposable Subscribe(IObserver<PreLoadingException> observer)
        => _errors.Subscribe(observer);

    public async Task Preload(CancellationToken cancellationToken)
    {
        // perform startup work; publish to _errors on failure
        await Task.CompletedTask;
    }
}

Register it with the DI container and pass its interface to TryPreloadServices.

5. Bind TreeView selected item

<TreeView>
    <i:Interaction.Behaviors>
        <app:BindableSelectedItemBehavior SelectedItem="{Binding SelectedNode, Mode=TwoWay}" />
    </i:Interaction.Behaviors>
</TreeView>

Configuration

Development notes

• The library targets net10.0-windows and has a hard dependency on WPF; it cannot be used in non-Windows or non-WPF projects.
• PathsAndNames reads from the entry assembly. In unit test hosts this may throw InvalidOperationException; mock IApplicationInfo instead of relying on AppInfoBase directly in tests.
• Unhandled exceptions from the UI thread, TaskScheduler, and AppDomain are all caught, logged, and marked as handled. Override the relevant handlers in a subclass to add custom recovery logic.
• The DI container is built once in the constructor and is available via Services. CommunityToolkit Ioc.Default is also configured during startup for XAML-friendly access.

License

MIT. Copyright (c) Oakrey 2016-present.

Repository: https://dev.azure.com/oakrey/OpenPackages/_git/ApplicationServices