Getting started with Silverlight: Part 7 – Out-of-browser experiences

This is part 7 in a series on getting started with Silverlight.  To view the index to the series click here.  You can download the completed project files for this sample application in C# or Visual Basic.

In our final stage of this getting started series, we are going to make our application available for installation outside of the browser.  The steps are much simpler than you think.

Create the manifest

Using Visual Studio, right-click on the Silverlight application’s project and choose properties.  You’ll see a dialog box come up – notice the checkbox about Out-of-browser settings:

When you click that you’ll be greeted with options to complete:

These settings are important to provide visual information about your application when installed and running out of the browser.

• Window Title – what is displayed in the window chrome for the app
• Width/Height – the starting width and height of your application when launched
• Shortcut name – the name for the desktop/start menu shortcut
• Download description – a description of the application
• Icons – must be PNG and must be included in the project marked as Content

Once you have all those in place your app is enabled for out-of-browser capabilities.  Let’s add an install button for your users in the navigation area in MainPage.xaml in the StackPanel called LinksStackPanel, add this XAML:

   1: <Rectangle x:Name="Divider3" Style="{StaticResource DividerStyle}"/>

   2: <HyperlinkButton x:Name="InstallLink" Style="{StaticResource LinkStyle}" 

   3:                  Content="install" Click="InstallOffline"/>

Now in MainPage.xaml.cs write the function for InstallOffline:

   1: private void InstallOffline(object sender, RoutedEventArgs e)

   2: {

   3:     if (Application.Current.Install())

   4:     {

   5:         InstallLink.Visibility = Visibility.Collapsed;

   6:     }

   7: }

You can see that after we check for a successful install, we hide the install button as it isn’t needed anymore.  What we need to do though is make that more dynamic in that it automatically knows to do that.  Additionally we don’t want the install button to show if the application is launched out-of-browser to begin with.  Luckily we have an API with a few properties that will help us out: InstallState and IsRunningOutOfBrowser.  Let’s make use of both of these.

Detecting InstallState and IsRunningOutOfBrowser

In the MainPage.xaml.cs file, we’re going to add an event handler to detect the change of our installation state of our application as well as a loaded event handler:

   1: public MainPage()

   2: {

   3:     InitializeComponent();

   4:     Loaded += new RoutedEventHandler(MainPage_Loaded);

   5:     Application.Current.InstallStateChanged += new EventHandler(OnInstallStateChanged);

   6: }

In that method we’ll check the various states to determine if our InstallLink should be visible or not (as well as the last divider):

   1: void OnInstallStateChanged(object sender, EventArgs e)

   2: {

   3:     switch (Application.Current.InstallState)

   4:     {

   5:         case InstallState.InstallFailed:

   6:             break;

   7:         case InstallState.Installed:

   8:             ToggleInstallLinks(true);

   9:             break;

  10:         case InstallState.Installing:

  11:             break;

  12:         case InstallState.NotInstalled:

  13:             ToggleInstallLinks(false);

  14:             break;

  15:         default:

  16:             break;

  17:     }

  18: }

  19:  

  20: void ToggleInstallLinks(bool hidden)

  21: {

  22:     InstallLink.Visibility = hidden ? Visibility.Collapsed: Visibility.Visible;

  23:     Link3.Visibility = hidden ? Visibility.Collapsed : Visibility.Visible;

  24: }

Now in the Loaded event handler we’ll check to see if the application is running out-of-browser or not:

   1: void MainPage_Loaded(object sender, RoutedEventArgs e)

   2: {

   3:     if (App.Current.IsRunningOutOfBrowser)

   4:     {

   5:         ToggleInstallLinks(true);

   6:     }

   7:     else

   8:     {

   9:         if (App.Current.InstallState == InstallState.Installed)

  10:         {

  11:             ToggleInstallLinks(true);

  12:         }

  13:     }

  14: }

Using these two APIs we can now automatically change our UI to hide functions not needed.

Detecting network changes

If our application doesn’t have network access, we shouldn’t allow the search to run because it may not have the capability of finding the Twitter search API.  There is an additional API for NetworkInterface that we can use to detect this.  We’ll do this in our Search.xaml.cs page by first adding an event handler in the constructor after our Loaded event handler line:

   1: NetworkChange.NetworkAddressChanged += new NetworkAddressChangedEventHandler(OnNetworkChanged);

This raises an event when the network status has changed.  Now in the OnNetworkChanged event handler we’ll check to see if the network is available and, if it isn’t, disable searching capabilities until it is:

   1: void OnNetworkChanged(object sender, EventArgs e)

   2: {

   3:     if (!NetworkInterface.GetIsNetworkAvailable())

   4:     {

   5:         // network may not be available, halt searching

   6:         SearchButton.IsEnabled = false;

   7:         SearchButton.Content = "DISCONNECTED";

   8:         _timer.Stop();

   9:     }

  10:     else

  11:     {

  12:         SearchButton.Content = "SEARCH";

  13:         SearchButton.IsEnabled = true;

  14:         _timer.Start();

  15:     }

  16: }

This is only an example of course, and you could provide other UI hints such as status indicators, etc. but for our application this should work now.

NOTE (Here be dragons): Simply checking for GetIsNetworkAvailable doesn’t guarantee in all circumstances that the Internet is not available.  Due to various ways corporations configure proxy servers and local IP addressing it is always good practice to have a fallback mechanism if you need to verify WAN Internet access.  This can be done by simply doing a WebClient request for a file on the web server – if the request succeeds you have Internet access, otherwise you may not.

You can find out more information about Out-of-browser experiences here:

• Out-of-browser APIs
• Out-of-browser Install Pattern

Out of browser updates

You may be wondering how to trigger updates to an application if it was installed on to the machine.  There is an API that a developer can use called CheckAndDownloadUpdateAsync which triggers the update model.  The update model is outlined here.  Even though that article has a different API, the model of updating is the same *after* that method above is called.

Summary

Now we’ve taken our application from a blank slate to a working application with data and that can be installed out of the browser.  I hope this has been a helpful exercise to walk through.  Download the code to be sure to play around with it and learn.  Here are some other helpful resources for you:

• Silverlight learning videos
• Optimizing your Silverlight application install experience
• Forums for asking questions

Hopefully this will get you started writing Silverlight applications!