.NET and .NET MAUI Setup

Use Ansight.Maui for .NET MAUI apps and Ansight for native .NET Android, iOS, or Mac Catalyst apps. Start with the matching all-in-one package; use Ansight.Core only when you need manual package and tool selection.

1. Add the package

For a .NET MAUI app:

dotnet add package Ansight.Maui --prerelease

For a non-MAUI app:

dotnet add package Ansight --prerelease

Before shipping, keep the all-in-one package in an approved development configuration and set AnsightRemoteToolsPolicy=Disallowed in protected Release and CI builds. See .NET Security for the full build policy.

2. Initialize the development build

.NET MAUI

Use Ansight.Maui from MauiProgram.cs before builder.Build():

#if DEBUG
using Ansight.Maui;
#endif

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder.UseMauiApp<App>();

#if DEBUG
    builder.UseAnsight<App>();
#endif

    return builder.Build();
}

Native .NET

Initialize once from the platform startup location: Android Application.OnCreate() after base.OnCreate(), or iOS and Mac Catalyst AppDelegate.FinishedLaunching(...).

#if DEBUG
using Ansight;

var options = Options.CreateBuilder()
    .WithAnsightSdk()
    .Build();

Runtime.InitializeAndActivate(options);
#endif

Use an explicit internal-build symbol instead of DEBUG when that is the app’s approved Ansight configuration.

3. Add stable automation ids

For .NET MAUI, give important controls stable AutomationId values so live and recorded visual trees remain easy to query:

<Button AutomationId="login-button"
        Text="Sign in" />

Use the platform-native accessibility identifier in non-MAUI apps.

4. Run and verify

Start the host in one terminal:

ansight host run

Launch the development app. From another terminal, confirm its session and tool catalog:

ansight session list --connected --json
ansight app tools <session-id> --detail summary --include-unavailable --max-results 50 --json

A physical device requires the one-time enrollment flow.

Troubleshooting

• No connected session: confirm the host is running, the app uses the Debug or approved internal configuration, and initialization runs before the app host finishes starting.
• The build rejects remote tools: use AllowedWithWarnings only for the intended development build and keep protected builds on Disallowed.
• MAUI tools are missing: confirm the app references Ansight.Maui and calls UseAnsight<App>(), rather than using only the base package.

Setup Reference

See .NET Packages to compare the all-in-one, core, workflow, and individual tool packages before using the alternative setup paths below.

Base SDK setup reference

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 enrollment UI can still live in an activity, view controller, or window scene after the runtime is active.

Install:

dotnet add package Ansight --prerelease

Initialize inside the development-build guard shown above:

using Ansight;

var options = Options.CreateBuilder()
    .WithAnsightSdk()
    .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 reference

Install:

dotnet add package Ansight.Maui --prerelease

Use it from MauiProgram.cs inside CreateMauiApp(), before builder.Build() and inside the development-build guard shown above:

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. On Android, Ansight.Maui wires the current MAUI activity into platform QR enrollment 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
• touch capture enabled
• host auto-probe enabled
• platform QR enrollment registered where supported
• all relevant remote tools registered
• read, write, and critical tool access enabled

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

Battery level telemetry remains opt-in. Touch capture is enabled by default; customize it or disable it in the same callback:

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

The all-in-one packages include Ansight.Annotations and Ansight.OfflineCapture, but those workflows remain opt-in. Call WithAnnotatedFeedback() for Debug-only in-app feedback or configure an OfflineCaptureController separately.

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

Core-Only Setup

Install Ansight.Core when you want telemetry and direct control 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 enrollment, capture, telemetry, or tool registration.

using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithBatteryLevel()
    .WithSessionJpegCapture(intervalMilliseconds: 2000, quality: 60, maxWidth: 720)
    .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.