Tools

Add Ansight tool suites, artifact providers, or custom app tools to a .NET app, gate them with MSBuild and ToolGuard, and keep them limited to local development workflows, including live reflection.

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.

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 delete 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="0.1.0-pre9" />
</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="0.1.0-pre9" />
  <PackageReference Include="Ansight.Tools.VisualTree" Version="0.1.0-pre9" />
  <PackageReference Include="Ansight.Tools.Reflection" Version="0.1.0-pre9" />
  <PackageReference Include="Ansight.Tools.Database" Version="0.1.0-pre9" />
</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.

Suite Registration API

Common entry points are:

Suite	Common registration API
`MAUI`	`WithMauiTools()`
`VisualTree`	`WithVisualTreeTools()`
`Reflection`	`ReflectionRootRegistry.Register(...)`, `ReflectionRootRegistry.Deregister(...)`, `WithReflectionTools(...)`, `WithDefaultMemberVisibility(...)`, `WithAssemblyTraversalMode(...)`, `WithNamespaceTraversalMode(...)`, `AllowAssembly(...)`, `AllowNamespacePrefix(...)`
`Database`	`WithDatabaseTools()`
`FileSystem`	`WithFileSystemTools(...)`, `AddRoot(tag, path)`
`Preferences`	`WithPreferencesTools(...)`, `WithDefaultStore(...)`, `AllowStore(...)`, `AllowKey(...)`, `AllowKeyPrefix(...)`
`SecureStorage`	`WithSecureStorageTools(...)`, `WithStorageIdentifier(...)`, `WithAndroidStore(...)`, `WithAppleService(...)`, `AllowKey(...)`, `AllowKeyPrefix(...)`
`Artifacts`	`WithArtifactProviders(...)`, `AddArtifactProvider(...)`, `AddArtifactProviders(...)`, `ContainsArtifactProvider(...)`
`Custom tools`	`AddTool(ITool)`, `AddTools(IEnumerable<ITool>)`

Guard Levels

Guard	What it allows
`WithToolsDisabled()`	No discovery, no execution.
`WithReadOnlyToolAccess()`	Read-scoped tools only.
`WithReadWriteToolAccess()`	Read and write tools. Delete tools remain blocked.
`WithAllToolAccess()`	Read, write, and delete tools.

Storage-package remove operations are Delete. Reflection writes and method invocations are Write; the simplified reflection options surface controls roots, traversal, and visibility rather than per-member write or invoke 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-scoped 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.
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:

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