Ditto .NET Tools

Ditto .NET Tools are diagnostic tools for Ditto.

These tools are available through NuGet.

Important

This repository is a read-only mirror maintained by Ditto's SDK release process. Pull requests opened outside that process are not accepted. To report a problem or request a change, contact Ditto Support (support@ditto.com).

Usage

These tools require you to have an already-initialized Ditto instance. Take a look at the C# Documentation.

Requires Ditto .NET SDK v5.x. These tools pin Ditto 5.0.1 as the minimum compatible SDK version. They are not compatible with Ditto v4.

Tools are individually shipped under different NuGet packages.

1. Presence Viewer

The Presence Viewer displays a mesh graph that allows you to see all connected peers within the mesh and the transport each peer is using to make a connection.

You can use Presence Viewer in your .NET MAUI applications:

1. Add the package:

<PackageReference Include="DittoTools.PresenceViewer" Version="2.0.0" />

2. Create a blank .NET MAUI Page and reference the Presence Viewer.

Add the namespace definition:

xmlns:presence="clr-namespace:DittoTools.PresenceViewer;assembly=DittoPresenceViewer"

Then simply include the view making sure to properly assign the Ditto instance:

<presence:DittoPresenceViewer
    Ditto="{Binding Ditto, Source={x:Reference self}}"/>

Full example:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="DittoMauiTasksApp.PresenceViewerPage"
             xmlns:presence="clr-namespace:DittoTools.PresenceViewer;assembly=DittoPresenceViewer"
             x:Name="self"
             Shell.PresentationMode="Modal"
             Title="PresenceViewerPage">
    <ContentPage.ToolbarItems>
        <ToolbarItem Text="Close"
                     Clicked="ToolbarItem_Clicked"/>
    </ContentPage.ToolbarItems>
    <presence:DittoPresenceViewer
        Ditto="{Binding Ditto, Source={x:Reference self}}"/>
</ContentPage>

And the code behind:

using System;
using DittoSDK;
using Microsoft.Maui.Controls;

namespace DittoMauiTasksApp;

public partial class PresenceViewerPage : ContentPage
{
    public Ditto Ditto { get; set; }

    public PresenceViewerPage(Ditto ditto)
    {
        this.Ditto = ditto;

        InitializeComponent();
    }

    async void ToolbarItem_Clicked(System.Object sender, System.EventArgs e)
    {
        await Shell.Current.GoToAsync("//MainPage");
    }
}

---

2. Heartbeat

The Ditto Heartbeat tool allows you to monitor, locally or remotely, the peers in your mesh. It allows you to regularly report data and health of the device.

Configure Heartbeat

These are the values you need to provide to the Heartbeat:

1. Id - Unique value that identifies the device.
2. SecondsInterval - The frequency at which the Heartbeat will scrape the data.
3. Metadata (optional) - Any metadata you want to attach to this heartbeat.

There is a DittoHeartbeatConfig struct you can use to construct your configuration.

// Provided with the Heartbeat tool
public class DittoHeartbeatConfig 
{
    public string Id { get; private set; }

    public int SecondsInterval { get; private set; }

    public Dictionary<string, object>? Metadata { get; private set; }
}

This tool generates a DittoHeartbeatInfo object with the given data:

public class DittoHeartbeatInfo
{
   public string Id { get; internal set; }

   public string Schema { get; internal set; }

   public int SecondsInterval { get; internal set;  }

   public string LastUpdated { get; internal set; }

   public string Sdk { get; internal set; }

   public int PresenceSnapshotDirectlyConnectedPeersCount { get; internal set; }

   public Dictionary<string, object> PresenceSnapshotDirectlyConnectedPeers { get; internal set; }

   public Dictionary<string, object>? Metadata { get; internal set;  }

   public string PeerKey { get; internal set; }
}

Each entry in PresenceSnapshotDirectlyConnectedPeers includes a connectionTypes map from every observed SDK connection-type name to its count. New code should use this map for connection-type counts. The bluetooth, p2pWifi, and lan keys are legacy summary fields retained in heartbeat documents for compatibility. The SDK enum names LAN connections AccessPoint, so that enum value supplies lan. WebSocket, Multicast, and other connection types are separate entries in connectionTypes.

Wire compatibility is additive: tools released before connectionTypes ignore that extra field and continue reading the fixed summary fields. Current tools also accept older documents without connectionTypes, treating the missing map as empty. For those documents, the legacy summaries are the only available breakdown. The lan summary means AccessPoint only. Earlier GA tools also included WebSocket in lan, so documents written by those versions can report a larger LAN count. In current documents, WebSocket has its own exact connectionTypes entry.

The isConnectedToDittoCloud field reports whether the peer is connected to Ditto Server. SDK v4 exposed this connection state as IsConnectedToDittoCloud; SDK v5 renamed the SDK property to IsConnectedToDittoServer. The heartbeat document schema retains the original key so independently versioned tools can exchange and read the same documents.

You can either check the provided UI in the sample app, or create your own and use the data as you please.

Read data:

var hearbeat = new DittoHeartbeat();
var config = new DittoHeartbeatConfig("<ID>", 10);
heartbeat.StartHeartbeat(ditto, config, (heartbeatInfo) => {
    // use data
});

Ditto Tools Example App

The Ditto Tools Example App included in this repo allows you to try the DittoDotnetTools in a standalone .NET MAUI app.

Before your first build, copy .env.sample to .env at the repo root and fill in values from the Ditto Portal:

cp .env.sample .env

Required keys: DITTO_APP_ID, DITTO_PLAYGROUND_TOKEN, DITTO_AUTH_URL. The app throws at launch if any are empty.