Configuration

Configure sampling, logging, capture, pairing, tool registration, and guard policy with the Ansight options builder.

The .NET SDK is configured through Options.CreateBuilder().

Minimal Example

using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithRetentionPeriodSeconds(600)
    .WithHostPairing()
    .Build();

Runtime.InitializeAndActivate(options);

Default Behavior

When you use Options.Default or an empty builder, Ansight starts with:

sample frequency: 500ms
retention: 10 minutes
FPS enabled: true
default memory channels: platform defaults
tool registry: empty
tool guard: disabled
host auto-probe: enabled
host pairing: default profile resolution rules

Validation clamps important values:

sample frequency is kept between 200ms and 2000ms
retention is kept between 60s and 3600s
JPEG capture interval is kept at 250ms or higher
JPEG maxWidth is clamped to 8192

Builder Methods

Method	Purpose
`WithSampleFrequencyMilliseconds(ushort)`	Set the telemetry sampling cadence.
`WithFramesPerSecond()`	Enable FPS tracking at startup.
`WithRetentionPeriodSeconds(ushort)`	Set how long metrics and events remain buffered.
`WithAdditionalChannels(IEnumerable<Channel>)`	Replace the custom channel collection.
`AddAdditionalChannel(Channel)`	Add one custom channel.
`WithDefaultMemoryChannels(DefaultMemoryChannels)`	Replace the built-in memory channel flags.
`WithoutDefaultMemoryChannels(DefaultMemoryChannels)`	Remove selected built-in memory channels.
`WithAdditionalLogger(ILogCallback)`	Forward Ansight logs to your logger.
`WithBuiltInLogger()`	Use the built-in console logger.
`WithTools(IEnumerable<ITool>)`	Replace the registered tool collection.
`AddTool(ITool)`	Add one tool.
`AddTools(IEnumerable<ITool>)`	Add multiple tools.
`WithSessionJpegCapture(...)`	Enable periodic live-session JPEG capture.
`WithSessionJpegCapture(SessionJpegCaptureOptions)`	Supply a fully populated JPEG capture object.
`WithoutSessionJpegCapture()`	Disable live-session JPEG capture.
`WithToolGuard(ToolGuard)`	Set an explicit guard policy.
`WithToolsDisabled()`	Disable tool discovery and execution.
`WithReadOnlyToolAccess()`	Allow read-scoped tools only.
`WithReadWriteToolAccess()`	Allow read and write tools, but not delete tools.
`WithAllToolAccess()`	Allow read, write, and delete tools.
`WithHostAutoProbe(HostAutoProbeOptions?)`	Enable or customize background reconnect probing.
`WithoutHostAutoProbe()`	Disable background reconnect probing.
`WithHostPairing(HostPairingOptions?)`	Replace the runtime-owned pairing configuration.
`ConfigureHostPairing(Action<HostPairingOptions>)`	Mutate the pairing configuration inline.
`Build()`	Validate and produce the final `Options` instance.

Package-specific tool registration extensions are added by the optional tool packages rather than the base Ansight package.

Tool Suite Extension Methods

Common entry points:

Extension	Package	Purpose
`WithVisualTreeTools()`	`Ansight.Tools.VisualTree`	Register live UI hierarchy and screenshot tools.
`WithReflectionTools(Action<ReflectionToolsOptionsBuilder>)`	`Ansight.Tools.Reflection`	Register live object roots, visibility rules, and reflection allow-lists.
`WithDatabaseTools()`	`Ansight.Tools.Database`	Register SQLite discovery, schema, and query tools.
`WithFileSystemTools(Action<FileSystemToolsOptionsBuilder>)`	`Ansight.Tools.FileSystem`	Register sandbox file access and additional tagged roots.
`WithPreferencesTools(Action<PreferencesToolsOptionsBuilder>)`	`Ansight.Tools.Preferences`	Register preference access with store and key restrictions.
`WithSecureStorageTools(Action<SecureStorageToolsOptionsBuilder>)`	`Ansight.Tools.SecureStorage`	Register secure-storage access with storage selection and key allow-lists.

Memory Channels

DefaultMemoryChannels is a flags enum:

ManagedHeap
NativeHeap
ResidentSetSize
PhysicalFootprint
All

Platform defaults:

Android: ManagedHeap | NativeHeap | ResidentSetSize
iOS and Mac Catalyst: ManagedHeap | PhysicalFootprint
other targets: ManagedHeap

Host Auto-Probe Options

HostAutoProbeOptions controls background reconnect behavior while the runtime is active.

Property	Meaning	Default
`Enabled`	Whether automatic probe/reconnect runs at all.	`true`
`InitialDelay`	Delay after activation before the first probe.	`2s`
`ProbeInterval`	Delay between probe attempts while disconnected.	`10s`
`ReconnectDelay`	Delay before probing resumes after a disconnect.	`15s`
`ClientName`	Optional client name override for automatic connects.	`null`

If you do not want automatic reconnect behavior, call:

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

Host Pairing Options

HostPairingOptions controls how the runtime discovers bundled or stored pairing profiles.

Property	Meaning
`PreferredProfilePath`	Override the path used to store the preferred profile.
`BundledProfileAssembly`	Assembly containing embedded `ansight.json` or `ansight.developer-pairing.json` resources.
`BundledDeveloperProfileLoader`	Custom loader for `ansight.developer-pairing.json`.
`BundledProfileLoader`	Custom loader for `ansight.json`.
`PayloadReader`	App-owned reader for file or QR payload input.

Session JPEG Capture Options

Use JPEG capture only when you actually need live visual artifacts.

var options = Options.CreateBuilder()
    .WithSessionJpegCapture(intervalMilliseconds: 2000, quality: 60, maxWidth: 720)
    .Build();

SessionJpegCaptureOptions properties:

Property	Meaning
`IntervalMilliseconds`	Capture interval while a pairing session is open.
`Quality`	JPEG quality from `1` to `100`.
`MaxWidth`	Optional output width cap. `null` keeps full width.

This feature adds rendering, encoding, and transport overhead. Keep it conservative.

Tool Guard Policy

Registering tools is not enough on its own. You must also choose a guard.

Built-in guards:

ToolGuard.Disabled
ToolGuard.ReadOnly
ToolGuard.ReadWrite
ToolGuard.FullAccess

Delete-scoped tools stay blocked unless you use WithAllToolAccess() or build a custom ToolGuard.

Reflection writes and invocations are Write tools, so they require WithReadWriteToolAccess() or a custom ToolGuard, plus the per-root allow-lists configured inside WithReflectionTools(...).

Example: Telemetry + Pairing + Tools

using Ansight;
using Ansight.Tools.Reflection;
using Ansight.Tools.VisualTree;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithRetentionPeriodSeconds(900)
    .WithSessionJpegCapture(intervalMilliseconds: 3000, quality: 60, maxWidth: 720)
    .WithVisualTreeTools()
    .WithReflectionTools(reflection =>
    {
        reflection.WithAssemblyTraversalMode(ReflectionAssemblyTraversalMode.AllowAll);
        reflection.WithNamespaceTraversalMode(ReflectionNamespaceTraversalMode.AllowAll);
        reflection.AddRoot(
            "session",
            new DebugSessionViewModel(),
            new ReflectionRootMetadata("Current Session"));
    })
    .WithReadOnlyToolAccess()
    .Build();

Runtime.InitializeAndActivate(options);