Creating a Vista Sidebar Gadget Using Microsoft Silverlight

Introduction

Some while ago I did a post on how to create a Vista Sidebar gadget using JavaScript. I also mentioned that I tried to create the gadget using XBAP or Silverlight, but due to the limitations in those technologies at that time, I decided that I had to give up on too much of the Sidebar gadget specific functionality (flyouts, cross domain data retrieval).

More than 6 months have passed since then and now I am pleased to announce that I’ve changed my opinion regarding Silverlight Sidebar gadgets. Due to the fact that the Silverlight technology has matured a lot (version 2.0 beta 2 is now available), Sidebar gadgets can be developed using this technology, without sacrificing any Sidebar gadget specific functionality. This is due to the fact that there is full interoperability between Silverlight and the JavaScript code. Also, cross domain calls are now allowed in Silverlight, so retrieving data is no longer an issue. Furthermore, it has been greatly enhanced due to the fact that one can consume WCF services using Silverlight.

Getting Started

The first step is to have a look over the "classic" way of developing Sidebar gadgets. Even though most of the "hard work" can now be done in Silverlight, the "wiring", the guts of the whole gadget are still the classic ones, relying on JavaScript and HTML. Next, if you are not familiar with Silverlight development, I recommend you spend some time getting comfortable with Silverlight. For this you can visit http://www.silverlight.net and try out the tutorials there.

The result of my inquiries in this subject is a Visual Studio project template that can be used to quickly start development for a Silverlight Sidebar gadget. I got inspired by the template Tim Heuer has created for jump starting Sidebar gadget development using just JavaScript/HTML. The requirements for installing and using the template are:

• Microsoft Visual Studio 2008 (Standard or better)
• Microsoft Silverlight 2.0 beta 2
• Silverlight Tools Beta 2 for Visual Studio 2008

After downloading the template installer from here, in order to install it, just run the downloaded file. The Visual Studio Content Installer will handle the rest (click next and ignore security warnings, because I did not sign the template).

After installing the template, in order to create a new Sidebar gadget, in Visual Studio click File->New->Project. You will notice that under the C# node, at the bottom, under "My Templates", a new entry has appeared: "Silverlight Sidebar Gadget". Give the solution a name and then click Ok.

You will notice that 6 projects have been automatically added to the newly created solution: SilverlightSidebarGadgetWeb, SilverlightGadgetDocked, SilverlightGadgetUnDocked, SilverlightGadgetSettings, SilverlightGadgetFlyout and SilverlightGadgetUtilities. In order, these correspond to: the main gadget web site project that will actually end up being deployed (all content and code is added to this site), the Silverlight control that is displayed when the gadget is docked, the Silverlight control that is displayed when the gadget is undocked, the Silverlight control that is displayed on the settings page of the gadget, the Silverlight control that is displayed on the flyout page of the gadget and a utilities library for Silverlight, providing a managed code API for Sidebar gadgets. This API translates to calls in the JavaScript Sidebar Gadget API.

IMPORTANT: Due to limitations in the way the template is built, the Silverlight applications have to be added to the gadget’s main project manually. This can be done by going to the Property Pages for the website project, the Silverlight Applications tab and then click add for each additional Silverlight project. Clear the "Add a test page that references the control" checkbox, and make sure the "Enable Silverlight debugging"checkbox is checked if you want debugging capabilities for Silverlight. Silverlight and JavaScript simultaneous debugging is not possible at the current time (Silverlight debugging requires disabling Script debugging from IE).

In a later version of the project template this will no longer be required, but for that I have to add a custom Wizard to the project template that can prepare the projects in the template.

The code is commented, so I’m not going to cover it in detail. Also, for Sidebar gadget development guidance, read my previous post on the topic. The gadget is set up to use Silverlight controls for each page of the gadget. This is not required, and Silverlight controls can be removed from the project (along with their projects form the solution) as needed. There are 2 main classes defined in the SilverlightGadgetUtilities class: SilverlightGadget and SilverlightGadgetEvents. The first is used to access the JavaScript Sidebar Gadget API. The second is used to expose the JavaScript events related to a gadget as managed events in the Silverlight controls.

Known "bumps"

There are some things that will simply not work, no matter how hard you try to get them to work. Usually this is due to the fact that the current Sidebar gadget API or the gadget user experience provided by Microsoft does not allow it. These "hick-ups" are specified in the documentation comments of the classes or directly as comments.

Due to the fact that the Gadget JavaScript object does not allow attaching multiple event handlers for the same event, one must take care what event handler is registered for a particular event. Possible outcomes are: events that do not get triggered at all in the Silverlight controls, events that get triggered only in some Silverlight controls.

Due to the user experience with Sidebar gadgets, some events cannot be triggered in Silverlight controls: the Docked, Undocked events, all gadget events in the flyout, etc.

Some properties from the SilverlightGadget class are read-only even though the Sidebar gadget JavaScript API specifies that they are read-write. This is due to the fact that attempting to set those properties resulted in exceptions at runtime and those exceptions are most probably caused by the JavaScript API itself.

I tried to "discover" all such "bumps" that might appear and document them in the template directly. If there is something I missed or you have a question, please contact me or post a comment and I will try to modify the template to fix or document the issue. Also, any suggestions on improving this project template are welcomed.

I’m looking forward to seeing many Silverlight Sidebar gadgets being developed. If you create such a gadget using this project template, please let me know by posting a comment with a link to the Live Gallery page of the gadget or a link to a page describing it.

Once again, the link for the Visual Studio project template is displayed below.

FILE: SilverlightSidebarGadget.vsi

UPDATE: If you have Microsoft Visual Studio 2008 SP1 installed, you will need the Microsoft Visual Studio Tools Beta 2 for Visual Studio 2008 in order to be able to create Silverlight projects. This also means that you cannot use the provided template without installing the new version of the Silverlight Tools.

UPDATE 2: I’ve upgraded the projects in the template for Silverlight 3 Beta. The corresponding template can be found here.

UPDATE 3: I’ve created a version of the template for Silverlight 2 final. The corresponding template can be found here.

UPDATE 4: I’ve upgraded the projects in the template for Silverlight 3 RTW. The corresponding template can be found here.

UPDATE 5: I’ve created a version of the template using Visual Basic projects. The corresponding template can be found here.

UPDATE 6: I’ve created a version of the template for Visual Studio 2010, using the new extension format. The corresponding template can be found here.