WebSync 2 Migration Guide

With the release of WebSync version 3, we have unfortunately had to made some changes that break backwards compatibility with WebSync 2.

We hesitated when doing this, but in the end, we decided the need to improve our features and fix certain inconsistencies was worth the cost of complete backwards compatibility.

We did strive to keep backwards compatibility wherever possible. When we couldn't, we wrote it down, and the result is this migration guide.

We've done our best to make the upgrade to WebSync 3 as painless as possible; please contact us if you run into trouble.

Contents

.NET

FM.WebSync.Server

With WebSync 3, many of the fundamental changes are under the hood; better performance, better use of threadpooling, and reduced overhead. However, there were a number also a number of API changes. These API changes included:

1. The arguments passed into our events. Instead of having different events for the various "sources" of events (such as idling out vs. explicitly disconnecting, or publishing from the server vs. the client), the events have been consolidated. The arguments now contain indicators to allow determining the source, if desired. These changes clarify and reduce code.
2. Streamlining the API by removing extraneous information. For example, the "Direct" prefix is no longer needed when using server-side methods (e.g., RequestHandler.DirectPublish has become Handler.Publish). These changes clarify code and reduce the learning curve.
3. Method and parameter naming has been adjusted to more accurately reflect the behaviour and purpose of the member. These changes reduce overhead and learning curve.

We've outlined all the breaking changes below. It may seem like a lot, but really most of the changes are naming changes that take 2 seconds to adjust.

If you run into any problems, please drop us a line!

WebSync Server Config

We've also cleaned up the clutter in the web.config! What clutter, you say? Well, for those of you who got under the hood of what you could configure in WebSync 2, you probably noticed that you could mess things up if you weren't careful. But never fear, WebSync 3 is here, with cleaner configuration options!

Please note that with WebSync 3, the underlying storage providers have been abstracted out. That means that settings that are specific to a specific WebSync provider (such as connection strings for the SQL provider, or Azure connection details for the Azure provider) now reside in a <providerSettings> sub-element beneath the <server> section of the WebSync web.config entry.

First of all, the name of the type used in the WebSync configSection has changed:

In addition to changing the type name, some of the settings have been moved and/or renamed. Provider-specific settings now exist in a <providerSettings> sub-section.

Finally, some of the timing values that were previously available are now automatically calculated based on other values you have set. The same resulting setups are all possible with WebSync 3, but without the possibility of conflicting values.

	        <WebSync>
		        <server providerType="FM.WebSync.Server.Providers.Sticky.SqlProvider">
	        <providerSettings>
                <add name="connectionStringName" value="WebSync3" />
              </providerSettings>
	        </WebSync>
        

Error Messages

Almost all error messages have been left unchanged. There are two exceptions: we removed one error code and updated another. The text on any of the error codes may have changed; for details, check the API documentation. In addition, several new error codes have been added; again, see the API documentation for details.

.NET Publisher

The .NET publisher underwent very few changes. The primary difference from WebSync 2 to WebSync 3 is the return type when calling Publisher.Publish and its various overloads.

With WebSync 2, an "out" parameter was used to get an error messages, and the method returned a boolean indicating success or failure. This was terrible. WebSync 3 now returns a Publication object, which includes all the information about the publish attempt, including success or failure, and a nice ToJson() method for easy serialization.

.NET Proxy

The .NET proxy has been updated to be much more powerful; you now have access to a before, during, and after event. This allows you to 1) modify the messages, and deny as appropriate, 2) set any HTTP settings you desire, and 3) inspect the returned values prior to final delivery to the client.

There were several additions to the proxy, but the only actual change is that he "callback" method that was previously passed to the proxy invocation is now the OnBeforeProxy property of the ProxyInvokeArgs class, an instance of which is passed to the proxy invocation.

WebSync 2:

        Proxy.Invoke(new ProxyCallback((args) =>
        {
            foreach (Message message in args.Messages) // messages come in as array
            {
                    // deserialize, modify, then reserialize the data
                    Data data = JSON.Deserialize<Data>(message.Data);
                    data.Text = data.Text.ToUpperInvariant();
                    message.Data = JSON.Serialize(data);
                
            }
        }));
    

WebSync 3:

        Proxy.Invoke(new ProxyInvokeArgs()
        {
            DomainKey = "11111111-1111-1111-1111-111111111111", // replace with your private key
            OnBeforeProxy = (args) =>
            {
		        // deserialize, modify, then reserialize the data
		        Data data = JSON.Deserialize<Data>(message.DataJson);
		        data.Text = data.Text.ToUpperInvariant();
		        message.DataJson = JSON.Serialize(data);
                
            }
        });
    

.NET Client

The .NET client underwent the most significant API changes. With WebSync 2, the .NET client support the basic operations: you could connect, subscribe, and publish. However, it was not easy to use, and did not lend itself to a very "natural" code flow.

Therefore, the WebSync 3 .NET client was completely rewritten. It now exposes the underlying HTTP connection, supports synchronous and asynchronous usage patterns, and has a much more logical API. In fact, it now works almost identically to the way the JavaScript client works.

The changes to the .NET client are rather extensive, and best illustrated through a full example:

WebSync 2

Client client = new Client("http://example.com/request.ashx");
client.ConnectCompleted += new EventHandler<ConnectCompletedEventArgs>(ConnectCompleted);
client.SubscribeCompleted += new EventHandler<SubscribeCompletedEventArgs>(SubscribeCompleted);
client.Receive += new EventHandler<ReceiveEventArgs>(Receive);
client.Connect();

void ConnectCompleted(object sender, ConnectCompletedEventArgs e)
{
    if (e.Error)
    {  
        if(e.Stream)
        {
            // handle stream failure
        }else{
            // handle connect error 
        }
    }
    else 
    { 
        // the subscribe call must occur after the connect callback has completed
        client.Subscribe("/example");
    }
}

void SubscribeCompleted(object sender, SubscribeCompletedEventArgs e)
{
    if (e.Error)
    {
      // handle error 
    }
    else 
    { 
        //success 
    }
}

void Receive(object sender, ReceiveEventArgs e)
{
    // process the receive data
    Process(e.Data);
}

WebSync 3: No more confusing if..else blocks or waiting for events to complete

Client client = new Client(new ClientArgs
{
    RequestUrl = "http://localhost:3010/request.ashx"
});
client.Connect(new ConnectArgs
{
    OnSuccess = (successArgs) =>
    {
        // success
    },
    OnFailure = (failureArgs) =>
    {
        // handle connect failure
    },
    OnStreamFailure = (streamFailureArgs) =>
    {
        // handle stream failures
    }
});
// the subscription can occur at any time, and the WebSync client will wait as needed
client.Subscribe(new SubscribeArgs
{
    Channel = "/example",
    OnSuccess = (successArgs) =>
    {
        // success
    },
    OnFailure = (failureArgs) =>
    {
        // handle error
    },
    OnReceive = (receiveArgs) =>
    {
        // process the received data
        Process(receiveArgs.DataJson);
    }
});

JavaScript

On-Demand URL

To upgrade your On-Demand application to WebSync 3, you'll simply need to change your script tags to point to:

    <script type="text/javascript" src="http://sync3.frozenmountain.com/client.js"></script>

That will get you going with the latest version of the WebSync JavaScript client. Check out the upgrade information for the JavaScript client here.

JavaScript Client

The JavaScript client had some internal cleanup, but few breaking API changes. It's simpler to illustrate these changes with some example code, so without further ado, here are the few adjustments you'll need to make to convert to WebSync 3.

Initialize

The handlerUrl property has been replaced by the requestUrl property, making it consistent with the server naming conventions.

Also, the stream settings are now specified through a sub-object, with a requestUrl property.

The frameUrl property has been removed, and will be determined automatically based on the path to the stream url.

If desired, the old frameUrl value can still be set by the use of the clientFrameUrl property, but generally this is not necessary.

WebSync 2:

		
        client.initialize({ 
            handlerUrl: 'request.ashx', 
            streamUrl: 'http://streaming-domain.com/request.ashx',
            frameUrl: 'http://streaming-domain.com/client.ashx?frame=1'
        });
    

WebSync 3:

		
        client.initialize({ 
            requestUrl: 'request.ashx', 
            stream: { 
                requestUrl: 'http://streaming-domain.com/request.ashx' 
            }
        });
    

Connect

The url property has been replaced by the requestUrl property, making it consistent with the server naming conventions and with the other client methods.

The onStreamFailure method has been added to simplify handling of failures in the long-held "streaming" connection. If the "willReconnect" flag is set in this method, then it can be considered notification only, as the client will automatically reconnect. If it is not set, then the failure was fatal and needs to be handled.

The "ext" property has been replaced by the "meta" property. This will allow for future user extensions (watch our blog for updates on user extensions in WebSync 3).

Note: The "stream" property of the args passed into the onFailure is no longer valid. Use the onStreamFailure method to detect failures in the streaming connection.

WebSync 2:

		
        client.connect({ 
            ext: { username: 'foo' },
            url: 'request.ashx', 
            onSuccess: function(args){},
            onFailure: function(args){
                if(args.stream){
                    alert('stream failure');
                }
            }
        });
    

WebSync 3:

		
        client.connect({ 
            meta: { username: 'foo' },
            requestUrl: 'request.ashx', 
            onSuccess: function(args){},
            onFailure: function(args){},
            onStreamFailure: function(args){ 
                if(args.willReconnect){ return; }
                alert('stream failure');
            }
        });
    

Subscribe

The onMetaReceive event has been replaced by the onSubscribersChange event. Note that this event is now available within WebSync Server as well as WebSync On-Demand, provided a reference to the FM.WebSync.Servers.Extensions.Subscribers dll has been added to your project.

A few of the properties in the function callbacks have been updated too, so don't miss those!

WebSync 2:

		
        client.subscribe({ 
            ext: { username: 'foo' },
            channel: '/test',
            onSuccess: function(args){
                var clientIds = args.data.channels['/test'].clientIds;
            },
            onFailure: function(args){},
            onReceive: function(args){},
            onMetaReceive: function(args){
                var event = args.data.event;
                var clientIds = args.data.clientIds;
            }
        });
    

WebSync 3:

		
        client.subscribe({ 
            meta: { username: 'foo' },
            channel: '/test',
            onSuccess: function(args){
                var clientIds = args.subscribers['/test'];
            },
            onFailure: function(args){},
            onReceive: function(args){},
            onSubscribersChange: function(args){
                var type = args.change.type; // used to be "event"
                var clientIds = args.change.clientIds;
            }
        });
    

Publish

As with connect and subscribe, the publish method's "ext" property is now the "meta" property:

WebSync 2:

		
        client.subscribe({ 
            ext: { username: 'foo' },
            channel: '/test',
            onSuccess: function(args){},
            onFailure: function(args){}
        });
    

WebSync 3:

		
        client.subscribe({ 
            meta: { username: 'foo' },
            channel: '/test',
            onSuccess: function(args){},
            onFailure: function(args){}
        });
    

Note that *all* methods now look for a "requestUrl" property instead of a "url" property when specifying a proxy.

JavaScript Utilities

The JavaScript utilities have undergone some cleanup and namespacing to make them more generic, easier to understand, and simpler to use.

PHP

Proxy

The PHP Proxy has remained virtually unchanged, aside from some minor tweaks internally. Thanks to PHP's capability to adjust settings globally for a given script, much of the new capabiliaties in WebSync 3 for the .NET proxy were already possible in PHP. If you have suggestions for how we can improve it, let us know!

Publisher

Like the .NET Publisher, the PHP Publisher now returns a full object after publishing a message. This object contains information about success or failure of the publication, and if the request failed, any associated error codes. The signature of the Publish call has not changed.

Summary

It seems like a lot of changes, but that's only because we've written it out in painful detail to make your life as easy as possible. We want to help; if you have a quick question, just drop us a line and we'll do our best to straighten things out. If you have more in-depth needs, please don't hesitate to pick up a support subscription and contact us to set up a time when we can work through your issues together!