A Silverlight 2 to Silverlight 3 Upgrade Checklist

I have to admit: I’ve been largely ignoring most of the Silverlight 3 blog posts and other information because, in many ways, I’m still getting comfortable with Silverlight 2. Also, getting on the beta merry-go-round one too many times can set one’s head spinning something awful. So I figured I’d just avoid this one altogether. However, now that Silverlight 3 is out, I’m all over it.

Ideally, upgrading your controls from Silverlight 2 to 3 should be a fairly painless process. I think the pain factor, however, is largely dictated by how “deep” you went with Silverlight 2. I can’t cover every case, obviously, and if you’re after what’s changed, there are plenty of other posts out there with that information. But I would like to highlight the path I took when upgrading from Silverlight 2 to Silverlight 3.

1.) First Thing’s First – Get Silverlight 3

The first thing you need to do is get all of the various Silverlight 3 packages. These are:

  1. Microsoft® Silverlight™ 3 Tools for Visual Studio 2008 SP1
  2. Microsoft Expression Blend 3 + SketchFlow RC
  3. Deep Zoom Composer
  4. The latest Silverlight 3 Toolkit
  5. ASP.NET Server Controls for Silverlight (see 4c below)

Personally, I haven’t used Expression or Deep Zoom Composer when doing Silverlight 2 development, but I figured I’d get them anyway.

2.) Remove Silverlight 2

You don’t have to uninstall Silverlight 2, but after reading this from Tim Heuer, I didn’t see the point of keeping it around:

Before you install please know that once you do, your machine now becomes a Silverlight 3 dev machine. You cannot down-level target to Silverlight 2. If you still need to develop Silverlight 2 applications easily, ensure you are installing Silverlight 3 (beta) on a separate machine. You’ve been warned :-).

I uninstalled the Silverlight 2 Toolkit, the Silverlight 2 SDK, Deep Zoom Composer, Expression Blend 2, and even the Silverlight 2 runtime.

3.) Install the Silverlight 3 pieces

Install, unzip, and otherwise get all those files onto your machine.

4.) Updating a Silverlight 2 project to Silverlight 3

a.) Open a Silverlight 2 Project

Once you have everything installed, pick a Silverlight project and open it. You’ll be presented with the familiar Visual Studio Conversion Wizard:


Let it do it’s thing.

b.) Update Silverlight 2 Toolkit Components

If you’re using any Silverlight 2 Toolkit components, update those by either updating references or copying the individual files into your imports folder (I use an imports folder for each solution so that anyone can simply ‘get’ the source and compile, and also because I like to control what I compile with that way). The Silverlight 3 Toolkit components are installed, by default, to “C:Program FilesMicrosoft SDKsSilverlightv3.0ToolkitJul09Bin”.

c.) Update Web Site References, or What Happened to System.Web.Silverlight.dll?

You also need to update references on your hosting web site… sort of. You see, if you’ve been using the <asp:Silverlight> tag instead of an <object> tag (and including the silverlight.js JavaScript file), then you’ve been referencing System.Web.Silverlight.dll. Unfortunately, the ASP.NET Silverlight control is no longer part of Silverlight:

In the Silverlight 2 SDK and the Silverlight 3 beta, we had two ASP.NET server controls: asp:Silverlight and asp:Media.  These were both controls that served as wrappers to emitting the <object> tag or other JavaScript to instantiate a Silverlight object.  The <object> method is more flexible for developers on various platforms and we have decided not to include updates to these controls for Silverlight 3 SDK.

You can, however, continue to use the control if you so desire (download here). The folks at Microsoft have even made the source available. For now, I’m taking the path of least resistance by keeping the ASP.NET control. I’ll probably convert to using the <object> tag as time allows.

d.) Update Silverlight.js

There was a small update to the silverlight.js file:

Just a minor update that we compressed the bits so that if you want to use them it is a 7K library instead of a 57K library.  The “debug” (human readable) version will be available for you to download if needed at the Silverlight.js code site and is licensed under Ms-PL.

The new silverlight.js file can be found at “C:Program FilesMicrosoft SDKsSilverlightv3.0Tools”

5.) Compile, Run, Bask in the Glory of Silverlight 3

You should be set now. Compile and run your project and hopefully your controls work as expected.