I wrote about the configuration functions in .NET here. My specific words were:
If your sideline utility needs to save a few settings, use the .NET configuration…
Ugh, I’m sorry I said that…
The .NET configuration namespace is powerful, no doubt about that. But, that comes at a huge cost. The thing is enormous. And the available documentation and examples just aren’t that good.
Honestly, though. The docs don’t bother me that much. What bothers me is that even though the existing framework will probably do everything I want it to, discovering how is just too dang hard and non-intuitive.
- Why the hell should I have to create a new ExeConfigurationFileMap object just to change the path of where the system reads its config file? Sorry, but that’s about as intuitive as a car you accelerate by yodeling.
- What on earth were they smoking when they came up with those ludicrous guid/hash/hex based folder names where your user level config files are stored by default? Facilitate upgrades? Yeah, maybe, but pretty much nothing else. That’s one that I guarantee will go down with the registry and DCOM as a bad idea.
- Registering ConfigurationSection handlers? Huh? Why should I have to write the full class names of classes internal to my application into my configuration file so that .NET can read them?
What Would Be Nice
What I was looking for was a simple way to create a class like so:
Public Sub MySettingClass Public Setting1 as string = "" Public Setting2 as Integer = 0 End Class
No need to explicitly use properties unless you need them. No need for attributes. Heck, you shouldn’t even have to declare the class <Serializable>, though that’s a minor point.
In lieu of coexisting within the My.Settings space, it should be able to persist itself to a config file, and then de-persist itself back when asked, like this:
Settings = New MySettingsClass Settings.Load ... Settings.Save
Accessing your settings should be completely early bound, with all that sweet Intellisense goodness baked right in:
x = Settings.Setting1 y = Setting.Setting2
Further, I should be able to easily persist sub-objects or collections made accessible off this root settings object. For example, to save a form’s current position and size, and then restore it, should take code similar to:
Settings.FormPositions.Save(MyForm) Settings.FormPositions.Restore(MyForm) Debug.print "Form position is " & Settings.FormPositions(0).Position
And a few additional requirements.
- First, having no initial configuration file shouldn’t be a problem. The entire collection of settings should easily default to some “built in” default values when no config file exists.
- Second, I should be able to go from 0-60 in no time. In other words, I should be able to take the .VB file for a settings base class, drop it in my application, add a settings class with the properties I need to persist, as well as a .LOAD and a .SAVE at the appropriate points in my project, and be off. No “presetting” my config file, no tweaks to anything, no registering this or that, mucking with the GAC, etc, etc.
The available Microsoft documentation on the configuration system was so confusing, I believe I knew less about it after I finished reading the docs than I did when I started.
I did turn up a very good article on CodeProject by Jon Rista called Cracking the Mysteries of .NET 2.0 Configuration. Definitely worth a read if you’re diving into this stuff.
While Jon gives several samples of code, nothing really illustrated exactly what I was looking for. However, there was more than enough info in the article to kick-start things for me.
Long story short, it turns out that the Configuration system in .NET is, in typical MS fashion, more than capable but ultra-overkill for many small-app type scenarios.
While this is definitely still a work in progress, it’s proved quite useful so far, so I thought others might find it handy too.
The system consists of one file, SettingsBase.vb. It defines two classes, SettingsBase and SettingsBaseDictionary.
SettingsBaseDictionary is just a simple extension to the normal generic Dictionary class that allows it to be serialized. This is something I found on the web and is so handy with respect to settings that I just include it directly in the file.
SettingsBase is a MustInherit class, meaning it’s abstract. To use it, you must create your own settings class (call it whatever you like) that inherits from SettingsBase:
Public Class Settings Inherits SettingsBase Public Name As String = "" Public Phone As String = "" End Class
When you want to load your settings, just instantiate your Settings object and invoke Settings.Load. To change settings, set the object’s properties as you normally would.
To save your settings, invoke Settings.Save.
Finally, you’ll need to add a reference to System.Configuration. Directly accessing the ConfigurationManager and EXEConfigurationFileMap objects requires it.
The sample project I’ve zipped up shows several examples of this, from ridiculously simple to moderately sophisticated. I even threw in a really simple example of DataBinding to a setting property (in this case, a Dictionary of contacts).
If you don’t want to download the sample, I’ve included the source to the SettingBase.VB file here. Note that this also includes the source to the SettingBaseDictionary, but if you don’t want it, you can simply delete it.
Imports System.Configuration Imports System.IO Imports System.Text Imports System.Xml Imports System.Xml.Serialization ''' <summary> ''' Base Class that will allow you to easily persist ''' a "settings" object via the .net configuration management framework ''' ''' By Darin Higgins ''' Sept 2008 ''' You are free to use this class in your own projects. ''' But please, keep the attributions as to the source. ''' </summary> ''' <remarks> ''' Be sure to add a reference to System.Configuration ''' </remarks> ''' <editHistory></editHistory> Public MustInherit Class SettingsBase #Region " Constants" '---- just some names of constants used in the class Private Const DEFAULTSETTINGFILENAME = "Settings.config" Private Const ROOTSECTION = "general" Private Const ROOTITEM = "settings" #End Region #Region " Properties" Private rFilename As String = DEFAULTSETTINGFILENAME ''' <summary> ''' The Settings filename (name only, no path) ''' </summary> ''' <value></value> ''' <remarks></remarks> Public Property FileName() As String Get Return rFilename End Get Set(ByVal value As String) rFilename = value End Set End Property Private rCompanyName As String = My.Application.Info.CompanyName ''' <summary> ''' The CompanyName used when creating a path to the settings store ''' </summary> ''' <value></value> ''' <remarks></remarks> Public Property CompanyName() As String Get Return rCompanyName End Get Set(ByVal value As String) rCompanyName = value End Set End Property Private rAppName As String = My.Application.Info.ProductName ''' <summary> ''' The AppName used when creating a path to the settings store ''' </summary> ''' <value></value> ''' <remarks></remarks> Public Property AppName() As String Get Return rAppName End Get Set(ByVal value As String) rAppName = value End Set End Property ''' <summary> ''' Retrieves the full path and filename to the settings store ''' Normally \Docs and Settings\All Users\Application Data\CompanyName\AppName\Settings.config ''' </summary> ''' <value></value> ''' <remarks></remarks> Private ReadOnly Property pAppConfigFilename() As String Get '---- Don't use My.Computer.FileSystem.SpecialDirectories ' because the commonappdata folder returned will always have ' the version in it and it will automatically be created ' but I don't want that here Dim path = System.Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData) '---- as is pretty standard practice, our app settings ' go in a CompanyName\Appname folder in the CommonAppData folder If Me.CompanyName.Length > 0 Then path = System.IO.Path.Combine(path, Me.CompanyName) If Not My.Computer.FileSystem.DirectoryExists(path) Then My.Computer.FileSystem.CreateDirectory(path) End If End If If Me.AppName.Length > 0 Then path = System.IO.Path.Combine(path, Me.AppName) If Not My.Computer.FileSystem.DirectoryExists(path) Then My.Computer.FileSystem.CreateDirectory(path) End If End If Dim Filename = System.IO.Path.Combine(path, Me.FileName) Return Filename End Get End Property ''' <summary> ''' Creates an ExeConfigurationFileMap object to properly ''' locate the config files we'll use ''' </summary> ''' <value></value> ''' <remarks></remarks> Private ReadOnly Property pAppConfigMap() As ExeConfigurationFileMap Get Dim filemap = New ExeConfigurationFileMap filemap.ExeConfigFilename = Me.pAppConfigFilename Return filemap End Get End Property ''' <summary> ''' Creates a Configuration object mapped to ''' the proper settings files ''' Sets up several internal setting elements and sections ''' so we can persist the host object ''' </summary> ''' <value></value> ''' <remarks></remarks> Private ReadOnly Property pConfig() As Configuration Get Static cfg As Configuration '---- cache the config object so we can reuse it If cfg Is Nothing Then cfg = ConfigurationManager.OpenMappedExeConfiguration(Me.pAppConfigMap, ConfigurationUserLevel.None) End If If Not cfg.HasFile Then '---- force a file to be created ' This settings is just general purpose placeholder ' not really intended to be used cfg.AppSettings.Settings.Add("version", My.Application.Info.Version.ToString) cfg.Save() End If Dim bDirty As Boolean = False If cfg.HasFile Then '---- no need for groups in this case ' but this sample code illustrates how you'd create a ConfigGroup if necessary 'If cfg.SectionGroups(ROOTSECTION) Is Nothing Then ' cfg.SectionGroups.Add(ROOTSECTION, New ConfigurationSectionGroup) ' bDirty = True 'End If 'If cfg.SectionGroups(ROOTSECTION).Sections("options") Is Nothing Then ' cfg.SectionGroups(ROOTSECTION).Sections.Add("options", New ClientSettingsSection) ' bDirty = True 'End If Dim sect As ClientSettingsSection = cfg.Sections(ROOTSECTION) If cfg.Sections(ROOTSECTION) Is Nothing Then sect = cfg.Sections(ROOTSECTION) cfg.Sections.Add(ROOTSECTION, sect) bDirty = True End If Dim element = sect.Settings.Get(ROOTITEM) If element Is Nothing Then element = New SettingElement(ROOTITEM, SettingsSerializeAs.Xml) sect.Settings.Add(element) bDirty = True End If If element.Value.ValueXml Is Nothing Then '---- make sure element contains something element.Value.ValueXml = New Xml.XmlDocument().CreateElement("value") bDirty = True End If If bDirty Then cfg.Save() End If Return cfg End Get End Property ''' <summary> ''' If you would like to use the built in ConfigurationStringsSection ''' just add a readonly property that exposes this property ''' Doing it this way, you can expose this property anywhere you want ''' in your Setting object heirarchy. ''' ''' </summary> ''' <value></value> ''' <remarks></remarks> Protected ReadOnly Property ConnectionStrings() As ConnectionStringsSection Get Return pConfig.ConnectionStrings End Get End Property ''' <summary> ''' Since this is essentially a key/value pair collection ''' there's not much benefit to exposing it, but I've included it ''' for completeness. ''' ''' These kinds of sections are particularly useful when config merging ''' is used heavily, but that's not the point of this base class ''' </summary> ''' <value></value> ''' <remarks></remarks> Protected ReadOnly Property AppSettings() As AppSettingsSection Get Return pConfig.AppSettings End Get End Property #End Region #Region " Methods" ''' <summary> ''' Persist the host object to the configuration file ''' </summary> ''' <remarks></remarks> Public Sub Save() With Me.pConfig '---- not using configgroups right now, but keeping this for reference 'Dim sect = TryCast(.SectionGroups(ROOTSECTION).Sections("options"), ClientSettingsSection) 'If sect.Settings.Get(ROOTITEM) Is Nothing Then ' element = New SettingElement(ROOTITEM, SettingsSerializeAs.Xml) ' element.Value.ValueXml = New Xml.XmlDocument().CreateElement("value") ' sect.Settings.Add(element) 'Else ' element = sect.Settings.Get(ROOTITEM) 'End If Dim sect = TryCast(.Sections(ROOTSECTION), ClientSettingsSection) Dim element = sect.Settings.Get(ROOTITEM) '---- Create a serializer to serial our superclass Dim s = New XmlSerializer(Me.GetType) Using ms = New MemoryStream '---- serialize it s.Serialize(ms, Me) '---- rewind and convert the stream to a string ms.Seek(0, SeekOrigin.Begin) Dim myutf As UTF8Encoding = New UTF8Encoding() '---- load it up into an xml doc Dim xml = New XmlDocument xml.LoadXml(myutf.GetString(ms.GetBuffer())) '---- and push into the settings "value" ' stripping out the XML header stuff element.Value.ValueXml.InnerXml = xml.DocumentElement.OuterXml End Using '---- Force the save, because we won't otherwise trigger ' the dirty condition sect.SectionInformation.ForceSave = True .Save() End With End Sub ''' <summary> ''' Reload the superclass's properties from configuration ''' </summary> ''' <remarks></remarks> Public Sub Load() With Me.pConfig Dim sect = TryCast(.Sections(ROOTSECTION), ClientSettingsSection) Dim element As SettingElement = sect.Settings.Get(ROOTITEM) '---- if we've got the required element... If Len(element.Value.ValueXml.InnerXml) Then '---- deserialize the xml Dim s = New XmlSerializer(Me.GetType) Dim myutf As UTF8Encoding = New UTF8Encoding() Using ms = New MemoryStream(myutf.GetBytes(element.Value.ValueXml.InnerXml)) '---- just get a generic object ' and we'll use reflection to ' update the properties and fields of THIS object Dim o As Object = Nothing Try o = s.Deserialize(ms) Catch ex As Exception Debug.Print("Problem") End Try If o IsNot Nothing Then '---- now need to refresh our values from ' this deserialized object For Each Field In Me.GetType().GetFields If Field.IsPublic Then '---- BaseSettings has no fields, so ' we don't need to check if the field ' is defined the the base object Try Field.SetValue(Me, Field.GetValue(o)) Catch End Try End If Next '---- now copy over any properties For Each Prop In Me.GetType().GetProperties '---- first, check that the property ' isn't one of the BaseSettings properties ' we don't want to depersist those! Dim n = Prop.Name Dim query As IEnumerable(Of System.Reflection.PropertyInfo) = Me.GetType.BaseType.GetProperties.Where(Function(Prop2) Prop2.Name = n) If query.Count = 0 Then '---- this is not a property on BaseSettings If Prop.CanWrite Then If Prop.GetIndexParameters.Count = 0 Then '---- handle non-indexed properties Try Prop.SetValue(Me, Prop.GetValue(o, Nothing), Nothing) Catch End Try Else '---- not handling indexed properties yet End If End If End If Next End If End Using End If End With End Sub #End Region #Region " SettingsBaseDictionary" ''' <summary> ''' A simple serializable dictionary class I pulled off the web. ''' ''' Originally at http://www.playswithcomputers.com/SGDCollection.aspx ''' ''' I've included it here because very often settings collections ''' need to be keyed for access, and lists/bindinglists (which will ''' persist just fine) don't make that especially straightforward ''' like a dictionary. ''' ''' However, you can also use a generic List or BindingList for properties ''' and they seem to be persisted just fine, they just aren't quite ''' as easy to perform keyed lookups on. ''' ''' </summary> ''' <remarks></remarks> ''' <editHistory> ''' </editHistory> <XmlRoot("dictionary", IsNullable:=True)> _ Public Class SettingsBaseDictionary(Of TKey, TValue) Inherits Generic.Dictionary(Of TKey, TValue) Implements IXmlSerializable Private Const ITEMNAME = "item" Private Const KEYNAME = "key" Private Const VALUENAME = "value" Public Function GetSchema() As System.Xml.Schema.XmlSchema Implements IXmlSerializable.GetSchema Return Nothing End Function Public Sub New() MyBase.New() End Sub Public Sub New(ByVal capacity As Integer) MyBase.New(capacity) End Sub Public Sub New(ByVal comparer As System.Collections.Generic.IEqualityComparer(Of TKey)) MyBase.New(comparer) End Sub Public Sub New(ByVal capacity As Integer, ByVal comparer As System.Collections.Generic.IEqualityComparer(Of TKey)) MyBase.New(capacity, comparer) End Sub Public Sub New(ByVal dictionary As Generic.IDictionary(Of TKey, TValue)) MyBase.New(dictionary) End Sub Public Sub New(ByVal dictionary As Generic.IDictionary(Of TKey, TValue), ByVal comparer As System.Collections.Generic.IEqualityComparer(Of TKey)) MyBase.New(dictionary, comparer) End Sub Public Sub New(ByVal info As System.Runtime.Serialization.SerializationInfo, ByVal context As System.Runtime.Serialization.StreamingContext) MyBase.New(info, context) End Sub ''' <summary> ''' Read a Serialized XML Dictionary of generic objects ''' </summary> ''' <param name="reader"></param> ''' <remarks></remarks> Public Sub ReadXml(ByVal reader As System.Xml.XmlReader) Implements IXmlSerializable.ReadXml Dim keySerializer As XmlSerializer = New XmlSerializer(GetType(TKey)) Dim valueSerializer As XmlSerializer = New XmlSerializer(GetType(TValue)) Dim wasEmpty As Boolean = reader.IsEmptyElement reader.Read() If wasEmpty Then Return Do While (reader.NodeType <> System.Xml.XmlNodeType.EndElement) reader.ReadStartElement(ITEMNAME) reader.ReadStartElement(KEYNAME) Dim key As TKey = DirectCast(keySerializer.Deserialize(reader), TKey) reader.ReadEndElement() reader.ReadStartElement(VALUENAME) Dim value As TValue = DirectCast(valueSerializer.Deserialize(reader), TValue) reader.ReadEndElement() Me.Add(key, value) '---- finish reading this element and move to the next reader.ReadEndElement() reader.MoveToContent() Loop reader.ReadEndElement() End Sub ''' <summary> ''' Write the XML Serialization of a dictionary of generic objects ''' </summary> ''' <param name="writer"></param> ''' <remarks></remarks> Public Sub WriteXml(ByVal writer As System.Xml.XmlWriter) Implements IXmlSerializable.WriteXml Dim keySerializer As XmlSerializer = New XmlSerializer(GetType(TKey)) Dim valueSerializer As XmlSerializer = New XmlSerializer(GetType(TValue)) For Each key As TKey In Me.Keys writer.WriteStartElement(ITEMNAME) writer.WriteStartElement(KEYNAME) keySerializer.Serialize(writer, key) writer.WriteEndElement() writer.WriteStartElement(VALUENAME) valueSerializer.Serialize(writer, DirectCast(Me(key), TValue)) writer.WriteEndElement() writer.WriteEndElement() Next End Sub End Class #End Region End Class
Points of Interest
- Your settings file will, by default, be written to the CommonApplicationData folder, and in there, in a folder named the same as the CompanyName in your assembly information screen, and in there, in a folder named the same as the Application Name in the assembly information screen.
So, for the above app, under Windows XP, you’ll find the default setting file in
c:\Documents and Settings\All Users\Application Data\One Nifty Company\SettingsTest\Settings.config
and under Vista
c:\Program Data\One Nifty Company\SettingsTest\Settings.config
This is pretty standard practice for config files, but if you want to change it, you’ve got the source<g>.
- You can change the setting filename, the Company Name and the Product Name used by simply changing the associated properties of your setting object (these properties are all inherited from the SettingsBase object).
- Although you can use fields in your base Settings object, you won’t be able to use any DataBinding support with them. This is a limitation of the .NET Databinding support, and not with the Settings class. Quite frankly, it sucks. Sometimes full blown properties make sense, but in this case, properties are just a lot more work for the same net effect.
If you want to use Databinding with your settings class, you’re probably best off declaring all persistent elements of your settings class as properties to begin with, and just avoid using fields at all.
- The SettingsBase object doesn’t even try to provide access to configuration “sections” or “section groups”. You can easily break settings down into groups or sections by using “sub objects” off your main settings object (the one that inherits from SettingsBase). I illustrate this is the sample app.
- There’s no merging (at least not intentionally anyway). I’m still not completely sure of how that works, and I haven’t needed it yet.
- As I indicated earlier, much of this could be accomplished by creating a custom ConfigurationSection class, and registering it in your config file, but from what I can tell so far, that mean you have to manually add gunk to your config file. To me, that’s got a code smell akin to that guy in the next cube that burns patchouli all day. It doesn’t stink, per se, but it sure makes your eyes water if you’re around it long enough.
- Really, this should be wrappable in a custom ConfigurationSection handler. My only gripes with that approach is that it doesn’t resolve the folder naming problem, and it requires the goofy registration of the section handler. I’m betting there’s ways around both those issues, though. I just haven’t found them yet.
- In the same vein, I’d really love to figure a way to accommodate what I’m looking for, AND still use the My.Settings namespace as it’s currently automatically defined by Visual Studio. Again, I’m working on that, but this simple approach works for the short and sweet utility apps I’ve needed to turn out recently.
Check it out and let me know what you think!