ApplicationDeployment.DownloadFileGroup(String) Method

  • Reference

Definition

Namespace:
System.Deployment.Application
Assembly:
System.Deployment.dll

Downloads a set of optional files on demand.

public:
 void DownloadFileGroup(System::String ^ groupName);
public void DownloadFileGroup (string groupName);
member this.DownloadFileGroup : string -> unit
Public Sub DownloadFileGroup (groupName As String)

Parameters

groupName
String

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

Exceptions

ArgumentNullException

The groupName parameter is null or zero-length.

Examples

The following code example demonstrates how to load an assembly on demand by listening for the AssemblyResolve event.

namespace ClickOnceOnDemand
{
    public class Form1 : Form
    {
        // Maintain a dictionary mapping DLL names to download file groups. This is trivial for this sample,
        // but will be important in real-world applications where a feature is spread across multiple DLLs,
        // and you want to download all DLLs for that feature in one shot. 
        Dictionary<String, String> DllMapping = new Dictionary<String, String>();

        public static void Main()
        {
            Form1 NewForm = new Form1();
            Application.Run(NewForm);
        }

        public Form1()
        {
            // Configure form. 
            this.Size = new Size(500, 200);
            Button getAssemblyButton = new Button();
            getAssemblyButton.Size = new Size(130, getAssemblyButton.Size.Height);
            getAssemblyButton.Text = "Test Assembly";
            getAssemblyButton.Location = new Point(50, 50);
            this.Controls.Add(getAssemblyButton);
            getAssemblyButton.Click += new EventHandler(getAssemblyButton_Click);

            DllMapping["ClickOnceLibrary"] = "ClickOnceLibrary";
            AppDomain.CurrentDomain.AssemblyResolve += new ResolveEventHandler(CurrentDomain_AssemblyResolve);
        }

        /*
         * Use ClickOnce APIs to download the assembly on demand.
         */
        private Assembly CurrentDomain_AssemblyResolve(object sender, ResolveEventArgs args)
        {
            Assembly newAssembly = null;

            if (ApplicationDeployment.IsNetworkDeployed)
            {
                ApplicationDeployment deploy = ApplicationDeployment.CurrentDeployment;

                // Get the DLL name from the Name argument.
                string[] nameParts = args.Name.Split(',');
                string dllName = nameParts[0];
                string downloadGroupName = DllMapping[dllName];

                try
                {
                    deploy.DownloadFileGroup(downloadGroupName);
                }
                catch (DeploymentException de)
                {
                    MessageBox.Show("Downloading file group failed. Group name: " + downloadGroupName + "; DLL name: " + args.Name);
                    throw (de);
                }

                // Load the assembly.
                // Assembly.Load() doesn't work here, as the previous failure to load the assembly
                // is cached by the CLR. LoadFrom() is not recommended. Use LoadFile() instead.
                try
                {
                    newAssembly = Assembly.LoadFile(Application.StartupPath + @"\" + dllName + ".dll," +
            "Version=1.0.0.0, Culture=en, PublicKeyToken=03689116d3a4ae33");
                }
                catch (Exception e)
                {
                    throw (e);
                }
            }
            else
            {
                //Major error - not running under ClickOnce, but missing assembly. Don't know how to recover.
                throw (new Exception("Cannot load assemblies dynamically - application is not deployed using ClickOnce."));
            }

            return (newAssembly);
        }

        private void getAssemblyButton_Click(object sender, EventArgs e)
        {
            DynamicClass dc = new DynamicClass();
            MessageBox.Show("Message: " + dc.Message);
        }
    }
}

Remarks

In a ClickOnce application, the files marked "optional" in the application manifest are not downloaded during initialization or update. You can use the DownloadFileGroup 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. 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 use an assembly you have downloaded with DownloadFileGroup, you attach an event listener to the AssemblyResolve event on the CurrentDomain. For an example, see =Walkthrough: Downloading Assemblies on Demand with the ClickOnce Deployment API Using the Designer.

All files are downloaded to the ClickOnce application cache and are therefore isolated to the current version of the application. Let's say that after an application downloads a file group, the user installs a new version of the application, but later 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. For more information about accessing data files, see Accessing Local and Remote Data in ClickOnce Applications.

DownloadFileGroup works in partially trusted applications, that is, in any ClickOnce application running with restricted permission. However, if you attempt to load assemblies dynamically, your application will require full trust.

On-demand downloading of data files is currently not supported.

Your application will not be responsive to user input until the DownloadFileGroup method returns. If you need to download files without interrupting the user's workflow, use the DownloadFileGroupAsync method instead.

You cannot download a single file by its file name alone. To download a single file, assign it a group name in your ClickOnce deployment and download the group using this method.

Applies to

See also