Utilisation de My.Settings avec Visual Basic 2005

Publié le jeudi 6 octobre 2005, dernière modification le lundi 28 janvier 2008

1. Remarques générales

Nous allons découvrir pas mal de nouvelles choses concernant les paramètres d'application.

Comme dans les précédentes versions du Framework .Net, la gestion des paramètres est réalisée par le fichier app.config (nom dans Visual Studio) ou monexe.exe.config une fois le projet compilé. La manière de procéder pour les paramètres d'application des versions antérieures reste toujours valable, mais vous verrez qu'elle possède de nombreux défauts comparée à cette version.

Cette façon de faire fonctionne toujours ...	Copier le code
1 <appSettings> 2 <add key="monanciensetting" value="Setting old school"/> 3 </appSettings>

Autre grande nouveauté. Si vous vous souvenez de l'ancienne manière de procéder, pour pouvoir définir un paramètre d'une assembly autre que l'éxécutable, il fallait ajouter ces paramètres dans le fichier de configuration de l'éxécutable. Pas très souple comme méthode non ? Cette nouvelle gestion vous permet de définir des paramètres pour une assembly satellite de votre application sans vous casser la tête à savoir si votre fichier de configuration sera à jour.

2. Les scopes

Le Framework .Net v2 introduit une nouveauté très intéressante : la portée des paramètres de l'application. Ainsi, vous pouvez définir des paramètres communs à tous les utilisateurs, ou des paramètres qui varieront en fonction de l'utilisateur. Nous verons plus tard comment les utiliser simplement.

• User : permet de définir un paramètre en fonction de l'utilisateur.
• Application : ce paramètre sera commun à tous les utilisateurs.

Les différents 'scope' pour un paramètre d'application

1-1. Scope Application

Comme dit précédemment, le scope Application permet de définir un paramètre commun à tous les utilisateurs. Ce paramètre peut être, par exemple, l'URL d'un serveur pour les mises-à-jour de l'application. Ce principe de fonctionnement ressemble par son comportement aux précédentes versions.

Configurer l'application pour que tous les utilisateurs aient les mêmes couleurs pour la console.	Copier le code
1 <applicationSettings> 2 <Settings.My.MySettings> 3 <setting name="ApplicationBGColor" serializeAs="String"> 4 <value>DarkBlue</value> 5 </setting> 6 <setting name="ApplicationForeColor" serializeAs="String"> 7 <value>Yellow</value> 8 </setting> 9 </Settings.My.MySettings> 10 </applicationSettings>

Si vous modifiez le contenu de votre fichier de configuration, tous les comptes utilisateur de la machine seront affectés. Voyons maintenant comment personnaliser notre application en fonction de chaque utilisateur.

Warning

Un paramètre ayant un scope application est en lecture seule pendant l'éxécution de l'application. Comme nous allons le voir plus tard, il est possible de modifier les paramètres durant l'éxecution, mais toute modification du fichier de configuration touchant un des ces paramètres est sans effet. Seul les paramètres de scope User sont modifiables à l'éxécution.

2-2. Scope User

Ce type de Scope est LA nouveauté de la gestion des paramètres d'application.

Laisser à l'utilisateur le choix d'afficher ou non le curseur dans la console	Copier le code
1 <userSettings> 2 <Settings.My.MySettings> 3 <setting name="UserCursorVisible" serializeAs="String"> 4 <value>True</value> 5 </setting> 6 </Settings.My.MySettings> 7 </userSettings>

3. Comment le Framework .Net 2 gère-t'il les paramètres d'application ?

Le Framework .Net 2 gère les paramètres d'application de manière légèrement différente que les précédentes versions. Pour ce qui concerne les paramètres ayant le scope application, ce n'est pas le bouleversement total. Seule la structure du fichier XML de configuration (monexe.exe.config) est modifiée comme vous avez pu le constater en 1.1.

Pour la gestion des paramètres d'application avec un scope User, là il y a changement, beaucoup de changement.

Pour mieux comprendre comment le Framework .Net gère tout ca, le mieux est de jeter un coups d'oeil par ici : C:\Documents and Settings\<utilisateur>\Local Settings\Application Data

Arborescence de LocalSettings

Tout se passe dans ce dossier. Comme vous pouvez le constater, ce dossier est bien structuré. Application Data contient un dossier au nom de l'éditeur de l'assembly. Ce sous dossier contient un répertoire du nom de l'assembly, lui-même contient un sous dossier avec la version du produit. Enfin, ce dernier contient un fichier user.config.

Contenu du fichier user.config	Copier le code
1 <?xml version="1.0" encoding="utf-8"?> 2 <configuration> 3 <userSettings> 4 <WinSettings.My.MySettings> 5 <setting name="formFont" serializeAs="String"> 6 <value>Verdana, 12pt, style=Bold, Italic</value> 7 </setting> 8 </WinSettings.My.MySettings> 9 </userSettings> 10 </configuration>

Comme vous pouvez le constater, la structure de ce document est similaire à celle du fichier de configuration de l'application elle-même. D'ailleurs, si vous vous amusez à modifier la taille de la police par exemple, vous vous appercevrez, en lançant votre application, que cette modification est prise en compte, génial non ?

4. Utilisation des paramètres d'application avec My.Settings

Comme vous l'avez déjà surement constaté, le namespace My apparu avec Visual Studio 2005 simplifie pas mal de chose. Pour les paramètres d'application, je dirais même qu'il les rend plus que trop facile, à condition de posséder Visual Studio 2005.

Lorsque vous créez des paramètres d'application avec Visual Studio 2005, vous pouvez vous rendez compte que celui-ci modifie le fichier app.config du projet. Mais il exécute en arrière plan un autre travail qui est très important afin de pouvoir utiliser ces paramètres au travers du namespace My.

Si vous affichez les fichiers cachés de votre projet, et que vous développez l'arborescence de My Project, vous obtiendrez le schéma suivant (en fonction de votre projet bien sur).

Arborescence de My Project

Le fichier qui nous intéresse est celui surligné en bleu. Si l'on regarde son contenu, voici ce que l'on trouve :

Contenu du fichier Settings.Designer.vb

Copier le code

1 '------------------------------------------------------------------------------ 2 ' <auto-generated> 3 ' This code was generated by a tool. 4 ' Runtime Version:2.0.50727.42 5 ' 6 ' Changes to this file may cause incorrect behavior and will be lost if 7 ' the code is regenerated. 8 ' </auto-generated> 9 '------------------------------------------------------------------------------ 10 11 Option Strict On 12 Option Explicit On 13 14 15 Namespace My 16 17 <Global.System.Runtime.CompilerServices.CompilerGeneratedAttribute(), _ 18 Global.System.CodeDom.Compiler.GeneratedCodeAttribute( _ 19 "Microsoft.VisualStudio.Editors.SettingsDesigner.SettingsSingleFileGenerator", "8.0.0.0"), _ 20 Global.System.ComponentModel.EditorBrowsableAttribute( _ 21 Global.System.ComponentModel.EditorBrowsableState.Advanced)> _ 22 Partial Friend NotInheritable Class MySettings 23 Inherits Global.System.Configuration.ApplicationSettingsBase 24 25 Private Shared defaultInstance As MySettings = _ 26 CType(Global.System.Configuration.ApplicationSettingsBase.Synchronized(New MySettings), _ 27 MySettings) 28 29 #Region "My.Settings Auto-Save Functionality" 30 #If _MyType = "WindowsForms" Then 31 Private Shared addedHandler As Boolean 32 33 Private Shared addedHandlerLockObject As New Object 34 35 <Global.System.Diagnostics.DebuggerNonUserCodeAttribute(), _ 36 Global.System.ComponentModel.EditorBrowsableAttribute(_ 37 Global.System.ComponentModel.EditorBrowsableState.Advanced)> _ 38 Private Shared Sub AutoSaveSettings(ByVal sender As Global.System.Object, ByVal e As Global.System.EventArgs) 39 If My.Application.SaveMySettingsOnExit Then 40 My.Settings.Save() 41 End If 42 End Sub 43 #End If 44 #End Region 45 46 Public Shared ReadOnly Property [Default]() As MySettings 47 Get 48 49 #If _MyType = "WindowsForms" Then 50 If Not addedHandler Then 51 SyncLock addedHandlerLockObject 52 If Not addedHandler Then 53 AddHandler My.Application.Shutdown, AddressOf AutoSaveSettings 54 addedHandler = True 55 End If 56 End SyncLock 57 End If 58 #End If 59 Return defaultInstance 60 End Get 61 End Property 62 63 <Global.System.Configuration.UserScopedSettingAttribute(), _ 64 Global.System.Diagnostics.DebuggerNonUserCodeAttribute(), _ 65 Global.System.Configuration.DefaultSettingValueAttribute("Verdana, 12pt, style=Bold")> _ 66 Public Property formFont() As Global.System.Drawing.Font 67 Get 68 Return CType(Me("formFont"),Global.System.Drawing.Font) 69 End Get 70 Set 71 Me("formFont") = value 72 End Set 73 End Property 74 75 <Global.System.Configuration.ApplicationScopedSettingAttribute(), _ 76 Global.System.Diagnostics.DebuggerNonUserCodeAttribute(), _ 77 Global.System.Configuration.DefaultSettingValueAttribute("192, 255, 192")> _ 78 Public ReadOnly Property formBackColor() As Global.System.Drawing.Color 79 Get 80 Return CType(Me("formBackColor"),Global.System.Drawing.Color) 81 End Get 82 End Property 83 84 <Global.System.Configuration.ApplicationScopedSettingAttribute(), _ 85 Global.System.Diagnostics.DebuggerNonUserCodeAttribute(), _ 86 Global.System.Configuration.DefaultSettingValueAttribute("http://localhost/update.aspx")> _ 87 Public ReadOnly Property updateURL() As String 88 Get 89 Return CType(Me("updateURL"),String) 90 End Get 91 End Property 92 93 <Global.System.Configuration.UserScopedSettingAttribute(), _ 94 Global.System.Diagnostics.DebuggerNonUserCodeAttribute(), _ 95 Global.System.Configuration.DefaultSettingValueAttribute("Utilisateur connecté {0}")> _ 96 Public Property formTextFormating() As String 97 Get 98 Return CType(Me("formTextFormating"),String) 99 End Get 100 Set 101 Me("formTextFormating") = value 102 End Set 103 End Property 104 End Class 105 End Namespace 106 107 Namespace My 108 109 <Global.Microsoft.VisualBasic.HideModuleNameAttribute(), _ 110 Global.System.Diagnostics.DebuggerNonUserCodeAttribute(), _ 111 Global.System.Runtime.CompilerServices.CompilerGeneratedAttribute()> _ 112 Friend Module MySettingsProperty 113 114 <Global.System.ComponentModel.Design.HelpKeywordAttribute("My.Settings")> _ 115 Friend ReadOnly Property Settings() As Global.WinSettings.My.MySettings 116 Get 117 Return Global.WinSettings.My.MySettings.Default 118 End Get 119 End Property 120 End Module 121 End Namespace

Ce fichier contient une classe et un module.

4-1. Etudions MySettings

Tout d'abord, elle hérite de ApplicationSettingsBase.

Membres de ApplicationSettingBase

Cette classe dont hérite MySettings propose quelques fonctions de base parmi lesquelles Save, Reset et Reload.

• Save permet d'enregistrer les modifications faites sur les paramètres utilisateur.
• Reset permet de réinitialiser les paramètres utilisateur à leur valeur par défaut, les noeuds enfants de configuration du fichier user.config étant simplement supprimés.
• Reload permet de réinistialiser notre classe avec le contenu des fichiers de configuration (user.config pour les paramètres utilisateur et monassembly.ext.config pour les paramètres d'application.

Vient ensuite la propriété par défaut de MySettings qui retourne une instance partagée de notre configuration, et qui ajoute, dans le cas d'une application WinForm un handler sur l'évènement Shutdown de l'application afin de pouvoir enregistrer les paramètres utilisateur à la sortie de l'application.

Ce qui suit ensuite est ce qui rend l'utilisation de My.Settings si facile.
Tous les paramètres de notre application existent sous forme de propriété.
Comme vous pouvez le constater, les paramètres avec un scope de type Application sont en lecture seule, alors que les autres sont en lecture / écriture.

Si vous regardez plus attentivement, vous vous appercevrez que chacune des propriétés possède un Global.System.Configuration.DefaultSettingValueAttribute . C'est la valeur de cet attribut qui sera utilisée lors d'un appel à Reset et non pas la valeur contenue dans le fichier monassembly.ext.config. Si vous voulez vous amuser, vous pouvez supprimer les sections applicationSettings et userSettings pour constater le résultat.

4-2. MySettingsProperty

Ce module n'a pas un grand intérêt à étudier, mais sa présence est très importante. C'est lui qui va ajouter l'extension Settings au namespace My.

5. Binding de propriété

Ceux qui utilisent les WinForms savent sans doute qu'il est possible de Binder (lier) des données aux contrôles d'une feuille. Il est maintenant possible de faire la même chose avec les paramètres d'application.

Liaison de propriétés au paramètres d'application

Cette méthode présente de nombreux avantages. Vous pouvez lier quasiment n'importe quel type de propriété avec un paramètre d'application, qu'il possède un scope User ou Application. La modification d'un paramètre utilisateur est immédiatement répercutée sur la propriété à laquelle il est associé, la modification de paramètres d'application par le code étant impossible puisque ce sont des propriétés en lecture seule.

6. Fusion de fichiers de configuration

Malheureusement, ce système n'est pas parfait. Si vous voulez utiliser My.Settings dans une assembly qui n'est pas l'éxécutable, vous devez ajouter les sections de configurations adéquates au fichier de configuration de l'exécutable.

Pour vous faciliter la tâche, je vous ai préparé un petit utilitaire qui fera ca tout seul ou presque. Mais avant, regardons un peu ce qu'il faut faire pour fusionner à la main les fichiers de configuration.

6-1. Structure du fichier de configuration

Il y a quatre points auxquels il faut faire attention lors de la fusion de fichiers de configuration.

	Copier le code
1 <?xml version="1.0" encoding="utf-8"?> 2 <configuration> 3 <configSections> 4 </configSections> 5 </configuration>

Ceci est un fichier de configuration de base (j'ai supprimé tout ce qui concerne le traçage pour clarifier un peu le tout). Pour pouvoir utiliser les paramètres, il faut spécifier au fichier de configuration toutes les sections de configuration qu'il y aura.

Dans /configuration/configSections , il y aura d'abord 2 groupes : un pour les paramètres Utilisateurs et un pour les paramètres d'Application. Les deux ne sont pas obligatoires. Si il n'y a pas de paramètres Utilisateurs, le groupe userSettings n'est pas nécessaire. Ces groupes contiendront toutes les déclarations de sections de paramètres utilisateurs, une section par Assembly.

Copier le code

1 <?xml version="1.0" encoding="utf-8"?> 2 <configuration> 3 <configSections> 4 <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, 5 Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"id="6-2"> 6 <section name="ConfigMerger.My.MySettings" type="System.Configuration.ClientSettingsSection, System, 7 Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 8 allowExeDefinition="MachineToLocalUser" requirePermission="false" /> 9 </sectionGroup> 10 </configSections> 11 </configuration>

Voici à quoi ressemble notre fichier de configuration après avoir ajouté la déclaration de paramètres avec portée Utilisateur pour l'assembly ConfigMerger.dll qu'utilise le petit utilitaire dont je vous ai parlé. Mais ce fichier XML est incomplet. Il manque la partie contenant la définition des paramètres eux-mêmes.

Copier le code

1 <?xml version="1.0" encoding="utf-8"?> 2 <configuration> 3 <configSections> 4 <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, 5 Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"> 6 <section name="ConfigMerger.My.MySettings" type="System.Configuration.ClientSettingsSection, System, 7 Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 8 allowExeDefinition="MachineToLocalUser" requirePermission="false" /> 9 </sectionGroup> 10 </configSections> 11 <userSettings> 12 <ConfigMerger.My.MySettings> 13 <setting name="DeleteMergeConfigFile" serializeAs="String"> 14 <value>False</value> 15 </setting> 16 </ConfigMerger.My.MySettings> 17 </userSettings> 18 </configuration>

Si vous regardez bien ce fichier de configuration, 100% opérationel, vous comprendrez mieux sa structure. /configuration/configSections contient les sectionGroup qui 'déclarent' les types de paramètres que nous allons rencontrer. Chaque sectionGroup contient toutes les sections que nous allons retrouver, c'est-à-dire une section par Assembly. Donc, pour en revenir à notre exemple, nous aurons un sectionGroup pour les paramètres utilisateurs, qui contiendra la déclaration de la sections des paramètres utilisateurs de l'Assembly ConfigMerger.

Ensuite vient la section userSettings , qui correspond au sectionGroup userSettings , logique. Celle-ci contient la sous-section ConfigMerger.My.Settings correspondant à notre Assembly ConfigMerger , comme indiqué dans la déclaration de la section. Dans cette section apparaissent tous les paramètres que nous avons définis pour notre assembly. C'est simple non.

6-2. ConfigMerge

Le petit utilitaire que je vous ai concocté ne fera rien de plus que de copier les déclarations de section et les sections elles-mêmes dans le fichier de configuration de l'exécutable.

Son fonctionnement n'est pas bien compliqué. C'est un exécutable console. Voici ses arguments :

Utilisation de ConfigMerger

Copier le code

1 /? ou /help 2 Affiche ce message 3 /configFile:<fichier> 4 Spécifie le fichier de configuration de destination. 5 Le chemin peut être relatif ou absolu 6 /useSameDirectory 7 Si ce paramètre est spécifié, le paramètre /searchDir est ignoré. 8 Si ce paramètre /searchDir n'est pas spécifié, 9 ConfigMerger utilise le répertoire du fichier de destination. 10 /searchDir:<dossier> 11 Spécifie le fichier de configuration de destination. 12 Le chemin peut être relatif ou absolu 13 Utilisation 14 ConfigMerger /configFile:<fichier> 15 ConfigMerger /configFile:<fichier> /useSameDirectory 16 ConfigMerger /configFile:<fichier> /searchDir:<dossier> 17 ConfigMerger /configFile:<fichier> /useSameDirectory /searchDir:<dossier>

Conclusion

Comme vous avez pu le constater, la nouvelle gestion des paramètres d'application est devenu un vrai jeu d'enfant. Il est possible de rendre une application complètement configurable sans taper une seule ligne de code. Que demander de plus ?

Démonstration

Afin d'illustrer un peu mieux ce tutoriel, je vous ai préparé une petite vidéo de présentation de My.Settings. Elle est disponible sur dotnet.developpez.tv : http://dotnet.developpez.tv/tutoriel/my.settings/

Télécharger les sources de l'exemple

Les sources sont disponibles au format Visual Studio 2005

Télécharger ConfigMerge

Téléchargez ConfigMerge avec ses sources

Remerciements

Merci aux correcteurs qui auront pris la peine de relire cet article.

Copyright © 2012 - Olivier Delmotte
Ce site utilise des icône de la librairy Silk icon set 1.3