When I created a template (posts here and here) that speeds up development of Silverlight Sidebar gadgets, I wanted to offer the smoothest development experience possible. Ironically, that in itself has been a very bumpy ride. The last hurdle I had to cross was to provide the familiar debug experience (F5).

My first attempt at this was just to set appropriate start options for the Web project that is in the template:

• Post build event that installs the gadget (runs a generated .gadget file)
• %ProgramFiles(x86)%\Windows Sidebar\sidebar.exe as the start program

This attempt failed with a very suggestive error:

I ran into this error every time the debugger was attached by the start options (F5, not using the Attach to Process command) and a Silverlight gadget was running in the Sidebar. I even tried to start debugging the sidebar when no Silverlight gadget ran, then added the Silverlight gadget to the Sidebar, but it was no use: same result.

I tried to get help with this error, but I could not find anything on it. The issue also seems like a very isolated corner case that does not affect too many people, so it would be tough to get any help.

While trying to find a workaround for F5 debugging, I wondered if I could run a custom app that manipulates the right Visual Studio instance to run the Attach to Process command and attach to sidebar.exe. Luckily, I was in Michael Leonard’s office at the time, because I got a quick answer: he had done similar things in the past. Half an hour later I had a code snippet about getting the Visual Studio automation object corresponding to a specific VS instance. Many thanks to Michael Leonard and Adam Nathan for getting the wheels turning on this.

The other parts of the solution flowed naturally:

• You can attach to the Visual Studio instance that has a specific solution open (info here).
• You can start the sidebar if it’s not already running (System.Diagnostics.Process.Start)
• You can launch the “Attach to Process” command using the DTE objects (info here).
• You can pass the full solution path as a command line parameter from the Visual Studio project Debug options (though not for all projects; for web projects it won’t work because macros are not supported).
• You can provide a transparent retry logic for COM calls that fail due to the destination being busy (info here; note the part about the single-thread apartment requirement).

I incorporated the custom app and the required build events into a new version of the Silverlight Windows Gadget template, available both in C# and VB flavour.

Version 1.8 of the gadget is released for the following Visual Studio/Silverlight version combinations:

I modified the CSS for the HTML page that hosts the flyout and the gadget itself in order to eliminate all margins and padding. You can set these from the Silverlight controls.

I fixed the issue with docking/undocking the gadget. Aside from a JS bug I had, there was also some weird Silverlight behaviour that cause the freeze on some machines.

I exposed the SettingsClosed event for both the docked and undocked Silverlight controls and fixed an issue related to saving settings values.

I added build events for the SilverlightGadgetWeb project that create a .gadget file that can be used to install/update the gadget. I also added code to actually install/update the gadget on each build. I did this in order to provide an easy way of trying out code changes.

I tried to fix the Silverlight application references in the SilverlightGadgetWeb project, but the only way that can be achieved is by providing a custom wizard for the project template that requires installation in the GAC. For now I think this requirement would be too strong for the template installation process. Aside from re-adding the Silverlight project references I also recommend setting the project dependencies manually to make sure that the project is the last one to be built in the solution. You can do this by right clicking the web project, choosing “Project Dependencies…” and then selecting all the Silverlight projects. (see below for details)

I also tried to arrange for “F5 debugging” in Visual Studio, but it was not possible. I managed to set the sidebar as the start program for the web project, but the debugger failed to attach to the process if the Silverlight gadget was running. Even if attaching succeeds at start-up (when no Silverlight gadget runs), when I added a Silverlight gadget the debugger crashed. In conclusion, Debug->Attach to Process is still the best way to debug gadgets.

I will be adding more versions of the template as soon as I get around to it, so stay tuned if your development configuration is not available yet.

UPDATE: In version 1.5 of the template I created a project template wizard to properly create Silverlight application references for the SilverlightGadgetWeb project and to establish a correct build order. This wizard also prompts for the Silverlight version to use when creating the projects.

UPDATE: In version 1.6 of the template I fixed the F5 debugging scenario by providing a fake SilverlightGadgetDebugger project in the template that runs a custom app which attaches the Visual Studio instance to the Sidebar process (more info on the workaround here). Starting with this version, I’m also providing a Visual Basic.NET flavour of the template. For the download link, check the table above.

UPDATE: Version 1.7 of the template offers a fully automated debug experience within Visual Studio 2010 for the gadgets. In short, the SilverlightGadgetDebugger  project will close any running version of the Sidebar and start a new one containing only the gadget to be debugged. When debugging/running is done, the original Sidebar (if it was running) is restored. Also, a bug involving detection of the 32 bit Program Files folder (which was used to detect installed Silverlight versions and locate the 32 bit Sidebar) has been fixed.

UPDATE: Version 1.8 of the template offers support for debugging 64 bit gadgets. This can be done by setting the Target Platform to “x64” for the SilverlightGadgetDebugger. Changes to the Target Platform require a reload of the SilverlightGadgetDebugger project, because Visual Studio does not update the values of the parameters used in command line parameters for debugging.

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.

I will be talking about developing Sidebar gadgets. These Sidebar gadgets are small applications that offer useful information, do frequent tasks more easily, or just offer a good laugh for the Windows Vista user. Until recently, I've been trying very hard to stay away from technologies like JavaScipt and PHP because it is my personal opinion that they fall miles away from a proper programming language (C#, VB.NET, C++). I won't go into the details of why I dislike these languages.

Microsoft launched a competition for Sidebar gadget developers with some very nice prizes. The competition takes place in several countries, including Romania. So, I decided to participate. The only problem is that the only fully supported programming model for developing Sidebar gadgets is HTML application + JavaScript.

I've spent several weeks trying to find another way to develop gadgets. I found out that by using XBAP(XAML Browser Application), one can obtain a gadget that can be programmed using WPF (Windows Presentation Foundation) - more information on that here. There are real drawbacks to this approach: no flyouts, no access to the gadget settings API, no access to the Gadget API, which are all accessible from JavaScript. Also, Silverlight can be used to create a Sidebar gadget. While this significantly improves access to the JavaScipt API's, there are still drawbacks. More on creating gadgets using Silverlight here and here. The decision was tough to make, but unavoidable: JavaScript won, due to the fact that my gadget needed settings, flyouts and a standard installation experience (no dependencies on Silverlight).

Now the phrase "there's no room for talibanisms" makes sense: you never know when you will be forced to do things you don't particularly enjoy (such as JavaScript). All these being said, I shall move on the the task at hand. The best place to start when learning to develop gadgets is the Overview Site from Microsoft. The ABCs of developing gadgets are covered there. Tim Heuer has made a project template for Visual Studio in order to help people getting started in gadget development. The template is available here.

From here, the purpose of the new gadget has to be formulated. It can be as simple as "Hello World", or as complicated as interfacing with your Windows Media Player. The first step is to go over to the Live Gallery dedicated to Vista Sidebar Gadgets and have a look at what's out there. I settled on creating a gadget that would display the postal code (ZIP) for a given address from Romania. I chose this because I had been searching too many times for postal codes on websites. The gadget is a very welcomed shortcut. The data is to be obtained from one of the many sites that offer Romanian ZIP search. The only requirement is to be able to pass the search string as a query string directly in the URL to keep things simple. I settled on http://coduri-postale.ro.

The next step is to get up to date with some basic JavaScript: HTML DOM, CSS, Regular Expressions, the Sidebar Gadget API. Now it's time to take a look at the structure generated by the Visual Studio template.

A Sidebar gadget has at least 2 files: a HTML file which defines the look of the gadget and an XML file which defines information about the gadget such as the name, version, author, description. However, usually, a gadget contains more files such as: HTML files for various flyouts, JS files for the JavaScript functions that are called and CSS files for defining styles in a civilized manner.

The main file of the gadget is called by default, gadget.html. It contains 2 div tags, one with the ID "docked" and one "undocked". As you can imagine, one holds the contents while docked, the other while undocked. In JavaScript, the events System.Gadget.onDock and System.Gadget.onUndock are defined in order to handle the switch between modes. The event handlers are set in the Init function found in the utils.js file.

<body onload="init();">

 <div id="docked">

 Gadget Docked

 <br/>

 <input type="button" value="Flyout" onclick="flyout();" />

 </div>

 <div id="undocked">

 Gadget Undocked

 </div>

</body>

The gadget.xml file contains the name, author, description of the gadget, but also it specifies the main source file for the gadget in the <base> node from <hosts>. The file also contains the path to an icon which represents the gadget and an image to display (defaultImage in <hosts>) while dragging the gadget (only when dragging it from the "Add Gadgets" window).

<?xml version="1.0" encoding="utf-8" ?>

<gadget>

 <!-- The name will appear on the Gadget Tile and settings window -->

 <name>[ YOUR GADGET NAME ]</name>

 <namespace>[YOUR CUSTOM NAMESPACE]</namespace>

 <version>1.0.0.0</version>

 <author name="[AUTHOR NAME]">

 <info url="[URL FOR INFO]" />

 <!-- The logo file will display on the more details window of the Gadget Tile window -->

 <logo src="logo.png" />

 </author>

 <copyright>© [COPYRIGHT INFO]</copyright>

 <!-- The description displays in the Gadget Tile window when the Gadget is selected -->

 <description>[YOUR DESCRIPTION]</description>

 <icons>

 <icon height="48" width="48" src="icon.png" />

 </icons>

 <hosts>

 <host name="sidebar">

 <base type="HTML" apiVersion="1.0.0" src="gadget.html" />

 <permissions>Full</permissions>

 <platform minPlatformVersion="1.0" />

 <defaultImage src="drag.png" />

 </host>

 </hosts>

</gadget>

The size of the gadget (or the flyout) can be changed by changing the size of the body of the html, either from CSS, HTML or JavaScript.  If the gadget has two different size when docked or undocked, then one should change the size of the html body using JavaScript in the event handlers for the Dock and Undock events. The utils.js file contains a function ShowOrHide that takes an HTML element and a boolean and hides(or shows) the element, along with any of its children. The function flyout() from utils.js creates a new flyout by specifying the file property of System.Gadget.Flyout, and then setting show to true.

One can specify a settings HTML page by setting the settingsUI property of System.Gadget. The settings page cannot be opened programmatically, only by the user's action (the settings button that the runtime creates for each gadget that supports settings automatically). The event onSettingsClosed is raised whenever the settings page closes, either by pressing ok or cancel. The onSettingsClosing event can be handled in order to save settings. It's handlers have a parameter which has a property closeAction. If this property is event.Action.commit, where event is the parameter passed to the handler, then the ok button was pressed. In order to write settings, one calls the write method and for reading, the read method of System.Gadget.Settings.

SystemGadget.Settings.write("settingname",settingvalue);

System.Gadget.Settings.read("settingname");

When loading the settings page, it is the responsibility of the page (through JavaScript) to read its settings and update the fields in the settings html in order to reflect the current values of the settings. This is the purpose of the loadSettings function available in the settings.html file from the template.

This covers all the main aspects in the template for Sidebar gadgets. Another very useful thing to master is the XMLHttpRequest object in JavaScript. This is used in order to obtain the contents of another page (any webpage) asynchronously. This object is part of the AJAX web programming paradigm. Unfortunately, like CSS, HTML and JavaScript, each browser has its own way of looking at this object. There are at least 3 methods of constructing the XMLHttpRequest  object, the bad news being that only one will work for a browser. So you have to try each method, catching exceptions along the way, until the object creation does not throw an exception or all the methods are exhausted, in the worst case. The good news is that for Sidebar gadgets, only Internet Explorer has to be taken into account. Sample code for creating the request object can be found below.

var xmlhttp = false;

 try

 {

 xmlhttp = new ActiveXObject("Msxml2.XMLHTTP");

 }

 catch (e)

 {

 xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");

 }

The simplest usage scenario involves using the GET http verb in order to simply retrieve a page.

var ret;

xmlhttp.open("GET", url, true);

xmlhttp.onreadystatechange=function()

{

 if (xmlhttp.readyState==4)

 if (xmlhttp.status==200)

 {

 ret=xmlhttp.responseText;

 //do something with ret;

 }

 else

 {

 //anything other than success can 

 //be treated as an error

 }

}

xmlhttp.send(null);

The open method takes as parameters the HTTP verb (GET, POST, etc.), the URL for the page to fetch and a boolean that when set to true allows JavaScript to launch the request asynchronously, meaning it keeps on processing the code. If set to false, the execution of JavaScript code stops until the data is fetched or an error occurs. The send method sends the request to the specified web server. If working asynchronously, you can define an event handler for the onreadystatechange event defined by the XMLHttpRequest object to monitor progress. The readyState property indicates the state of the object (4 mean request completed, response available). The status property holds the HTTP status of the response, 200 meaning OK. The actual response can be accessed using the responseText property. When fetching an ordinary webpage, this string will contain the actual HTML of the page.

Sometimes it's useful to do a POST request in order to get to a page that cannot be accessed through an URL. For example for filling out a form in order to obtain some search results (that are not accessible through URL query string parameters). Besides changing the GET into POST, you must also specify the form parameters just as you would query string parameters,only without "?" ('par1=val1&par2=val2') and pass the resulted string to the send method of the request object. Also, some HTTP header have to be set: Content-Type to "application/x-www-form-urlencoded" in order to pass the parameters of the form, Content-length to the length of the string of parameters and Connection to "close" in order to specify that the connection is to be closed once the response is obtained.

xmlhttp.open("POST", url, false);

xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");

xmlhttp.setRequestHeader("Content-length", parameters.length);

xmlhttp.setRequestHeader("Connection", "close");

var ret;

xmlhttp.onreadystatechange=function()

{

 if (xmlhttp.readyState==4)

 if (xmlhttp.status==200)

 {

 ret=xmlhttp.responseText;

 //do something with ret

 }

 else

 {

 // error occurred

 }

}

xmlhttp.send(parameters);

This concludes a basic, but comprehensive article on developing Sidebar gadgets. Even though I was not very specific, I hope you will have no problem stating your own gadget after reading this post.

Currently I have developed 2 gadgets: one to display postal codes from Romania and one to search for schedule and route information for urban transportation in a few major cities from Romania. The source code for these gadget can be obtained by installing them, then by getting the contents of the "C:\Users\%YourUser%\AppData\Local\Microsoft\Windows Sidebar\Gadgets\GadgetName" folder. Also, these two gadgets are competing in the Romanian edition of Gadget Competition. You can download and vote for my gadgets by clicking the two screenshots below.