DownloadFileGroupAsync Method (String, Object)
Collapse the table of content
Expand the table of content
This documentation is archived and is not being maintained.

ApplicationDeployment.DownloadFileGroupAsync Method (String, Object)

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

Downloads, on-demand, a set of optional files in the background, and passes a piece of application state to the event callbacks.

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

public void DownloadFileGroupAsync (
	string groupName,
	Object userState
)
public void DownloadFileGroupAsync (
	String groupName, 
	Object userState
)
public function DownloadFileGroupAsync (
	groupName : String, 
	userState : Object
)

Parameters

groupName

The named group of files to download. All files marked "optional" in a ClickOnce application require a group name.

userState

An arbitrary object containing state information for the asynchronous operation.

Exception typeCondition

ArgumentNullException

groupName parameter is null or zero-length.

InvalidOperationException

You cannot initiate more than one download of groupName at a time.

In a ClickOnce application, all files marked "optional" in the application manifest are not downloaded during initialization or update. You can use the DownloadFileGroupAsync method to download all of the files belonging to a named group on demand, so that they do not consume network resources and disk space until you are sure the user requires them. This works not only for static files, but also for assemblies that an application may or may not require. For example, certain users may need to use a data analysis package included in your application on a daily basis, while other users may never invoke it. To download assemblies on demand, attach an event listener to the AssemblyResolve event on the CurrentDomain.

You can download multiple file groups simultaneously using DownloadFileGroupAsync. You can distinguish among them by using the Group property of the DeploymentProgressChangedEventArgs class, which is passed to the DownloadFileGroupProgressChanged event. If you need to pass more complex state, you can use

DownloadFileGroupAsync to pass in a state object that is passed to the DownloadFileGroupCompleted event through the UserState property.

All static files are downloaded to the ClickOnce application's data directory. For more information about accessing static files, see Accessing Local and Remote Data in ClickOnce Applications. Because of this, the files are isolated to the current version of the application. Say that an application downloads a file group, and then the user installs a new version. Later, the user reverts to the previous version of the application. In this case, the previous version will still have the copies of the files it originally downloaded.

To cancel an asynchronous download, call the DownloadFileGroupAsyncCancel method.

The following code example downloads a group of help files in the background. 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 named downloadStatus.

private void DownloadFileGroupAsync(string fileGroup)
{
    if (ApplicationDeployment.IsNetworkDeployed)
    {
        ApplicationDeployment deployment = ApplicationDeployment.CurrentDeployment;

        try
        {
            if (deployment.IsFileGroupDownloaded(fileGroup))
            {
                deployment.DownloadFileGroupProgressChanged += new DeploymentProgressChangedEventHandler(deployment_DownloadFileGroupProgressChanged);
                deployment.DownloadFileGroupCompleted += new DownloadFileGroupCompletedEventHandler(deployment_DownloadFileGroupCompleted);

                deployment.DownloadFileGroupAsync(fileGroup);
            }
        }
        catch (InvalidOperationException ioe)
        {
            MessageBox.Show("This application is not a ClickOnce application. Error: " + ioe.Message);
            return;
        }
    }
}

void deployment_DownloadFileGroupProgressChanged(object sender, DeploymentProgressChangedEventArgs e)
{
    downloadStatus.Text = String.Format("Downloading file group {0}; {1:D}K of {2:D}K completed.", e.Group, e.BytesCompleted / 1024, e.BytesTotal / 1024);               
}

void deployment_DownloadFileGroupCompleted(object sender, DownloadFileGroupCompletedEventArgs e)
{
    if (e.Error != null)
    {
        downloadStatus.Text = "Could not download files. Will try again later.";
        return;
    }
    else if (e.Cancelled)
    {
        downloadStatus.Text = "The file download has been cancelled.";
        return;
    }

    downloadStatus.Text = String.Format("Download of file group {0} complete.", e.Group);
}

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
Show:
© 2016 Microsoft