Procédure pas à pas : téléchargement d'assemblys à la demande avec l'API du déploiement ClickOnce à l'aide du concepteurWalkthrough: Downloading Assemblies on Demand with the ClickOnce Deployment API Using the Designer

Par défaut, tous les assemblys inclus dans une application ClickOnceClickOnce sont téléchargés lors de la première exécution de l’application.By default, all the assemblies included in a ClickOnceClickOnce application are downloaded when the application is first run. Toutefois, il peut y avoir certaines parties de votre application qui sont utilisées par un petit ensemble d’utilisateurs.However, there might be parts of your application that are used by a small set of the users. Dans ce cas, vous souhaiterez sans doute télécharger un assembly uniquement quand vous créez l’un de ses types.In this case, you want to download an assembly only when you create one of its types. La procédure suivante montre comment marquer certains assemblys de votre application comme « facultatifs » et comment les télécharger à l’aide de classes dans l’espace de noms System.Deployment.Application quand le Common Language Runtime en a besoin.The following walkthrough demonstrates how to mark certain assemblies in your application as "optional", and how to download them by using classes in the System.Deployment.Application namespace when the common language runtime demands them.

Note

Votre application doit s’exécuter avec une confiance totale pour utiliser cette procédure.Your application will have to run in full trust to use this procedure.

Note

Les boîtes de dialogue et les commandes de menu qui s'affichent peuvent être différentes de celles qui sont décrites dans l'aide, en fonction de vos paramètres actifs ou de l'édition utilisée.The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. Pour modifier ces paramètres, cliquez sur Importation et exportation de paramètres dans le menu Outils .To change your settings, click Import and Export Settings on the Tools menu. Pour plus d’informations, consultez Personnaliser l’IDE Visual Studio.For more information, see Personalize the Visual Studio IDE.

Création des projetsCreating the Projects

Pour créer un projet qui utilise un assembly à la demande avec Visual StudioTo create a project that uses an on-demand assembly with Visual Studio

  1. Créez un projet Windows Forms dans Visual StudioVisual Studio.Create a new Windows Forms project in Visual StudioVisual Studio. Dans le menu Fichier , pointez sur Ajouter, puis cliquez sur Nouveau projet.On the File menu, point to Add, and then click New Project. Choisissez un projet de Bibliothèque de classes dans la boîte de dialogue et nommez-le ClickOnceLibrary.Choose a Class Library project in the dialog box and name it ClickOnceLibrary.

    Note

    Dans Visual Basic, nous vous recommandons de modifier les propriétés du projet pour affecter Microsoft.Samples.ClickOnceOnDemand ou un espace de noms de votre choix comme espace de noms racine pour ce projet.In Visual Basic, we recommend that you modify the project properties to change the root namespace for this project to Microsoft.Samples.ClickOnceOnDemand or to a namespace of your choice. Pour des raisons de simplicité, les deux projets de cette procédure pas à pas sont dans le même espace de noms.For simplicity, the two projects in this walkthrough are in the same namespace.

  2. Définissez une classe nommée DynamicClass avec une propriété unique nommée Message.Define a class named DynamicClass with a single property named Message.

    Public Class DynamicClass
        Sub New()
    
        End Sub
    
        Public ReadOnly Property Message() As String
            Get
                Message = "Hello, world!"
            End Get
        End Property
    End Class
    
    using System;
    using System.Collections.Generic;
    using System.Text;
    
    namespace Microsoft.Samples.ClickOnceOnDemand
    {
        public class DynamicClass
        {
            public DynamicClass() {}
    
            public string Message
            {
                get
                {
                    return ("Hello, world!");
                }
            }
        }
    }
    
  3. Sélectionnez le projet Windows Forms dans l’ Explorateur de solutions.Select the Windows Forms project in Solution Explorer. Ajoutez une référence à l’assembly System.Deployment.Application et une référence de projet au projet ClickOnceLibrary .Add a reference to the System.Deployment.Application assembly and a project reference to the ClickOnceLibrary project.

    Note

    Dans Visual Basic, nous vous recommandons de modifier les propriétés du projet pour affecter Microsoft.Samples.ClickOnceOnDemand ou un espace de noms de votre choix comme espace de noms racine pour ce projet.In Visual Basic, we recommend that you modify the project properties to change the root namespace for this project to Microsoft.Samples.ClickOnceOnDemand or to a namespace of your choice. Pour des raisons de simplicité, les deux projets de cette procédure pas à pas figurent dans le même espace de noms.For simplicity, the two projects in this walkthrough are located in the same namespace.

  4. Cliquez avec le bouton droit sur le formulaire, cliquez sur Afficher le code dans le menu, puis ajoutez les références suivantes au formulaire.Right-click the form, click View Code from the menu, and add the following references to the form.

    using System.Reflection;
    using System.Deployment.Application;
    using Microsoft.Samples.ClickOnceOnDemand;
    using System.Security.Permissions;
    
    Imports System.Reflection
    Imports System.Deployment.Application
    Imports System.Collections.Generic
    Imports Microsoft.Samples.ClickOnceOnDemand
    Imports System.Security.Permissions
    
  5. Ajoutez le code suivant pour télécharger cet assembly à la demande.Add the following code to download this assembly on demand. Ce code montre comment mapper un jeu d’assemblys à un nom de groupe à l’aide d’une classe Dictionary générique.This code shows how to map a set of assemblies to a group name using a generic Dictionary class. Comme nous ne téléchargeons qu’un seul assembly dans cette procédure pas à pas, il n’y a qu’un seul assembly dans notre groupe.Because we are only downloading a single assembly in this walkthrough, there is only one assembly in our group. Dans une application réelle, il faudrait probablement télécharger simultanément tous les assemblys liés à une même fonctionnalité dans votre application.In a real application, you would likely want to download all assemblies related to a single feature in your application at the same time. La table de mappage vous permet de le faire facilement en associant toutes les DLL qui appartiennent à une fonctionnalité à un nom de groupe de téléchargement.The mapping table enables you to do this easily by associating all the DLLs that belong to a feature with a download group name.

    // 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>();
    
    [SecurityPermission(SecurityAction.Demand, ControlAppDomain=true)]
    public Form1()
    {
        InitializeComponent();
    
        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");
            }
            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);
    }
    
    ' 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. 
    Dim DllMappingTable As New Dictionary(Of String, String)()
    
    <SecurityPermission(SecurityAction.Demand, ControlAppDomain:=True)> _
    Sub New()
        ' This call is required by the Windows Form Designer.
        InitializeComponent()
    
        ' Add any initialization after the InitializeComponent() call.
        DllMappingTable("ClickOnceLibrary") = "ClickOnceLibrary"
    End Sub
    
    Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        AddHandler AppDomain.CurrentDomain.AssemblyResolve, AddressOf Me.CurrentDomain_AssemblyResolve
    End Sub
    
    Private Function CurrentDomain_AssemblyResolve(ByVal sender As Object, ByVal args As ResolveEventArgs) As System.Reflection.Assembly
        Dim NewAssembly As Assembly = Nothing
    
        If (ApplicationDeployment.IsNetworkDeployed) Then
            Dim Deploy As ApplicationDeployment = ApplicationDeployment.CurrentDeployment
    
            ' Get the DLL name from the argument.
            Dim NameParts As String() = args.Name.Split(",")
            Dim DllName As String = NameParts(0)
            Dim DownloadGroupName As String = DllMappingTable(DllName)
    
            Try
                Deploy.DownloadFileGroup(DownloadGroupName)
            Catch ex As Exception
                MessageBox.Show("Could not download file group from Web server. Contact administrator. Group name: " & DownloadGroupName & "; DLL name: " & args.Name)
                Throw (ex)
            End Try
    
            ' 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")
            Catch ex As Exception
                Throw (ex)
            End Try
        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.")
        End If
    
        Return NewAssembly
    End Function
    
  6. Dans le menu Affichage , cliquez sur Boîte à outils.On the View menu, click Toolbox. Faites glisser un Button de la Boîte à outils vers le formulaire.Drag a Button from the Toolbox onto the form. Double-cliquez sur le bouton et ajoutez le code suivant au gestionnaire d’événements Click .Double-click the button and add the following code to the Click event handler.

    private void getAssemblyButton_Click(object sender, EventArgs e)
    {
        DynamicClass dc = new DynamicClass();
        MessageBox.Show("Message: " + dc.Message);
    }
    
    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        Dim DC As New DynamicClass()
        MessageBox.Show("Message is " & DC.Message)
    End Sub
    

Marquage d’assemblys comme facultatifsMarking Assemblies as Optional

Pour marquer des assemblys comme facultatifs dans votre application ClickOnce à l’aide de Visual StudioTo mark assemblies as optional in your ClickOnce application by using Visual Studio

  1. Cliquez avec le bouton droit sur le projet Windows Forms dans l’ Explorateur de solutions , puis cliquez sur Propriétés.Right-click the Windows Forms project in Solution Explorer and click Properties. Sélectionnez l’onglet Publier .Select the Publish tab.

  2. Cliquez sur le bouton Fichiers d’application .Click the Application Files button.

  3. Recherchez ClickOnceLibrary.dll dans la liste.Find the listing for ClickOnceLibrary.dll. Affectez la valeur Inclure à la zone de liste déroulante État de la publication.Set the Publish Status drop-down box to Include.

  4. Développez la zone de liste déroulante Groupe et sélectionnez Nouveau.Expand the Group drop-down box and select New. Entrez ClickOnceLibrary comme nom du nouveau groupe.Enter the name ClickOnceLibrary as the new group name.

  5. Continuer la publication de votre application comme décrit dans Comment : publier une Application ClickOnce à l’aide de l’Assistant Publication.Continue publishing your application as described in How to: Publish a ClickOnce Application using the Publish Wizard.

Pour marquer des assemblys comme facultatifs dans votre application ClickOnce à l’aide de l’Outil Manifest Generation and Editing — Client graphique (MageUI.exe)To mark assemblies as optional in your ClickOnce application by using Manifest Generation and Editing Tool — Graphical Client (MageUI.exe)

  1. Créer votre ClickOnceClickOnce comme décrit dans les manifestes procédure pas à pas : déploiement manuel d’une Application ClickOnce.Create your ClickOnceClickOnce manifests as described in Walkthrough: Manually Deploying a ClickOnce Application.

  2. Avant de fermer MageUI.exe, sélectionnez l’onglet qui contient le manifeste d’application de votre déploiement et, sous cet onglet, sélectionnez l’onglet Fichiers .Before closing MageUI.exe, select the tab that contains your deployment's application manifest, and within that tab select the Files tab.

  3. Recherchez ClickOnceLibrary.dll dans la liste des fichiers d’application et affectez la valeur Aucun à sa colonne Type de fichier.Find ClickOnceLibrary.dll in the list of application files and set its File Type column to None. Pour la colonne Groupe , tapez ClickOnceLibrary.dll.For the Group column, type ClickOnceLibrary.dll.

Test du nouvel assemblyTesting the New Assembly

Pour tester votre assembly à la demandeTo test your on-demand assembly

  1. Démarrez votre application déployée avec ClickOnceClickOnce.Start your application deployed with ClickOnceClickOnce.

  2. Quand votre formulaire principal apparaît, appuyez sur Button.When your main form appears, press the Button. Une chaîne « Hello, World ! » doit apparaître dans une fenêtre de message.You should see a string in a message box window that reads, "Hello, World!"

Voir aussiSee Also

ApplicationDeployment