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.