CleanUpdate.Core 0.1.3

<div align="center">

⬆️ CleanUpdate

A small, modern, secure self-update library for .NET desktop apps.

</div>

What is it?

Desktop apps need to update themselves — but you can't overwrite a running .exe, XML-feed updaters feel a decade old, and rolling your own means re-solving hashing, signatures, and safe file swaps.

CleanUpdate is an instance-based, async self-update library (a cleaner alternative to AutoUpdater.NET). A headless core checks a source, downloads and verifies a package, and applies it; an optional WPF or WinForms dialog gives you the whole experience in one call. It reads a JSON feed or GitHub Releases, verifies every package (SHA-256, optionally RSA-signed), and applies zip updates through an atomic swap helper that backs up, replaces, and rolls back on failure.

Reach for it when you ship a portable .NET desktop app and want secure, reliable in-app updates without standing up an update server.

• 🧩 UI is optional. CleanUpdate.Core is fully headless; the WPF/WinForms dialogs are one-call wrappers.
• 🔒 Secure by default. Every package needs a SHA-256 hash; missing hashes are rejected. Add a public key to require RSA signatures.
• 🔁 Atomic zip swaps. An external helper replaces the app folder after exit, with automatic rollback.
• 🌐 Bring your own source. A hosted JSON feed or GitHub Releases — both via one IReleaseProvider seam.

How it works

flowchart LR
    A[App starts] --> B{CheckAsync}
    B -->|up to date| Z[Do nothing]
    B -->|update available| C[Show prompt / your UI]
    C --> D[DownloadAndVerifyAsync]
    D -->|SHA-256 + signature OK| E{Package type}
    E -->|installer| F[Launch installer]
    E -->|zip| G[Stage files → launch swap helper]
    G --> H[App exits]
    H --> I[Helper: backup → swap → rollback on error]
    I --> J[Relaunch app]

Quick start

1. Install the package for your UI (or the headless core).
2. Add a few lines to your app to check and apply updates (see Minimal examples).
3. Publish a release — the cleanupdate CLI turns your dotnet publish folder into the zip, hashes, feed.json and signatures for you.
4. Upload those artifacts and point the app's Feed at your feed.json.

Install

dotnet add package CleanUpdate.Wpf        # WPF app with the ready-made dialog
dotnet add package CleanUpdate.WinForms   # WinForms app with the ready-made dialog
dotnet add package CleanUpdate.Core       # headless / custom UI (pulled in by the UI packages)

All packages target net8.0 and .NET Framework 4.8 (UI packages use net8.0-windows). The swap helper (CleanUpdate.Tool.exe) is bundled in Core and copied into your output automatically — no manual step for the zip flow.

Minimal examples

WPF

using CleanUpdate;
using CleanUpdate.Wpf;

using var updater = new Updater(new UpdaterOptions
{
    Feed            = new Uri("https://example.com/update.json"),
    ExitApplication = () => Application.Current.Shutdown()   // let files be swapped cleanly
});

// Check the feed and, if an update is available (and not skipped/postponed), show the dialog.
await WpfUpdater.CheckAndPromptAsync(updater, owner: this);

WinForms

using CleanUpdate;
using CleanUpdate.WinForms;

using var updater = new Updater(new UpdaterOptions
{
    Feed            = new Uri("https://example.com/update.json"),
    ExitApplication = () => Application.Exit()
});

await WinFormsUpdater.CheckAndPromptAsync(updater, owner: this);

Headless / custom UI

using CleanUpdate;
using CleanUpdate.Download;

using var updater = new Updater(new UpdaterOptions { Feed = new Uri(feedUrl) });

UpdateCheckResult check = await updater.CheckAsync(ct);
if (check.ShouldPrompt)                                   // available and not skipped/postponed
{
    var progress = new Progress<DownloadProgress>(p =>
        Console.Write($"\rDownloading… {p.Fraction * 100:0}%"));

    string file = await updater.DownloadAndVerifyAsync(check.Info!, progress, ct);
    await updater.ApplyAndRestartAsync(check.Info!, file, ct);
}

For production, also set CurrentVersion, a Channel, and — strongly recommended — sign your releases and set PublicKeyXml. See the Security model.

Feed format

The feed is one release object, or an object with a releases array (multiple versions/channels). The updater picks the highest version on the requested channel.

Minimal:

{
  "version": "2.1.0",
  "package": {
    "type": "zip",
    "url": "https://downloads.example.com/myapp/myapp-2.1.0.zip",
    "sha256": "<lowercase hex sha-256 of the file>"
  }
}

Full:

{
  "releases": [
    {
      "version": "2.1.0",
      "channel": "stable",
      "mandatory": { "enabled": false, "minVersion": "2.0.0" },
      "changelog": "• New dashboard\n• Faster startup\n• Bug fixes",
      "package": {
        "type": "zip",
        "url": "https://downloads.example.com/myapp/myapp-2.1.0.zip",
        "size": 10485760,
        "sha256": "<lowercase hex sha-256 of the file>",
        "signature": "<base64 RSA-SHA256 signature, required when a public key is set>"
      }
    }
  ]
}

The complete field reference is in docs/api.md.

Publishing updates

You don't hand-write the feed or compute hashes. The cleanupdate .NET tool turns a publish folder into everything the app consumes — and signs it with the same algorithm the app verifies with:

dotnet tool install --global CleanUpdate.Cli

dotnet publish -c Release -o publish
cleanupdate pack --input publish --version 2.1.0 --name myapp \
    --base-url https://downloads.example.com/myapp \
    --key private.xml --delta --feed feed.json

That emits the release zip + .sha256, a feed.json (release upserted by version), the package/feed RSA signatures, and a delta manifest.json. Generate a key pair once with cleanupdate keygen. Full workflow, options, and CI usage: docs/publishing.md.

Security model

CleanUpdate verifies every update package before it is applied.

By default:

• every package needs a SHA-256 hash — a missing hash is rejected, not installed unverified;
• serve the feed and packages over HTTPS;
• set a public key and RSA signatures become required — unsigned or tampered packages are refused.

What each layer proves:

• SHA-256 — the package bytes were not corrupted or swapped (but not who produced them).
• RSA package signature — the package was signed with your private key.
• Feed signature — the whole feed document (version, url, installer args, …). Without it, unsigned metadata is only as trustworthy as its transport.

Full setup — generating keys, signing packages, signing the feed, and zip-extraction hardening — is in docs/security.md.

Delivery modes

Chosen per release via package.type:

• zip — atomic swap (recommended for portable apps). Extracted to a staging folder, verified, and handed to CleanUpdate.Tool.exe, which relocates itself, waits for your app to exit, backs up the current install, swaps in the new files, rolls back on any error, and relaunches.
• installer — run a setup. The verified .exe/.msi is launched with package.args (optionally elevated via RunAsAdmin). No helper required.

Advanced

• GitHub Releases as a source — point at a repo's Releases, nothing to host.
• Delta updates — ship a manifest so only changed files download.
• Skip / Remind me later — attach a StateStore (JsonFileStateStore by default) and choices persist across runs; CheckAsync then reports Suppressed/ShouldPrompt. Mandatory updates are never suppressed. The ready-made dialogs wire this automatically.
• Changelogs — await updater.GetChangelogAsync(info, ct) returns the inline changelog or fetches changelogUrl. The dialogs display it for you.
• Custom sources — implement IReleaseProvider to read from a CDN, an internal service, or a file share.

API reference

The full type, options, and method reference lives in docs/api.md. Most apps only touch a handful:

Contributing & releasing

Building, testing, packing, the repository layout, and the CI/release workflows are documented in docs/releasing.md.

License

MIT © CleanUpdate contributors