Standalone Hosts

Run an API, Worker, or Function without an Instance, as a console app, service, IIS application, or container.
Framework Docs Menu

A Package runs on an Instance, but an API, a Worker, or a Function can also run on its own: as a console app, a Windows Service, a Linux (systemd) service, an IIS application, a container, or a cloud web app. A host project runs it with the standard .NET host, and the Package project itself doesn't change, so the same code can still be installed on an Instance.

Package project An API, Worker, or Function. Unchanged
Installed on an Instance With its routing, security, Zones, metrics, and admin UI
Host project th host create: runs it with the standard .NET host
ConsoleWindows ServicesystemdIISContainerCloud web app
Instance (optional) The host's Client connects to it for Services and Functions
The same code runs on an Instance or on its own, so a module can move between them without changes.

Use a standalone host when a module needs to run where there's no Instance, for example:

  • An API in a cloud web app or a container platform your organization already uses
  • A Worker on a PC next to a machine, as a Windows Service or systemd service
  • A Function run by Task Scheduler, cron, or a container job

Create a Host

In the Package project's folder, run:

th host create --api-key
dotnet run --project ../MyCompany.MyApi.Host

th host create creates a host project next to the Package project, named after it with .Host. It picks the kind of host from the Package's category, finds the module class, copies trakhound.debug.json into the host's appsettings.Development.json, and with --api-key generates an API key for an API host, adds its hash to appsettings.json, and prints the key. Or create it with the template:

dotnet new trakhound.host -n MyCompany.MyApi.Host --module MyCompany.MyApi --kind api

--kind is api, worker, or function. The host has a Program.cs, its settings in appsettings.json, and a Dockerfile (build it from the parent folder: docker build -f MyCompany.MyApi.Host/Dockerfile .).

API Hosts

An API host's Program.cs:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddTrakHound(builder.Configuration.GetSection(TrakHoundHostOptions.SectionName));
builder.Services.AddTrakHoundApiKeyAuthentication();
builder.Services.AddHealthChecks().AddTrakHoundInstance();
builder.Services.AddWindowsService(); // Runs as a Windows Service or a systemd service when started as one
builder.Services.AddSystemd();

var app = builder.Build();
var api = app.MapTrakHoundApi(typeof(Controller).Assembly);
api.Group.RequireAuthorization(); // Every endpoint and stream needs an API key
app.MapTrakHoundOpenApi(api);     // The OpenAPI document at /openapi.json
app.MapHealthChecks("/health");
app.Run();
  • MapTrakHoundApi creates the API's controllers and maps their endpoints and streams the same way the Instance does.
  • Callers send one of the host's API keys in the X-API-Key header (or Authorization: Bearer {key}). These aren't the Instance's API keys, and an API host refuses every request until it has one. Any other ASP.NET Core authentication can be added instead.
  • The host serves its OpenAPI document at /openapi.json, named and versioned from the Package, and a health check at /health.

Worker and Function Hosts

  • Worker - AddTrakHoundWorker<Worker>() starts the Worker when the host starts, and stops it when the host stops.
  • Function - RunTrakHoundFunction<Function>() runs the Function once, writes its response (JSON) to the console, and exits with 0 when the run succeeds, for Task Scheduler, cron, or a container job. MapTrakHoundFunction<Function>("/run") runs it for each POST instead.
  • Service - AddTrakHoundService<Service>() adds a Service for your own code to call.

Settings

The settings are the "TrakHound" section of appsettings.json, environment variables (ex. TrakHound__InstanceUrl), or the command line (ex. --TrakHound:Parameters:interval=1000):

{
  "TrakHound": {
    "InstanceUrl": "https://instance.example.com",
    "ApiKey": "...",
    "ConfigurationId": "barcodes",
    "ApiKeys": [ { "Name": "line-1", "Hash": "..." } ],
    "Parameters": { "interval": "1000" }
  }
}
SettingWhat it does
InstanceUrlThe Instance the Client connects to. Without it, the module runs on its own and every Client call fails with an error that says so
ApiKey, BearerTokenCredentials for the Instance
ConfigurationIdThe module's configuration ID (default when not set)
VolumePath, VariablesPathWhere the Volume and Variables are kept, relative to the application's folder
ParametersThe configuration parameters. Values are strings, and GetParameter<T> converts them
ApiKeysAPI hosts: the keys callers send. Each has a Name (the signed in user) and the key's SHA-256 hash in Hash, or the key itself in Key when it comes from a secret store
InputFunction hosts: the input parameters of the run

The host connects to the Instance when it starts. If it can't be reached, a warning is logged, the module still starts, and the health check reports Degraded. What the module logs goes to ILogger, so the host's log providers (the console, the Windows Event Log, or Application Insights) receive it.

Compared with an Instance

A standalone host runs one module with only what the host project sets up. The Instance's admin UI, security profiles, Zones, metrics, and Package updates don't apply to it, so a module that many people use or that changes often is usually easier to manage on an Instance (see Architecture for Plant Teams).

Not supported yet: Apps, Identity providers, and signing in with an Instance's users. An API host uses its own API keys, or any ASP.NET Core authentication you add.