Out-of-Browser Support

Out-of-Browser Install, Launch, and Uninstall

To install a properly configured Silverlight application, a user right-clicks the application within its host Web page and then selects Install <application name> onto this computer. This causes the following dialog box to appear, which enables the user to specify the location of the application shortcuts.

If you configure the application to require elevated trust, a security warning dialog box appears instead. This dialog box contains the same shortcut options, but also alerts the user that the application will have greater access to the computer. For more information, see Trusted Applications.

The application name on the right-click menu and in the dialog box corresponds to the shortcut name in the out-of-browser configuration. The image on the dialog box corresponds to the largest icon in the configuration. If you do not specify any icons in the configuration, the default icon is used, as shown in the example image.

You can display the installation dialog box programmatically by calling the Application.Install method. However, this works only within an event handler for a user-initiated event, and only if the application is correctly configured.

Note:
System administrators can disable the ability to install trusted applications. In this case, attempting to install has no effect, and the Install method returns false. For more information, see Trusted Applications.

There are several good reasons to provide a custom installation experience for out-of-browser applications:

• To ensure that the out-of-browser install option is discoverable.

• To describe what will be installed and how long it will take to install.

• To indicate whether any functionality requires an active network connection.

The last two points are particularly important for applications where the boundaries between the Web site, the application, and the content are unclear. For example, you should inform users whether they are downloading an entire library of videos or just a video browser that requires a network connection.

If you handle the MouseRightButtonDown event, the application right-click menu is suppressed automatically. In this case, you must provide your own out-of-browser install UI. If you do not handle the MouseRightButtonDown event and you want to suppress the right-click install option, set the OutOfBrowserSettings.ShowInstallMenuItem property to false in the out-of-browser configuration. For more information, see How to: Configure an Application for Out-of-Browser Support.

User consent is required for out-of-browser installation, so you cannot disable the installation dialog box. However, you can access the configuration data through the Deployment.OutOfBrowserSettings property if you want to display it in your own UI.

Administrator privileges are not required for out-of-browser installation. When a user installs an application, a copy is placed in an out-of-browser application cache located in the user's profile folder. This means that the application is available only to the user who installed it.

The user can launch the application through the shortcuts specified in the installation dialog box. The shortcuts run a program named sllauncher.exe, passing it a unique ID assigned to the out-of-browser application. The sllauncher program loads the application into a window created with the width, height, and title bar text specified in the out-of-browser configuration.

To remove an installed application, the user launches the application, right-clicks it, and then selects Remove this application. Alternately, the user can uninstall the application from Programs and Features in Control Panel. This is necessary if you suppress the application right-click menu by handling the MouseRightButtonDown event.

System administrators can use the Silverlight 4 version of sllauncher.exe to automate out-of-browser installs. For more information, see the Silverlight Deployment Guide.

Detecting Network Connectivity and Out-of-Browser Status

Many Silverlight-based applications depend on network or browser-based services, and will not work correctly outside the browser. For example, the Deep Zoom feature will not work without a network connection, and the HTML Bridge feature will not work without a host Web page.

To address this limitation, you can modify your application code to detect the network connectivity and out-of-browser state, and provide alternative code paths when appropriate. For example, you can replace browser-based HTML with HTML rendered in the WebBrowser control.

You can check the network connectivity state by calling the NetworkInterface.GetIsNetworkAvailable method.

To respond to connectivity changes, handle the NetworkChange.NetworkAddressChanged event.

You can determine whether an application has been installed for out-of-browser use by checking the Application.InstallState property. To respond to out-of-browser installation, handle the Application.InstallStateChanged event. You can also determine whether an application was launched from outside the browser by checking the Application.IsRunningOutOfBrowser property.

Typically, you will provide an alternate code path for any application functionality that relies on network or browser services. For example, you can use isolated storage to cache network-based data for offline use. You can then respond to network availability by synchronizing the cached data with the server.

Each out-of-browser application can use 25 MB of isolated storage by default. For more information, see Isolated Storage. Alternately, you can configure your application to require elevated trust, which enables the application to store user state information and other data on the local file system.

Note:
If you have multiple instances of an out-of-browser application running on the same computer and you use IsolatedStorageSettings, you may experience unexpected behavior when reading and saving settings. If this is a scenario for your application, consider using the IsolatedStorageFile APIs instead of IsolatedStorageSettings.

You can use local messaging to communicate between an out-of-browser application and a Web-hosted application. However, in Internet Explorer, local messaging is disabled by default between applications that run within different security zones. Web-hosted applications typically run within the Internet zone, while out-of-browser applications run within the Trusted zone. Therefore, to enable local messaging for this scenario, you must set the LocalMessageReceiver.DisableSenderTrustCheck property to true. For more information, see Communication Between Local Silverlight-Based Applications.

Special Features for Out-of-Browser Applications

Out-of-browser applications that target Silverlight 4 or later can use the following features that are unavailable to browser-hosted applications:

• Window manipulation. You can modify the out-of-browser application window at run time. For example, you can change its size, display it as a topmost window, and minimize or maximize it programmatically. You can also handle the Window.Closing event, which you can cancel except when the computer is shutting down or the user is logging off. The Closing event enables you to perform actions such as displaying a warning if the user has unsaved changes in the application data. For more information, see Window.

• Window customization. Trusted applications can hide the title bar and border of the out-of-browser application window in order to provide a completely customized user interface. The Window class provides APIs that trusted applications can use to replace the title bar buttons and enable mouse dragging to move or resize the window. For more information, see Trusted Applications.

• HTML hosting. You can display HTML content within your out-of-browser application to replace functionality provided by a host Web page. For example, you can display HTML-based ads that you would normally display alongside your Silverlight-based application in a Web page. For more information, see the WebBrowser class.

• Notification windows. Out-of-browser applications can display temporary notification windows, similar to the ones used by Outlook, to inform users of incoming e-mail. Notification windows provide limited user interactivity, but can respond to user clicks, for example, to activate the main out-of-browser window. For more information, see the NotificationWindow class.

• Digital Rights Management support for offline media files. For more information, see Digital Rights Management (DRM).

• Elevated trust. Trusted applications can integrate with native functionality and are not subject to the same security restrictions as normal Silverlight-based applications. For example, trusted applications do not restrict cross-domain Web requests. For more information, see Trusted Applications.

• File system access. Trusted applications can access System.IO types and related types that are otherwise unavailable to Silverlight. These APIs provide direct read and write access to files in user folders on the local computer. For more information, see How to: Access the Local File System in Trusted Applications.

Trusted, out-of-browser applications that target Silverlight 5 can use the following features that are unavailable to earlier versions:

• Multiple windows. You can create additional Window instances to provide a more flexible user interface. For example, users can open parts of your application in separate windows, and then move those windows to a second monitor. You can also create modal dialog boxes and tear-off windows. For more information, see Window.

• Additional elevated trusted capabilities. In Silverlight 5, trusted applications can use PInvoke to call functions in unmanaged assemblies. Trusted applications also have greater access to the local file system. Additionally, system administrators can enable trusted applications to run inside the browser (although without the ability to use the Window class). For more information, see Trusted Applications.

Checking for Application Updates

If your application was launched from outside the browser, and network connectivity is available, you can check the host server for application updates.

Note:
In general, you should check for updates only with the consent of the user, and notify the user when an update is available.

To check for and retrieve an update, call the CheckAndDownloadUpdateAsync method on the UI thread, and handle the Application.CheckAndDownloadUpdateCompleted event. In the event handler, the UpdateAvailable property is true if a newer version of your application was discovered and successfully downloaded. In this case, you can alert the user to restart in order to load the update.

If an application update is available, but uses a newer version of Silverlight that the user has not yet installed, the update will not be downloaded. This also occurs if an update changes the application to require elevated trust. In both cases, the UpdateAvailable property value is false, and the Error property value is an Exception instance. With a Silverlight version change, the exception is a PlatformNotSupportedException instance. With a security change, the exception is a SecurityException instance. When this happens, you can alert the user to open the application's host Web site, triggering your HTML-based Silverlight upgrade experience.

Silverlight 4 provides support for running out-of-browser applications with elevated trust. Trusted applications cannot use the update mechanism described in this section unless the application and the update have both been signed with the same valid, code-signing certificate. To update a trusted application that does not have a valid signature, users must uninstall the old version and install the new version manually. For more information, see Trusted Applications.

Note:
The OutOfBrowserSettings.ShortName value must remain the same across multiple versions of an application for the update mechanism to work correctly.

Debugging Out-of-Browser Applications

Visual Studio 2010 and Silverlight 4 provide additional support for debugging out-of-browser applications.

In Visual Studio, on the Debug page of the Project Designer, you can select Out-of-browser application as the Start Action. Then, when you start debugging, Visual Studio will launch the out-of-browser application and attach the debugger automatically. If you have a Web project in your solution, you must set the Silverlight project as the startup project in order to use this feature.

Silverlight 4 provides command-line support for debugging on Windows only. You can use sllauncher.exe to run a XAP file in an out-of-browser window as if it had been installed. You can then attach a debugger to the out-of-browser window process.

To run a XAP file in an out-of-browser window, use the following command line:

sllauncher /emulate:xapfilename /origin:uri

The origin parameter indicates the URI of the application's site of origin. This is required to assign security privileges, such as access to isolated storage. It also provides a base URI that the application can use to resolve relative URIs, access remote resources, and perform application updates.

You can find the sllauncher.exe program in one of the following locations:

• On 32-bit operating systems: C:\Program Files\Microsoft Silverlight

• On 64-bit operating systems: C:\Program Files (x86)\Microsoft Silverlight

For information about sllauncher error messages, see SLLauncher Error Messages.

Version Notes

 In Silverlight for Windows Phone, the desktop out-of-browser feature does not apply.

See Also

Tasks

Concepts

Other Resources