Silverlight-based applications typically run within Web pages, but you can enable users to install them from the Web and run them outside the browser. The following QuickStart shows you how to enable out-of-browser support and provides a quick survey of the features available.

This QuickStart contains the following sections:

Configuration, Install, Launch, and Uninstall

You can enable out-of-browser support in Visual Studio on the Silverlight page of the project designer.

This enables a right-click menu option so that users can install the application from its host Web page.

Users are required to confirm the installation, and they can also choose shortcut locations.

The out-of-browser application launches immediately after installation. Users can uninstall with a right-click menu option or with Control Panel -> Programs and Features -> Uninstall.

If your application is self-contained, you don't need to do anything else. The application will have the same behavior both inside and outside the browser.

Basic Customization

The Out-of-Browser Settings button (shown above) gives you access to various configuration options. These options are documented in the Silverlight MSDN topic How to: Configure an Application for Out-of-Browser Support.

In most cases, you'll want to do a few basic things like the following:

• Set the shortcut and window title-bar text.
• Set the window startup size and location.
• Set the icons; these are used in the install dialog box (as shown), in shortcuts, on the taskbar, and elsewhere.

Advanced Customization

You can also add code to your application so that it behaves differently outside the browser. For example, you can provide out-of-browser substitutes for external dependencies or make use of out-of-browser-only features.

The following sections describe a few common scenarios.

Scenario: Display a custom install experience inside the browser and an application update experience outside the browser.

You can show or hide the relevant user interface (UI) components depending on the Application.InstallState and Application.IsRunningOutOfBrowser property values, as shown in the following example.

C#

InstallButton.Visibility =
    Application.Current.InstallState == InstallState.NotInstalled ?
    Visibility.Visible : Visibility.Collapsed;

UpdateButton.Visibility = 
    Application.Current.IsRunningOutOfBrowser ?
    Visibility.Visible : Visibility.Collapsed;

Visual Basic

InstallButton.Visibility = If(
    Application.Current.InstallState = InstallState.NotInstalled,
    Visibility.Visible, Visibility.Collapsed)

UpdateButton.Visibility = If(
    Application.Current.IsRunningOutOfBrowser,
    Visibility.Visible, Visibility.Collapsed)

Scenario: Provide your own windowing experience outside the browser. (This requires an "elevated trust" installation; more on that below.)

You can draw the entire window surface yourself, and manipulate the window programmatically through the Window class. This example implements a draggable border and title bar by using a nested Grid layout and several MouseLeftButtonDown event handlers that call the Window.DragMove and Window.DragResize methods.

C#

Window mainWindow = Application.Current.MainWindow;
TitleBar.MouseLeftButtonDown += delegate { 
    mainWindow.DragMove(); }; 
TopLeftCorner.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.TopLeft); };
TopEdge.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.Top); };
TopRightCorner.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.TopRight); };
LeftEdge.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.Left); };
EastEdge.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.Right); };
BottomLeftCorner.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.BottomLeft); };
BottomEdge.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.Bottom); };
BottomRightCorner.MouseLeftButtonDown += delegate { 
    mainWindow.DragResize(WindowResizeEdge.BottomRight); };

Visual Basic

Dim mainWindow = Application.Current.MainWindow
AddHandler TitleBar.MouseLeftButtonDown,
    Sub() mainWindow.DragMove()
AddHandler TopLeftCorner.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.TopLeft)
AddHandler TopEdge.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.Top)
AddHandler TopRightCorner.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.TopRight)
AddHandler LeftEdge.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.Left)
AddHandler EastEdge.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.Right)
AddHandler BottomLeftCorner.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.BottomLeft)
AddHandler BottomEdge.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.Bottom)
AddHandler BottomRightCorner.MouseLeftButtonDown,
    Sub() mainWindow.DragResize(WindowResizeEdge.BottomRight)

For the complete example, download the C# sample project.

Scenario: Implement popup alerts using the NotificationWindow class.

To display the popup, create a new NotificationWindow instance, set its Content property, then call Show, passing in the display duration in milliseconds. To activate the main window from the notification, call the Window.Activate method.

C#

var notification = new NotificationWindow();
var message = new IncomingMessageNotification();
message.MouseLeftButtonDown += delegate { 
    Application.Current.MainWindow.Activate(); };
notification.Content = message;
notification.Show(3000); 

Visual Basic

Dim notification As New NotificationWindow()
Dim message As New IncomingMessageNotification()
AddHandler message.MouseLeftButtonDown,
    Sub() Application.Current.MainWindow.Activate()
notification.Content = message
notification.Show(3000)

Scenario: Replace browser dependencies. For example, you can display HTML, Flash, or JavaScript-based advertising on the host Web page inside the browser and in the WebBrowser control outside the browser.

XAML

<WebBrowser x:Name="Advertisement" Width="233" Height="50" Margin="20"
  Source="http://www.adatum.com/advertising.aspx" />

C#

Advertisement.Visibility = 
    Application.Current.IsRunningOutOfBrowser ?
    Visibility.Visible : Visibility.Collapsed;

Visual Basic

Advertisement.Visibility = If(
    Application.Current.IsRunningOutOfBrowser,
    Visibility.Visible, Visibility.Collapsed)

Scenario: Replace network dependencies. For example, you can use Isolated Storage (with an increased default capacity of 25 MB) to cache data when the application is offline.

You can determine whether there is a network connection by calling the NetworkInterface.GetIsNetworkAvailable method, as shown in the following code. You can also detect a change in network connectivity by handling the NetworkChange.NetworkAddressChanged event.

C#

int highScore;

public InitializeHighScore()
{
    var appSettings = IsolatedStorageSettings.ApplicationSettings;

    if (NetworkInterface.GetIsNetworkAvailable()) 
        GetHighScoreFromWebService(); 
    else highScore = appSettings.Contains("highScore") ?
        (int)appSettings["highScore"] : 0;

    Application.Current.MainWindow.Closing += delegate {
        if (NetworkInterface.GetIsNetworkAvailable()) 
            SaveHighScoreToWebService();
        else appSettings["highScore"] = highScore; };
}

Visual Basic

Dim highScore As Integer

Private Sub InitializeHighScore()
    Dim appSettings = IsolatedStorageSettings.ApplicationSettings

    If (NetworkInterface.GetIsNetworkAvailable()) Then
        GetHighScoreFromWebService()
    Else
        highScore = If(appSettings.Contains("highScore"), appSettings("highScore"), 0)
    End If

    AddHandler Application.Current.MainWindow.Closing,
        Sub()
            If (NetworkInterface.GetIsNetworkAvailable()) Then
                SaveHighScoreToWebService()
            Else
                appSettings("highScore") = highScore
            End If
        End Sub
End Sub

Scenario: Interoperate with native code. For example, you can access Automation APIs for applications such as Microsoft Office by using the AutomationFactory class. (This also requires elevated trust.)

C#

private void ExportButton_Click(object sender, RoutedEventArgs e)
{
    dynamic excel = AutomationFactory.CreateObject("Excel.Application");
    excel.Visible = true;
    excel.workbooks.Add();
    dynamic sheet = excel.ActiveSheet;
    dynamic cell = null;
    int i = 1;
    foreach (Customer c in DataGrid1.ItemsSource)
    {
        cell = sheet.Cells[i /*row*/, 1 /*col*/];
        cell.Value = c.CustomerName;
        cell.ColumnWidth = 14;
        cell = sheet.Cells[i /*row*/, 2 /*col*/];
        cell.Value = c.UnitSales;
        cell.ColumnWidth = 5;
        i++;
    }
}

Visual Basic

Private Sub ExportButton_Click(ByVal sender As System.Object,
                               ByVal e As System.Windows.RoutedEventArgs)
    Dim excel = AutomationFactory.CreateObject("Excel.Application")
    excel.Visible = True
    excel.workbooks.Add()
    Dim sheet = excel.ActiveSheet
    Dim cell = Nothing
    Dim i As Integer = 1
    For Each c In DataGrid1.ItemsSource
        cell = sheet.Cells(i, 1)
        cell.Value = c.CustomerName
        cell.ColumnWidth = 14
        cell = sheet.Cells(i, 2)
        cell.Value = c.UnitSales
        cell.ColumnWidth = 5
        i = i + 1
    Next
End Sub

Debugging

Visual Studio provides an option to launch an application outside the browser when you press F5 to start debugging. This prevents you from having to uninstall and reinstall after each change in order to debug.

Note: If your solution includes a Web project, then you must also set the Silverlight project as the startup project to debug it outside the browser.

Trusted Applications and XAP Signing

Some out-of-browser-only features require an elevated trust installation because they can bypass some of the restrictions of the Silverlight security sandbox or otherwise pose a potential threat. To use these features, you must specify the requirement in the Out-of-Browser Settings dialog box.

When users attempt to install an application that requires elevated trust, they are shown a security warning instead of the normal install dialog box. The default warning indicates that the publisher is not verified, and does not display your application icon.

You should always sign an application that requires elevated trust to enable verification that you are the publisher. For debugging purposes, Visual Studio lets you create and use a test certificate.

A signed application still displays the security warning at install time, but the message is milder and includes your application icon.

After installation, the trusted application can access all of the out-of-browser features. Additionally, it is not subject to security restrictions such as user-consent requests and full-screen keyboard limitations.

For more information about elevated trust features and application signing, see the Silverlight MSDN topic Trusted Applications.

See Also

Conceptual Overview Topics

• Out-of-Browser Support
• Trusted Applications

How-To Topics

• How to: Configure an Application for Out-of-Browser Support
• How to: Implement Offline Support for Out-of-Browser Applications
• How to: Access the Local File System in Trusted Applications
• How to: Use Automation in Trusted Applications

Reference Topics

• Window Class
• NotificationWindow Class
• WebBrowser Class
• AutomationFactory Class