Kaazing WebSocket Gateway
Orange guy with box of questions

How to Access the HTML5 Communication Protocols from a Silverlight Client

Technology used: Microsoft Silverlight

This document contains the following sections:

Overview of Microsoft Silverlight

Microsoft Silverlight (Silverlight) is a browser plugin that enables rich Internet applications. It runs in browsers on the Microsoft Windows and Mac operating systems. Silverlight version 2.0 provided support for .NET languages and development tools.

For more information about Silverlight, visit http://www.microsoft.com/silverlight/.

WebSocket and Microsoft Silverlight

Kaazing Gateway enables the HTML 5 Communication protocol libraries in Silverlight. Using the Silverlight client library, you can enable the HTML 5 Communication protocols (for example, server-sent events and WebSocket) in new or existing Silverlight applications. For example, you can create a Silverlight application that uses WebSocket or ByteSocket to get streaming financial data from a Stomp server, or you can create a Silverlight application that receives streaming news data through server-sent events.

Taking a Look at the Microsoft Silverlight Client Demo

Before you start, take a look at a demonstration that was built with the Silverlight client library: the Silverlight Stomp demo that is part of the Kaazing Gateway demo bundle. To see this Silverlight demo in action, perform the following steps:

  1. Start the Kaazing WebSocket Gateway demo bundle as described in Getting Started.
  2. In a browser, navigate to http://localhost:8000/demo/demo.html#stomp-silverlight.

The Silverlight Stomp demo uses the Silverlight version of the Simple Text Oriented Message Protocol (Stomp) protocol library.

Setting Up Your Development Environment

To develop a Silverlight 2 application, you must install the following software:

  • A .NET Integrated Development Environment (IDE) such as Visual Studio 2008 or the free Visual Web Developer 2008 Express
  • Microsoft Silverlight 2 Tools for Visual Studio 2008 Add-on
  • The Silverlight 2 browser plugin

To use the Kaazing Silverlight client library in your Silverlight application, you must add a reference to the Kaazing library located in the .DLL file kaazing-enterprise-gateway-client-release-version.dll to your Silverlight project. This .DLL file can be found in the Kaazing Gateway demo bundle in the directory KAAZING_HOME/lib/client/silverlight.

Note: You can develop Silverlight 2 applications in any of the .NET programming languages. Microsoft Visual C# is used in this how-to.

Silverlight applications primarily consist of Extensible Application Markup Language (XAML) files and their corresponding code-behind classes .XAML.CS (in C#). The .XAML files typically contain the User Interface (UI) elements and the .XAML.CS files contain the page's code-behind classes.

A typical Silverlight application is deployed as a compressed .XAP file. Adding the reference to the Silverlight client library .DLL file in your Silverlight application packages the .DLL file in your finished application. To deploy your Silverlight application .XAP file, you can host it on the Kaazing Gateway. For example, you can place it in the web directory KAAZING_HOME/web.

To access the Kaazing Silverlight client library API documentation in Visual Studio (after you have added a reference to the client library to your Silverlight project), select Object Browser from the View menu and select kaazing-enterprise-gateway-client-release-version, as shown in the following image.

Silverlight API documentation in the Object Browser

Using the HTML 5 Communications Protocols in a Silverlight application

Note: In this how-to it is assumed that you are familiar with Silverlight programming and C#.

This section contains the following subsections:

Using the EventSource API

This section describes how you can use the EventSource API--provided by the Kaazing Silverlight client library--from a Silverlight application. This API allows you to take advantage of the server-sent events standard as described in the HTML 5 specification. For example, you can create a Silverlight application that uses the Silverlight HTML 5 Communications client library to receive streaming data from a news feed or streaming financial data. The support for server-sent events is provided by the EventSource class and its supporting classes. The following steps allow you to use the EventSource API in a Silverlight application. This example highlights some of the most commonly used EventSource methods and is not meant to be an end-to-end tutorial.

  1. First, add the required import statement:

using com.kaazing.gateway.client.html5;

  1. Next, to use the features of the Kaazing Silverlight client library , you must register the id of its object element (as specified in the object tag in the HTML file that contains the Silverlight application) with the library as shown in the following example.

Html5Utils.Init("MyApplicationId");

  1. Next, create a new EventSource object as shown in the following example.

EventSource mySource = new EventSource();

  1. Next, add event listeners to the EventSource object. The following example shows how three event listeners are added to the EventSource object. The open listener is called when a server-sent events connection is established, the message listener is called when messages are received, and the error listener is called when errors occur.

mySource.OpenEvent += new ProgressEventHandler((object sender,
  ProgressEventArgs e) =>
  {
    // Update the UI to show that the Silverlight application
    // is now receiving events.
  });

mySource.MessageEvent += new MessageEventHandler((object sender,   MessageEventArgs e) =>
  {
    string messageData = e.Data;
    string origin = e.Origin;
    string lastEvent = e.LastEventId;

    //
    // Use the data and event info to update the UI.
    //
  });

mySource.ErrorEvent += new ProgressEventHandler((object sender,   ProgressEventArgs e) =>
  {
    // Handle errors by closing the application
    // or attempting to reconnect.
  });

  1. Next, connect to an event source as shown in the following example. Once this method is called, the EventSource is activated and message can flow through at any time.

mySource.Connect("http://localhost:8000/sse");

  1. Later, you can call a method to disconnect the EventSource in case you want to stop listening to messages from a particular event source.

mySource.Disconnect();

Using the WebSocket API

This section describes how you can use the WebSocket API--provided by the Kaazing Silverlight client library--from a Silverlight application. This API allows you to take advantage of the WebSocket standard as described in the HTML 5 specification. For example, you can create a Silverlight application that uses the Silverlight HTML 5 Communications client library to interact directly with a backend chat or Stomp server. The support for WebSocket is provided by the WebSocket class and its supporting classes. The following steps allow you to use the WebSocket API in a Silverlight application. This example highlights some of the most commonly used WebSocket methods and is not meant to be an end-to-end tutorial.

  1. First, add required import statement:

using com.kaazing.gateway.client.html5;

  1. Next, to use the features of the Kaazing Silverlight client library , you must register the id of its object element (as specified in the object tag in the HTML file that contains the Silverlight application) with the library as shown in the following example.

Html5Utils.Init("MyApplicationId");

  1. Next, create a new WebSocket object as shown in the following example.

WebSocket mySocket = new WebSocket();

  1. Next, add event listeners to the WebSocket object. The following example shows how three event listeners are created and then registered with the WebSocket object. The OpenEvent listener is called when a WebSocket connection is established, the MessageEvent listener is called when messages are received, and the CloseEvent listener is called when the WebSocket connection is closed.

mySocket.OpenEvent += new EventHandler((object sender, EventArgs e) =>
  {
    // Update the UI to show that the Silverlight application
    // is now connected.
    // Now that the socket is open, you can use mySocket.PostMessage
    // to send messages.
  });

mySocket.MessageEvent += new MessageEventHandler((object sender,          MessageEventArgs e) =>
  {
    string messageData = e.Data;

    //
    // Use the data and event info to update the UI.
    //
  });

mySocket.CloseEvent += new EventHandler((object sender, EventArgs e) =>
  {
    // Handle errors by closing the application
    // or attempting to reconnect.
  });

  1. Next, use the connect method to connect to a backend service as shown in the following example.

mySocket.Connect("ws://localhost:8001/echo");

A WebSocket can only connect to one URI at a time.

  1. While the socket is open (that is, after the OpenEvent listener is called and before the CloseEvent listener is called), you can use the PostMessage method to send text-only messages as shown in the following example.

mySocket.PostMessage("Hello, World");

  1. Later, you can use the disconnect method at any time to deliberately disconnect from the WebSocket server as shown in the following example.

mySocket.Disconnect();

Using the ByteSocket API

This section describes how you can use the ByteSocket API--provided by the Kaazing Silverlight client library--from a Silverlight application. You use the ByteSocket API in the same way you use the WebSocket API, but ByteSocket allows you to establish a bi-directional socket connection that you can use to send and receive binary data. This section only highlights where the use of WebSocket and ByteSocket differ.

  1. You can create a new ByteSocket object as shown in the following example.

ByteSocket mySocket = new ByteSocket();

  1. The event listeners for the ByteSocket object must handle binary data as opposed to text data. For example, you can add a listener that handles a ByteBuffer object as shown in bold in the following example.

mySocket.MessageEvent += new MessageEventHandler((object sender,   ByteMessageEventArgs e) =>
  {
    ByteBuffer messageData = e.Data;

    //
    // Use the data and event info to update the UI.
    //
  });

  1. When you send messages, you send binary data using a ByteBuffer object as shown in the following example. Since you are sending binary data, you first have to create a ByteBuffer object in which you store the bytes that you want to send.

// send a buffer of data.
ByteBuffer SendBuffer = new ByteBuffer();

// ...
// Modify the ByteBuffer and fill it with binary data.
// ...

mySocket.PostMessage(SendBuffer);

Adding the Object Tag

To ensure the Silverlight application works properly, you must add an object tag that points to the location of your XAP file to the HTML file that includes your Silverlight application. At runtime, Silverlight downloads the XAP file that is referenced and run it in the browser. The following is an example object tag:

<object data="data:application/x-silverlight,"
    type="application/x-silverlight-2"         
    width="100%" height="100%"
    id="MyApplicationId">
  <param name="source" value="MySilverlightApplication.xap"/>
  <param name="EnableHtmlAccess" value="true"/>
  
  <!--
    Optional parameters
  -->
</object>

The following attributes are required if you want to use Kaazing Silverlight client library in your Silverlight application.

  • source--The path to the Silverlight application XAP file.
  • EnableHtmlAccess--Enables the Kaazing Silverlight client library to communicate with the HTML page that contains it.
  • id--An id that is required for communication between the Silverlight application and the HTML page that contains it.

Summary

As you have seen in this how-to, you can access the HTML 5 Communication protocols from a Microsoft Silverlight application.