SubZeroDev.Platform.Updater 0.1.0

SubZeroDev.Platform.Updater

UI-independent Windows x64 desktop updates for .NET 10, backed by Velopack 1.2.161 and public GitHub Releases.

Call Velopack.VelopackApp.Build().Run(); as the first operation in your executable's Main, before any single-instance guard or UI. Create one UpdaterClient after startup, observe StartAutomaticCheckAsync, and marshal StateChanged to your UI dispatcher. Unpackaged development executables report UnsupportedInstallation.

The host implements IUpdateRestartCoordinator. Return Defer while settings or critical work are open. For Ready, stop detection/work, dispose the tray and release the instance guard. If the update cannot be scheduled after that, the updater calls RestartAbortedAsync: restore detection, tray and instance guard so the current version keeps running (it can follow a partial quiesce, so make it idempotent). The staged update stays available to RetryPendingRestartAsync. Automatic installs never throw from StartAutomaticCheckAsync; a failure comes back as a result with ShouldPrompt set. After the updater reaches Completed, exit the process normally: Velopack waits for exit before applying the verified package and restarting. Never wait for updater shutdown from the UI thread that the coordinator needs.

Preferences are stored atomically in the caller's settings directory. Automatic checks default on, Stable, with explicit consent for every installation and a persisted fifteen-minute attempt interval. Manual checks bypass those preferences and receive their own visible result. A cancelled waiter does not cancel a shared check; disposal cancels the underlying operation. Download cancellation leaves the running application intact. If preferences cannot be saved, the check result still stands and the attempt interval is enforced in memory. While an update is being installed or is staged, checks return UpdateInProgress with that candidate instead of offering another update or waiting for the install.

InstallAsync(candidate, rememberAutomaticConsent: true) records consent only as part of an explicit install action. SavePreferencesAsync can revoke it. DeferAsync suppresses automatic prompts for the same version for 24 hours. RetryPendingRestartAsync retries a staged update when the host becomes idle. Both return an InstallOutcome: RestartScheduled, Deferred (the update stays staged), or NoPendingUpdate. When a restart is scheduled the target version is recorded, and UpdaterClient.CreateAsync confirms it on the next start; if the old version is still running, the client reports Failed and suppresses automatic prompts for that version for 24 hours. Disposal waits at most ten seconds for an unresponsive restart coordinator.

Stable releases use vX.Y.Z and win-stable; previews use vX.Y.Z-preview.N and win-preview. Preview clients examine both channels and never downgrade. Releases must contain matching full packages and SHA-256 feed entries. Those hashes only prove a package matches its own release, so anyone who can write releases controls both. Set UpdaterOptions.PackageSigningKey to the publisher's ECDSA P-256 public key (PEM or base64 SubjectPublicKeyInfo) to require a <package>.sig signature from the matching private key; unsigned or foreign-signed releases are then never offered. Without a key, InstallAutomatically consent still prompts before each installation instead of installing silently. Release notes are untrusted text, never active HTML. No access token is accepted or embedded in clients. GitHub sees normal HTTPS request metadata, including IP address; there is no application telemetry.

See docs/consumer-guide.md for integration, CHANGELOG.md for changes, and samples/WpfTrayHost and samples/WinUIHost for working hosts. Users only ever see fixed messages, never exception text. A Retry-After from GitHub pauses automatic checks (manual checks still run). Downloads follow at most five redirects, stay on GitHub hosts, and are capped at the size the release declares. The preferences file keeps unknown fields and newer schema versions.

Build

Use the .NET 10 SDK on Windows. dotnet test runs deterministic tests. dotnet pack src/SubZeroDev.Platform.Updater -c Release -o artifacts/packages creates the library and symbols packages. Samples restore the actual package from that local feed or nuget.org.

Licensed under the MIT License. NuGet publication uses trusted publishing; the initial package is published once that is configured. See docs/release-guide.md for release and validation instructions.