ironservices
/
ironservices-maui
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ironservices-maui/README.md

363 lines
10 KiB
Markdown
Raw Blame History

# IronServices.Maui
MAUI controls and services for IronServices (IronLicensing, IronNotify, IronTelemetry).
## Installation
```xml
<PackageReference Include="IronServices.Maui" Version="1.0.0" />
```
## Quick Start
### 1. Register Services
```csharp
// MauiProgram.cs
builder.Services.AddIronServices();
// Or with custom URLs
builder.Services.AddIronServices(options =>
{
options.LicensingUrl = "https://ironlicensing.com";
options.NotifyUrl = "https://ironnotify.com";
options.TelemetryUrl = "https://irontelemetry.com";
});
```
### 2. Use Controls
```xaml
<ContentPage xmlns:iron="clr-namespace:IronServices.Maui.Controls;assembly=IronServices.Maui">
<iron:LoginView Client="{Binding IronClient}" LoginSuccess="OnLoginSuccess" />
</ContentPage>
```
---
## Controls
### LoginView
A drop-in login form for IronServices authentication.
**Type:** `ContentView` (embeddable)
#### Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Client` | `IronServicesClient` | `null` | **Required.** The client instance for authentication. |
| `Title` | `string` | `"Sign In"` | Header text above the form. |
| `Subtitle` | `string` | `"Enter your credentials..."` | Subheader text. |
| `Logo` | `ImageSource` | `null` | Optional logo image. |
| `ShowRegisterLink` | `bool` | `true` | Show "Sign Up" link. |
| `ShowForgotPasswordLink` | `bool` | `true` | Show "Forgot Password?" link. |
#### Events
| Event | Args | Description |
|-------|------|-------------|
| `LoginSuccess` | `LoginSuccessEventArgs` | Fired on successful login. Contains `UserId`, `Email`, `DisplayName`. |
| `LoginFailed` | `LoginFailedEventArgs` | Fired on failed login. Contains `Error` message. |
| `RegisterRequested` | `EventArgs` | User tapped "Sign Up" link. |
| `ForgotPasswordRequested` | `EventArgs` | User tapped "Forgot Password?" link. |
#### Example
```csharp
// XAML
<iron:LoginView x:Name="LoginView"
Client="{Binding IronClient}"
Title="Welcome Back"
Logo="logo.png"
ShowRegisterLink="True"
LoginSuccess="OnLoginSuccess"
RegisterRequested="OnRegisterRequested" />
// Code-behind
private async void OnLoginSuccess(object sender, LoginSuccessEventArgs e)
{
await DisplayAlert("Success", $"Welcome, {e.DisplayName}!", "OK");
await Shell.Current.GoToAsync("//main");
}
private async void OnRegisterRequested(object sender, EventArgs e)
{
await Shell.Current.GoToAsync("//register");
}
```
---
### LicenseActivationView
A license key entry and activation form.
**Type:** `ContentView` (embeddable)
#### Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `LicenseManager` | `ILicenseManager` | `null` | **Required.** The license manager instance. |
| `Title` | `string` | `"Activate License"` | Header text. |
| `Subtitle` | `string` | `"Enter your license key..."` | Subheader text. |
| `LicenseKey` | `string` | `null` | Pre-filled license key (two-way binding). |
| `ShowHelpLink` | `bool` | `true` | Show help link below form. |
| `HelpUrl` | `string` | `"https://..."` | URL opened when help tapped. |
#### Events
| Event | Args | Description |
|-------|------|-------------|
| `LicenseActivated` | `LicenseActivatedEventArgs` | Activation succeeded. Contains `License` info. |
| `ActivationFailed` | `LicenseActivationFailedEventArgs` | Activation failed. Contains `Error` message. |
| `HelpRequested` | `EventArgs` | User tapped help link. |
#### Methods
| Method | Returns | Description |
|--------|---------|-------------|
| `ValidateAsync()` | `Task<bool>` | Validate the entered license key without activating. |
#### Example
```csharp
// XAML
<iron:LicenseActivationView x:Name="ActivationView"
LicenseManager="{Binding LicenseManager}"
LicenseActivated="OnLicenseActivated" />
// Code-behind
private async void OnLicenseActivated(object sender, LicenseActivatedEventArgs e)
{
var license = e.License;
await DisplayAlert("Activated",
$"License: {license.Tier}\nExpires: {license.ExpiresAt:d}", "OK");
}
```
---
### AppLogView
A full-page log viewer for exceptions and telemetry events. Shows queued items from `TelemetryClient.OfflineQueue`.
**Type:** `ContentPage` (standalone page, use with NavigationPage)
#### Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `TelemetryClient` | `TelemetryClient` | `null` | Client to pull queued logs from. Auto-refreshes on set. |
| `Title` | `string` | `"App Logs"` | Page title (shown in navigation bar). |
| `ShowShareButton` | `bool` | `true` | Enable Share toolbar button. |
| `ShowClearButton` | `bool` | `true` | Enable Clear toolbar button. |
#### Events
| Event | Args | Description |
|-------|------|-------------|
| `LogsCleared` | `EventArgs` | User cleared the log list. |
| `LogsShared` | `EventArgs` | User shared the logs. |
| `LogSelected` | `LogItem` | User selected a log entry. |
| `LogsRefreshed` | `EventArgs` | Log list was refreshed. |
#### Methods
| Method | Returns | Description |
|--------|---------|-------------|
| `RefreshLogs()` | `void` | Reload logs from TelemetryClient queue. |
| `AddLog(type, title, message, stackTrace?)` | `void` | Add a manual log entry. |
| `AddException(Exception)` | `void` | Add an exception as a log entry. |
| `ClearLogs()` | `void` | Clear displayed logs (not the queue). |
| `ClearAllLogs()` | `void` | Clear displayed logs AND the offline queue. |
| `ExportLogs()` | `string` | Export all logs as formatted text. |
| `GetLogs()` | `IReadOnlyList<LogItem>` | Get current log items. |
| `LogCount` | `int` | Number of log items. |
#### LogItem Properties
| Property | Type | Description |
|----------|------|-------------|
| `Timestamp` | `DateTime` | UTC timestamp. |
| `Type` | `string` | `"exception"`, `"message"`, `"info"`, `"warning"`, etc. |
| `Title` | `string` | Exception type name or message title. |
| `Message` | `string` | Log message. |
| `StackTrace` | `string?` | Stack trace for exceptions. |
| `JourneyId` | `string?` | Associated user journey ID. |
| `UserId` | `string?` | Associated user ID. |
#### Example
```csharp
// Navigate to log view
await Navigation.PushAsync(new AppLogView
{
TelemetryClient = _telemetryClient,
Title = "Error Logs"
});
// With event handling
var logView = new AppLogView { TelemetryClient = _telemetryClient };
logView.LogsCleared += (s, e) => Debug.WriteLine("Logs cleared");
logView.LogSelected += (s, item) => Debug.WriteLine($"Selected: {item.Title}");
await Navigation.PushAsync(logView);
// Manual log entries (without TelemetryClient)
var logView = new AppLogView();
logView.AddException(ex);
logView.AddLog("warning", "Network Issue", "Connection timeout after 30s");
```
#### Toolbar
- **Share** (Primary): Exports logs as text and opens system share sheet.
- **Clear** (Secondary/overflow menu): Clears displayed logs.
- **Refresh** button in summary bar: Reloads from queue.
---
## Services
### MauiSecureTokenStorage
Secure token storage using MAUI `SecureStorage`. Automatically registered when using `AddIronServices()`.
```csharp
// Automatically used by IronServicesClient
builder.Services.AddIronServices();
// Or manually
services.AddSingleton<ITokenStorage, MauiSecureTokenStorage>();
```
### ServiceCollectionExtensions
```csharp
// Default URLs
services.AddIronServices();
// Custom URLs
services.AddIronServices(options =>
{
options.LicensingUrl = "https://licensing.myapp.com";
options.NotifyUrl = "https://notify.myapp.com";
options.TelemetryUrl = "https://telemetry.myapp.com";
});
```
Registers:
- `MauiSecureTokenStorage` as `ITokenStorage`
- `IronServicesClient` as singleton
---
## Complete Example
```csharp
// MauiProgram.cs
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder.UseMauiApp<App>();
// Register IronServices
builder.Services.AddIronServices();
// Register TelemetryClient for logging
builder.Services.AddSingleton(sp => new TelemetryClient(new TelemetryOptions
{
Dsn = "your-dsn-here",
EnableOfflineQueue = true
}));
return builder.Build();
}
// LoginPage.xaml
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:iron="clr-namespace:IronServices.Maui.Controls;assembly=IronServices.Maui">
<ScrollView>
<iron:LoginView x:Name="LoginControl"
Client="{Binding IronClient}"
Logo="app_logo.png"
Title="Welcome"
LoginSuccess="OnLoginSuccess" />
</ScrollView>
</ContentPage>
// LoginPage.xaml.cs
public partial class LoginPage : ContentPage
{
public LoginPage(IronServicesClient client)
{
InitializeComponent();
LoginControl.Client = client;
}
private async void OnLoginSuccess(object sender, LoginSuccessEventArgs e)
{
await Shell.Current.GoToAsync("//main");
}
}
// SettingsPage.xaml.cs - Navigate to logs
private async void OnViewLogsClicked(object sender, EventArgs e)
{
var telemetry = Handler.MauiContext.Services.GetService<TelemetryClient>();
await Navigation.PushAsync(new AppLogView
{
TelemetryClient = telemetry
});
}
```
---
## Styling
All controls use MAUI resource dictionaries. Override these colors in your `App.xaml`:
```xaml
<Color x:Key="Primary">#512BD4</Color>
<Color x:Key="Secondary">#DFD8F7</Color>
<Color x:Key="Gray100">#E1E1E1</Color>
<Color x:Key="Gray200">#C8C8C8</Color>
<Color x:Key="Gray400">#919191</Color>
<Color x:Key="Gray500">#6E6E6E</Color>
<Color x:Key="Gray600">#404040</Color>
<Color x:Key="Gray900">#212121</Color>
<Color x:Key="White">#FFFFFF</Color>
```
Controls support light/dark themes via `AppThemeBinding`.
---
## Platform Support
| Platform | Minimum Version |
|----------|-----------------|
| Android | API 21 (5.0) |
| iOS | 14.0 |
| macOS | 11.0 |
| Windows | 10.0.17763.0 |
---
## Dependencies
- `IronServices.Client` - Core API client
- `IronLicensing.Client` - License validation
- `IronTelemetry.Client` - Telemetry and logging
- `Microsoft.Maui.Controls` - MAUI framework
---
## License
Proprietary. See LICENSE file.
Reference in New Issue View Git Blame Copy Permalink