Pairing

Pair a .NET app with Ansight Studio by bundling a Studio-issued config or scanning a QR payload in the app.

The .NET SDK supports two practical pairing flows:

  • developer pairing from a Studio-issued config bundled with the app
  • QR pairing where the app scans a Studio payload and connects immediately

The runtime-owned surface for both flows is Runtime.HostPairing.

Pairing APIs

The pairing interface exposes these high-level flows:

  • AutoConnectAsync(...)
  • ConnectUsingStoredProfileAsync(...)
  • ConnectUsingBundledProfileAsync(...)
  • ConnectFromPayloadAsync(...)
  • ConnectFromPayloadReaderAsync(...)
  • DisconnectAsync(...)
  • ClearStoredProfiles()

ConnectFromPayloadAsync(...) accepts:

  • a QR payload
  • a bootstrap document
  • a full pairing config JSON payload

Developer Pairing with a Bundled Config

This is the smoothest development workflow when your team can keep a Studio-issued config near the app project.

1. Issue a Config in Studio

In Studio:

  1. Register the app.
  2. Issue a pairing config.
  3. Save or copy the generated JSON.

Store that file in the app project as ansight.json.

2. Enable the Developer Pairing Target and Embed the Resources

The base package ships a build target that can generate ansight.developer-pairing.json from ansight.json.

<PropertyGroup>
  <AnsightDeveloperPairingEnabled>true</AnsightDeveloperPairingEnabled>
</PropertyGroup>

<ItemGroup>
  <EmbeddedResource Include="ansight.json" LogicalName="ansight.json" />
  <EmbeddedResource Include="$(BaseIntermediateOutputPath)ansight.developer-pairing.json"
                    LogicalName="ansight.developer-pairing.json"
                    Condition="'$(AnsightDeveloperPairingEnabled)' == 'true' and Exists('$(BaseIntermediateOutputPath)ansight.developer-pairing.json')" />
</ItemGroup>

The logical names matter. When you use BundledProfileAssembly, Ansight looks for embedded resources named exactly ansight.json and ansight.developer-pairing.json.

Optional MSBuild properties:

<PropertyGroup>
  <AnsightDeveloperPairingSourceFile>ansight.json</AnsightDeveloperPairingSourceFile>
  <AnsightDeveloperPairingOutputFile>$(BaseIntermediateOutputPath)ansight.developer-pairing.json</AnsightDeveloperPairingOutputFile>
</PropertyGroup>

3. Point Ansight at the Embedded Resources

using Ansight;

public static class AppBootstrap
{
    public static void ConfigureAnsight()
    {
        var options = Options.CreateBuilder()
            .WithHostPairing(new HostPairingOptions
            {
                BundledProfileAssembly = typeof(AppBootstrap).Assembly
            })
            .Build();

        Runtime.InitializeAndActivate(options);
    }
}

If the embedded resources live in a different assembly, point BundledProfileAssembly at that assembly instead.

4. Auto-Connect

var result = await Runtime.HostPairing.AutoConnectAsync();
if (!result.IsSuccess)
{
    throw new InvalidOperationException(result.Message);
}

AutoConnectAsync() tries the runtime cache first, then stored and bundled profiles.

QR Pairing

QR pairing is useful when you do not want to move files around manually or when you are pairing a physical device directly from Studio.

Lean QR Sample

When your scanner returns the QR payload as a string, hand it straight to Runtime.HostPairing:

using Ansight;

public static async Task PairFromQrPayloadAsync(string qrPayload, CancellationToken cancellationToken = default)
{
    var result = await Runtime.HostPairing.ConnectFromPayloadAsync(
        qrPayload,
        sourceDescription: "QR pairing code",
        clientName: AppInfo.Current.PackageName,
        cancellationToken: cancellationToken);

    if (!result.IsSuccess)
    {
        throw new InvalidOperationException(result.Message);
    }
}

That is the smallest supported QR flow.

Using a Platform-Owned Reader

If your app already has a file picker or QR scanner abstraction, implement IHostPairingPayloadReader and call:

var result = await Runtime.HostPairing.ConnectFromPayloadReaderAsync(
    new HostPairingPayloadReadRequest(
        HostPairingPayloadReadKind.QrCode,
        SourceDescription: "Camera scanner",
        Title: "Scan Ansight pairing code"));

Supported reader kinds:

  • HostPairingPayloadReadKind.File
  • HostPairingPayloadReadKind.QrCode

Use this order of preference:

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

Pairing behavior is also affected by:

  • WithHostPairing(...)
  • ConfigureHostPairing(...)
  • WithHostAutoProbe(...)
  • WithoutHostAutoProbe()

See .NET Configuration for the full option surface.