Shiny Core

Library Overview

Companion Libraries

Setup

MAUI Setup

In MauiProgram.cs, call UseShiny() on the MauiAppBuilder. This registers all core infrastructure services and lifecycle wiring automatically:

using Shiny;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseShiny(); // Registers Shiny core services and lifecycle hooks

        // Register your own services using AddShinyService for auto-binding
        builder.Services.AddShinyService<MySettings>();

        // Add device monitoring
        builder.Services.AddConnectivity();
        builder.Services.AddBattery();

        // Add repository
        builder.Services.AddDefaultRepository();

        return builder.Build();
    }
}

Native (Non-MAUI) Setup

For native iOS apps, inherit from ShinyAppDelegate:

[Register("AppDelegate")]
public class AppDelegate : ShinyAppDelegate
{
    protected override IHost CreateShinyHost()
    {
        var builder = HostBuilder.Create();
        // Register services on builder.Services
        return builder.Build();
    }
}

For native Android apps, inherit from ShinyAndroidApplication and use ShinyAndroidActivity:

[Application]
public class MainApplication : ShinyAndroidApplication
{
    public MainApplication(IntPtr handle, JniHandleOwnership transfer) : base(handle, transfer) {}

    protected override IHost CreateShinyHost()
    {
        var builder = HostBuilder.Create();
        // Register services on builder.Services
        return builder.Build();
    }
}

[Activity(MainLauncher = true)]
public class MainActivity : ShinyAndroidActivity { }

Code Generation Instructions

When generating code that uses Shiny.Core, follow these conventions:

1. Always call UseShiny() in MAUI apps or inherit the proper native base classes. This is required before any Shiny module works.
2. Use AddShinyService<T>() to register singleton services that implement interfaces. It auto-registers all interfaces, binds INotifyPropertyChanged objects to persistent storage, and calls ComponentStart() on IShinyComponentStartup implementations.
3. Implement IShinyStartupTask for code that should run immediately after the DI container is built. Register it with services.AddSingleton<IShinyStartupTask, MyTask>().
4. Inherit ShinyLifecycleTask for startup tasks that also need foreground/background lifecycle events. Override OnStateChanged(bool backgrounding) and Start().
5. Implement IAndroidLifecycle.* or IIosLifecycle.* sub-interfaces for platform-specific lifecycle hooks. Register them in DI and the lifecycle executor dispatches to them automatically.
6. Use IKeyValueStore for simple key-value persistence. Use IKeyValueStoreFactory to retrieve named stores ("settings", "secure", "memory").
7. Decorate classes with [ObjectStoreBinder("storeAlias")] to control which store backs an INotifyPropertyChanged object.
8. Use NotifyPropertyChanged base class for view models and settings objects that should persist through the object store binder. It provides Set<T>() and RaisePropertyChanged().
9. Use IPlatform to access AppData, Cache, Public directories and InvokeOnMainThread().
10. Use AccessState enum and state.Assert() extension method to validate permissions before proceeding with platform operations.
11. Use reactive extensions (WhenAnyProperty, SubscribeAsync, SelectSwitch, DisposedBy) for composing observable streams.
12. Use IConnectivity.WhenChanged() and IBattery.WhenChanged()** for reactive monitoring of device state.
13. Use IRepository for entity persistence, with entities implementing IRepositoryEntity (must have an Identifier property).

Conventions

• All Shiny services are singletons.
• Settings/state classes should inherit from NotifyPropertyChanged.
• Place startup tasks in a Tasks/ or Infrastructure/ folder.
• Place settings classes in a Settings/ or Models/ folder.
• Always handle AccessState.Denied, AccessState.Disabled, and AccessState.NotSetup gracefully.
• Use System.Reactive (IObservable<T>) for event streams, not C# events.
• Extension methods in Shiny namespace are available when the appropriate package is referenced.

Namespace Ambiguities with MAUI

When using Shiny in a MAUI app, several Shiny types collide with MAUI implicit usings. Do NOT add all Shiny namespaces as global usings. Use explicit namespaces or FQNs for these:

Safe global usings (won't conflict with MAUI):

global using Shiny;
global using Shiny.Stores;
global using Shiny.Jobs;
global using Shiny.Locations;
global using Shiny.BluetoothLE;
// Do NOT globally use: Shiny.Net, Shiny.Power, Shiny.Notifications, Shiny.Push, Shiny.BluetoothLE.Hosting

Best Practices

• Initialize Shiny early -- UseShiny() must be called in the builder chain before building the MAUI app. For native apps, the host must be created and Run() called in the application startup.
• Prefer AddShinyService<T> over manual DI registration for types that implement interfaces or INotifyPropertyChanged. It handles all the wiring automatically.
• Keep startup tasks lightweight -- IShinyStartupTask.Start() runs synchronously on the main thread at startup.
• Use named stores appropriately -- "settings" for general preferences (backed by SharedPreferences/NSUserDefaults), "secure" for sensitive data (backed by Android Keystore/iOS Keychain).
• Dispose observable subscriptions -- use DisposedBy(CompositeDisposable) to manage subscription lifetimes.
• Use StoreExtensions.Get<T>() for type-safe retrieval with default values. Use GetRequired<T>() when a missing key should throw.
• Use SetOrRemove() to automatically clean up null/default values from the store.
• Check Host.IsInitialized before accessing Host.Current in code that may run before initialization.
• Use BindingList<T> for thread-safe observable collections that can be bound to UI.
• Use ShinySubject<T> instead of raw Subject<T> for error-safe multicasting with logging support.

Reference Files

• API Reference