Shaunebu.Analytics.AppInsights 1.0.3

Shaunebu.Analytics.AppInsights 📗

A lightweight, cross-platform application lifecycle manager for .NET MAUI. This library provides foreground/background lifecycle events across Android, iOS, and Windows, allowing developers to react to app state changes in a consistent way. It abstracts platform differences and exposes a simple event-driven API.

Features

• Singleton-based AppInsights telemetry manager for MAUI + .NET Standard.

• Tracks custom events, page views, and exceptions.

• Supports offline buffering and batch flushing.

• Automatically enriches telemetry with platform, OS, app version, session, and user info.

• Lifecycle-aware: automatically flushes on app resume or sleep.

• Global default properties for all telemetry.

• Fully compatible with Microsoft.ApplicationInsights TelemetryClient.

• Optional debug mode for local logging.

Installation

Install via NuGet:

Install-Package Shaunebu.Analytics.AppInsights

Add namespace references in your project:

using Shaunebu.Analytics.AppInsights;

Initialization

// Initialize AppInsightsManager in App.xaml.cs
AppInsightsManager.Current.Initialize(
    connectionString: "<YOUR-CONNECTION-STRING>",
    debugMode: true,           // Optional: enables debug logging
    batchIntervalSeconds: 30   // Optional: flush interval in seconds
);

Optional: provide a custom TelemetryClient:

var customClient = new TelemetryClient(new TelemetryConfiguration("<YOUR-CONNECTION-STRING>"));
AppInsightsManager.Current.Initialize("<YOUR-CONNECTION-STRING>", customClient: customClient);

Usage

Track Custom Event

AppInsightsManager.Current.TrackEvent(
    "ButtonClicked",
    new Dictionary<string, string>
    {
        { "ButtonName", "Login" }
    },
    metric: 1
);

Track Page View

AppInsightsManager.Current.TrackPageView("MainPage");

Track Exception

try
{
    // Some code that throws
}
catch (Exception ex)
{
    AppInsightsManager.Current.TrackException(ex, new Dictionary<string, string>
    {
        { "Context", "LoginButtonClicked" }
    });
}

Add Global Properties

AppInsightsManager.Current.AddGlobalProperty("AppFlavor", "Beta");

Flush Telemetry Immediately

await AppInsightsManager.Current.FlushAsync();

Properties

Methods

Example: Full App.xaml.cs

public partial class App : Application
{
    public App()
    {
        InitializeComponent();

        // Initialize AppInsights
        AppInsightsManager.Current.Logger = new ConsoleLogger();
        AppInsightsManager.Current.Initialize("<YOUR-CONNECTION-STRING>", debugMode: true);

        // Track app start
        AppInsightsManager.Current.TrackEvent("App_Started");
    }
}

Logger Interface

Implement your own logger if needed:

public class ConsoleLogger : AppInsightsManager.IAppLogger
{
    public void Info(string message) => Console.WriteLine("[INFO] " + message);
    public void Warn(string message) => Console.WriteLine("[WARN] " + message);
    public void Error(string message, Exception? ex = null)
    {
        Console.WriteLine("[ERROR] " + message + (ex != null ? " " + ex.Message : ""));
    }
}

Lifecycle & Platform Awareness

• Hooks into Application.Current.Resumed and Application.Current.Slept to automatically flush telemetry.

• Automatically enriches all telemetry with:

  • Platform (Android/iOS/Windows)

  • OSVersion

  • AppVersion

  • AppBuild

  • SessionId

  • UserId

Notes & Best Practices

• Enable DebugMode for development to log telemetry locally.

• AddGlobalProperty for app-wide telemetry metadata.

• FlushAsync should be called during app shutdown if needed.

• Works with .NET MAUI and .NET Standard 2.1+ libraries.