Skip to content

Development

Michael Riddle edited this page Aug 19, 2026 · 6 revisions

Development

Prerequisites

Everything in Getting Started — the .NET 10 SDK, Node.js 18+ with npm, and FFmpeg on PATH — plus:

  • (Optional) Docker Desktop — for the Aspire dashboard's local telemetry when running via KHost.AppHost.
  • (Optional) ffprobe — ships with FFmpeg; the transcode tests use it to assert a segment really carries audio.
  • (Optional) Chromecast-Emulator listening on 127.0.0.1:8009 — the Cast tests skip without it.

Running for development

# With the Aspire dashboard (telemetry, resource view)
dotnet run --project src/KHost.AppHost

# The Blazor UI directly
dotnet run --project src/KHost.UserInterface

# Headless (no native window; serve the console to a browser)
dotnet run --project src/KHost.UserInterface -- --headless

Screens are normally launched from the host's Screens dialog, which injects the host's live listening address as --server-uri. To run one by hand:

# --screen-id defaults to the machine name
dotnet run --project src/KHost.Screen2 -- --server-uri http://localhost:5251/ipc/screen --screen-id main

# --log-level debug adds the state the page reports each tick (position, expected
# position, readyState) — how to tell a screen that is behind from one that never started
dotnet run --project src/KHost.Screen2 -- --server-uri http://localhost:5251/ipc/screen --log-level debug

Screen logs land in logs/ beside the screen executable, one file per screen id per day.

Hot reload

cd src/KHost.UserInterface
npm run dev           # runs dotnet watch

Building alongside Visual Studio

Redirect the output so the IDE's bin/ isn't locked:

dotnet build KHost.slnx "-p:BaseOutputPath=./obj/_build"

SCSS

SCSS compiles inside dotnet build (AspNetCore.SassCompiler) — there is no separate sass step. The build needs node_modules (npm install in src/KHost.UserInterface/) for copy:vendors.

  • Component styles live beside their component (Foo.razor.scss → scoped Foo.razor.css; the generated .css is gitignored — never edit or commit it).
  • Shared blocks live under wwwroot/scss and are pulled in via app.scss. Only app.scss and themes/* should lack a _ prefix — any other file without one compiles to its own stylesheet.
  • Top-level class names are prefixed kh-, with BEM naming. No inline style attributes, no <style> blocks. Bootstrap Icons only — no Bootstrap CSS/JS; its utility classes resolve to nothing.

Code conventions

  • Interfaces live in KHost.Abstractions, concrete types in their implementation project, registered in that project's ProjectExtensions (AddDomain() / AddDataAccess() / …); UI-only services in Program.cs.
  • Domain services are singletons — guard mutable state with SemaphoreSlim.
  • Stateful services raise StateChanged (EventHandler-style delegates, never event Action); components subscribe in OnInitialized, unsubscribe in Dispose, and call StateHasChanged.
  • Services that expose configuration use the nested ServiceOptions class pattern with BindConfiguration(ServiceOptions.SectionName) and IOptionsMonitor<> for live reload.
  • Every Task/ValueTask-returning method ends in Async — enforced by reflection in AsyncNamingConventionTests.
  • Component logic lives in a code-behind partial (Foo.razor.cs), never an inline @code block.
  • Member order: fields → events → properties → public → protected → private → nested types.
  • Method names that cross a string boundary ([JSInvokable] called from JS, SignalR hub methods invoked by name) are passed as nameof(...) from C# and taken as a parameter on the JS side, so a rename cannot break silently.

The full conventions, including agent-facing gotchas, live in AGENTS.md in the repository.

Schema changes

Venue.Settings is a JSON column — adding/removing properties on VenueSettings is not a schema change and needs no migration reset. But EF reads keys missing from stored rows as default, ignoring property initializers, so a new setting that must default to true needs a data-only json_set backfill migration.

Real schema changes (any DbSet<T> model):

  1. Delete src/KHost.DataAccess/Migrations/ and the runtime DB.
  2. dotnet ef migrations add InitialSchema --project src/KHost.DataAccess
  3. Recreate the AddMediaFts migration by hand — the FTS5 table and its triggers are raw SQL EF will not regenerate (search throws no such table: media_fts without it). Copy the Up/Down SQL from a prior AddMediaFts.cs.

Contributing

See CONTRIBUTING.md for the contribution workflow, license grant, and DCO sign-off requirements.

Learn more

Starting points for the technologies KHost uses:

Clone this wiki locally