Tools

Ansight.Core defines the tool abstraction layer. The concrete tool suites ship in separate packages, and the Ansight and Ansight.Maui all-in-one packages reference the common suites for you.

File-descriptor diagnostics are currently implemented only by the native Android and iOS SDKs. There is no Ansight.Tools.FileDescriptorDiagnostics NuGet package.

JNI reference diagnostics is a separate Android-only exception to the package-per-suite model: the .NET tool and bridge live in Ansight.Core, and the all-in-one packages register it automatically for Android targets.

If you want an AI agent to create a new app-specific remote tool, use the Ansight .NET Remote Tool Skill.

Important Security Rule

Treat all remote tools as development-only capabilities.

Do this:

• install tool packages or all-in-one packages with tools only in local Debug builds
• keep AnsightRemoteToolsPolicy=AllowedWithWarnings for those Debug builds, or set Allowed only when you intentionally want to bypass scanning and warnings
• use the narrowest runtime guard that works for the workflow

Do not do this:

• ship tool packages in Release or distribution builds
• set AnsightRemoteToolsPolicy=Allowed broadly
• expose write or critical tools when read-only inspection is enough

Build-Time Opt-In

The Ansight build target scans the build output for concrete ITool implementations unless AnsightRemoteToolsPolicy=Allowed.

The default AllowedWithWarnings policy logs detected tools, emits a build warning, and allows local development builds to continue. Disallowed fails builds that include detected tools, so protected Release or CI builds must omit all-in-one tool packages and individual tool packages.

Recommended pattern for the MAUI all-in-one package:

<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <PackageReference Include="Ansight.Maui" Version="1.4.0-preview.1" />
</ItemGroup>

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <AnsightRemoteToolsPolicy>AllowedWithWarnings</AnsightRemoteToolsPolicy>
</PropertyGroup>

Core-only apps can keep explicit tool packages:

<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <PackageReference Include="Ansight.Tools.Maui" Version="1.4.0-preview.1" />
  <PackageReference Include="Ansight.Tools.VisualTree" Version="1.4.0-preview.1" />
  <PackageReference Include="Ansight.Tools.Reflection" Version="1.4.0-preview.1" />
  <PackageReference Include="Ansight.Tools.Database" Version="1.4.0-preview.1" />
</ItemGroup>

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <AnsightRemoteToolsPolicy>AllowedWithWarnings</AnsightRemoteToolsPolicy>
</PropertyGroup>

Notes:

• AllowedWithWarnings is the default and emits warnings when remote tools are detected.
• Disallowed fails builds with detected remote tools, so protected Release or CI builds must omit all-in-one tool packages and individual tool packages.
• Allowed bypasses scanning and warnings; keep it for rare local builds only.

Runtime Registration

The all-in-one APIs register the standard tool suites for you:

using Ansight;
using Ansight.Tools.SecureStorage;

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

For MAUI apps:

using Ansight.Maui;

builder.UseAnsight<App>();

The all-in-one callbacks run before default tool-suite registration. If the callback registers a suite, the default registration for that suite is skipped and the configured version is used. Full tool access is applied before the callback, so the callback can still narrow the guard.

When you use Ansight.Core, register each suite explicitly:

using Ansight;
using Ansight.Tools.Maui;
using Ansight.Tools.Reflection;
using Ansight.Tools.Database;
using Ansight.Tools.VisualTree;

var session = new DebugSessionViewModel();

var sessionRoot = ReflectionRootRegistry.Register(
    "session",
    session,
    new ReflectionRootMetadata("Current Session")
    {
        Hints = ["debug", "session"]
    },
    ReferenceType.Strong);

var options = Options.CreateBuilder()
    .WithMauiTools()
    .WithVisualTreeTools()
    .WithReflectionTools(reflection =>
    {
        reflection.WithAssemblyTraversalMode(ReflectionAssemblyTraversalMode.AllowAll);
        reflection.WithNamespaceTraversalMode(ReflectionNamespaceTraversalMode.AllowAll);
        reflection.WithDefaultMemberVisibility(ReflectionMemberVisibility.PublicOnly);
    })
    .WithDatabaseTools()
    .WithReadOnlyToolAccess()
    .Build();

Registered tools stay unusable until the guard allows them.

Runtime Availability

tool.query evaluates each visible tool against current app state. Catalog entries include runtime.available, reasonCode, reason, requiredState, remediation, retryable, and evaluatedAtUtc, plus a top-level executable flag. Availability is evaluated again immediately before tool.call; an unavailable call returns a structured error instead of executing the tool. ITool.GetAvailabilityAsync(...) defaults to ToolAvailability.Available.

Suite Registration API

Common entry points are:

Guard Levels

Storage removal, secure-storage access, and reflection object inspection, writes, and invocation are Critical. The simplified reflection options surface controls roots, traversal, and visibility rather than per-member allow-lists.

Tool Suites

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

Artifacts are a core provider model rather than an Ansight.Tools.* package. Registering an artifact provider automatically adds the Read policy artifacts.query and artifacts.request tools. See Artifacts when the app should expose file-like diagnostic exports.

Suite	Package	NuGet	Typical use
MAUI	Ansight.Tools.Maui		Inspect and drive MAUI pages, visual trees, elements, XAML experiments, themes, bindings, resources, navigation, layout, handlers, bindable properties, and binding contexts.
VisualTree	Ansight.Tools.VisualTree		Inspect the live UI hierarchy and capture screenshots.
Reflection	Ansight.Tools.Reflection		Inspect registered live objects, describe runtime types, and optionally enable writable-member updates or method invocation.
Database	Ansight.Tools.Database		Discover SQLite databases, inspect schema, and run read-only queries.
FileSystem	Ansight.Tools.FileSystem		List directories, read, download, push, copy, move, and delete sandboxed files.
Preferences	Ansight.Tools.Preferences		Read and mutate shared preferences or user defaults under allow-lists.
SecureStorage	Ansight.Tools.SecureStorage		Read and mutate secure storage values under explicit key allow-lists.
JNI Reference Diagnostics	Ansight.Core on Android	Included	Capture a bounded, redacted JNI-rooted Android heap graph.
Custom Tools	Your app or local development assembly	N/A	Expose app-specific diagnostic or development operations by implementing ITool.

Recommended Defaults

For most teams:

1. Start with VisualTree and Database.
2. Add MAUI when you need MAUI-specific element, bindable-property, or binding-context inspection.
3. Use WithReadOnlyToolAccess().
4. Add Reflection when you need live in-memory state outside MAUI binding contexts.
5. Add FileSystem, Preferences, or SecureStorage only when there is a specific debugging workflow that needs them.
6. Add Artifacts when app-specific output should become a streamed file or durable session artifact.
7. Add Custom Tools only for narrow app-specific operations that the packaged suites cannot cover.
8. Keep write and delete operations off unless the workflow genuinely depends on them.