Shiny .NET Framework

Shiny is a cross-platform framework designed to simplify working with device services and background processes. It provides a structured way to implement dependency injection, logging, and platform-specific features while handling complex tasks like permissions, main thread traversal, persistent storage, and app restarts.

Shiny is designed to be Native AOT and trim-friendly. It supports a wide range of platforms including iOS, Android, Mac Catalyst, macOS, Windows, Linux, and Blazor WebAssembly (where platform capabilities allow).

When communicating with your backend server, it is important to distinguish between the two types of tokens available on IPushManager:

• RegistrationToken: The provider-level token (e.g., the Azure Notification Hubs InstallationId). Use this for your backend.
• NativeRegistrationToken: The raw OS-level token (e.g., the FCM token on Android or the APNs device token on iOS).

The behavior of ICalendarStore varies significantly depending on the underlying operating system:

• Apple (EventKit):
  • Attendees cannot be written: Any Attendees set during creation or updates are ignored.
  • Reminders use a relative lead-time.
• Android (CalendarContract):
  • Event CRUD works with permissions.
  • Creating or modifying calendars uses sync-adapter semantics and may behave differently depending on the device manufacturer (OEM).
• Windows (AppointmentStore):
  • Best-effort support: Reads and queries cover all calendars.
  • Write restrictions: Create, update, and delete operations only work within an app-owned calendar. Attempting to write to a system calendar will throw a NotSupportedException.
  • Requires the appointments capability.

The IBleHostingManager is the primary service for BLE peripheral hosting, typically injected via Dependency Injection as a singleton. It manages advertising, GATT server services, and L2CAP channels.

Key workflows include:

1. Requesting Access: Use RequestAccess(bool advertise, bool connect) to ensure the app has permissions for advertising and GATT connections.
2. Advertising: Use StartAdvertising(AdvertisementOptions?) to begin broadcasting or AdvertiseBeacon(...) to act as an iBeacon.
3. GATT Server Management: Use AddService(...) to define services and their characteristics, or AttachRegisteredServices() to attach services configured via DI.

The API uses Shiny.DocumentDb.Sqlite for persistence. The following files and structures are used:

• app.db: The SQLite document store containing three tables: todos, sync_changes, and files.
• uploads/{id}: A directory containing the raw bytes for each uploaded file. The metadata for these files is stored in the files table.

To completely reset the application state, delete both the app.db file and the uploads/ directory.

Shiny.Jobs behaves differently depending on the target platform:

• iOS & Android: Uses native OS schedulers (BGTaskScheduler on iOS and AndroidX WorkManager on Android).
• Windows: Uses COM-activated in-process background tasks.
• Plain .NET (Linux, macOS, Console, Blazor WASM): Runs an in-process managed JobManager driven by a recurring timer (default 30s, configurable via JobManager.Interval between 15s and 5 minutes). Jobs only run while the host process is alive.

Blazor WASM Warning: Background jobs only run while the browser tab is open and foregrounded. Service Workers cannot invoke C# jobs because they lack access to the Blazor WASM runtime. For true background HTTP work in Blazor, use Shiny.Net.Http.Blazor.

Use ConnectionConfig to manage connection behavior.

• On Android, setting AutoConnect to false can speed up the initial connection at the cost of disabling auto-reconnect.
• On iOS, AutoConnect controls whether the system reconnects automatically.

AndroidConnectionConfig adds ConnectionPriority (e.g., GattConnectionPriority.Balanced) for Android devices.

// Android: false disables auto-reconnect but speeds up initial connection
// iOS: controls whether to reconnect automatically
public record ConnectionConfig(bool AutoConnect = true);

public record AndroidConnectionConfig(
    bool AutoConnect = true,
    GattConnectionPriority ConnectionPriority = GattConnectionPriority.Balanced
) : ConnectionConfig(AutoConnect);

The PushAccessState record describes the current status of push notification permissions and provides the registration token.

AccessState Values

• Available: Permission granted and ready.
• Denied: Permission explicitly denied.
• Restricted: Permission restricted by OS settings.
• Disabled: Push is disabled.
• NotSetup: Push is not configured.
• NotSupported: Platform does not support push.
• Unknown: State is unknown.

Usage

You can call PushAccessState.Assert() to throw a PermissionException if the status is not Available.

public record PushAccessState(
    AccessState Status,
    string? RegistrationToken
)
{
    public static PushAccessState Denied { get; }
    public void Assert(); // Throws PermissionException if Status != Available
}

Shiny provides source-generated dependency injection via Shiny.Extensions.DependencyInjection. Instead of manual registration, decorate your classes with attributes. The source generator will then pick them up when you call AddGeneratedServices() during host construction.

Supported attributes:

• [Service(ServiceLifetime.Singleton)] (or the shortcut [Singleton])
• [Scoped]
• [Transient]

This approach supports multiple interfaces, keyed services, and open generics automatically.

Use GpsRequest to define how the GPS listener should behave, specifically regarding background execution.

GpsBackgroundMode options:

• None: No background mode.
• Standard:
  • iOS: Significant Location Changes.
  • Android: BACKGROUND mode (receives 3-4 updates per hour).
• Realtime:
  • iOS: Full background request (updates every 1 second).
  • Android: Foreground Service (updates every 1 second).

Factory Methods:

• GpsRequest.Foreground: Creates a request with GpsBackgroundMode.None and RequestPreciseAccuracy = false.
• GpsRequest.Background: Creates a request with GpsBackgroundMode.None and RequestPreciseAccuracy = false.
• GpsRequest.Realtime(bool requestPreciseAccuracy): Creates a request with GpsBackgroundMode.Realtime.