NetSparkle Software Update Framework

NetSparkle 3.x provides ChannelAppCastFilter to easily filter app cast items by a specific channel (e.g., beta, alpha, or preview). This is useful for allowing users to opt-in to specific update tracks.

To use it, set the AppCastHelper.AppCastFilter property on your SparkleUpdater instance.

Configuration Options

• ChannelSearchNames: A List<string> of channel names to search for (e.g., new List<string>() {"beta"}). It uses a simple string.Contains invariant lowercase check.
• RemoveOlderItems: If true, it removes items that don't match the channel. If false, it keeps old versions (useful for rollbacks).
• KeepItemsWithNoChannelInfo: If false, it removes all items that do not match the specified channel. Warning: Setting this to false may prevent users on a beta version from updating to a non-beta version.

// Example setup for a beta channel filter
var filter = new ChannelAppCastFilter
{
    ChannelSearchNames = new List<string> { "beta" },
    RemoveOlderItems = true,
    KeepItemsWithNoChannelInfo = false
};

// Apply to the helper
sparkleUpdater.AppCastHelper.AppCastFilter = filter;

NetSparkle is highly extensible through several key interfaces. You can implement these to provide custom UI, networking, or logic:

UI Customization

• IUIFactory: The primary way to provide your own UI. It manages the creation of windows for checking updates, download progress, and available updates.
• ICheckingForUpdates: Interface for UI to show 'Checking...' status.
• IDownloadProgress: Interface for UI to show download progress.
• IUpdateAvailable: Interface for UI to show update details and release notes.

Data and Networking

• IAppCastDataDownloader: Control how the app cast file is downloaded (e.g., WebRequestAppCastDataDownloader for web, LocalFileAppCastDownloader for local files).
• IAppCastFilter: Filter AppCastItem objects (e.g., using ChannelAppCastFilter to filter by alpha/beta channels).
• IAppCastGenerator: Control serialization/deserialization (e.g., XMLAppCastGenerator, JsonAppCastGenerator).
• IUpdateDownloader: Control how the actual update files (installers) are downloaded (e.g., WebFileDownloader).

System and Security

• IAssemblyAccessor: Control how version and product metadata is loaded.
• ILogger: Implement to redirect NetSparkle logs to your own logging system.
• ISignatureVerifier: Implement to change how signatures are validated.

Configuration and Subclassing

• Configuration: Subclass this to change where data is saved (e.g., RegistryConfiguration for Windows, JSONConfiguration for macOS/Linux).
• AppCastHelper: Subclass for absolute control over the downloading and parsing process.
• ReleaseNotesGrabber: Subclass to control how release notes are fetched and displayed.

An app cast is an XML or JSON file containing product metadata and release definitions. NetSparkle reads <item> tags to identify available updates.

Key App Cast Elements

• <description>: HTML or Markdown description of the update. Overrides <sparkle:releaseNotesLink>.
• <sparkle:releaseNotesLink>: URL to an HTML/Markdown document. Can be signed via sparkle:signature.
• <pubDate>: Publication date.
• sparkle:channel: Release channel (e.g., beta).
• <enclosure>: Defines the update file. Important attributes:
  • url: Download URL.
  • sparkle:version: Machine-readable version.
  • sparkle:signature: DSA/Ed25519 signature of the file.
  • sparkle:criticalUpdate: If true or 1, the UI flags it as critical.
  • sparkle:os: Target OS (windows, macos, or linux).

Security Requirements

For SecurityMode.Strict, you need two signatures:

1. Enclosure Signature: A signature for the update file itself (sparkle:signature).
2. App Cast Signature: A signature for the app cast file, located at [AppCastURL].signature (e.g., http://example.com/appcast.xml.signature).

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
    <channel>
        <title>NetSparkle Test App</title>
        <link>https://netsparkleupdater.github.io/NetSparkle/files/sample-app/appcast.xml</link>
        <description>Most recent changes with links to updates.</description>
        <language>en</language>
        <item>
            <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
            <sparkle:releaseNotesLink>
            https://netsparkleupdater.github.io/NetSparkle/files/sample-app/2.0-release-notes.md
            </sparkle:releaseNotesLink>
            <pubDate>Thu, 27 Oct 2016 10:30:00 +0000</pubDate>
            <enclosure url="https://netsparkleupdater.github.io/NetSparkle/files/sample-app/NetSparkleUpdate.exe"
                       sparkle:version="2.0"
                       sparkle:os="windows"
                       length="12288"
                       type="application/octet-stream"
                       sparkle:signature="NSG/eKz9BaTJrRDvKSwYEaOumYpPMtMYRq+vjsNlHqRGku/Ual3EoQ==" />
        </item>
    </channel>
</rss>

To integrate NetSparkle into your application, follow these steps:

1. Install NuGet Packages: Install a pre-built UI package (e.g., for WPF, WinForms, or Avalonia) or just the core package if building your own UI.
2. Configure Project File: Ensure your .csproj contains necessary metadata like <Version>, <AssemblyVersion>, <Company>, and <Product>. To avoid git commit hashes appearing in your version string in .NET 8+, add <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>.
3. Install CLI Tool: Install the app cast generator tool via dotnet:

   dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator

4. Generate Keys: Create Ed25519 keys for signing updates:

   netsparkle-generate-appcast --generate-keys
   # To view your keys:
   netsparkle-generate-appcast --export

5. Initialize SparkleUpdater: Add the SparkleUpdater instance to your main UI thread (e.g., MainWindow).
6. Generate App Cast: Use the CLI tool to generate your update manifest:

   netsparkle-generate-appcast -b binary/folder -p change/log/folder -u https://example.com/downloads -l https://example.com/downloads/changelogs

7. Deploy: Upload the app cast and all signed update files (including .signature files) to your server.

dotnet tool install --global NetSparkleUpdater.Tools.AppCastGenerator

# Generate keys
netsparkle-generate-appcast --generate-keys
# Export keys to console
netsparkle-generate-appcast --export

# Generate appcast
netsparkle-generate-appcast -b binary/folder -p change/log/folder -u https://example.com/downloads -l https://example.com/downloads/changelogs