Apps

Build Blazor user interfaces hosted within the Instance.
Framework Docs Menu

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.

New version installed (ex. 1.4.0)The Instance loads it without restarting; new visitors get it right away
Open pages keep running 1.3.2They show a banner: An updated version is available, with Reload Now and Later
Nothing is refreshed out from under someone using the page
Reload Now, the next page change, or a few minutes idle
The page reloads on 1.4.0Never while a field is being edited
Pages that lose their connection reconnect on their own
Admin UI: Apps and App Connections See every open page and the version it runs, then Identify, Notify, Reload, or Send Message to one page or all of them
Displays and operator stations that stay open all day pick up new versions at a convenient time.

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:

MethodReturns
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

PropertyDescription
ClientClient used to call APIs, run Functions, and read and write Services.
Volume, VariablesThe App's Volume and Variables.
SessionThe 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, AppNameInformation about the App.
BaseUrl, BasePathThe App's base URL and path.
LoggerLogger 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:

ActionDescription
IdentifyShows 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.
NotifyAsks the page to reload when convenient. The page shows the update banner and reloads on its next page change or when idle.
ReloadReloads the page immediately (confirmed with a second click).
Send MessageShows 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).

Pages without @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.
Wrap parts of a page in <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 forValues
Each AppPage views, open views, connections, total and average time on page, the longest view, when it was last viewed, and its CPU
Each pageViews, open views, total, average, and longest time on the page, and when it was last viewed
Each connectionThe 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.

ColumnDescription
CodeA short code for the connection. Identify shows it on the screen, to match a terminal or display to its row
ClientThe IP address and hostname of the computer, and its browser
App, PathThe App and page it's viewing now
VersionThe App version the page is running, marked Current or Retired after an update
StatusWhether the page is in use, and so whether it's safe to reload (see below)
StatusMeaningSafe to reload?
EditingA text field or other input has focusNo
UnsavedThe page has unsaved changes (declared by the App, or input has been typed)No
ActiveSomeone used the page in the last 5 minutesNot yet
IdleNo interaction for 5 minutes or moreYes
BackgroundThe page is in a background tab or minimized windowYes, unless it has unsaved changes
UnknownThe 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:

RouteReturns or does
GET /_apps/metricsMetrics for every App (/_apps/metrics/{appId} for one)
GET /_apps/metrics/connectionsThe 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
App metrics can be turned off in Settings > Metrics (they're applied after a restart). The Access Log records client addresses and hostnames, so review it against your organization's policies for monitoring workstations.

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.