Silverlight Out-of-Browser Applications

.Out-of-Browser Applications

"Out-of-Browser applications appear and function much like a desktop application. They contain the same standard window as desktop applications and can be launched from the user’s desktop or the start menu. When given elevated trust, they can be almost as powerful as a desktop application."

Silverlight Out-of-Browser applications (OOB) were introduced in Silverlight version 3, enhanced in version 4 with a powerful elevated trust capability, and given support for multiple windows in version 5. Users can install an OOB from a host Web page. Administrator privileges are not required for installing an OOB. The OOB is placed in the user's profile folder, making it only available to the user who installed it. The install can provide a link to the application from the user’s desktop or start menu.

OOBs appear and function much like a desktop application. OOBs contain the same standard window as desktop applications and can be launched from the user’s desktop or the start menu. An Internet connection is not required as OOBs can be designed to working offline, or with intermittent Internet connectivity. When given elevated trust, OOBs can be almost as powerful as a desktop application. OOBs conceal the browser's presence to provide the illusion of running outside of a browser. The shortcut to the OOB shows that it is actually running under the sllauncher.exe program:

C:\Program Files (x86)\Microsoft Silverlight\sllauncher.exe" 856784606.localhost

The sllauncher.exe program hosts a browser control without the standard browser user interface (ie. no navigation buttons, toolbar, etc.).



Overview

  • Without elevated trust, OOBs have mostly the same restrictions as in-browser application, although they do have some additional features such as application updating, window manipulation, and notification windows. With elevated trust OOBs gain a powerful set of additional privileges (local user-folder file system access, COM interoperability, no cross-domain access restrictions, fewer user-consent restrictions, window customization, multiple windows).

  • OOBs do not contain all the capabilities of an in-browser Silverlight application, such as the ability to access the DOM. Also, OOBs always run in the Trusted zone, which by default will not be able to communicate with applications running in the Internet zone. However this can be easily changed.

  • Typical Silverlight in-browser applications are allocated 1MB of disk space, while OOBs are allocated 25MB. In both cases more disk space can be allocated if approved through a user prompt.

  • Silverlight remembers the root URI of the website used to download the OOB. This "website of origin" may be given additional privileges, such as the ability to apply updates to the OOB. If OOBs are installed using sllauncher.exe (instead of from a browser), then usually the /origin parameter is used to identify the server which will be used for updates. There are also settings in Visual Studio to identify the website of origin when debugging OOBs.

  • Creating a OOB in Visual Sudio requires simple updates to the project's properties. You can provide the OOB project with icons used by typical desktop applications (eg. title bar, shortcut, etc.). With elevated trust, you can even customize the windows appearance (eg. borderless with round corners, etc.).

  • Installing the OOB onto a desktop computer can be accomplished with the default Silverlight install menu or with a custom install menu. The custom install method must be called from an event handler that responds to a user-initiated action. OOBs can also be silently installed outside of a browser using sllauncher.exe. These install methods are described below.

Simple OOB with Default Install Menu

Silverlight OOBs contain a default install menu. The steps for creating a simple OOB (with the default install menu) using Visual Studio 2012 are:

  1. Create a new Silverlight project (with associated web project).
  2. Change the OOB project's properties:
    1. Right-click on the Silverlight project in the Solution Explorer.
    2. Go to "Properties" and check the Enable running application out of browser check box.
    3. Press the Out-of-Browser Settings ... button. A dialog box will display containing the following:
      • Use GPU Acceleration checkbox (check if graphics acceleration is desired).
      • Show install menu checkbox (check if you want to use the Silverlight install menu instead of coding your own install interface).
      • Require elevated trust when running outside the browser checkbox (check if application needs elevated trust).
      • You can also set the screen dimensions (defaults to 800 x 600), the window title, the shortcut name, and the application description. The shortcut name is used as the application name in several places, such as the start menu. The application description displays when you hover over the application name in the start menu.
      • You can also provide various size icons for use in your application, instead of using the default icon. If you only specify the 128 x 128 icon, it will be scaled down for the smaller icon sizes. However the scaled icons may not look as good as if you do the scaling yourself.
      • If you have selected elevated trust, you can also select a window style (default is borderless round corners). As a security measure, untrusted code is not allowed to turn off standard Windows borders.
    4. After updating the setting in the dialog box, press the OK button to save the settings. Notice the settings from the dialog box will be saved in a file called OutOfBrowserSettings.xml under the Silverlight project.
    5. Save the project.
  3. Set up the desired UIElements in the XAML.
  4. Run the project.

The OOB can be installed on the desktop computer by using Silverlight's default install menu. This installation method requires you initiate the install from a browser. For example, inside Visual Studio, the steps for installing an OOB are:

  1. Set the associated Web project (xxxx.Web project) as the Startup project. When you check the Enable running application out of browser check box, Visual Studio automatically changes the Startup project to be the Silverlight project. The startup project needs to be set back to the Web project in order for the install menu to display.
  2. Run the project.
  3. Right-click inside the browser window and select the Install Simple OOB Application onto this computer ... option from the context menu.
  4. When the Install Application dialog box appears, select the desired shortcuts and press the OK button. Note the dialog box indicates the website used for the install. The installing website root URL is stored by Silverlight and will be given additional capabilities within the instance of the application install.

After the install, the application can be run from the desktop, as shown in the series of screen shots below. Notice the title bar on the desktop application indicates the installing website root URL (localhost in this case). If you right-click inside the application you will also receive a menu option to Remove this application... which will uninstall the application. You can also uninstall the program from the control panel, just as you would any other desktop application.

Out-of-Browser applications appear and function much like a desktop application. They contain the same standard window as desktop applications and can be launched from the user’s desktop or the start menu. When given elevated trust, they can be almost as powerful as a desktop application.

.OOB Default Install


Default Install of Out-of-Browser Application

Creating an OOB with a Custom Install Interface

The steps for creating a Silverlight OOB with a custom install interface, using Visual Studio 2012 are:

  • Create a new Silverlight project (with associated web project).
  • Change the OOB project's properties:
    1. Right-click on the project in the Solution Explorer.
    2. Go to "Properties" and check the "Enable running application out of browser" check box.
    3. Press the "Out-of-Browser Setting ... " button. Inside the dialog box check the "Require elevated trust when running outside the browser" checkbox. The checkbox for "Show install menu" should be checked by default -- leave it checked. Press the "OK" button to close the dialog box.
    4. Inside the projects' Properties Dialog, you can also set the screen dimensions (defaults to 800 x 600), the window title, the shortcut name, and the window style (default, no border, borderless round corners).
    5. Save the project.
  • Set up the Install button and desired UIElements in the XAML.
  • Code the following logic in the behind-file:
    1. Register and add the event handler for the Loaded event. Handler logic performs checks app install state, and if installed, runs the appIsInstalled logic.
    2. Register and add the event handler for the InstallStateChanged event. Handler logic runs the appIsInstalled logic.
    3. Register and add the event handler for the install button's Click event. Handler logic installs the app (Application.Current.Install();
Install OOB from Browser
.Install OOB App from Browser


Custom Install of Out-of-Browser Application

Silverlight OOB with Customer Interface Code

  • OOBs need to access the Application object to determine if the application is currently installed:

            void MainPage_Loaded(object sender, RoutedEventArgs e)
            {
                if (Application.Current.InstallState == InstallState.Installed)
                {
                    // App is installed, run app logic
                }
            }

    Note: The Application class is a per-AppDomain singleton type that implements the static Current property to provide shared access to the Application instance for the current AppDomain.

  • The application can then execute the appropriate logic based on the installation state of the application:
    • If the application is not installed

      Display the install button, with its event handler set to install the app (Application.Current.Install()).

    • If the application is installed

      Disable (or make invisible) the install button.
      Make the screen controls visible, with their associated event handlers added.
      Start program logic.

The following code is for the OOB shown at the top of this page. In addition to the OOB logic, notice the second text box is bound to the first text box in the XAML code (Text="{Binding ElementName=firstTextBox, Path=Text}"). So anything typed in the first text box will also appear in the second text box ... but not vice versa.

MainPage.xaml

<UserControl x:Class="OOB.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="300" d:DesignWidth="400">

    <Grid x:Name="LayoutRoot" Background="White">
        <Button Content="Install App"
                Height="23"
                HorizontalAlignment="Left"
                Margin="152,76,0,0"
                Name="installButton"
                VerticalAlignment="Top"
                Width="75"
                Click="installButton_click" />
        <TextBlock Height="23"
                   HorizontalAlignment="Left"
                   Margin="0,29,0,0"
                   Name="pageTitle"
                   Text="Kevin's Out-of-Browser Application"
                   VerticalAlignment="Top"
                   Width="400"
                   TextAlignment="Center"
                   Visibility="Collapsed" />
        <TextBox Height="23"
                 HorizontalAlignment="Left"
                 Margin="128,131,0,0"
                 Name="firstTextBox"
                 VerticalAlignment="Top"
                 Width="120"
                 Visibility="Collapsed"
                 Text="{Binding}" />
        <TextBox Height="23"
                 HorizontalAlignment="Left"
                 Margin="128,179,0,0"
                 Name="secondTextBox"
                 VerticalAlignment="Top"
                 Width="120"
                 Visibility="Collapsed"
                 Text="{Binding ElementName=firstTextBox, Path=Text}" />
        <TextBlock Height="15"
                   HorizontalAlignment="Left"
                   Margin="12,185,0,0"
                   Name="textBlock1"
                   Text="Bound To Name Field"
                   VerticalAlignment="Top"
                   Width="98"
                   FontSize="9"
                   Visibility="Collapsed" />
        <TextBlock FontSize="9"
                   Height="15"
                   HorizontalAlignment="Left"
                   Margin="12,137,0,0"
                   Name="textBlock2"
                   Text="Name Field"
                   VerticalAlignment="Top"
                   Width="98"
                   Visibility="Collapsed" />
    </Grid>
</UserControl>

MainPage.xaml.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;

namespace OOB
{
    public partial class MainPage : UserControl
    {
        public MainPage()
        {
            InitializeComponent();
            this.Loaded += new RoutedEventHandler(MainPage_Loaded);
            Application.Current.InstallStateChanged += new EventHandler(Current_InstallStateChanged);
            firstTextBox.DataContext = "";           
        }

        private void installButton_click(object sender, RoutedEventArgs e)
        {
            Application.Current.Install();
        }

        void MainPage_Loaded(object sender, RoutedEventArgs e)
        {
            if (Application.Current.InstallState == InstallState.Installed)
            {
                isInstalledLogic();
            }
        }

        private void isInstalledLogic()
        {
            installButton.Visibility = Visibility.Collapsed;
            firstTextBox.Visibility = Visibility.Visible;
            secondTextBox.Visibility = Visibility.Visible;
            pageTitle.Visibility = Visibility.Visible;
            textBlock2.Visibility = Visibility.Visible;
            textBlock1.Visibility = Visibility.Visible;
        }

        void Current_InstallStateChanged(object sender, EventArgs e)
        {
            isInstalledLogic();
        }

    }
}

Silent Install of OOB using sllauncher.exe

  • To install Silverlight OOB outside of Visual Studio (and browser):
    1. Determine path to the Microsoft Silverlight Out-of-Browser Launcher program (sllauncher.exe). Mine was "C:\Program Files (x86)\Microsoft Silverlight\sllauncher.exe".
    2. Put your .xap file into desired folder. Mine was in "C:\sl_apps\oob2.xap".
    3. Determine the http address of the xap file. Mine was http://localhost:55769/oob2.xap.
    4. Create the following command in notepad using the three values determined above. The command must be one long line with no line return characters.

      "C:\Program Files (x86)\Microsoft Silverlight\sllauncher.exe" /install:"C:\sl_apps\oob2.xap" /origin:http://localhost:55769/oob2.xap
      /shortcut:desktop+startmenu /overwrite


      Copy the command from notepad and paste (right-click) into command window. Press enter to execute command.
    5. When successful, the command will execute without any messages and the shortcut will be created in specified places.
Executing OOB Launcher in Command Window
.Command Window with Silverlight OOB Launcher


Command Window with Silverlight OOB Launcher

Updating the OOB

  • Silverlight maintains the OOB executable in local storage (e.g. local hard drive), so the user has to request updates be downloaded. The Application class has a method to check and download updated versions of the application:
    • CheckAndDownloadUpdateAsync - Handle the CheckAndDownloadUpdateCompleted event to receive notification when the application has finished checking for an update. In the event handler, the UpdateAvailable property is true if a newer version of the application was discovered and successfully downloaded. In this case, you can alert the user to restart the application in order to load the update.
  • Applications can not be upgraded to have elevated trust. To gain elevated trust the application must be uninstalled, and reinstalled with the version permitting elevated trust.