MDH.Streamdeck.Companion 1.0.2

MDH.Streamdeck.Companion

Embeddable HTTP + SSE control API for a host application. Register named actions and a state provider; drive them from a Stream Deck (via Bitfocus Companion) or any HTTP client.

Targets netstandard2.0, net48, net8.0-windows. The WPF status bar item and settings editor are on the two Windows targets only.

Install

dotnet add package MDH.Streamdeck.Companion

Quick start

var settings = CompanionSettings.LoadFromFile(@"C:\ProgramData\YourApp\companion.xml");

var server = new CompanionServer(settings)
    .SetStateProvider(() => JsonSerializer.Serialize(new { heat = _app.Heat?.Name }))
    .MapAction("start", _ => _app.StartTimer())
    .MapAction("stop",  _ => _app.StopTimer())
    .MapAction("stand", q => _app.SelectStand(CompanionQuery.GetInt(q, "n", 1)));

server.OnLog   += Log;
server.OnError += Log;
server.Start();

Endpoints

With default settings:

Routing is path-only; any HTTP method works.

API

CompanionServer MapAction(string relativePath, Action<IReadOnlyDictionary<string, string>> handler);
CompanionServer MapAction(string relativePath, Func<IReadOnlyDictionary<string, string>, string?> handler);
CompanionServer SetStateProvider(Func<string> stateJsonProvider);
void Start();
void Stop();

bool IsRunning { get; }
int  ConnectedClients { get; }

event Action<string>? OnLog;
event Action<string>? OnError;
event Action<int>?    ClientCountChanged;

Start() is a no-op when Enabled is false or already running. The Func overload returns a JSON response body; null replies {"ok":true}.

ConnectedClients counts open events streams. ClientCountChanged fires on connect and disconnect.

Query parameters

CompanionQuery.Get(q, "name");           // string or null
CompanionQuery.GetInt(q, "n", 1);        // fallback when absent or unparseable
CompanionQuery.GetBool(q, "on", true);   // "false"/"0" are false; anything else true

Settings

IsConfigured / ConfigurationProblem report whether the settings are usable. LoadFromFile returns defaults if the file is missing; throws if it exists and cannot be parsed.

Changing settings on a running server has no effect until Stop() then Start().

Embed in a host's settings tree:

[Category("Stream Deck"), DisplayName("Connection")]
public CompanionSettings StreamDeck { get; set; } = new CompanionSettings();

Serialises as one XML element (MdhStreamdeckCompanionSettings) and expands in a PropertyGrid.

WPF status bar item

<StatusBar>
  <companion:CompanionStatusBarItem x:Name="Item" FontWeight="Bold" />
</StatusBar>

Item.Settings = mySettings;
Item.StartRequested += (s, e) => server.Start();
Item.StopRequested  += (s, e) => server.Stop();

server.ClientCountChanged += n => Dispatcher.Invoke(() => Item.ClientCount = n);

Displays MDH Stream Deck (1) — the label plus the connected client count.

Appearance: Label, FontWeight, FontSize, FontFamily, Padding, and one brush property per state (RunningBackground, StoppedForeground, …).

Add host-specific menu items to the right-click menu, in XAML or in code. They render between Start/Stop and Properties.

<companion:CompanionStatusBarItem>
  <companion:CompanionStatusBarItem.HostMenuItems>
    <MenuItem Header="Open dashboard" Click="OnClick" />
  </companion:CompanionStatusBarItem.HostMenuItems>
</companion:CompanionStatusBarItem>

Item.HostMenuItems.Add(new MenuItem { Header = "Open dashboard" });

Threading

Actions, the state provider, OnLog, OnError and ClientCountChanged all run on Kestrel request threads. Marshal to the UI thread in your handlers:

.MapAction("start", _ => Dispatcher.Invoke(() => _app.StartTimer()))

Status

Not verified against a Stream Deck since the library moved repositories.