Oakrey.Applications.AppCenterAnalyticTools 7.0.0

Oakrey.Applications.AppCenterAnalyticTools

A .NET library for integrating Microsoft App Center analytics and crash reporting into WPF applications. Tracks custom events with metadata, detects previous-session crashes, and uploads log files to Azure Blob Storage. Designed for DI-based applications built on Oakrey.Applications.Base.

Main features

• Event tracking � AnalyticaService wraps Analytics.TrackEvent and supports arbitrary string property dictionaries.
• Crash detection and log upload � CrashService checks Crashes.HasCrashedInLastSessionAsync() and uploads the newest log file to Azure Blob Storage synchronously or asynchronously.
• Azure Blob Storage upload � CrashLogSender creates the target container if it does not exist, then uploads the log file using BlobClient. Both fire-and-forget and await-able paths are provided.
• Preloading support � both AnalyticaService and CrashService implement IPreLoadable and integrate with OakreyApplication.TryPreloadServices.
• Debugger guard � all App Center calls are skipped when a debugger is attached, preventing noise during development.
• Oakrey logging and telemetry � every operation is traced with ITracing and logged with ILogger from Oakrey.Log / Oakrey.Telemetry.

Architecture

classDiagram
    class IAnalyticaService {
        +TrackEvent(eventName, properties)
    }

    class ICrashService {
        +SendCrashLog()
        +SendCrashLogAsync() Task
    }

    class ICrashLogSender {
        +Upload(fileName, path)
        +UploadAsync(fileName, path) Task
    }

    class ICrashServiceDataSource {
        +AppSecret : string
        +InstallId : Guid
        +LogDirectory : DirectoryInfo
        +MetaData : Dictionary~string,string~
        +ReportersName : string
    }

    class ICrashLogSenderSettings {
        +ConnectionString : string
        +ContainerReference : string
    }

    class AnalyticaService {
        +Preload(CancellationToken) Task
        +TrackEvent(eventName, properties)
    }

    class CrashService {
        +Preload(CancellationToken) Task
        +SendCrashLog()
        +SendCrashLogAsync() Task
    }

    class CrashLogSender {
        +Upload(fileName, path)
        +UploadAsync(fileName, path) Task
    }

    AnalyticaService ..|> IAnalyticaService
    AnalyticaService ..|> IPreLoadable
    AnalyticaService --> ICrashServiceDataSource : reads

    CrashService ..|> ICrashService
    CrashService ..|> IPreLoadable
    CrashService --> ICrashServiceDataSource : reads
    CrashService --> ICrashLogSender : uses

    CrashLogSender ..|> ICrashLogSender
    CrashLogSender --> ICrashLogSenderSettings : reads

Requirements

• .NET 10 or higher
• Windows (WPF target: net10.0-windows)
• Microsoft App Center account with an app secret
• Azure Storage account with a Blob container connection string

Installation

NuGet Package Manager

1. Open Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
2. Search for Oakrey.Applications.AppCenterAnalyticTools and click Install.

.NET CLI

dotnet add package Oakrey.Applications.AppCenterAnalyticTools

Package Manager Console

Install-Package Oakrey.Applications.AppCenterAnalyticTools

Configuration

ICrashServiceDataSource

Implement this interface and register it with DI to provide App Center credentials and session metadata.

public class MyAppDataSource : ICrashServiceDataSource
{
    public string AppSecret => "your-appcenter-app-secret";
    public Guid InstallId => GetOrCreateInstallId();
    public DirectoryInfo LogDirectory => new(Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
        "MyApp", "Logs"));
    public Dictionary<string, string> MetaData => new()
    {
        ["Version"] = "1.0.0",
        ["Environment"] = "Production"
    };
    public string ReportersName => Environment.UserName;
}

ICrashLogSenderSettings

Implement this interface to provide the Azure Blob Storage connection string and container name.

public class MyBlobSettings : ICrashLogSenderSettings
{
    public string ConnectionString => "DefaultEndpointsProtocol=https;AccountName=...";
    public string ContainerReference => "crash-logs";
}

Usage

1. Register services

services.AddSingleton<ICrashServiceDataSource, MyAppDataSource>();
services.AddSingleton<ICrashLogSenderSettings, MyBlobSettings>();
services.AddSingleton<ICrashLogSender, CrashLogSender>();
services.AddSingleton<ICrashService, CrashService>();
services.AddSingleton<IAnalyticaService, AnalyticaService>();

2. Preload during application startup

Both services implement IPreLoadable. Pass them to TryPreloadServices inside your OakreyApplication subclass:

protected override async Task AppStartup(CancellationToken cancellationToken)
{
    await TryPreloadServices(cancellationToken, typeof(ICrashService), typeof(IAnalyticaService));
    // continue with main window setup
}

During preload, CrashService starts App Center Crashes and AnalyticaService starts App Center Analytics, both firing a login event with the configured metadata.

3. Track custom events

IAnalyticaService analytics = GetService<IAnalyticaService>();
analytics.TrackEvent("ButtonClicked", new Dictionary<string, string>
{
    ["Screen"] = "MainWindow",
    ["Action"] = "Export"
});

4. Upload crash logs after a previous crash

Call this after preloading, typically from the splash screen or startup flow:

ICrashService crashService = GetService<ICrashService>();
await crashService.SendCrashLogAsync();

The service checks whether the application crashed in its last session. If it did, it finds the newest log file in ICrashServiceDataSource.LogDirectory and uploads it to the configured Blob container. The blob is named using the pattern <InstallId> [<ReportersName>] <filename>.

Development notes

• All App Center API calls are guarded by !Debugger.IsAttached. No events or crash logs are sent during a debug session.
• CrashLogSender.Upload is a fire-and-forget wrapper; use UploadAsync when you need to await the result.
• CrashLogSender calls CreateIfNotExistsAsync on the container and sets its access policy to PublicAccessType.Blob if the container was just created. Ensure the storage account allows this if your policy requires private containers.
• AnalyticaService.Preload throws InvalidOperationException on failure (propagated to the preloading error handler). CrashService.Preload publishes failures as PreLoadingException through its observable instead of throwing.

License

MIT. Copyright (c) Oakrey 2016-present.

Repository: https://dev.azure.com/oakrey/OpenPackages/_git/ApplicationServices

.NET CLI

Run the following command in your terminal:

dotnet add package Oakrey.Applications.AppCenterAnalyticTools

Package Manager Console

Run the following command in your Package Manager Console:

Install-Package Oakrey.Applications.AppCenterAnalyticTools

Requirements

• .NET 8 or higher

Project Information

• Author: Oakrey
• Company: Oakrey
• License: MIT
• Repository: Git Repository
• Project URL: Project Website

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve the package.

License

This project is licensed under the MIT License. See the LICENSE file for details.