Skip to content

Messaging

Michael Riddle edited this page Aug 24, 2026 · 1 revision

Messaging

Services and components in the host talk through IMessageBroker rather than through C# events. It lives in KHost.Plugins.Sdk/Messaging/, not Abstractions, so a plugin can subscribe to what the show is doing.

There is no StateChanged event and no IKHostService — a service that has something to report takes IMessageBroker in its own constructor. The services that never report anything take nothing.

Publishing

_broker.Announce(new PlaybackChanged());          // fire and forget
await _broker.PublishAsync(new SomethingHappened()); // wait for every handler

Announce is for a message that only means "this moved, redraw" — a publisher that waited for every component to finish rendering would stall the show to do it. PublishAsync is for the case where the publisher's next decision depends on what the handlers did: playback awaits the end-of-performance gap so an ad can claim it before break music comes back.

Subscribing

[Inject] private IMessageBroker Broker { get; set; } = default!;
private readonly SubscriptionSet _subscriptions = new();

protected override void OnInitialized()
    => _subscriptions.Add(Broker.Subscribe<PlaybackChanged>(_ => InvokeAsync(StateHasChanged)));

public void Dispose() => _subscriptions.Dispose();

A missed unsubscribe keeps the subscriber alive on the broker, which for a Blazor component means holding its whole circuit. SubscriptionSet exists so one Dispose drops all of them.

Guarantees

  • Handlers run one at a time, in subscription order. What one handler does can decide what the next is allowed to do, and a show where an ad and break music race for the room cannot be reproduced.
  • A handler that throws is logged and skipped. A broken subscriber must not stop the queue reaching the next singer.
  • Routing is on the message's runtime type, and exact — a handler for a base type is not called for a derived one.
  • Never take a lock around a publish. ScreenConnected arrives on the SignalR hub thread already holding one, which is why those handlers detach with _ = Task.Run(...).

The messages

Empty records in KHost.Plugins.Sdk.Messaging.Messages, one per service, named for the fact: PlaybackChanged, BreakMusicChanged, AdsChanged, SingerQueueChanged, PerformancesChanged, ScreensChanged, MediaLibraryChanged, MediaImportChanged, MediaPoolsChanged, VenuesChanged, SelectedVenueChanged, UsersChanged, UserGroupsChanged, TipsChanged, DownloadsChanged, PluginsChanged, FlashChanged, CastChanged. Two carry data: BreakMusicTrackChanged names the provider, and ThemeChanged lives in the UI project because what the console looks like is nobody else's business.

VenuesChanged and SelectedVenueChanged are not interchangeable. The first says the list moved and is for the UI. The second says the console is now running a different venue, or the one it is running was edited — that is the one anything pushing settings to screens must take, because the venue carries the room's audio baseline. Subscribing screen or audio code to VenuesChanged means editing an unrelated venue's phone number re-pushes volume to every screen mid-song.

What is still an event, and why

  • Screen2's IMediaPlayer and IScreenClient — Screen2 is a separate process. The broker is in-process; SignalR is the transport, and pretending otherwise would hide the network.
  • IDialogService.ShowRequested — a request with a payload and one legitimate subscriber, not a notification.
  • IPlaybackService.PositionChanged — twice a second all night, and it says only that Position moved. Take it to redraw a playhead and nothing else.

Clone this wiki locally