.NET Setup Packages

Choose between Ansight.Core, the Ansight all-in-one package, and the Ansight.Maui package, then initialize the runtime with the matching builder API.

Ansight has two recommended all-in-one setup paths and one lower-level package path.

Package Model

The NuGet badges link to each package and show the current prerelease version from NuGet.

Package	NuGet	Use when	Includes
`Ansight`		You want the standard non-MAUI app setup.	`Ansight.Core`, native pairing where supported, all non-MAUI remote tool packages, and the `WithAnsightSdk(...)` setup API.
`Ansight.Maui`		You are integrating a .NET MAUI app.	`Ansight`, `Ansight.Tools.Maui`, and `MauiAppBuilder` setup helpers.
`Ansight.Core`		You want direct control over every runtime and tool registration call.	Core runtime, telemetry, pairing protocol, tool abstractions, host connection, JPEG capture, and build-time safety targets.
`Ansight.Tools.*`	Tool package badges	You are staying on `Ansight.Core` and want explicit tool packages.	One tool suite per package.

The runtime namespace remains Ansight even when the NuGet package id is Ansight.Core.

Base SDK Setup

For native non-MAUI apps, add base SDK initialization to the platform startup file that owns the app host: Platforms/Android/MainApplication.cs in Application.OnCreate() after base.OnCreate(), Platforms/iOS/AppDelegate.cs in FinishedLaunching(...), or Platforms/MacCatalyst/AppDelegate.cs in FinishedLaunching(...). Do not put one-time runtime initialization in a page, view model, service constructor, or Android MainActivity; platform-specific QR pairing UI can still live in an activity, view controller, or window scene after the runtime is active.

Install:

dotnet add package Ansight --prerelease

Initialize:

The example below is suitable for a shared bootstrap helper. If you place the builder directly in a platform file, use that startup type for bundled host discovery, such as typeof(MainApplication).Assembly on Android or typeof(AppDelegate).Assembly on iOS and Mac Catalyst.

using Ansight;

var options = Options.CreateBuilder()
    .WithAnsightSdk(ansight =>
    {
        ansight.WithBundledHostConnection(typeof(AppBootstrap).Assembly);
#if ANDROID
        ansight.WithPlatformPairing(() => CurrentActivityProvider());
#endif
    })
    .Build();

Runtime.InitializeAndActivate(options);

WithAnsightSdk(...) registers the standard runtime setup and all non-MAUI remote tools. Because this package includes concrete tools, keep it scoped to local development builds. The default AnsightRemoteToolsPolicy=AllowedWithWarnings scans those builds, logs detected tools, emits warnings, and allows local development to continue. Use AnsightRemoteToolsPolicy=Disallowed in protected Release or CI builds; those builds must omit all-in-one tool packages or individual tool packages.

MAUI All-In-One

Install:

dotnet add package Ansight.Maui --prerelease

Use it from MauiProgram.cs inside CreateMauiApp(), before builder.Build():

using Ansight.Maui;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .UseAnsight<App>();

    return builder.Build();
}

Use UseAnsight<App>() to initialize and activate the runtime. The generic App overload points bundled host connection discovery at the application assembly. On Android, Ansight.Maui wires the current MAUI activity into platform QR pairing automatically. The MAUI app-builder integration also records foreground/background lifecycle transitions and Application.PageAppearing screen-view events automatically.

For custom tool options, use the same tool builders inside the UseAnsight<App>(...) callback:

using Ansight.Maui;
using Ansight.Tools.Preferences;
using Ansight.Tools.SecureStorage;

builder.UseAnsight<App>(ansight =>
{
    ansight.WithPreferencesTools(preferences =>
    {
        preferences.AllowKeyPrefix("com.example.");
    });
    ansight.WithSecureStorageTools(secure =>
    {
        secure.WithStorageIdentifier("ExampleApp");
        secure.AllowKey("session_token");
    });
});

Default Setup

WithAnsightSdk(...) and WithAnsightMaui(...) apply these defaults:

FPS sampling enabled
sample frequency set to 400ms
retention set to 120s
live JPEG capture every 2000ms at quality 60 and max width 480
host auto-probe enabled
bundled host connection enabled
platform QR pairing registered where supported
all relevant remote tools registered
read, write, and delete tool access enabled

Important: Screen capture will result in an FPS drop while frames are captured, encoded, and transported. Disable session JPEG capture for performance-focused runs unless visual evidence is required.

Battery level telemetry and touch input capture are runtime opt-ins. Enable them in the same callback when a session needs those streams:

builder.UseAnsight<App>(ansight =>
{
    ansight
        .WithBatteryLevel()
        .WithTouchCapture();
});

Callbacks on WithAnsightSdk(...), WithAnsightMaui(...), and UseAnsight(...) receive the existing Options.OptionsBuilder after runtime defaults and default tool access, but before default tool-suite registration, so custom channels, loggers, host connection changes, guard overrides, and deny-all tool configuration use the same model as Ansight.Core. If a callback registers a suite such as secure storage or preferences, the all-in-one setup skips its default registration for that suite and keeps the configured version.

Setup APIs

API	Package	Purpose
`WithAnsightSdk(...)`	`Ansight`	Apply runtime defaults, non-MAUI tools, platform pairing, bundled host config, host auto-probe, JPEG capture, and full tool access.
`WithAnsightDefaults()`	`Ansight`	Apply the runtime defaults without registering tools or enabling tool access.
`WithAnsightRemoteTools()`	`Ansight`	Register all non-MAUI remote tools only, skipping suites already registered on the builder.
`WithAnsightMaui(...)`	`Ansight.Maui`	Apply the base `WithAnsightSdk(...)` setup and register MAUI tools, skipping suites already registered on the builder.
`UseAnsight(...)`	`Ansight.Maui`	Initialize and activate Ansight from a `MauiAppBuilder`.

Core-Only Setup

Install Ansight.Core when you want telemetry, pairing, and build targets without bundled tool packages:

dotnet add package Ansight.Core --prerelease

Put this builder in the same startup file as the app host and call Runtime.InitializeAndActivate(...) before pairing, capture, telemetry, or tool registration.

using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithBatteryLevel()
    .WithSessionJpegCapture(intervalMilliseconds: 2000, quality: 60, maxWidth: 720)
    .WithBundledHostConnection(typeof(AppBootstrap).Assembly)
    .Build();

Runtime.InitializeAndActivate(options);

Add Ansight.Pairing separately if a core-only app should own native QR acquisition. Add individual Ansight.Tools.* packages only for the tool suites the workflow needs.