Export (0) Print
Expand All

ApplicationDeployment.UpdateAsync Method

Note: This method is new in the .NET Framework version 2.0.

Starts an asynchronous download and installation of this application's latest version.

Namespace: System.Deployment.Application
Assembly: System.Deployment (in system.deployment.dll)

public void UpdateAsync ()
public void UpdateAsync ()
public function UpdateAsync ()

Exception typeCondition

TrustNotGrantedException

The local computer did not grant this application the permission level it requested to execute.

InvalidDeploymentException

Your ClickOnce deployment is corrupted. For tips on how to diagnose and correct the problem, see Troubleshooting ClickOnce Deployments.

DeploymentDownloadException

The new deployment could not be downloaded from its location on the network.

An application is considered updated when you publish a new version of the application to the location specified by UpdateLocation, and the version number in the application's deployment manifest is greater than the version number of the application currently installed on the user's computer.

While downloading the update, ClickOnce will raise the UpdateProgressChanged event handler on the main application thread to inform you of the status of the download. When the asynchronous update finishes or encounters an exception, ClickOnce will raise the UpdateCompleted event on the main application thread. Examine the AsyncCompletedEventArgs supplied to this event to determine whether the update succeeded or not.

If UpdateAsync throws an exception, ClickOnce will call UpdateCompleted and set the Error property of AsyncCompletedEventArgs to the exception that was thrown.

UpdateAsync will download all files in a deployment not marked as "optional" in the application manifest. You can download optional files on demand using the DownloadFileGroup or the DownloadFileGroupAsync method.

ClickOnce may already be updating the application automatically when you call this method; if that happens, calls to this method will throw an InvalidOperationException.

If you have updated one or more files in your deployment, but have not refreshed your application manifest, you will receive an InvalidDeploymentException. Most of the time, rebuilding your application manifest solves this. You will also receive this exception if a public-key signature on a deployment manifest or application manifest is invalid or missing.

An update may request a higher level of trust on the local computer than the previous version. If the application uses Trusted Application Deployment, the common language runtime trust manager will examine the deployment manifest to determine whether it contains a valid trust license. If the deployment manifest does not contain a valid trust license, ClickOnce will stop the installation and throw a TrustNotGrantedException. UpdateAsync will never cause a prompt to display asking the user if they want to grant permission for the application to run.

The following code example determines at application load time whether a new update is available; if it is a required update, it installs it asynchronously. The example requires that you are deploying a Windows Forms application, and that this application contains a StatusStrip control, and it contains a ToolStripStatusPanel control name downloadStatus.

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);
}

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();
    }
}

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft