Table of Contents

Updating HiNC on Windows

A copy of HiNC put in place by a Windows setup program, such as HiNC-2025-webservice-win-Setup.exe, or by a portable package, such as HiNC-2025-webservice-win-Portable.zip, updates itself from the menu bar: it checks what the update servers offer, and downloads and installs a version when you ask for one. The dongle package and the cloud package take their versions from folders of their own on the update servers, win and win-cloud, so an update never turns one into the other. This page covers the update badge, the Software Update dialog, how a version is installed, the update settings, a classroom mirror, and updating a computer that runs several stations; installing HiNC, its data folder and its settings file are on Installing HiNC on Windows.

Installed copies and other copies

A copy put in place by the setup program or the portable package is an installed copy: it can check for new versions, download one — an older one included — and restart into it. It keeps the update choices made in the dialog in update-state.json in its data folder: the automatic-check switch and the Offer choice.

A copy of the installed HiNC's program, HiNC-2025.exe, put in place any other way — a folder copied by hand out of an installation, say — can still check what the update servers offer and list their versions, but it cannot install one: the Software Update dialog says so in a grey banner, its versions table carries no Install buttons, and the HTTP interface refuses an install with NotInstalled. It keeps no update choices across a restart.

The HiNC-2025-webservice sample — the web service on its own, as a server deployment runs it or dotnet run starts it from source — has no update check at all: its version mark shows the version only, its Help menu ends at Log Viewer, and it serves no api/app-update (see Hosting from another project).

The update badge

The version mark at the left end of the menu bar, v followed by the running version, is also the update badge. Its colour, icon and tooltip follow the update state:

State Badge Tooltip
Not checked yet grey outline Not checked for updates yet. Click to check.
Up to date green outline, tick Up to date (checked …).
Servers unreachable grey outline, cloud crossed out The update servers could not be reached (…).
Newer version offered orange, upward arrow, v<current> → <new> Version … is available. Click to update.
Downloading orange, the percent Downloading version …: …%
Preparing orange, preparing… and, where measured, the step's percent Download complete; preparing version ….
Download failed, waiting to retry grey, clock The last download failed; retrying at ….
Downloaded, waiting to be applied orange, restart icon, v<current> → <new> Version … is downloaded. Click to restart and apply it.
Restarting orange, turning arrows Restarting into version …
Running version recalled red This version was recalled: …

A click on the badge opens Software Update in every state; nothing is checked, downloaded or applied from the badge itself. Help ▸ Check for Updates… opens the same dialog. The page reads the update state once a minute, every second while a check or a download runs, and reloads itself when the service comes back on another version, so the new front end loads with it.

The Software Update dialog

The dialog opens with the current version and Check Now, then a line naming when the last check ran and the configured name of the server that answered it — or, after a check no server answered, saying so. Opening the dialog does not check; Check Now does, whatever the automatic-check switch says. It is unavailable when no update server is configured, and for 30 seconds after each check asked for from the same page — its tooltip says when it may be pressed again.

Below that, as they apply: the grey banner of a copy that cannot install; a grey banner when no server is configured; a red banner when the publisher has recalled the running version, giving the reason and offering Install … instead; the state of a download in progress; Version … is available. when a newer version is offered, with Update to … on an installed copy; or This computer has the newest version offered to it. A failed check or download leaves its reason on an orange Last problem line, in English whatever the interface language.

Two settings follow. Check for updates automatically switches the automatic checks, and Offer chooses between Stable versions and All versions, previews included. An installed copy keeps both choices in its data folder, where they take precedence over the defaults in the settings.

Versions lists every version the last check found, newest first, with its date, status, note and download size, whatever Offer says. The running version's row is highlighted and marked Running; on an installed copy, every other version with a full package carries Install — which is also how a teacher brings a whole class to one version.

Status Meaning
Stable promoted by the publisher; offered to every installation, on either Offer choice
Preview published for those who take every version; offered only on All versions. A version the publisher's table does not list counts as a preview. When the publisher promotes a version to stable, the previews older than the newest stable version are taken off the update servers: Versions no longer lists them, not even on a computer running one, and they can no longer be installed, while a computer running one updates as usual
Recalled withdrawn: never offered and not installable, and listed only while it is the version running

A version the publisher recalls keeps running wherever it is installed. The badge turns red, and the banner's Install … instead installs the newest version offered to this installation — possibly an older one. Nothing changes until it is pressed.

Installing a version

  1. Press Update to …, Install … instead, or Install on a row. The confirmation reads HiNC downloads version … and restarts when the download is done. This page reconnects by itself. For a version older than the running one it adds Projects saved by the newer version may not open in it.
  2. The download shows its percent, with Cancel Download beside it.
  3. When the download carried only the changes from the installed version, HiNC then prepares the new version: the changes are applied to the installed version and the package is rebuilt, in three steps — unpacking the installed version, applying the changes, packing the new version. This takes 20 seconds to a minute and cannot be cancelled.
  4. The downloaded version is applied at once — unless a run is in progress, or other stations run from the same installation. Then it waits, the badge shows v<current> → <new>, and the dialog offers Restart and Apply. Pressing it asks Restarting now stops the run. Restart anyway?, or lists the stations that applying the update will close; Restart Anyway goes ahead.
  5. HiNC restarts into the new version, which usually takes 20 to 40 seconds, with the same command line it was started with, and the page reloads when it is back. The cloud package comes back signed in as before, whether or not the computer is remembered, except after an update from 3.2.51 or earlier on a computer that is not remembered (see Signing In with a Cloud Account).

A downloaded version is never applied by itself at the next start. After a restart a newer one is offered for applying again; an older one is not, and is installed again from its row. If the switch to the new version did not complete — a program other than HiNC holding a file in the installation folder, such as a command prompt opened there — the old version starts again and Last problem says so. Close that program and install the version again: Restart and Apply when the dialog offers it, otherwise Install on its row.

Checking by itself, and retrying

Only an installed copy checks by itself, and only while Check for updates automatically is on: first 1 to 10 minutes after it starts, then every ScanIntervalHours, each wait shifted by up to 10% so that installations started together do not check together. Switching the setting on checks at once. A check reads two small index files from the first server that answers, and never downloads a version: a download starts only when a user asks for one.

Servers are tried in ascending Priority, and in random order among servers of equal priority. When a download fails on every server, it is queued and retried after 1, 2, 4 and 8 minutes and then every 15, each wait scaled at random between 0.7 and 1.3; after twelve failed attempts it gives up, and the version has to be installed again later. While it waits, the dialog reads The last download failed. HiNC retries by itself at … (retry …), and Cancel Download withdraws it. Keep HiNC running meanwhile.

The Update settings section

The Update section ships in HiNC-2025.settings.json in the program folder, which every update replaces. Change it in appsettings.local.json in the data folder, which is read after it (see Changing a setting). Key by key:

Key Meaning Default
ScanEnabled whether an installed copy checks by itself true
ScanIntervalHours hours between automatic checks 24
Track Stable or Latest — the Offer setting Stable
Servers the update servers, by a name of the operator's choosing the four servers HiNC-2025.settings.json names
Servers:<name>:Url the feed folder: an http/https address, or a local or \\server\share folder; blank disables the entry —
Servers:<name>:Priority lower is tried first 1

ScanEnabled and Track are defaults only: once the dialog has changed either, the choice kept in the data folder wins. Servers is keyed by name so that appsettings.local.json can add a server, or disable a shipped one by giving its name an empty Url, without restating the others. The shipped entries are named after their hosts — the four addresses the installer downloads from on Installing HiNC on Windows, each at its package's own folder, tried in that order — so "superhightech.com.tw": { "Url": "" } switches off the last of them.

A classroom mirror

When a whole class updates through one internet connection, a copy of the update on the local network spares downloading the same version once per computer.

  1. Make a shared folder the class's computers can read, such as \\teacher-pc\hinc-update\win — for the cloud package, a folder of its own such as \\teacher-pc\hinc-update\win-cloud: the two packages keep their version tables under the same name, so they cannot share one. A folder on an internal web server works as well.

  2. Copy into it, from the package's folder on the update server — https://hinc-1.superhightech.com.tw/hinc-update/win/, or …/hinc-update/win-cloud/ for the cloud package:

    • releases.win.json (cloud package: releases.win-cloud.json) and hinc-versions.json;
    • HiNC-2025-webservice-<version>-full.nupkg (cloud package: HiNC-2025-webservice-<version>-win-cloud-full.nupkg) for the version the class is to get;
    • HiNC-2025-webservice-<version>-delta.nupkg (cloud package: HiNC-2025-webservice-<version>-win-cloud-delta.nupkg) for that version and for each version between it and the one the class runs now. A computer updates with these change-only packages whenever it can, one version behind included.

  3. On each computer, add the mirror to appsettings.local.json, with the folder of step 1 as its Url, and restart HiNC:

    {
  "Update": {
    "Servers": {
      "Classroom": { "Url": "\\\\teacher-pc\\hinc-update\\win", "Priority": 0 }
    }
  }
}

    JSON doubles every backslash. The dialog now reports its checks via Classroom.

  • The full package serves the computers that cannot use the change-only ones: a computer more than ten versions behind, one going back to an older version, one whose change-only update fails. Whatever the mirror does not hold — the change-only package of an older version, for instance — comes from the internet servers.
  • A mirror that cannot be reached, or holds no version, is passed over for the internet servers, and the service log records the check that passed it over, with the reason.
  • While the mirror answers, HiNC takes the version list and every version's status from it alone. Copy the two .json files again whenever the publisher releases, promotes or recalls a version: an old copy hides a recall from the whole class, and keeps listing the previews a promotion took off the update servers.
  • A mirror of one package offers nothing to the other: a cloud-package computer pointed at a mirror of the dongle package passes it over, as it does a mirror holding no version.

Several stations on one installation

Extra stations run from the same installation, each started with --environment <name> under the rules of Multi-Station Setup. They share the data folder and the update choices. Only one station at a time downloads or applies an update, a version waiting on one station is dropped when another downloads a different one, and applying an update closes every station of the installation while only the station that applied it starts again — Updates with several stations gives the rules and the dialogs.

The HTTP interface

The badge and the dialog run on api/app-update, which only the installed HiNC's program, HiNC-2025.exe, serves. The HiNC-2025-webservice sample has no such route: a GET there answers 404. See Driving the Web Service over HTTP for calling the service.

Method Path Does
GET api/app-update/status the update state: currentVersion, installed, serversConfigured, scanEnabled, track, checking, lastCheckedAt, lastCheckSucceeded, lastError, lastServer, newestOffered, updateAvailable, currentRecalled, currentNote, phase (Idle, Downloading, Queued, Downloaded, Applying), targetVersion, progress, stage (Transfer, Rebuild), rebuildStep, rebuildPercent, attempt, nextRetryAt
GET api/app-update/versions every version the last check found, newest first: version, status, date, note, fullSize, downloadable, offered, isCurrent
PUT api/app-update/settings body { scanEnabled, track }, either omitted to leave it; answers the status
POST api/app-update/check checks the servers now; answers the status
POST api/app-update/install body { version, restartWhenDone } (restartWhenDone defaults to true); answers the status
POST api/app-update/apply body { force }; 202 once the restart is under way
POST api/app-update/cancel cancels a running or queued download; answers the status

lastServer is the configured name of the server that answered the last check, and null after a check no server answered.

install, apply and cancel refuse with 409 and a body { success: false, code, message }:

code Refused because
NotInstalled this copy of HiNC-2025.exe was not put in place by the setup program or the portable package
UnknownVersion the servers do not offer that version (unknown, recalled, or without a package)
AlreadyCurrent that version is the one running
Busy a download or a restart is already under way
NothingDownloaded no downloaded version is waiting to be applied — or another station of the installation has since downloaded a different one, which lastError then says
SessionBusy a run is in progress or paused; force overrides
OtherStationsRunning other stations run from the installation; the body adds stations, and force overrides
UpdaterFailed the updater could not be started; nothing changed, and the reason is in lastError
CannotCancelNow the package is being rebuilt, which cannot be stopped

See Also