Pairing

The .NET SDK supports two practical pairing flows for local development:

• developer pairing generated at build time and embedded into the app assembly
• explicit QR or pasted payload pairing when you want to override the current host session

The runtime-owned surface is Runtime.HostConnection.

Pairing APIs

The pairing interface exposes these high-level flows:

• ConnectAsync()
• ConnectAsync(HostConnectionRequest.Auto())
• ConnectAsync(HostConnectionRequest.SavedConfig())
• ConnectAsync(HostConnectionRequest.BundledConfig())
• ConnectAsync(HostConnectionRequest.PayloadText(payload))
• ConnectAsync(HostConnectionRequest.QrCode())
• DisconnectAsync(...)
• ClearSavedConfigs()
• RefreshCapabilitiesAsync(...)

ConnectAsync() without a request uses the same behavior as HostConnectionRequest.Auto().

Connection results are HostConnectionResult values. Check Success, then inspect Message, Kind, Source, and ReasonCode when you need diagnostics.

var result = await Runtime.HostConnection.ConnectAsync();
if (!result.Success)
{
    throw new InvalidOperationException(result.Message);
}

You can also observe Runtime.HostConnection.StatusChanged for UI state. The current Status includes ConnectionState, SummaryKind, SummaryMessage, HasSavedConfig, HasBundledConfig, and HasCachedSession. Capabilities tells a UI whether saved-config connect, bundled-config connect, file selection, QR scanning, or config clearing is currently available.

Developer Pairing

Developer pairing is the smoothest local workflow because the app can connect to Ansight Studio without pasting or scanning a payload every run.

1. Enable the Build Target

Ansight.Core ships an MSBuild target that generates and embeds ansight.developer-pairing.json. The Ansight and Ansight.Maui all-in-one packages include the same build target.

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <AnsightDeveloperPairingEnabled>true</AnsightDeveloperPairingEnabled>
</PropertyGroup>

When enabled, the target uses $(MSBuildProjectDirectory)/ansight.json as the default source file, writes ansight.developer-pairing.json under the intermediate output path, and embeds it automatically with the logical name ansight.developer-pairing.json.

Only set these optional properties when the project intentionally uses non-default paths:

<PropertyGroup>
  <AnsightDeveloperPairingSourceFile>path/to/ansight.json</AnsightDeveloperPairingSourceFile>
  <AnsightDeveloperPairingOutputFile>$(IntermediateOutputPath)ansight.developer-pairing.json</AnsightDeveloperPairingOutputFile>
</PropertyGroup>

AnsightDeveloperPairingEnabled requires a signed pairing JSON at AnsightDeveloperPairingSourceFile. The generated resource wraps that signed config with local host discovery metadata. No manual EmbeddedResource item is required for the generated developer pairing file.

Keep this property scoped to local Debug builds. Do not ship developer-pairing resources in Release, TestFlight, App Store, Play Store, or other distributable builds.

2. Optional Bundled Config Sources

The generated developer-pairing resource is embedded into the consuming app assembly automatically, and the SDK has a default fallback that can discover that resource for auto-connect. You do not need to call WithBundledHostConnection(...) for the default generated developer-pairing path.

Use WithBundledHostConnection(...) only when you also embed a plain bundled ansight.json fallback, place resources in a non-default assembly, or package pairing documents as app assets.

For embedded resources in a specific assembly:

var options = Options.CreateBuilder()
    .WithBundledHostConnection(typeof(AppBootstrap).Assembly)
    .Build();

For packaged app assets, such as MAUI assets, use the shared loader overload:

var options = Options.CreateBuilder()
    .WithBundledHostConnection(
        (assetName, cancellationToken) => TryLoadBundledTextAssetAsync(assetName, cancellationToken))
    .Build();

3. Auto-Connect

var result = await Runtime.HostConnection.ConnectAsync(HostConnectionRequest.Auto());
if (!result.Success)
{
    throw new InvalidOperationException(result.Message);
}

HostConnectionRequest.Auto() tries the bundled developer pairing resource first, then falls back to the runtime-cached session, saved config, and plain bundled ansight.json config. When Runtime is activated and a bundled developer pairing resource is present, the SDK also performs a startup auto-connect attempt.

Host auto-probe is enabled by default while the runtime is active. After a session has paired once and cached a host profile, auto-probe periodically reconnects that cached session. Disable it with WithoutHostAutoProbe() or customize it with WithHostAutoProbe(new HostAutoProbeOptions { ... }).

QR Pairing

QR pairing is useful when you are pairing a physical device directly from Ansight Studio or need an explicit override of the current host session.

The Ansight and Ansight.Maui all-in-one packages include native QR acquisition where supported. Install Ansight.Pairing separately only when the app is staying on Ansight.Core:

dotnet add package Ansight.Pairing --prerelease

Then wire the platform pairing reader into the runtime-owned host connection:

using Ansight;
#if ANDROID
using Microsoft.Maui.ApplicationModel;
#endif

public static class AppBootstrap
{
    public static void ConfigureAnsight()
    {
        var optionsBuilder = Options.CreateBuilder()
            .WithBundledHostConnection(typeof(AppBootstrap).Assembly);

#if ANDROID
        optionsBuilder = optionsBuilder.WithPlatformPairing(() => Platform.CurrentActivity);
#else
        optionsBuilder = optionsBuilder.WithPlatformPairing();
#endif

        Runtime.InitializeAndActivate(optionsBuilder.Build());
    }
}

On Android, pass the current Activity so the package can launch the scanner UI.

To scan and connect:

var result = await Runtime.HostConnection.ConnectAsync(HostConnectionRequest.QrCode());

If your app already has its own scanner and receives the payload as a string, use a payload request instead:

var result = await Runtime.HostConnection.ConnectAsync(
    HostConnectionRequest.PayloadText(qrPayload, "QR pairing code"));

Explicit QrCode(...) and PayloadText(...) requests always use the supplied payload and replace the current host session, even when developer pairing is configured.

Recommended Pairing Flow

Use this order of preference:

1. Bundled developer pairing for repeat local development.
2. QR pairing for physical devices and one-off connections.
3. Saved-config reconnects for daily iteration once the app has already paired successfully.

Related Configuration

Pairing behavior is also affected by:

• WithBundledHostConnection(...)
• WithHostConnection(...)
• ConfigureHostConnection(...)
• WithHostAutoProbe(...)
• WithoutHostAutoProbe()
• WithPlatformPairing(...) from Ansight.Pairing

See .NET Configuration for the full option surface.