# App Class Documentation

## Overview

The `App` class is the main entry point for the **FrymasterBadgeApp** .NET MAUI application. It inherits from `Microsoft.Maui.Controls.Application` and is responsible for:

- Initializing the application components
- Applying the user's saved theme preference
- Setting up dependency injection
- Creating the main application window with robust error handling

## Namespace

```csharp
namespace FrymasterBadgeApp;
```

## Class Definition

```csharp
public partial class App : Application
```

## Fields

| Field            | Type              | Description |
|------------------|-------------------|-----------|
| `_serviceProvider` | `IServiceProvider` | Holds the dependency injection container used to resolve services like `AppShell`. |
| `ThemePrefKey`   | `const string`    | Constant key used to store and retrieve the app theme preference. Must match the key used in `SettingsPage`. |

## Constructor

```csharp
public App(IServiceProvider serviceProvider)
```

### Purpose
Initializes the application, applies the saved theme, and stores the service provider for later use.

### Behavior
1. Logs the start of constructor execution.
2. Calls `InitializeComponent()` to load XAML-defined UI elements.
3. Applies the saved user theme preference via `ApplySavedTheme()`.
4. Stores the injected `IServiceProvider`.
5. Catches and logs any fatal XAML initialization errors.

## Methods

### ApplySavedTheme()

```csharp
private void ApplySavedTheme()
```

**Summary**:  
Applies the user's previously saved theme preference (Light, Dark, or System) to the application.

**Behavior**:
- Retrieves the theme preference from `Preferences.Default` using the key `"AppTheme"`.
- Defaults to `"System"` if no preference is found.
- Maps the string preference to the corresponding `AppTheme` enum value.
- Sets `Application.Current.UserAppTheme`.
- Logs the applied theme or any failure (as a warning).

### CreateWindow(IActivationState? activationState)

```csharp
protected override Window CreateWindow(IActivationState? activationState)
```

**Summary**:  
Overrides the default window creation to provide proper dependency injection support and robust error handling.

**Behavior**:
- Logs entry into the method.
- Resolves `AppShell` using the injected `IServiceProvider`.
- Returns a new `Window` containing the resolved `AppShell`.
- If dependency resolution fails (e.g., missing service registration), a user-friendly error page is displayed instead of crashing the app.
- The fallback error page shows:
  - "Startup Failed" title
  - The exception message in red
  - A note to check the log for details

## Key Features

- **Theme Persistence**: Automatically restores the user's last chosen theme on startup.
- **Dependency Injection Ready**: Uses `IServiceProvider` to resolve the main `AppShell`.
- **Graceful Error Handling**: Critical startup failures are caught and presented in a clean error screen rather than a hard crash.
- **Comprehensive Logging**: Uses `AppLogger` for all major initialization steps and errors.

## Dependencies

- `Microsoft.Maui.Controls.Application`
- `Microsoft.Maui.Storage.Preferences`
- `IServiceProvider` (from Microsoft.Extensions.DependencyInjection)
- `AppShell`
- `AppLogger` (custom logging service)

## Related Files

- `SettingsPage.xaml.cs` — Uses the same `ThemePrefKey` constant
- `AppShell.xaml` — Main navigation shell resolved in `CreateWindow`
- `MauiProgram.cs` — Where services are registered and `App` is configured

## Best Practices Implemented

- Separation of theme logic into a dedicated method
- Defensive programming with try-catch blocks around critical startup operations
- Meaningful logging at each stage of initialization
- Fallback UI for startup failures to improve user experience