.NET

The .NET SDK is the current primary Ansight runtime integration.

Supported Targets

The core package targets:

• net9.0
• net9.0-android
• net9.0-ios
• net9.0-maccatalyst

Package ids:

Package	NuGet
Ansight
Ansight.Maui
Ansight.Core

Recommended Install

Use the package that matches the app:

• Ansight for non-MAUI apps that want the standard runtime and all non-MAUI remote tools.
• Ansight.Maui for .NET MAUI apps that want the standard runtime, all non-MAUI tools, MAUI tools, and MauiAppBuilder setup.
• Ansight.Core for apps that want manual registration and no bundled concrete tool packages.

See .NET Setup Packages for the full package matrix.

Base SDK Setup

Use the base Ansight package for native .NET Android, iOS, or Mac Catalyst apps that are not using .NET MAUI. Create the options and call Runtime.InitializeAndActivate(...) once during platform startup.

Android

Put the setup in your Android Application class, typically Platforms/Android/MainApplication.cs, inside OnCreate().

using Android.App;
using Android.Runtime;
using Ansight;

namespace MyApp;

[Application]
public class MainApplication : Application
{
    public MainApplication(IntPtr handle, JniHandleOwnership ownership)
        : base(handle, ownership)
    {
    }

    public override void OnCreate()
    {
        base.OnCreate();

        var options = Options.CreateBuilder()
            .WithAnsightSdk(ansight =>
            {
                ansight.WithBundledHostConnection(typeof(MainApplication).Assembly);
            })
            .Build();

        Runtime.InitializeAndActivate(options);
    }
}

iOS

Put the setup in your iOS AppDelegate, typically Platforms/iOS/AppDelegate.cs, inside FinishedLaunching(...).

using Ansight;
using Foundation;
using UIKit;

namespace MyApp;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        var options = Options.CreateBuilder()
            .WithAnsightSdk(ansight =>
            {
                ansight.WithBundledHostConnection(typeof(AppDelegate).Assembly);
            })
            .Build();

        Runtime.InitializeAndActivate(options);

        return true;
    }
}

Mac Catalyst

Put the setup in your Mac Catalyst AppDelegate, typically Platforms/MacCatalyst/AppDelegate.cs, inside FinishedLaunching(...).

using Ansight;
using Foundation;
using UIKit;

namespace MyApp;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        var options = Options.CreateBuilder()
            .WithAnsightSdk(ansight =>
            {
                ansight.WithBundledHostConnection(typeof(AppDelegate).Assembly);
            })
            .Build();

        Runtime.InitializeAndActivate(options);

        return true;
    }
}

For shared startup code, keep the option builder in a common helper and call that helper from the platform startup location:

using Ansight;

var options = Options.CreateBuilder()
    .WithAnsightSdk(ansight =>
    {
        ansight.WithBundledHostConnection(typeof(AppBootstrap).Assembly);
    })
    .Build();

Runtime.InitializeAndActivate(options);

WithAnsightSdk(...) applies the standard runtime defaults, host auto-probe, bundled host connection, JPEG capture, platform pairing where supported, all non-MAUI remote tools, and full tool access. Its callback runs before default tool-suite registration, so deny-all suites can be configured there:

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.

using Ansight;
using Ansight.Tools.SecureStorage;

var options = Options.CreateBuilder()
    .WithAnsightSdk(ansight =>
    {
        ansight.WithSecureStorageTools(secure =>
        {
            secure.WithStorageIdentifier("MyApp");
            secure.AllowKeyPrefix("ansight.secure.");
        });
    })
    .Build();

MAUI All-In-One Setup

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

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

    builder
        .UseMauiApp<App>()
        .UseAnsight<App>(ansight =>
        {
            ansight.WithSecureStorageTools(secure =>
            {
                secure.WithStorageIdentifier("MyMauiApp");
                secure.AllowKeyPrefix("ansight.secure.");
            });
        });

    return builder.Build();
}

What the Core Package Covers

Ansight.Core includes:

• sampling and retention configuration
• built-in memory and FPS metrics
• opt-in battery level metrics
• screen-view and lifecycle events
• runtime log callbacks
• custom channels
• optional session JPEG capture
• optional touch input capture
• app artifact providers and streamed artifact requests
• runtime-owned host connection and reconnection
• tool abstractions, custom tools, and tool guard policy
• build-time remote tool enforcement

Common Next Steps

• Use Setup Packages to choose Ansight, Ansight.Maui, or Ansight.Core.
• Use .NET Security before enabling all-in-one packages or remote tools.
• Use Pairing to connect the app to Ansight Studio.
• Use Configuration to tune sampling, capture, and pairing behavior.
• Use JPEG Screenshots to choose between periodic session capture and on-demand VisualTree screenshots.
• Use Performance Telemetry to capture built-in FPS, memory, and battery metrics.
• Use Touch Input to capture taps, drags, long presses, and gesture cancellations in session replay.
• Use Screen Views to record page and screen navigation events.
• Use Capturing Logs to capture runtime logs and receive third-party logs into Ansight.
• Use App Lifecycle to track foreground and background transitions.
• Use Artifacts to expose app-owned diagnostic exports as discoverable, requestable files.
• Use Tools to add VisualTree, reflection, database, file-system, preferences, secure-storage, or custom app-defined tools.

Tool Packages

Install tool packages separately only when you are using Ansight.Core. The all-in-one packages already include their respective tool sets.

Examples:

dotnet add package Ansight.Tools.VisualTree --prerelease
dotnet add package Ansight.Tools.Maui --prerelease
dotnet add package Ansight.Tools.Reflection --prerelease
dotnet add package Ansight.Tools.Database --prerelease

Available tool packages:

Tool	Package	NuGet
VisualTree	Ansight.Tools.VisualTree
MAUI	Ansight.Tools.Maui
Reflection	Ansight.Tools.Reflection
Database	Ansight.Tools.Database
FileSystem	Ansight.Tools.FileSystem
Preferences	Ansight.Tools.Preferences
SecureStorage	Ansight.Tools.SecureStorage