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.
th host create: runs it with the standard .NET host
Client connects to it for Services and FunctionsUse 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();
MapTrakHoundApicreates 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-Keyheader (orAuthorization: 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" }
}
}
| Setting | What it does |
|---|---|
InstanceUrl | The 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, BearerToken | Credentials for the Instance |
ConfigurationId | The module's configuration ID (default when not set) |
VolumePath, VariablesPath | Where the Volume and Variables are kept, relative to the application's folder |
Parameters | The configuration parameters. Values are strings, and GetParameter<T> converts them |
ApiKeys | API 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 |
Input | Function 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).