ashokgelal / magpie

A modern software update framework for .net applications

Magpie

A smart modern software update framework for .net applications.

Magpies are birds of the crow family which is considered one of the most intelligent animals in the world, and the only non-mammal species able to recognize itself in a mirror test. They love collecting sparkly things for their nests

Master Branch Status:

Features:

• Based on WPF - modern, beautiful and stylish
• JSON based appcast - no fugly xml
• Channels - support for beta, alpha, stable etc. channels with a simple API to switch
• Markdown based release notes - because there is no reason to use any other formats
• Looks great out of the box - no need to write your own CSS
• Easy integration - install via Nuget and add two lines of code
• Very flexible APIs - provides plenty of hooks and raises right events at the right time
• Built-in logging for quick debugging - plug-in a logger of your choice to see what's going on behind the scene
• Built-in analytics - measure the effectiveness of your updates by plugging-in your analytics logger to capture important events
• Signature Verification - DSA signatures for secure updates. Comes with an utility app for generating keys, creating a signature and verifying an artifact
• Minimal dependencies - only one 1 external dependency (for Markdown parsing)

Installing

Use Magpie nuget package:

PM> Install-Package Magpie -Pre

Using Magpie:

To use Magpie in your project, you only need to interact with Magpie class:

1. Create an instance of AppInfo class:

var appInfo = new AppInfo("<url to appcast.json>");

2. Now, to run Magpie in the background:

new Magpie(appInfo).CheckInBackground();

3. (Optional) To force check for updates (like via a 'Check for Updates' menu item):

new Magpie(appInfo).ForceCheckInBackground();

---

Publishing updates:

Add some basic information to a valid json file and publish it somewhere publicly accessible. Because of out-of-the-box channel support, your build info should contain inside a channels field. Here is a basic example with all the required fields:

{
	"channels": [{
 	  "version": "x.y.z",
 	  "release_notes_url": "https://raw.githubusercontent.com/ashokgelal/Magpie/master/README.md",
 	  "artifact_url": "https://github.com/ashokgelal/Magpie/tree/master/installer.msi"
	}]
}

Obviously, release_notes_url and artifact_url should be somewhere publicly accessible as well. You can add extra information to this appcast file and can access those values later from RemoteAppcast's RawDictionary property.

---

Signing Updates:

For security reasons, it's a good idea to sign your updates before publishing. With Magpie and its companion Magpie Signature Verifier app, it only takes couple of minutes to generate your keys and create a signature. Once you generate the keys, the subsequent signing tasks should only take few seconds.

This is what you need to do to sign your updates:

Initial Keys Generation

1. Download MagpieVerifier.exe from utils folder from this repo.

2. From your command window, execute:

MagpieVerifier.exe generate

This creates two files: MagpieDSA.priv and MagpieDSA.pub.

IMPORTANT! Keep MagpieDSA.priv in a secure place. If you lose it, you won't be able to sign your updates again.

3. Drag-and-drop MagpieDSA.pub in your main project, select it, and from the Properties window, select Embedded Resource for Build Action.

These first 3 steps should only be done once. Now to sign every new updates release:

4. From you command window, execute:

MagpieVerifier.exe sign <updater_file> <private_key_file>

updater_file is the file you want to sign and private_key_file is the private DSA file you generated from step 2 above.

This step will print a long signature string for you. Copy paste this signature string in your appcast.json file under "dsa_signature" key and you are all set.

See Magpie Signature Generator project for more information.

---

Providing a logo:

1. Create an instance of AppInfo class:

var appInfo = new AppInfo("<url to appcast.json>");

2. Call SetAppIcon() method with a namespace of your project that contains the logo, and the name of the logo itself:

appInfo.SetAppIcon("<namespace of your project>", "<yourlogo.png>");

Look into Magpie.Example project for a demo application.

---

Hooking up analytics:

When instantiating MagpieUpdater, you can also pass an instance IAnalyticsLogger if you want to log different user actions such as logging download, remind me later, skip etc. Magpie comes with an empty implementation of IAnalyticsLogger called AnalyticsLogger that you can extend and hook-in your own logic for actual logging of different events. We actually recommend that you extend AnalyticsLogger instead of extending IAnalyticsLogger interface. If we add more events to IAnalyticsLogger, and we will, it won't break your application.

TODO

• Build on AppVeyor
• Markdown support for Release Notes
• Download installer and allow to open it
• Custom CSS Support
• Force check
• Notify "No Updates Available"
• Create Nuget package
• Add XML docs
• Analytics interface
• Validate signature of payloads
• Add more tests
• Implement a debugging window

magpie's Issues

Add an interface and a default implementation for logging analytics

Notification window for "No Updates"

If no updates are available, a window should popup with "No Updates Available" message

Validate Signature of download files

Thanks for making Magpie, it looks great.

When downloading an update, it doesn't look like Magpie currently validates the file in any way. (i couldn't find it if it does)

It would be great if Magpie would validate signatures based on a Public Key. Traditionally Appcasts / Sparkle have used DSA signatures, but it would be very reasonable to use a RSA w/ SHA256 as a more modern approach.

Add XML Docs to all public methods

Verify and complete the API for force checking

This has been implemented but needs to be explored to see if the behavior is what we want (it actually works and also is easy to invoke)

Add more unit tests

System.Net.WebException crashes app

Hi,

please see the exception below that is thrown on a Check task and crashes my app. This is inside a Win10-x64-VM and the jsonUrl was not 127.0.0.1 but a custom one (172.x.x.x).

ERROR System.Net.WebException: Unable to connect to the remote server ---> System.Net.Sockets.SocketException: No connection could be made because the target machine actively refused it 127.0.0.1:8000
   at System.Net.Sockets.Socket.EndConnect(IAsyncResult asyncResult)
   at System.Net.ServicePoint.ConnectSocketInternal(Boolean connectFailure, Socket s4, Socket s6, Socket& socket, IPAddress& address, ConnectSocketState state, IAsyncResult asyncResult, Exception& exception)
   --- End of inner exception stack trace ---
   at System.Net.HttpWebRequest.EndGetResponse(IAsyncResult asyncResult)
   at System.Net.WebClient.GetWebResponse(WebRequest request, IAsyncResult result)
   at System.Net.WebClient.DownloadBitsResponseCallback(IAsyncResult result)
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Magpie.Services.DefaultRemoteContentDownloader.<DownloadStringContent>d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Magpie.ViewModels.MainWindowViewModel.<FetchReleaseNotesAsync>d__3.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Magpie.ViewModels.MainWindowViewModel.<StartAsync>d__0.MoveNext()

Embed a default CSS style

Right now there is no CSS attached to the release notes. For now we'd like to have a decent looking CSS stylesheet. In the future, we should allow the appcast to provide an optional alternative CSS url.

Pack and publish as a Nuget package

No Updates Available Window is shown when it shouldn't be

The window should only be shown if there was a "force check" for updates and there were no updates found.

Right now, the window shows every time you run the app unless there is an actual update.

Move all hard coded strings to Resources