Update Internals

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
• The update pipeline (steps)
• Settings and enums
• Asset name pattern
• Download modules and speed limiting
• Install: extract vs. run
• Release-list cache
• Update telemetry
• See also

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)"]

Loading

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. Default Visible.

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

• Updating Sucrose — the user-facing guide to update modes, sources, and triggering a check.
• Settings: Other — the update server / channel / module / extension / limit / auto-type settings and the access token.
• Bundle / Installer Internals — what the downloaded installer does when run.
• Commandog Dispatcher — the ✔Update✖… and ✔Bundle✖… commands.
• Installation — the GitHub release asset names and distribution channels.