README.md

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