Repository navigation
Development
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.
# 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 -- --headlessScreens 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 debugScreen logs land in logs/ beside the screen executable, one file per screen id per day.
cd src/KHost.UserInterface
npm run dev # runs dotnet watchRedirect the output so the IDE's bin/ isn't locked:
dotnet build KHost.slnx "-p:BaseOutputPath=./obj/_build"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→ scopedFoo.razor.css; the generated.cssis gitignored — never edit or commit it). - Shared blocks live under
wwwroot/scssand are pulled in viaapp.scss. Onlyapp.scssandthemes/*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 inlinestyleattributes, no<style>blocks. Bootstrap Icons only — no Bootstrap CSS/JS; its utility classes resolve to nothing.
- Interfaces live in
KHost.Abstractions, concrete types in their implementation project, registered in that project'sProjectExtensions(AddDomain()/AddDataAccess()/ …); UI-only services inProgram.cs. - Domain services are singletons — guard mutable state with
SemaphoreSlim. - Stateful services raise
StateChanged(EventHandler-style delegates, neverevent Action); components subscribe inOnInitialized, unsubscribe inDispose, and callStateHasChanged. - Services that expose configuration use the nested
ServiceOptionsclass pattern withBindConfiguration(ServiceOptions.SectionName)andIOptionsMonitor<>for live reload. - Every
Task/ValueTask-returning method ends inAsync— enforced by reflection inAsyncNamingConventionTests. - Component logic lives in a code-behind partial (
Foo.razor.cs), never an inline@codeblock. - 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 asnameof(...)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.
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):
- Delete
src/KHost.DataAccess/Migrations/and the runtime DB. dotnet ef migrations add InitialSchema --project src/KHost.DataAccess- Recreate the
AddMediaFtsmigration by hand — the FTS5 table and its triggers are raw SQL EF will not regenerate (search throwsno such table: media_ftswithout it). Copy theUp/DownSQL from a priorAddMediaFts.cs.
See CONTRIBUTING.md for the contribution workflow, license grant, and DCO sign-off requirements.
Starting points for the technologies KHost uses:
- .NET / C# — .NET docs, C# guide
- .NET Aspire — overview, AppHost
- Blazor Server — docs, component lifecycle, render modes
- Photino — docs, Photino.NET; HLS spec (RFC 8216)
- EF Core + SQLite — EF Core docs, SQLite provider, SQLite docs
- Media — FFmpeg docs, FFMpegCore, TagLib#
- Observability — Serilog, OpenTelemetry for .NET, HTTP resilience
- Testing — xUnit, NSubstitute, coverlet
- Styling — Sass guide, BEM, Bootstrap Icons
KHost
Architecture
- Architecture
- Projects
- Screens and Casting
- Break Music and Ads
- Messaging
- Data and Persistence
- Plugins
Contributing