Menu ▾ ▴

Update Internals

Bayram Emekli

Update Internals

Sucrose.Update.exe is the WPF process that checks for, downloads, and launches a new version of Sucrose. Internally it is a strict, sequential pipeline of "step" methods — each step must succeed before the next runs — that resolves the release list, compares versions, finds the matching installer asset, downloads it (with optional speed limiting), and then either extracts and runs it or runs it directly. The behavior is shaped by a handful of enum-typed settings (server, channel, module, extension, auto mode) and a short HTTP cache. This page documents that pipeline for developers. For the user-facing description of update modes and how to trigger updates, see Updating Sucrose.

Contents

Launch and visibility

Sucrose.Update.exe is launched through Commandog:

✔Update✖<path-to-Sucrose.Update.exe>          (manual check, visible)
✔Update✖<path-to-Sucrose.Update.exe>✖False    (silent background check)

On startup (App.OnStartup → Configure):

  • Single-instance guard via the {Sucrose-Wallpaper-Engine-Update} mutex (see Single-Instance & Mutexes).
  • Sets the setting Update.State = false on start and again on close.
  • The AutoType (the UpdateAutoType setting) defaults to Visible when no args are passed; with args it reads SSDMMU.AutoType.
  • If AutoType is not Visible, the window is hidden for silent checks (Opacity = 0, ShowInTaskbar = false).

The update pipeline (steps)

MainWindow.Start runs gated steps with roughly 1 second between each; a step returning false aborts the chain:

Order Step What it does
1 StepCache Clear and recreate the cache directory (Internal.CachePath).
2 StepNetwork Network.GetHostEntryAsync; on success applies security, records Update.Time = now, and (if TelemetryData) POSTs update telemetry.
3 StepReleases Fetch the release list from the configured server (GitHub or Soferity).
4 StepRelease Pick the newest release; if the channel is Release, skip pre-releases (!PreRelease).
5 StepComparing Version.Compare(current, latest); continue only if Latest (a newer version exists).
6 StepSearching Find the matching installer asset by name pattern; set Internal.Source = the download URL and Bundle = the cache path.
7 StepSilent Only for SemiSilent: reveal the previously hidden window now that an update is confirmed.
8 StepDownloading Download the asset via the chosen module, driving a progress ring + taskbar progress.
9 StepExtracting / StepRunning After download, by extension type: Compressed → extract the 7-Zip then run the extracted .exe; Executable → run the installer directly. 
flowchart TD
    S1["1. StepCache<br/>clear / recreate cache"] --> S2["2. StepNetwork<br/>connectivity + telemetry"]
    S2 --> S3["3. StepReleases<br/>fetch release list (GitHub / Soferity)"]
    S3 --> S4["4. StepRelease<br/>pick newest (skip pre-release on Release)"]
    S4 --> S5{"5. StepComparing<br/>newer version?"}
    S5 -->|no| Abort["abort — already up to date"]
    S5 -->|yes| S6["6. StepSearching<br/>match installer asset"]
    S6 --> S7["7. StepSilent<br/>SemiSilent: reveal window"]
    S7 --> S8["8. StepDownloading<br/>Native or Downloader + progress"]
    S8 --> S9{"9. ExtensionType"}
    S9 -->|Compressed| Ext["StepExtracting<br/>extract 7-Zip, run .exe"]
    S9 -->|Executable| RunEx["StepRunning<br/>run installer (/s if CompleteSilent)"]

Each step must return true to proceed; any step returning false aborts the chain.

Settings and enums

The pipeline is driven by these enum settings (verified enum members):

Setting Enum members Default / notes
UpdateServerType GitHub, Soferity Where the release list comes from.
UpdateChannelType Release, PreRelease Release skips pre-releases.
UpdateModuleType Native, Downloader Download engine (see below).
UpdateExtensionType Compressed (.7z), Executable (.exe) Determines extract-then-run vs. run-directly.
UpdateAutoType Visible, SemiSilent, UpdateSilent, CompleteSilent Window visibility + silent-install behavior. The persisted setting defaults to SemiSilent; Visible is only the in-process fallback used when Sucrose.Update.exe is launched with no args (a manual UI check).

The UpdateAutoType modes in practice:

  • Visible — window shown; user watches the progress.
  • SemiSilent — hidden until an update is found, then revealed via StepSilent.
  • CompleteSilent — runs the installer with the /s silent switch.

The release list is fetched per server type:

  • GitHub — Skylark.Standard.Helper.GitHub.ReleasesList(owner, SucroseRepository, UserAgent, PAT). The UserAgent and optional 93-character PersonalAccessToken come from the Settings → Other page (the PAT raises GitHub's anonymous rate limit).
  • Soferity — …/v8/Kernel/Release on the Soferity v8 backend.

Asset name pattern

StepSearching selects the installer asset by matching its file name against the pattern:

Sucrose_Bundle_<Framework>_<Arch>_<Version><ExtensionDescription>

For example, the .NET Framework 4.8 x64 compressed asset matches Sucrose_Bundle_.NET_Framework_4.8_x64_<version>.7z, and the executable asset ends in .exe. If no asset matches the configured framework, it falls back to the default framework. The matched asset's BrowserDownloadUrl becomes Internal.Source. See Installation for the same naming on GitHub releases.

Download modules and speed limiting

StepDownloading supports two UpdateModuleType engines:

  • Native — a manual HttpClient streaming download with an optional speed limit from the Update.LimitValue / LimitType settings (default download limit ≈ 500 MB).
  • Downloader — the Downloader NuGet package, configured with DownloadConfiguration and a MaximumBytesPerSecond cap.

Both drive the on-screen progress ring and the Windows taskbar progress indicator.

Install: extract vs. run

After a successful download, the install path depends on UpdateExtensionType:

  • Compressed → StepExtracting: validate and extract the 7-Zip archive (SevenZip.Helper.Zip.CheckArchive + Extract), then run the extracted .exe.
  • Executable → StepRunning: run the downloaded installer directly.

When AutoType == CompleteSilent, the installer is launched with "/s" for an unattended install.

The window's Reload button (Reload_Click) hands the pending installer off to Commandog instead of running it inline:

✔Bundle✖<path-to-installer.exe>

For a Compressed download, the extension is swapped to the executable first. This routes the launch through Commandog's Bundle command. See Bundle / Installer Internals for what the installer itself does.

Release-list cache

Helper/Update.cs caches the release-list HTTP responses for 5 minutes (Time = TimeSpan.FromMinutes(5)), keyed by (Uri, UserAgent). It exposes the releases as string / object / JArray / List plus async variants. The cache means repeated checks within five minutes do not re-hit the server.

Update telemetry

If TelemetryData consent is enabled, StepNetwork POSTs an UpdateTelemetryData { AppVersion, UpdateAutoType } record to …/v8/Telemetry/Update/<UserGuid> on the Soferity v8 backend. This is gated by the same consent switch as the rest of telemetry — see Privacy & Telemetry.

See also

Related

Wiki: Installation

Auth0 Logo