Procédure pas à pas : téléchargement d’assemblys à la demande avec l’API du déploiement ClickOnce à l’aide du concepteur

Par défaut, tous les assemblys inclus dans une application ClickOnce sont téléchargés lors de la première exécution de l’application. Toutefois, il peut y avoir certaines parties de votre application qui sont utilisées par un petit ensemble d’utilisateurs. Dans ce cas, vous souhaiterez sans doute télécharger un assembly uniquement quand vous créez l’un de ses 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.

Notes

La classe ApplicationDeployment et les API de l’espace de noms System.Deployment.Application ne sont pas prises en charge dans .NET Core, .NET 5 et les versions ultérieures. Dans .NET 7, une nouvelle méthode d’accès aux propriétés de déploiement d’application est prise en charge. Pour plus d’informations, consultez Accéder aux propriétés de déploiement ClickOnce dans .NET. .NET 7 ne prend pas en charge l’équivalent des méthodes ApplicationDeployment.

Remarque

Votre application doit s’exécuter avec une confiance totale pour utiliser cette procédure.

Notes

Les boîtes de dialogue et les commandes de menu affichées peuvent différer de celles décrites dans l'Aide selon les paramètres actifs ou le mode d'édition. Pour modifier ces paramètres, cliquez sur Importation et exportation de paramètres dans le menu Outils . Pour plus d’informations, consultez Réinitialiser les paramètres.

Créer les projets

Pour créer un projet qui utilise un assembly à la demande avec Visual Studio

1. Créez un nouveau projet Windows Forms dans Visual Studio. Dans le menu Fichier , pointez sur Ajouter, puis cliquez sur Nouveau projet. Choisissez un projet de Bibliothèque de classes dans la boîte de dialogue et nommez-le ClickOnceLibrary.

   Notes

   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. Pour des raisons de simplicité, les deux projets de cette procédure pas à pas sont dans le même espace de noms.

2. Définissez une classe nommée DynamicClass avec une propriété unique nommée Message.

   C#

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

   VB

   Public Class DynamicClass
       Sub New()
   
       End Sub
   
       Public ReadOnly Property Message() As String
           Get
               Message = "Hello, world!"
           End Get
       End Property
   End Class
   

3. Sélectionnez le projet Windows Forms dans l’ Explorateur de solutions. Ajoutez une référence à l’assembly System.Deployment.Application et une référence de projet au projet ClickOnceLibrary .

   Notes

   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. Pour des raisons de simplicité, les deux projets de cette procédure pas à pas figurent dans le même espace de noms.

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.

   C#

   using System.Reflection;
   using System.Deployment.Application;
   using Microsoft.Samples.ClickOnceOnDemand;
   using System.Security.Permissions;
   

   VB

   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. Ce code montre comment mapper un jeu d’assemblys à un nom de groupe à l’aide d’une classe Dictionary générique. 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. 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. 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.

   C#

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

   VB

   ' 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. Faites glisser un Button de la Boîte à outils vers le formulaire. Double-cliquez sur le bouton et ajoutez le code suivant au gestionnaire d’événements Click .

   C#

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

   VB

   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
   

Marquer les assemblys comme facultatifs

Pour marquer des assemblys comme facultatifs dans votre application ClickOnce à l’aide de Visual Studio

1. Cliquez avec le bouton droit sur le projet Windows Forms dans l’ Explorateur de solutions , puis cliquez sur Propriétés. Sélectionnez l’onglet Publier .

2. Cliquez sur le bouton Fichiers d’application .

3. Recherchez ClickOnceLibrary.dll dans la liste. Affectez la valeur Inclure à la zone de liste déroulante État de la publication.

4. Développez la zone de liste déroulante Groupe et sélectionnez Nouveau. Entrez ClickOnceLibrary comme nom du nouveau groupe.

5. Continuez à publier votre application comme décrit dans le Guide pratique pour publier une application ClickOnce à l’aide de l’Assistant Publication.

Pour marquer des assemblys comme facultatifs dans votre application ClickOnce à l’aide de l’Outil Manifest Generation and Editing — Client graphique (MageUI.exe)

1. Créez vos manifestes ClickOnce comme décrit dans la Procédure pas à pas pour déployer manuellement une application ClickOnce.

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 .

3. Recherchez ClickOnceLibrary.dll dans la liste des fichiers d’application et affectez la valeur Aucun à sa colonne Type de fichier. Pour la colonne Groupe , tapez ClickOnceLibrary.dll.

Test du nouvel assembly

Pour tester votre assembly à la demande :

1. Démarrez votre application déployée avec ClickOnce.

2. Quand votre formulaire principal apparaît, appuyez sur Button. Une chaîne « Hello, World ! » doit apparaître dans une fenêtre de message.

Contenu connexe

• ApplicationDeployment