Share via

  • Article

Application.CheckAndDownloadUpdateAsync Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Updated: September 2010

Launches an asynchronous process to check for and download an updated version of the application.

Namespace:  System.Windows
Assembly:  System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Sub CheckAndDownloadUpdateAsync

public void CheckAndDownloadUpdateAsync()

Remarks

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.

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.

NoteNote:

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

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

Examples

The following code example demonstrates how to use this method. This example is part of a larger example available in How to: Implement Offline Support for Out-of-Browser Applications.

Private WithEvents app As Application = Application.Current


...


Private Sub updateButton_Click(ByVal sender As Object, _
    ByVal e As RoutedEventArgs)

    app.CheckAndDownloadUpdateAsync()

End Sub

Private Sub App_CheckAndDownloadUpdateCompleted(ByVal sender As Object, _
    ByVal e As CheckAndDownloadUpdateCompletedEventArgs) _
    Handles app.CheckAndDownloadUpdateCompleted

    If e.UpdateAvailable Then

        MessageBox.Show("An application update has been downloaded. " & _
            "Restart the application to run the new version.")

    ElseIf e.Error IsNot Nothing Then
        MessageBox.Show( _
            "An application update is available, but an error has occurred.\n" & _
            "This can happen, for example, when the update requires\n" & _
            "a new version of Silverlight or requires elevated trust.\n" & _
            "To install the update, visit the application home page.")
        LogErrorToServer(e.Error)
    Else
        MessageBox.Show("There is no update available.")
    End If

End Sub

Private Sub LogErrorToServer(ByRef ex As Exception)
    ' Not implemented. Logging the exact error to the server can help
    ' diagnose any problems that are not resolved by the user reinstalling
    ' the application from its home page. 
End Sub

Application app = Application.Current;
public MainPage()
{
    InitializeComponent();
    LayoutRoot.DataContext = Deployment.Current.OutOfBrowserSettings;
    UpdateUI();
    app.CheckAndDownloadUpdateCompleted += 
        App_CheckAndDownloadUpdateCompleted;
    app.InstallStateChanged += (s,e) => UpdateUI();
    NetworkChange.NetworkAddressChanged += 
        (s, e) => UpdateNetworkIndicator();

    MessageBox.Show(Deployment.Current.OutOfBrowserSettings
        .WindowSettings.WindowStyle.ToString());
}


...


private void updateButton_Click(object sender, RoutedEventArgs e)
{
    app.CheckAndDownloadUpdateAsync();
}

private void App_CheckAndDownloadUpdateCompleted(object sender,
    CheckAndDownloadUpdateCompletedEventArgs e)
{
    if (e.UpdateAvailable)
    {
        MessageBox.Show("An application update has been downloaded. " +
            "Restart the application to run the new version.");
    }
    else if (e.Error != null)
    {
        MessageBox.Show(
            "An application update is available, but an error has occurred.\n" +  
            "This can happen, for example, when the update requires\n" + 
            "a new version of Silverlight or requires elevated trust.\n" + 
            "To install the update, visit the application home page.");
        LogErrorToServer(e.Error);
    }
    else
    {
        MessageBox.Show("There is no update available.");
    }
}

private void LogErrorToServer(Exception ex)
{
    // Not implemented. Logging the exact error to the server can help
    // diagnose any problems that are not resolved by the user reinstalling
    // the application from its home page. 
}

Version Information

Silverlight

Supported in: 5, 4, 3

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Change History

Date

History

Reason

September 2010

Added note about ShortName requirement.

Customer feedback.