Migrating from PushSharp 2.x to 3.x

How to Migrate from PushSharp 2.x to 3.x

I've had a number of users asking about how to migrate from 2.x to 3.x. While this isn't meant to be a guide on exactly how to do that (because it will depend on each developer), but it will hopefully help highlight the differences.

Why the concept of a single broker no longer exists:

There was much more confusion than I would have expected around how PushSharp previously supported registering multiple services using a single broker, that I decided to let you the developer decide how to work with multiple brokers.

This is really simple. For most people, they will want to create an instance of a platform specific broker for each platform they want to use. In some cases where you are supporting multiple apps, you may need to create multiple brokers for each platform as well (one for each app).

It might make sense for you to define your own objects to keep track of broker instances. Typically this would involve some sort of dictionary, and could be as simple as creating a Dictionary<string, ApnsServiceBroker> type of dictionary for each platform, where the key is your application's id.

Or, here's something I would likely use:

public class AppPushBrokers
{
	public ApnsServiceBroker Apns { get;set; }
	public GcmServiceBroker Gcm { get;set; }
}

// Somewhere, setup our dictionary of apps we will send to
var apps = new Dictionary<string, AppPushBrokers> {
	{ 
		"com.altusapps.someapp", 
		new AppPushBrokers {
			Apns = new ApnsServiceBroker (someAppApnsConfig),
			Gcm = new GcmServiceBroker (someAppGcmConfig)
		}
	},
	{
		"com.altusapps.anotherapp",
		new AppPushBrokers {
			Apns = new ApnsServiceBroker (anotherAppApnsConfig),
			Gcm = new GcmServiceBroker (anotherAppGcmConfig)
		}
	}
};


// Now pick the right set of brokers to send notifications to
apps["com.altusapps.someapp"].Apns.Send (new ApnsNotification (..));

This way you are left with as much flexibility as you need. Only need a single platform for a single app? No problem, just create one instance. Need a more complex solution? You're free to set it up however you like.

Ultimately I think this will cause much less developer confusion, at the small expense of having to create a simple dictionary or object model to achieve what you want.

Where are all the Fluent notification payload helpers?

Apns expects a JSON payload, GCM a key/value pair in JSON format, and Windows expects XML. Previously, PushSharp attempted to provide helper methods to construct these payloads without having to know the raw data behind them. This no longer exists in 3.x and you must provide a raw payload in the format the platform is expecting.

This will probably be the most difficult adjustment while migrating.

There are a couple of reasons behind this decision:

1. It became very onerous to maintain these methods as the platform changed, and it was easy to quickly fall behind which didn't make users happy.
2. Users weren't forced to know enough about the platform's expectations and this lead to a lot of unnecessary support questions simply because of not reading the platform's documentation properly, or being confused about how PushSharp was generating a payload.
3. The 3.x release is all about simplicity. In practice, it doesn't seem to be a lot of work to write the code to generate the appropriate payload string without the helpers. This eliminates all confusion about the payload of notifications.