110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# 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 |