Beacon .NET SDK

The Beacon .NET SDK provides native integration for desktop (WPF, WinForms, MAUI), server (ASP.NET Core, Windows Services), and console applications.

Installation

Install via NuGet:

dotnet add package SoftAgility.Beacon

Or via the Package Manager Console:

Install-Package SoftAgility.Beacon

System Requirements

  • .NET 8.0 or later
  • Windows, Linux, or macOS
  • No additional dependencies

Configuration

ASP.NET Core / Host Builder

Register Beacon with dependency injection to resolve IBeaconTracker:

services.AddBeacon(options =>
{
    options.ApiKey = "your-api-key";
    options.ApiBaseUrl = "https://api.beacon.softagility.com";
    options.AppName = "MyApp";
    options.AppVersion = "1.2.0";
});

Manual Initialization

For applications without dependency injection, use the static Configure method. This creates a singleton BeaconTracker instance:

var tracker = BeaconTracker.Configure(options =>
{
    options.ApiKey = "your-api-key";
    options.ApiBaseUrl = "https://api.beacon.softagility.com";
    options.AppName = "MyApp";
    options.AppVersion = "1.2.0";
});

Configuration Options

OptionTypeDefaultDescription
ApiKeystring—Your Beacon API key (required)
ApiBaseUrlstring—Beacon API base URL (required)
AppNamestring—Your application name, max 128 chars (required)
AppVersionstring—Your application version, max 256 chars (required)
EnabledbooltrueEnable or disable tracking globally
FlushIntervalSecondsint60How often to send batched events (1-3600)
MaxBatchSizeint25Events per batch, clamped to 1-1000
MaxQueueSizeMbint10Maximum offline queue size in MB (1-1000)
MaxBreadcrumbsint25Breadcrumb ring buffer size (0-200)
EventsEventDefinitionBuilder—Builder for registering known events
LoggerILogger?nullOptional logger for SDK diagnostics

Identifying Users

Before tracking events or sessions, identify the current actor (user or device):

tracker.Identify("user-123");

Actor IDs can be up to 512 characters. Once identified, all subsequent Track, StartSession, and TrackException calls use this actor. You can also pass an explicit actor ID to any tracking method.

Tracking Events

Events are organized by category and name, with optional properties.

Basic Event

tracker.Track("ui", "button_clicked", new
{
    button_name = "export",
    screen = "dashboard"
});

With Explicit Actor

tracker.Track("reports", "report_exported", "user-456", new
{
    format = "pdf",
    row_count = 1500
});

Event Limits

  • Category: max 128 characters
  • Name: max 256 characters
  • Actor ID: max 512 characters

Session Management

Sessions group related events and track duration.

// Start a session (uses the identified actor)
tracker.StartSession();

// Or start with an explicit actor ID
tracker.StartSession("user-123");

// End the current session
tracker.EndSession();

Exception Tracking

Track handled or unhandled exceptions with full stack traces. Beacon automatically fingerprints exceptions by type and stack trace for grouping.

try
{
    ProcessOrder(order);
}
catch (Exception ex)
{
    tracker.TrackException(ex, ExceptionSeverity.NonFatal);
    throw;
}

Severity options are ExceptionSeverity.Fatal and ExceptionSeverity.NonFatal. Recent tracking calls are automatically attached as breadcrumbs to provide context.

The SDK maintains a circular ring buffer of recent Track calls. When an exception is reported, these breadcrumbs are attached automatically, giving you a timeline of what happened before the error.

Configure the buffer size with MaxBreadcrumbs (default 25, max 200). Set to 0 to disable.

Flushing Events

Events are batched and sent on a timer (FlushIntervalSeconds) or when the batch reaches MaxBatchSize. To flush manually:

await tracker.FlushAsync();

Check the last flush result:

FlushStatus status = tracker.LastFlushStatus;

Offline Persistence

The SDK queues events in a local SQLite database at %LOCALAPPDATA%\SoftAgility\Beacon\{AppName}\queue.db. Events persist across application restarts and sync automatically when connectivity returns.

  • FIFO queue with configurable maximum size (MaxQueueSizeMb)
  • No data is lost during transient network failures
  • Background timer handles automatic flushing

Event Manifest

Export a JSON manifest of your registered events for import into the Beacon portal's allowlist page:

tracker.ExportEventManifest("events.json");

Thread Safety

BeaconTracker is fully thread-safe. A single instance can be shared across your application and called from any thread.

Disposal

BeaconTracker implements both IDisposable and IAsyncDisposable. Dispose when your application shuts down to flush pending events:

tracker.Dispose();
// or
await tracker.DisposeAsync();

WPF Example

public partial class App : Application
{
    private IBeaconTracker _tracker;

    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);

        _tracker = BeaconTracker.Configure(options =>
        {
            options.ApiKey = "your-api-key";
            options.ApiBaseUrl = "https://api.beacon.softagility.com";
            options.AppName = "MyDesktopApp";
            options.AppVersion = "2.1.0";
        });

        _tracker.Identify("device-" + Environment.MachineName);
        _tracker.StartSession();
    }

    protected override void OnExit(ExitEventArgs e)
    {
        _tracker.EndSession();
        _tracker.Dispose();
        base.OnExit(e);
    }
}

Next Steps

Getting StartedC++ SDK

All Documentation