An App Package is a Blazor user interface hosted within the Instance. Apps are served at the route set in their configuration
(or the .defaultRoute in the manifest) and can use Radzen and TrakHound Blazor components.
Create an App
dotnet new trakhound.app
Pages inherit from TrakHoundComponentBase, which gives them access to the Instance:
@page "/"
@inherits TrakHoundComponentBase
@layout Layout
<h3>Machines</h3>
@if (count != null)
{
<p>@count records</p>
}
@code {
private int? count;
protected override async Task OnInitializedAsync()
{
var response = await Client.Services.KeyValues.Count("machines");
if (response.Success) count = response.Result;
}
}
Routes and Links
Page routes (@page "/") are relative to the App's route. Because an App can be configured at any route,
build links with the helper methods instead of hard coding paths:
| Method | Returns |
|---|---|
GetPath(destination) | The path to a page within the App (combined with the App's base path). |
GetUrl(destination) | A site-relative URL to a page within the App, with any Instance route rewrites applied. |
<a href="@GetPath("machines/details")">Machine Details</a>
Component Properties
| Property | Description |
|---|---|
Client | Client used to call APIs, run Functions, and read and write Services. |
Volume, Variables | The App's Volume and Variables. |
Session | The current user's session (and roles) when authentication is used. |
Parameters, GetParameter<T>() | The App configuration's parameters, with Configuration Variables replaced. GetConfigurationVariable(name) reads a Variable by name. |
Package, AppName | Information about the App. |
BaseUrl, BasePath | The App's base URL and path. |
Logger | Logger for the App. |
Override OnLocationChanged or OnLocationChangedAsync to respond to navigation within the App,
and call Refresh() to re-render.
Updates and Open Pages
When a new version of an App is installed, the Instance hot loads it without refreshing pages that are already open. Each open page shows a banner that an updated version is available, with Reload Now and Later buttons. If the user does neither, the new version loads the next time they change pages, or after a few minutes of inactivity. A page never reloads while an input has focus or after a field has been edited, so work in progress is not lost.
The Apps and App Connections pages in the admin UI (under Explorer) list every open App page and the Version it is running, marked Current or Retired. From these pages you can:
| Action | Description |
|---|---|
| Identify | Shows the connection's Code (4 characters), App, and client in the lower right corner of the page for 5 seconds, to match a screen to its connection. |
| Notify | Asks the page to reload when convenient. The page shows the update banner and reloads on its next page change or when idle. |
| Reload | Reloads the page immediately (confirmed with a second click). |
| Send Message | Shows a Message at the top of the page with a From name (default Administrator) and an Information or Warning type. It closes when dismissed or after a set number of seconds. |
Each action can be used for a single connection or for every open page of an App, and Notify and Reload can also target every connection still on a Retired Version. Messages are not stored, so only pages that are open when a Message is sent show it.
If a page loses its connection to the Instance (for example while the Instance restarts), it shows a reconnecting message with a countdown and retries automatically, or the user can click Retry Now. Disconnected pages are kept for a minute so they can reconnect without losing their state.
When a page throws an exception, the App shows an error message with a Request ID instead of the stack trace, and recovers on the next navigation. Search the Instance's logs for the Request ID to find the exception (the stack trace is only shown on the page in the Development environment).
@layout use the App's Layout component (a LayoutComponentBase named Layout, as in the template). Set @layout on a page to use a different one.
The App's stored theme is applied before the first paint, so pages don't flash the wrong theme. An App shows the Light theme until a user picks one;
to use Dark instead, add ".defaultTheme": "dark" to metadata in trakhound.package.json.
<TrakHoundProtectedView Permissions="..."> to show them only to users with those roles. See Security.
Page Views, Connections and Metrics
Every Instance records how its Apps are used: each browser tab connected to an App, the page it's on, and how long each page was viewed. Nothing needs to be added to the App. See Managing Apps on the Shop Floor for how to put this to use.
Page Views
A page view starts when a browser tab navigates to an App page and ends when it moves to a different page, leaves the App, or disconnects.
Changing only the query string (ex. a filter) continues the same view. Pages are grouped by their route template, so /orders/1234 and
/orders/5678 both count toward /orders/{id}.
| Recorded for | Values |
|---|---|
| Each App | Page views, open views, connections, total and average time on page, the longest view, when it was last viewed, and its CPU |
| Each page | Views, open views, total, average, and longest time on the page, and when it was last viewed |
| Each connection | The pages it viewed, how long it spent on each, and the page it's on now |
Totals are kept since the Instance started. The App list under Explorer > Apps shows each App's Views and Last Viewed, and Diagnostics > Metrics > Apps charts them live. Connections are recorded whether the browser connects with WebSockets or falls back to another transport.
Click an App in the list to open its page, with its Package details and pages. Its toolbar has the same actions as the App list: Refresh, Open, Access Log, Connections, Configuration, Identify, Notify Users, Send Message, Reload Pages, and Reload Configuration.
Access Log
Each completed page view is also written to the log history, under a logger for each App (access/apps/{packageId}), so there's a lasting record of
which stations viewed which pages and when. Open it from the App's Access Log action, or search Diagnostics > Logs:
Page View : /dashboard/line-1 (/dashboard/{id}) : Duration = 00:02:14.512 : App = Dashboard : Client = 192.168.1.20 (pc-104.local) : Code = K7QF : Connection = 0HNA1... : Agent = "Mozilla/5.0 ..."
Entries include the client's IP address, its hostname (looked up by reverse DNS), the connection's Code, and the browser. They're kept for as long as the Instance's log settings keep log history (30 days by default, then archived).
Active Connections
Diagnostics > Connections > App Pages lists every browser tab connected to an App right now. Recently closed connections stay in the list for 24 hours (up to 1,000), so recent visits can be reviewed.
| Column | Description |
|---|---|
| Code | A short code for the connection. Identify shows it on the screen, to match a terminal or display to its row |
| Client | The IP address and hostname of the computer, and its browser |
| App, Path | The App and page it's viewing now |
| Version | The App version the page is running, marked Current or Retired after an update |
| Status | Whether the page is in use, and so whether it's safe to reload (see below) |
| Status | Meaning | Safe to reload? |
|---|---|---|
| Editing | A text field or other input has focus | No |
| Unsaved | The page has unsaved changes (declared by the App, or input has been typed) | No |
| Active | Someone used the page in the last 5 minutes | Not yet |
| Idle | No interaction for 5 minutes or more | Yes |
| Background | The page is in a background tab or minimized window | Yes, unless it has unsaved changes |
| Unknown | The page hasn't reported its activity yet (ex. it's still connecting) | Check first |
From this page you can Identify, Notify, Reload, or Send Message to one connection or to every open page of an App (see Updates and Open Pages). The list flags connections still on a retired version, and summarizes how pages are being used (ex. 2 idle, 1 in use).
From Other Systems
The same information is available from the System API (protected by the system:apps resource), for plant monitoring and IT dashboards:
| Route | Returns or does |
|---|---|
GET /_apps/metrics | Metrics for every App (/_apps/metrics/{appId} for one) |
GET /_apps/metrics/connections | The open connections, with their pages and times |
GET /_apps/refresh/app/{appId} | Asks every open page of an App to refresh |
GET /_apps/refresh/connection/{connectionId} | Asks one connection's page to refresh |
Debugging
The App template includes a Program.cs that runs the App as a standalone Blazor application at http://localhost:5092, connected to the Instance in
trakhound.debug.json (localhost:8472). Run it with dotnet run to develop and debug the App before packing it.
It loads the Instance's stylesheets, Theme, and scripts, and gives your pages what the Instance does (Client, Volume, Variables, and parameters),
so pages look and behave the same as they will on the Instance. See Debugging & Testing.