Merge pull request #605 from NetSparkleUpdater/feature/app-cast-rework

Rework app cast handling; add JSON compatibility; add AppCastItem.Channel; built-in channel-based app cast filter implementation

README.md

@@ -116,6 +116,12 @@ In your project file, make sure you set up a few things so that the library can
 </PropertyGroup>
 ```
 
+IMPORTANT NOTE: In .NET 8+, a change was made that causes your git/source code commit hash to be included in your app's `<Version>` number. This behavior cannot be avoided by NetSparkleUpdater at this time as we rely on `AssemblyInformationalVersionAttribute`, and this attribute's behavior was changed. Your users may be told that they are currently running `1.0.0+commitHashHere` by NetSparkleUpdater (and your native app itself!). We recommend adding the following lines to your project file (in a new `<PropertyGroup>` or an existing one):
+
+```xml
+<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
+```
+
 ### Code
 
 ```csharp
@@ -426,7 +432,7 @@ Having just the latest version of your software in the app cast has the added si
 3. If you don't want to generate signatures because you trust your AppCenter builds, use `SecurityMode.Unsafe` or the following `IAppCastHandler` override:
 
 ```csharp
-public bool DownloadAndParse()
+public override bool DownloadAndParse()
 {
     try
     {
@@ -435,7 +441,8 @@ public bool DownloadAndParse()
         var appCast = _dataDownloader.DownloadAndGetAppCastData(_castUrl);
         if (!string.IsNullOrWhiteSpace(appCast))
         {
-            ParseAppCast(appCast);
+            Items.Clear();
+            Items.AddRange(ParseAppCast(appcast));
             return true;
         }
     }
@@ -504,7 +511,7 @@ Contributions are ALWAYS welcome! If you see a new feature you'd like to add, pl
 
 * Unit tests for all parts of the project
 * Extensive testing on macOS/Linux
-* More built-in app cast parsers (e.g. natively support using/creating JSON feeds) -- possible via interfaces but not built-in yet
+* More built-in app cast parsers
 * More options in the app cast generator
 * See the [issues list](https://github.com/NetSparkleUpdater/NetSparkle/issues) for more
 

UPGRADING.md

@@ -34,7 +34,25 @@
   * By default, timestamps are now output along with the `Tag` and actual log item
 * `RegistryConfiguration` has changed its default final path to `NetSparkleUpdater` instead of `AutoUpdate`. Please migrate saved configuration data yourself if you need to do so for your users (probably not necessary).
 * `ShowUpdateNeededUI` no longer shows an update window if the number of update items is 0. (Arguably a bug fix, but technically a breaking change.)
-
+* Major refactoring for app cast handling/parsing to clean up logic / make new formats easier
+  * New `AppCast` model class that holds info on the actual app cast and its items
+  * `AppCastItem` no longer contains information on serializing or parsing to/from XML
+  * App cast parsing/serializing is now handled by an `IAppCastGenerator` implementation
+    * `XMLAppCast` renamed to `AppCastHelper`
+    * `SparkleUpdater` now has an `AppCastGenerator` member that handles deserializing the app cast rather than `AppCastHelper`
+    * `AppCastItem` serialization now expects the full download link to already be known (serialization will not consider the overall app cast URL)
+  * `IAppCastHandler` is no longer available/used.
+    * App cast downloading and item filtering is now handled by `AppCastHelper`.
+    * If you want to manage downloads, implement `IAppCastDataDownloader` and set `SparkleUpdater.AppCastDataDownloader`
+    * If you want to manage deserializing/serializing the app cast, implement `IAppCastGenerator` and set `SparkleUpdater.AppCastGenerator`
+    * If you want to manage filtering on your own, implement `IAppCastFilter` and set `SparkleUpdater.AppCastHelper.AppCastFilter`
+      * `AppCastHelper` also has two new properties: `FilterOutItemsWithNoVersion` and `FilterOutItemsWithNoDownloadLink`, which both default to `true`.
+    * If you need absolute control more than the above, you can subclass `AppCastHelper` and override methods: `SetupAppCastHelper`, `DownloadAppCast`, and `FilterUpdates`. This probably is not necessary, however, and you can do what you want through the interfaces, most likely.
+  * `AppCastHelper.SetupAppCastHelper` signature is now `SetupAppCastHelper(IAppCastDataDownloader dataDownloader, string castUrl, string? installedVersion, ISignatureVerifier? signatureVerifier, ILogger? logWriter = null)` (note: no longer takes a `Configuration` object)
+* Renamed `AppCastItem.OperatingSystemString` to `OperatingSystem`
+* XML app casts write `version`, `shortVersion`, and `criticalUpdate` to the `<item>` tag and the `<enclosure>` (both for backwards/Sparkle compat; we'd rather not write to `<enclosure>` but we don't want to break anyone that updates their app cast gen without updating the main library).
+  * If both the overall `<item>` and the `<enclosure>` have this data, the info from the `<item>` is prioritized.
+  * JSON app casts are not affected.
 
 **Changes/Fixes**
 
@@ -64,6 +82,13 @@
 * Added `nullability` compatibility to core and UI libraries (#595)
   * Base language version is now 8.0 (9.0 for Avalonia), but this is only used for nullability compatibility (compile-time), so this shouldn't affect older projects (`.NET 4.6.2`, `netstandard2.0`) and is thus a non-breaking change
 * Fixed initialization issue in DownloadProgressWindow (WinForms) icon use
+* Added `JsonAppCastGenerator` to read/write app casts from/to JSON (use with app cast generator option `--output-type`)
+* Added `ChannelAppCastFilter` (implements `IAppCastFilter`) for easy way to filter your app cast items by a channel, e.g. `beta` or `alpha`. Use by setting `AppCastHelper.AppCastFilter`. Uses simple `string.Contains` invariant lowercase string check to search for channels in the `AppCastItem`'s version information.
+  * If you want to allow versions like `2.0.0-beta.1`, set `ChannelSearchNames` to `new List<string>() {"beta"}`
+  * Set `RemoveOlderItems` to `false` if you want to keep old versions when filtering, e.g. for rolling back to an old version
+  * Set `KeepItemsWithNoSuffix` to `false` if you want to remove all items that don't match the given channel (doing this will not let people on a beta version update to a non-beta version!)
+* `AppCast? SparkleUpdater.AppCastCache` holds the most recently deserialized app cast information.
+* `AppCastItem` has a new `Channel` property. Use it along with `ChannelAppCastFilter` if you want to use channels that way instead of via your `<Version>` property. In the app cast generator, use the `--channel` option to set this.
 
 ## Updating from 0.X or 1.X to 2.X
 

src/NetSparkle.Samples.Avalonia.MacOS/NetSparkle.Samples.Avalonia.MacOS.csproj

@@ -5,6 +5,8 @@
     <ApplicationIcon>software-update-available.ico</ApplicationIcon>
     <RootNamespace>NetSparkleUpdater.Samples.Avalonia</RootNamespace>
     <AssemblyName>NetSparkleUpdater.Samples.Avalonia</AssemblyName>
+    <Version>1.0.0-beta1</Version>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
   <ItemGroup>
     <AvaloniaResource Include="Assets\*" />

src/NetSparkle.Samples.Avalonia.MacOSZip/NetSparkle.Samples.Avalonia.MacOSZip.csproj

@@ -5,6 +5,7 @@
     <ApplicationIcon>software-update-available.ico</ApplicationIcon>
     <RootNamespace>NetSparkleUpdater.Samples.Avalonia</RootNamespace>
     <AssemblyName>NetSparkleUpdater.Samples.Avalonia</AssemblyName>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
   <ItemGroup>
     <AvaloniaResource Include="Assets\*" />

src/NetSparkle.Samples.Avalonia/NetSparkle.Samples.Avalonia.csproj

@@ -5,8 +5,9 @@
     <ApplicationIcon>software-update-available.ico</ApplicationIcon>
     <RootNamespace>NetSparkleUpdater.Samples.Avalonia</RootNamespace>
     <AssemblyName>NetSparkleUpdater.Samples.Avalonia</AssemblyName>
-	<PublishTrimmed>true</PublishTrimmed>
-	<AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
+    <PublishTrimmed>true</PublishTrimmed>
+    <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
   <ItemGroup>
     <AvaloniaResource Include="Assets\*" />

src/NetSparkle.Samples.DownloadedExe/NetSparkle.Samples.UpdateExe.csproj

@@ -12,6 +12,7 @@
     <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
     <FileAlignment>512</FileAlignment>
     <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
     <PlatformTarget>AnyCPU</PlatformTarget>

src/NetSparkle.Samples.HandleEventsYourself/NetSparkle.Samples.HandleEventsYourself.csproj

@@ -4,6 +4,7 @@
     <OutputType>WinExe</OutputType>
     <TargetFramework>net8.0-windows</TargetFramework>
     <UseWPF>true</UseWPF>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
 
   <ItemGroup>

src/NetSparkle.Samples.NetCore.WPF/NetSparkle.Samples.NetCore.WPF.csproj

@@ -5,6 +5,7 @@
     <TargetFrameworks>net7.0-windows</TargetFrameworks>
     <UseWPF>true</UseWPF>
     <ApplicationIcon>software-update-available.ico</ApplicationIcon>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
 
   <ItemGroup>

src/NetSparkle.Samples.NetCore.WinForms/NetSparkle.Samples.NetCore.WinForms.csproj

@@ -5,6 +5,7 @@
     <TargetFrameworks>net7.0-windows</TargetFrameworks>
     <UseWindowsForms>true</UseWindowsForms>
     <ApplicationIcon>software-update-available.ico</ApplicationIcon>
+    <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
   </PropertyGroup>
 
   <ItemGroup>