Silverlight 3 Beta install experience for users

If you are like any other developer, including me, you probably disregard most warnings and are usually the same type that keeps clicking next when installing things without paying attention to detail.  That’s okay I do it too.

In the release of Silverlight 3 Beta, we noted that this is a developer release and that no “Go Live” licensing was going to be available for this release.  What this means is that we don’t recommend putting things in production as we’ve not exposed or wired up the end-user runtime for Silverlight 3.  The only way people can view Silverlight 3 content during this Beta phase is by having one of the versions of the developer runtime for either Windows or Mac installed.  We’ve not integrated the end-user upgrade/install into the template for now.  So what does this mean to you when you put a sample out for people to see in your organization or perhaps if you have a preview of a product or something and users visit this application.  Here’s a few scenarios for you – keeping in mind the information below is related to the application being build in Silverlight 3: No Silverlight installed, Silverlight 3 installed, Silverlight 1/2 installed and a note about the plugin MIME type.

Scenario: No Silverlight Installed

If the user has no previous version of Silverlight installed at all, they’ll be presented with whatever your default “not installed” experience is.  If you’ve don nothing to customize this, shame on you :-).  The default Visual Studio templates will simply provide you with a static image.  That link in the templates links to a “coming soon” page which describes the situation.  You can view that page here: Silverlight 3 coming soon page.  If the user installs one of the developer runtimes then they’d be able to review your application.

NOTE: People with Silverlight 3 Developer runtimes cannot “upgrade” to an end-user runtime.  This means that if an end-user (non-developer) installs the developer runtime, then when Silvelright 3 releases they will have to manually uninstall the developer runtime to get the update of the released runtime.  If you’re a developer, you probably don’t care and future developer runtimes can install on top of other developer runtimes.  This is one of the driving reasons for no Go Live support at this time.

You should inform your viewers of your beta sample of the scenario and what they may have to do in the future.

Scenario: Silverlight 3 developer runtime installed

If the user has the correct version of the Silverlight 3 runtime as defined by your application, then they will be able to view your application.  You define the minimum version of the runtime required when you instantiate the plugin using the minRuntimeVersion parameter.  This might look like:

   1: <object data="data:application/x-silverlight-2," type="application/x-silverlight-2">

   2:     <param name="minRuntimeVersion" value="3.0.40307.0" />

   3:     ...

   4: </object>

If the user has the minimum you specified, all should be well.

Scenario: Silverlight installed (any released version)

Ah, this is the tricky one.  If the user has any released version of Silverlight (1.0 or 2), the experience they see at your beta sample will be driven off of two properties as you instantiate the plugin: minRuntimeVersion and autoUpgrade.  Let’s look at what will happen and assume that the user has Silverlight 2 installed.

minRuntimeVersion=”3.0.40307.0” and autoUpgrade=”true” – if you do nothing else, the user will see this:

This is bad on a few levels.  First because it isn’t a customized experience, it is the default.  Second because the “install” link will take them to the latest released runtime – which they already have most likely.  What happens?  The user feels like they are in and endless loop of Visit Site –> prompted to upgrade –> seemingly install –> visit site –> prompted to upgrade –> repeat.  This will frustrate your beta visitor and confuse you :-). 

You should always customize the user experience for the end user.  For beta, here’s what I recommend doing to ensure they aren’t confused with the goals being the following:

• Detect if the user needs to upgrade to see your beta sample
• Inform them of the situation and that your sample is beta
• Direct them to the coming soon information page for Silverlight 3

Here’s what you need to do.  Ensure that your application (object tag) is within some type of HTML container, like a div and give that an appropriate ID.  In your plugin instantiation you’ll want to add 3 parameters like this:

   1: <div id="silverlightControlHost">

   2:     <object data="data:application/x-silverlight-2," type="application/x-silverlight-2">

   3:         <param name="minRuntimeVersion" value="3.0.40307.0" />

   4:         <param name="autoUpgrade" value="false" />

   5:         <param name="onerror" value="pluginError" />

   6:         ... other param values as required ...

   7:     </object>

   8: </div>

The minRuntimeVersion specifies the version required for your application, which for Silverlight 3 beta is 3.0.40307.0.  The second is to turn autoUpgrade to false.  This prevents the default experience.  The third is to add an error handler as since autoUpgrade is now false it will throw an error saying that the required version isn’t installed.  In your error function you would want to do something like this:

   1: function pluginError(sender, args) {

   2:     if (args.ErrorCode == 8001) {

   3:         var msg = "This sample application was built with Silverlight 3 Beta.\n";

   4:         msg += "You currently have Silverlight installed, but not the version required to view this sample.\n\n";

   5:         msg += "For more information about Silverlight 3, please visit: \n";

   6:         msg += "<a href=\"http://go.microsoft.com/fwlink/?LinkID=141205\">Silverlight 3 Coming Soon</a>.";

   7:  

   8:         var hostContainer = document.getElementById("silverlightControlHost");

   9:         hostContainer.innerHTML = msg;

  10:     }

  11:     else {

  12:         // handle other plugin errors here

  13:     }

  14: }

The error code of 8001 means that an upgrade is required.  Since we know we have a beta app and we know that the user has some version of Silverlight installed, but not the beta version.  Replace the container inner content with some HTML explaining that your application is a sample application and direct them to the coming soon page for more information.  This way your users aren’t sent in an endless loop, get confused, and hate you.

Why isn’t the <object> type attribute “application/x-silverlight-3”?

A common misconception is that the data and type attributes on the plugin object directly correlate to the runtime version of the plugin you are using.  This is not true.  Just because you have a Silverlight 3 application does not mean you need to change it to type=”application/x-silverlight-3” and in fact you’ll have problems if you do!  These attributes refer to the plugin MIME type and not the runtime version.  You would still use application/x-silverlight-2 for a Silverlight application (in fact you could use x-silverlight if you wanted to handle edge cases of Silverlight 1.0).

Summary

Beta software is fun and confusing.  It’s fun for us developers because we’re technically astute, understand what beta means, and are probably accustomed to working with others’ beta software all the time.  For end users, it can be confusing because they see things/links/articles and want to check it out, but may not have the required software.  As developers we can do things to help our beta visitors understand the scenario much clearer and do our job to inform.

So if you are showing Silverlight 3 beta samples, please take an extra moment to follow this guidance and trap the upgrade error code and handle it with information to inform the user.

Hope this helps!