Miles Framework

Le Framework Miles est une librairie open-source qui permet de créer des extensions telles que des pages personnalisées pour les installations DreamShield. Au fil du temps il sera enrichit de différentes manières afin de proposer un moyen simple de personnaliser n'importe quel aspect des installations.

1.  Téléchargement et utilisation

Le Framework Miles est disponible dans un téléchargement séparé pour DreamShield.

Les premières étapes lors de la création d'un plugin basé sur Miles pour étendre une installation seront, après avoir crée un projet d'installation, de procéder comme suit :

  • Créer une nouvelle bibliothèque de classes avec un langage supporté par le framework .NET (C#,VB.Net,Delphi.Net,etc.)
  • Rajouter les références suivantes au projet
    • DreamShield.Deployment.Miles.dll (présent dans l'archive .zip de Miles)

Cette référence doit être copiée dans le dossier de sortie de votre assembly

  • DreamShield.Data.dll
  • DreamShield.Deployment.dll
  • DreamShield.Extentions.dll
  • DreamShield.IO.Utils.dll
  • DreamShield.Luna.dll
  • DreamShield.Windows.Themes.dll

Ces références sont présentes dans le dossier d'installation de DreamShield mais ne doivent pas être copiées dans le dossier de sortie de votre assembly. (Elles constitue le runtime DreamShield qui sera automatiquement chargé par l'installeur).


Incorporation du plugin à l'installation

Après avoir créé vos éléments (ces tâches seront décrites dans les points suivants), vous pourrez alors compiler votre assembly. Ensuite, dans votre projet d'installation, vous devrez rajouter votre plugin. Pour se faire allez dans l'exploration de projet, rubrique "Assemblies d'installation et plugins". Sous extentions faites un click droit puis "Nouvelle extention d'installation" et donnez lui un nom.
Ensuite, comme Assembly principale naviguez vers votre assembly fraichement crée et dans la liste juste en dessous, faites un clique droit puis "Ajouter une assembly managée" et là rajoutez l'assembly DreamShield.Deployment.Miles.dll. Et votre installation sera alors prête. Il ne reste plus qu'à créer les plugins ...

2.  Création du plugin

Maintenant que vous avez une bibliothèque de classes prête à personnaliser l'installation, il faut créer le plugin qui va s'intégrer à DreamShield (via Miles).
Pour cela, créez une nouvelle classe MyPlugin que vous compléterez ainsi :

using System;
using DreamShield.Extentions;
using DreamShield.Deployment.Installers.DreamPlugins;
using DreamShield.Deployment.Miles;
using System.IO;
using System.Xml;

namespace MilesCustomPage
{
        /// <summary>
        /// Description of UserPlugin.
        /// </summary>
        [Extention(BaseDreamPluginContainer.DreamPluginExtentionGuid,
        "{77B51474-B088-4d40-ACD3-9B2F6450C466}")
        /* Le guid précédent doit être unique. Plusieurs outils existent pour créer des GUIDs uniques ...
        *  Il servira à l'installeur afin d'identifier de manière unique votre plugin */

        ]
        public class MyPlugin : MilesRoot /* MilesRoot : classe qui permet de connecter les plugins Miles à l'installation */
        {
                protected override void OnServerInitialized()
                {
                        base.OnServerInitialized();

                        /* Ici, il faudra rajouter les différents plugins que l'on veut connecter à DreamShield */
                }
        }
}

Le code devra ensuite être complété en fonction de vos besoins. Les différents modules disponibles sont décrits dans les sections suivantes.

3.  Pages personnalisées

Un point important de Miles est la création de pages personnalisées pour DreamShield. Il existe des pages préconçues pour remplir certaines fonctions, bien qu'il soit possible de créer n'importe quel type de page.

3.1  Page personnalisée

Création d'une page entièrement personnalisée.
La création d'une page entièrement personnalisée avec Miles est aussi simple que de créer un nouveau contrôle utilisateur (UserControl) à l'aide du Framework .NET.
Pour créer une page personnalisée, vous devez donc créer un nouveau contrôle personnalisé (dans notre exemple il sera nommé UserControl1) dans votre assembly d'extension. (Par défaut les pages de l'assistant d'installation DreamShield ont une taille de 488x283 et un fond transparent pour s'intégrer au skin. Il est donc préférable de respecter ces paramètres).
Dans votre contrôle personnalisé, rajoutez un using vers le namespace DreamShield.Deployment.Miles.CustomPage puis rajoutez un champ comme suit :

public CustomPagePlugin PagePlugin = null;

Ce champ permettra de communiquer avec les autres plugins si nécessaire. Par exemple, pour définir une variable globale qui sera utilisée par tous les autres plugins (et échanger simplement des informations entre plusieurs plugins personnalisés), vous procéderez comme suit :

PagePlugin.GlobalInstallerVariables["myvalue"] = textBox1.Text;
...
string myvalue = PagePlugin.GlobalInstallerVariables["myvalue"] as string;

Ensuite, dans la classe MyPlugin rajoutez une fonction RegisterCustomPage comme suit :

public virtual void RegisterCustomPage()
                {
                        /* création de la page personnalisée */
                        UserControl1 customPage = new UserControl1();
                        /* création du plugin de page personnalisée */
                        CustomPagePlugin plugin = new CustomPagePlugin(
                                /* premier argument invariant */
                                Server,
                                /* position où rajouter la page. Les valeurs de l'énumération WizardPagesId contiennent
                                * toutes les pages par défaut. Ici, la page personnalisée est rajoutée à la position de la page de
                                * de sélection du mode d'installation (Installation personnalisée ou standard) */

                                WizardPagesID.InstallationModePage,
                                /* false : indique que la page doit être rajoutée avant la position définie précédemment
                                * true : la page aurait été rajoutée après la position */

                                false,
                                /* id de la page, peut être laissé vide */
                                "",
                                /* page personnalisée */
                                customPage);
                        /* Il est possible de définir quelles actions seront possibles à partir de la page personnalisée, ie.
                        * Précédent - Suivant - Annuler. Ici, on désactive la possibilité d'annuler sur cette page.
                        * les propriétés et méthodes de plugin offrent tout un panel de personnalisations et d'évènements
                        * accessibles pour une page de l'assistant */

                        plugin.CanCancel = false;
                        /* définition du plugin, ainsi il sera accessible via la page personnalisée */
                        customPage.PagePlugin = plugin;
                        /* enregistrement du plugin */
                        Server.RegisterPlugin(customPage.PagePlugin);
                }

Le code complet de MyPlugin sera alors le suivant :

using System;
using DreamShield.Extentions;
using DreamShield.Deployment.Installers.DreamPlugins;
using DreamShield.Deployment.Miles;
using DreamShield.Deployment.Miles.CustomPage;
using DreamShield.Deployment.Miles.IO;
using System.IO;
using System.Xml;
using DreamShield.Deployment.Miles.CustomPage.StandardPages;

namespace MilesCustomPage
{
        [Extention(BaseDreamPluginContainer.DreamPluginExtentionGuid, "{77B51474-B088-4d40-ACD3-9B2F6450C466}")]
        public class MyPlugin : MilesRoot
        {
                protected override void OnServerInitialized()
                {
                        base.OnServerInitialized();

                        RegisterCustomPage();
                }

                public virtual void RegisterCustomPage()
                {
                        UserControl1 customPage = new UserControl1();
                        CustomPagePlugin plugin = new CustomPagePlugin(
                                Server,
                                WizardPagesID.InstallationModePage,
                                false,
                                "",
                                customPage);
                        plugin.CanCancel = false;
                        customPage.PagePlugin = plugin;
                        Server.RegisterPlugin(customPage.PagePlugin);
                }
        }
}

note: Vous pouvez bien sur rajouter plusieurs plugins en rajoutant les autres à la suite de la fonction OnServerInitialized.

3.2  Vérification d'une clef de produit

Création d'une page personnalisées qui demande à l'utilisateur pendant l'installation de rentrer une clef de produit.

check_serial.jpg: 545x403, 17k

Première étape : Créer une classe qui va remplir la fonction de "vérificateur de licence". Cette classe aura pour fonction de valider la clef rentrée par l'utilisateur, autorisant ou non l'installation à se poursuivre.

using System;
using DreamShield.Deployment.Miles.CustomPage.StandardPages;

namespace MilesCustomPage
{
        public class SerialVerificationClass : PageVerifySerialNumber.IPageVerifySerialNumber_Validator
        {
                public SerialVerificationClass()
                {
                }

                public bool CanContinueWithSerial(string serial)
                {
                        return serial == "serial";
                        /* le serial dans cet exemple est "serial".
                        * c'est ici qu'il faut donc vérifier la clef rentrée par l'utilisateur et renvoyer true
                        * si la clef est valide, false sinon
                        */

                }

                public void SerialAccepted(string serial)
                {
                        /* l'installeur appelle cette fonction lorsque la clef rentrée par l'utilisateur a été validée
                        * et que la page suivante est affichée */

                }
        }
}

Bien sur, la vérification de la clef est ici très basique, mais il vous est possible d'implémenter votre propre algorithme dans la fonction CanContinueWithSerial.
Attention : comme toute méthode de protection, celle ci n'est pas infaillible mais peut rebuter les utilisateurs de bases qui souhaiteraient utiliser le programme sans clef.

Deuxième étape : enregistrer la page dans votre plugin Miles. Pour cela, retournez dans la classe MyPlugin et rajoutez la ligne suivante à la fin de la fonction OnServerInitialized :

RegisterSerialPage();

Et ensuite, rajoutez à la classe MyPlugin la fonction suivante :

public virtual void RegisterSerialPage()
                {
                        PageVerifySerialNumber pg = new PageVerifySerialNumber(Server, new SerialVerificationClass());
                        Server.RegisterPlugin(pg.Plugin);
                }

La classe MyPlugin aura donc le code suivant :

using System;
using DreamShield.Extentions;
using DreamShield.Deployment.Installers.DreamPlugins;
using DreamShield.Deployment.Miles;
using DreamShield.Deployment.Miles.CustomPage;
using DreamShield.Deployment.Miles.IO;
using System.IO;
using System.Xml;
using DreamShield.Deployment.Miles.CustomPage.StandardPages;

namespace MilesCustomPage
{
        [Extention(BaseDreamPluginContainer.DreamPluginExtentionGuid, "{77B51474-B088-4d40-ACD3-9B2F6450C466}")]
        public class MyPlugin : MilesRoot
        {
                protected override void OnServerInitialized()
                {
                        base.OnServerInitialized();

                        RegisterSerialPage();
                }

                public virtual void RegisterSerialPage()
                {
                        PageVerifySerialNumber pg = new PageVerifySerialNumber(Server, new SerialVerificationClass());
                        Server.RegisterPlugin(pg.Plugin);
                }
        }
}

note: Vous pouvez bien sur rajouter plusieurs plugins en rajoutant les autres à la suite de la fonction OnServerInitialized.

3.3  Image au démarrage de l'installation

Il est possible d'afficher une image comme première page de l'installation, avant la page par défaut d'acceuil.

splash_begin.jpg: 545x403, 28k

Pour cela il vous suffit d'aller dans la classe MyPlugin et d'y rajouter la fonction suivante :

public virtual void RegisterSplash()
                {                                              
                        /* il faut charger votre image à partir des ressources de votre assembly, ou via n'importe quel autre moyen compatible */
                        System.Drawing.Bitmap image = new System.Drawing.Bitmap(GetType().Assembly.GetManifestResourceStream("MilesCustomPage.3ds_max_concept_car.jpg"));
                        PageSetupSplash sp = new PageSetupSplash(Server,image);
                        Server.RegisterPlugin(sp.Plugin);
                }

Il vous suffit ensuite d'enregistrer votre plugin dans MyPlugin. Le code complet sera le suivant :

using System;
using DreamShield.Extentions;
using DreamShield.Deployment.Installers.DreamPlugins;
using DreamShield.Deployment.Miles;
using DreamShield.Deployment.Miles.CustomPage;
using DreamShield.Deployment.Miles.IO;
using System.IO;
using System.Xml;
using DreamShield.Deployment.Miles.CustomPage.StandardPages;

namespace MilesCustomPage
{
        /// <summary>
        /// Description of UserPlugin.
        /// </summary>
        [Extention(BaseDreamPluginContainer.DreamPluginExtentionGuid, "{77B51474-B088-4d40-ACD3-9B2F6450C466}")]
        public class MyPlugin : MilesRoot
        {
                protected override void OnServerInitialized()
                {
                        base.OnServerInitialized();

                        RegisterSplash();
                }

                public virtual void RegisterSplash()
                {                                              
                        System.Drawing.Bitmap image = new System.Drawing.Bitmap(GetType().Assembly.GetManifestResourceStream("MilesCustomPage.3ds_max_concept_car.jpg"));
                        PageSetupSplash sp = new PageSetupSplash(Server,image);
                        Server.RegisterPlugin(sp.Plugin);
                }
        }
}

note: Vous pouvez bien sur rajouter plusieurs plugins en rajoutant les autres à la suite de la fonction OnServerInitialized.


Catégorie : Tutoriaux, Miles