shiny-maui-hosting

Shiny MAUI Hosting Skill

You are an expert in Shiny Extensions MAUI Hosting, a .NET library providing modular MAUI app configuration via IMauiModule, a static service provider accessor, an IAppSupport service for device info and orientation/culture/timezone change detection, and an IAppStore service for cross-platform store info and deep links.

Platform lifecycle hooks (IIosLifecycle.*, IAndroidLifecycle.*, IMacLifecycle.*) are wired automatically by UseShiny() from Shiny.Hosting.Maui — they are not handled by this library.

When to Use This Skill

Invoke this skill when the user wants to:

• Create MAUI hosting modules with IMauiModule
• Access the service provider via Host.Services
• React to orientation, culture, or time-zone changes via IAppSupport
• Programmatically lock or reset device orientation
• Check store version / deep-link to store / launch a review page via IAppStore

Library Overview

Documentation: https://shinylib.net/mauihost/ Repository: https://github.com/shinyorg/extensions Package: Shiny.Extensions.MauiHosting Namespace: Shiny

Registration

Starting in v4, each capability ships as its own extension method. AddInfrastructureModules only wires modules — opt into the rest:

using Shiny;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .AddInfrastructureModules(new MyModule(), new AnotherModule())
    .AddAppSupport()                              // IAppSupport
    .AddAppStore(opts =>                          // IAppStore + IOptions<AppStoreOptions>
    {
        opts.AppleAppId = "1234567890";
        opts.WindowsProductId = "9NBLGGH4NNS1";
        opts.CountryCode = "us";
    });

return builder.Build();

Each extension is idempotent (uses TryAddSingleton / HasImplementation guards) so it's safe to call from libraries.

AddAppStore has a convenience overload:

builder.AddAppStore(appleAppId: "1234567890", windowsProductId: "9NBLGGH4NNS1");

IMauiModule Interface

public interface IMauiModule
{
    void Add(MauiAppBuilder builder);           // Register services
    void Use(IPlatformApplication app);         // Post-build initialization (do NOT block)
}

Each module implements two methods:

• Add(MauiAppBuilder builder) — register services, configure the builder. Runs before the app is built.
• Use(IPlatformApplication app) — post-build initialization. Host.Services is available here. Do NOT block — runs on the main thread.

public class AnalyticsModule : IMauiModule
{
    public void Add(MauiAppBuilder builder)
    {
        builder.Services.AddSingleton<IAnalytics, AppCenterAnalytics>();
    }

    public void Use(IPlatformApplication app)
    {
        var analytics = Host.Services.GetRequiredService<IAnalytics>();
        analytics.TrackEvent("AppStarted");
    }
}

Static Host Access

After initialization, Host.Services provides access to the service provider from anywhere:

var service = Host.Services.GetRequiredService<IMyService>();

:::caution Host.Services throws InvalidOperationException if accessed before initialization. :::

IAppSupport

IAppSupport exposes device info, browser/map launch, programmatic orientation lock, and change-detection events for orientation, culture, and time zone.

public interface IAppSupport
{
    Version AppVersion { get; }
    string DeviceManufacturer { get; }
    string DeviceModel { get; }
    Version? PlatformVersion { get; }

    DisplayOrientation CurrentOrientation { get; }
    event EventHandler<DisplayOrientation>? OrientationChanged;

    CultureInfo CurrentCulture { get; }
    event EventHandler<CultureInfo>? CultureChanged;

    TimeZoneInfo CurrentTimeZone { get; }
    event EventHandler<TimeZoneInfo>? TimeZoneChanged;

    Task<bool> SetOrientation(DisplayOrientation orientation);
    Task<bool> ResetOrientation();

    Task<bool> OpenBrowser(string uri, /* … */);
    Task<bool> OpenMap(double latitude, double longitude, /* … */);
}

Change-detection events

Each event has its own lazy subscription — the native listener spins up when the first handler attaches and tears down when the last detaches.

Capability	iOS / macCatalyst	Android	Windows	Bare TFM
Orientation	DeviceDisplay.MainDisplayInfoChanged (MAUI)	DeviceDisplay.MainDisplayInfoChanged (MAUI)	DeviceDisplay.MainDisplayInfoChanged (MAUI)	2s poll
Culture	NSLocale.CurrentLocaleDidChangeNotification	BroadcastReceiver on Intent.ActionLocaleChanged	SystemEvents.UserPreferenceChanged (Locale category)	30s poll
Time zone	NSSystemTimeZoneDidChangeNotification	BroadcastReceiver on Intent.ActionTimezoneChanged	SystemEvents.TimeChanged	30s poll

public class SettingsViewModel(IAppSupport app)
{
    public void Init()
    {
        app.OrientationChanged += (s, o) => { /* new DisplayOrientation */ };
        app.CultureChanged += (s, c) => { /* new CultureInfo */ };
        app.TimeZoneChanged += (s, tz) => { /* new TimeZoneInfo */ };
    }
}

Orientation lock

await app.SetOrientation(DisplayOrientation.Landscape);
await app.ResetOrientation();   // restore system default

Platform	Mechanism	Notes
Android	Activity.RequestedOrientation	Uses SensorPortrait/SensorLandscape so the device can still flip left↔right within the chosen orientation. Returns false if no current Activity
iOS 16+	UIWindowScene.RequestGeometryUpdate	The active view controller must permit the requested mask via supportedInterfaceOrientations or the request is silently dropped
iOS 15 and earlier	Not supported	Returns false
macCatalyst	Not supported (windows don't rotate)	Returns false
Windows	DisplayInformation.AutoRotationPreferences	None restores system default

IAppStore

IAppStore looks up the latest published version from the relevant platform store, exposes deep links, and launches the review page.

public interface IAppStore
{
    Task<AppStoreResult?> GetCurrent(CancellationToken cancellationToken = default);
    Task<bool> OpenStore();
    Task<bool> OpenReviewPage();
}

public record AppStoreResult(
    Version StoreVersion,
    Version CurrentVersion,
    bool NeedsUpdate,
    string StoreUrl,
    string? ReleaseNotes = null,
    DateTimeOffset? ReleasedAt = null,
    double? AverageRating = null,
    long? RatingCount = null,
    string? MinimumOsVersion = null
);

public class AppStoreOptions
{
    public string? AppleAppId { get; set; }         // numeric App Store ID (required for iOS deep links)
    public string? AppleBundleId { get; set; }      // defaults to AppInfo.PackageName
    public string? AndroidPackageName { get; set; } // defaults to AppInfo.PackageName
    public string? WindowsProductId { get; set; }   // required on Windows
    public string CountryCode { get; set; } = "us";
}

Lookup behaviour

Platform	API	Fields populated
iOS / macCatalyst	iTunes Search API (itunes.apple.com/lookup?bundleId=…)	All fields — version, release notes, ratings, release date, min OS. Auto-caches trackId back into AppleAppId for subsequent deep links
Android	Play Store HTML scrape (play.google.com/store/apps/details?id=…) with two GeneratedRegex strategies (JSON-LD softwareVersion and legacy [[["x.y.z"]]] AF_initDataCallback)	Version + NeedsUpdate only — Play HTML doesn't reliably expose other fields
Windows	Microsoft Store DisplayCatalog (displaycatalog.mp.microsoft.com/v7.0/products?bigIds=…)	Version, release notes (from ProductDescription), ReleasedAt where available
Other TFMs	Not supported	Returns null

Deep links

Platform	OpenStore	OpenReviewPage
iOS / macCatalyst	itms-apps://itunes.apple.com/app/id{AppleAppId}	itms-apps://…/app/id{AppleAppId}?action=write-review
Android	market://details?id={packageName}	Same as OpenStore (Play Store has no separate review URL)
Windows	ms-windows-store://pdp/?ProductId={WindowsProductId}	ms-windows-store://review/?ProductId={WindowsProductId}

Usage

public class UpdateChecker(IAppStore store)
{
    public async Task CheckForUpdates(CancellationToken ct = default)
    {
        var result = await store.GetCurrent(ct);
        if (result?.NeedsUpdate == true)
        {
            // result.StoreVersion, result.CurrentVersion, result.ReleaseNotes
            await store.OpenStore();
        }
    }

    public Task PromptForReview() => store.OpenReviewPage();
}

:::caution Android version detection relies on scraping the Play Store HTML. Google changes the page structure periodically — if GetCurrent returns null on Android even when the app exists, the regex likely needs updating. :::

Platform Lifecycle Hooks

Platform lifecycle is wired by UseShiny() in Shiny.Hosting.Maui — register handlers against the per-platform interfaces in Shiny.Core (IIosLifecycle.*, IMacLifecycle.*, IAndroidLifecycle.*). This library does not duplicate that surface.

API Summary

public static class MauiHostingExtensions
{
    public static MauiAppBuilder AddInfrastructureModules(this MauiAppBuilder builder, params IEnumerable<IMauiModule> modules);
    public static MauiAppBuilder AddAppSupport(this MauiAppBuilder builder);
    public static MauiAppBuilder AddAppStore(this MauiAppBuilder builder, Action<AppStoreOptions>? configure = null);
    public static MauiAppBuilder AddAppStore(this MauiAppBuilder builder, string? appleAppId = null, string? androidPackageName = null, string? windowsProductId = null, string? countryCode = null);
}

public class Host : IMauiInitializeService
{
    public static IServiceProvider Services { get; }
}

Code Generation Instructions

• One module per concern (similar to web modules)
• Keep Add() for service registration and Use() for post-build initialization
• Do NOT block in Use() — it runs on the main thread during app startup
• Use Host.Services to resolve services after the app is built
• Register platform lifecycle handlers against IIosLifecycle.* / IAndroidLifecycle.* / IMacLifecycle.* (Shiny.Core); UseShiny() dispatches them
• For each capability the app needs (AppSupport, AppStore), call the matching Add* extension — they don't auto-register
• For IAppStore on Windows, always configure WindowsProductId — there's no auto-detect (the package family name from AppInfo is a different concept than the Store ProductId)

Best Practices

1. One concern per module — separate modules for analytics, networking, auth, etc.
2. Never block in Use() — if you need async work, use Task.Run or similar
3. Use Host.Services sparingly — prefer constructor injection; use Host.Services only where DI is unavailable
4. Register lifecycle handlers via DI — use [Singleton] attributes on platform lifecycle handler classes (Shiny.Core's IIosLifecycle.* / IAndroidLifecycle.* / IMacLifecycle.*)
5. Detach event handlers — IAppSupport's native listeners auto-stop when the last subscriber detaches, so always unsubscribe on dispose/teardown to free the OS listener
6. Cache AppStoreResult — store lookups are network calls; don't call GetCurrent on every navigation