Share via


ApplicationDeployment.UpdateCompleted Event

Definition

Occurs when ClickOnce has finished upgrading the application as the result of a call to UpdateAsync().

public:
 event System::ComponentModel::AsyncCompletedEventHandler ^ UpdateCompleted;
public event System.ComponentModel.AsyncCompletedEventHandler UpdateCompleted;
member this.UpdateCompleted : System.ComponentModel.AsyncCompletedEventHandler 
Public Custom Event UpdateCompleted As AsyncCompletedEventHandler 

Event Type

Examples

The following code example determines at application load time whether a new update is available; if a required update is available, it installs the update asynchronously. The example requires that you deploy a Windows Forms application that includes a StatusStrip control, and that this control contain a ToolStripStatusLabel control named downloadStatus.

private:
    long sizeOfUpdate;


private:
    void Form1_Load(Object^ sender, System::EventArgs^ e)
    {
        DoUpdate();
    }

public:
    void DoUpdate()
    {
        if (ApplicationDeployment::IsNetworkDeployed)
        {
            ApplicationDeployment^ currentAppDeployment =
                ApplicationDeployment::CurrentDeployment;
            currentAppDeployment->CheckForUpdateCompleted +=
                gcnew CheckForUpdateCompletedEventHandler(
                this, &Form1::currentDeploy_CheckForUpdateCompleted);
            currentAppDeployment->CheckForUpdateAsync();
        }
    }

    // If update is available, fetch it.
    void currentDeploy_CheckForUpdateCompleted(Object^ sender,
        CheckForUpdateCompletedEventArgs^ e)
    {
        if (nullptr != e->Error)
        {
            // Log error.
            return;
        }

        if (e->UpdateAvailable)
        {
            sizeOfUpdate = (long) e->UpdateSizeBytes;
            if (!e->IsUpdateRequired)
            {
                System::Windows::Forms::DialogResult 
                    updateDialogueResult = MessageBox::Show(
                    "An update is available.Would you like to update the" +
                    " application now?", "Update Available",
                    MessageBoxButtons::OKCancel);
                if (System::Windows::Forms::DialogResult::OK == 
                    updateDialogueResult)
                {
                    BeginUpdate();
                }
            }
            else
            {
                BeginUpdate();
            }
        }
    }

    void BeginUpdate()
    {
        ApplicationDeployment^ ad = ApplicationDeployment::CurrentDeployment;
        ad->UpdateCompleted +=
            gcnew AsyncCompletedEventHandler(
            this, &Form1::CurrentDeployment_UpdateCompleted);

        // Indicate progress in the application's status bar.
        ad->UpdateProgressChanged +=
            gcnew DeploymentProgressChangedEventHandler(this, 
            &Form1::ad_ProgressChanged);

        ad->UpdateAsync();
    }

    void CurrentDeployment_UpdateCompleted(Object^ sender,
        AsyncCompletedEventArgs^ e)
    {
        if (!e->Cancelled)
        {
            if (nullptr != e->Error)
            {
                System::Windows::Forms::DialogResult 
                    restartDialogueResult = MessageBox::Show(
                    "The application has been updated. Restart?",
                    "Restart Application",
                    MessageBoxButtons::OKCancel);
                if (System::Windows::Forms::DialogResult::OK == 
                    restartDialogueResult)
                {
                    Application::Restart();
                }
            }
            else
            {
                // Replace with your own error reporting or logging.
                MessageBox::Show(
                    "The application encountered an error in downloading" +
                    " the latest update. Error: {0}",
                    e->Error->Message);
            }
        }
        else
        {
            // Replace with your own error reporting or logging.
            MessageBox::Show("The update of the application's latest" +
                " version was cancelled.");
        }
    }

    void ad_ProgressChanged(Object^ sender,
        DeploymentProgressChangedEventArgs^ e)
    {
        String^ progressText =
            String::Format(
            "{0:D}K out of {1:D}K downloaded - {2:D}% complete",
            e->BytesCompleted / 1024, e->BytesTotal / 1024,
            e->ProgressPercentage);
        statusStrip1->Text = progressText;
    }
long sizeOfUpdate = 0;

private void UpdateApplication()
{
    if (ApplicationDeployment.IsNetworkDeployed)
    {
        ApplicationDeployment ad = ApplicationDeployment.CurrentDeployment;
        ad.CheckForUpdateCompleted += new CheckForUpdateCompletedEventHandler(ad_CheckForUpdateCompleted);
        ad.CheckForUpdateProgressChanged += new DeploymentProgressChangedEventHandler(ad_CheckForUpdateProgressChanged);

        ad.CheckForUpdateAsync();
    }
}

void  ad_CheckForUpdateProgressChanged(object sender, DeploymentProgressChangedEventArgs e)
{
    downloadStatus.Text = String.Format("Downloading: {0}. {1:D}K of {2:D}K downloaded.", GetProgressString(e.State), e.BytesCompleted/1024, e.BytesTotal/1024);   
}

string GetProgressString(DeploymentProgressState state)
{
    if (state == DeploymentProgressState.DownloadingApplicationFiles)
    {
        return "application files";
    } 
    else if (state == DeploymentProgressState.DownloadingApplicationInformation) 
    {
        return "application manifest";
    } 
    else 
    {
        return "deployment manifest";
    }
}

void ad_CheckForUpdateCompleted(object sender, CheckForUpdateCompletedEventArgs e)
{
    if (e.Error != null)
    {
        MessageBox.Show("ERROR: Could not retrieve new version of the application. Reason: \n" + e.Error.Message + "\nPlease report this error to the system administrator.");
        return;
    }
    else if (e.Cancelled == true)
    {
        MessageBox.Show("The update was cancelled.");
    }

    // Ask the user if they would like to update the application now.
    if (e.UpdateAvailable)
    {
        sizeOfUpdate = e.UpdateSizeBytes;

        if (!e.IsUpdateRequired)
        {
            DialogResult dr = MessageBox.Show("An update is available. Would you like to update the application now?\n\nEstimated Download Time: ", "Update Available", MessageBoxButtons.OKCancel);
            if (DialogResult.OK == dr)
            {
                BeginUpdate();
            }
        }
        else
        {
            MessageBox.Show("A mandatory update is available for your application. We will install the update now, after which we will save all of your in-progress data and restart your application.");
            BeginUpdate();
        }
    }
}

private void BeginUpdate()
{
    ApplicationDeployment ad = ApplicationDeployment.CurrentDeployment;
    ad.UpdateCompleted += new AsyncCompletedEventHandler(ad_UpdateCompleted);

    // Indicate progress in the application's status bar.
    ad.UpdateProgressChanged += new DeploymentProgressChangedEventHandler(ad_UpdateProgressChanged);
    ad.UpdateAsync();
}

void ad_UpdateProgressChanged(object sender, DeploymentProgressChangedEventArgs e)
{
    String progressText = String.Format("{0:D}K out of {1:D}K downloaded - {2:D}% complete", e.BytesCompleted / 1024, e.BytesTotal / 1024, e.ProgressPercentage);
    downloadStatus.Text = progressText;
}

void ad_UpdateCompleted(object sender, AsyncCompletedEventArgs e)
{
    if (e.Cancelled)
    {
        MessageBox.Show("The update of the application's latest version was cancelled.");
        return;
    }
    else if (e.Error != null)
    {
        MessageBox.Show("ERROR: Could not install the latest version of the application. Reason: \n" + e.Error.Message + "\nPlease report this error to the system administrator.");
        return;
    }

    DialogResult dr = MessageBox.Show("The application has been updated. Restart? (If you do not restart now, the new version will not take effect until after you quit and launch the application again.)", "Restart Application", MessageBoxButtons.OKCancel);
    if (DialogResult.OK == dr)
    {
        Application.Restart();
    }
}
Private sizeOfUpdate As Long = 0

Dim WithEvents ADUpdateAsync As ApplicationDeployment

Private Sub UpdateApplication()
    If (ApplicationDeployment.IsNetworkDeployed) Then
        ADUpdateAsync = ApplicationDeployment.CurrentDeployment

        ADUpdateAsync.CheckForUpdateAsync()
    End If
End Sub

Private Sub ADUpdateAsync_CheckForUpdateProgressChanged(ByVal sender As Object, ByVal e As DeploymentProgressChangedEventArgs) Handles ADUpdateAsync.CheckForUpdateProgressChanged
    DownloadStatus.Text = [String].Format("{0:D}K of {1:D}K downloaded.", e.BytesCompleted / 1024, e.BytesTotal / 1024)
End Sub


Private Sub ADUpdateAsync_CheckForUpdateCompleted(ByVal sender As Object, ByVal e As CheckForUpdateCompletedEventArgs) Handles ADUpdateAsync.CheckForUpdateCompleted
    If (e.Error IsNot Nothing) Then
        MessageBox.Show(("ERROR: Could not retrieve new version of the application. Reason: " + ControlChars.Lf + e.Error.Message + ControlChars.Lf + "Please report this error to the system administrator."))
        Return
    Else
        If (e.Cancelled = True) Then
            MessageBox.Show("The update was cancelled.")
        End If
    End If

    ' Ask the user if they would like to update the application now.
    If (e.UpdateAvailable) Then
        sizeOfUpdate = e.UpdateSizeBytes

        If (Not e.IsUpdateRequired) Then
            Dim dr As DialogResult = MessageBox.Show("An update is available. Would you like to update the application now?", "Update Available", MessageBoxButtons.OKCancel)
            If (System.Windows.Forms.DialogResult.OK = dr) Then
                BeginUpdate()
            End If
        Else
            MessageBox.Show("A mandatory update is available for your application. We will install the update now, after which we will save all of your in-progress data and restart your application.")
            BeginUpdate()
        End If
    End If
End Sub

Private Sub BeginUpdate()
    ADUpdateAsync = ApplicationDeployment.CurrentDeployment
    ADUpdateAsync.UpdateAsync()
End Sub


Private Sub ADUpdateAsync_UpdateProgressChanged(ByVal sender As Object, ByVal e As DeploymentProgressChangedEventArgs) Handles ADUpdateAsync.UpdateProgressChanged
    Dim progressText As String = String.Format("{0:D}K out of {1:D}K downloaded - {2:D}% complete", e.BytesCompleted / 1024, e.BytesTotal / 1024, e.ProgressPercentage)
    DownloadStatus.Text = progressText
End Sub


Private Sub ADUpdateAsync_UpdateCompleted(ByVal sender As Object, ByVal e As AsyncCompletedEventArgs) Handles ADUpdateAsync.UpdateCompleted
    If (e.Cancelled) Then
        MessageBox.Show("The update of the application's latest version was cancelled.")
        Exit Sub
    Else
        If (e.Error IsNot Nothing) Then
            MessageBox.Show("ERROR: Could not install the latest version of the application. Reason: " + ControlChars.Lf + e.Error.Message + ControlChars.Lf + "Please report this error to the system administrator.")
            Exit Sub
        End If
    End If

    Dim dr As DialogResult = MessageBox.Show("The application has been updated. Restart? (If you do not restart now, the new version will not take effect until after you quit and launch the application again.)", "Restart Application", MessageBoxButtons.OKCancel)
    If (dr = System.Windows.Forms.DialogResult.OK) Then
        Application.Restart()
    End If
End Sub

Remarks

The UpdateCompleted event is called on the main application thread. You may call your application's Windows Forms controls directly within this callback without triggering an exception.

Check the Error property of the AsyncCompletedEventArgs supplied to this callback. If this property is null, the installation was successful; if it is not null, the installation did not succeed, and you can find more information about this installation failure through the Error property. Once the update has been downloaded, you will need to call the Restart method on the Application to use the newer version of the application.

If the installation of the update was canceled by a call to UpdateAsyncCancel, the Cancelled property of the AsyncCompletedEventArgs class will be true.

To use this event handler, your application must import both the System.Deployment.Application and System.ComponentModel namespaces.

Applies to