.NET v2 Configuration Sections - Nick's .NET Travels

Anyone who has written a custom configuration section handler for .NET v1 will appreciate the headaches and the painful process of parsing an xml block. Well .NET v2 has a much better model for building custom configuration sections. In this post I will walk you through the basics:

Getting Started: You need to make sure that your application has a reference to System.Configuration. While by default there is a System.Configuration namespace it is quite limited and doesn’t include the classes you need to build your own custom sections.

We will start with a simple scenario and build it up. In this case the scenario is that you want to store information about a Person in the configuration file. Initially you only need to track a single person and you are only really interested in their name. The easiest way to do this would of course just to add an entry to the appSettings section of the configuration file (alternatively you could use the Application Settings area using the UI designer in Visual Studio 2005 – but we will leave this discussion for another time when we look at application settings):

While this serves the purpose it might mean that this setting gets mixed up with the other settings you might have defined for your application. It also means that in code you have to do a by-name lookup for that value:

MsgBox(ConfigurationManager.AppSettings(“Person”))

This is where we can define our custom configuration section. The first thing you need to do is define what the custom section is going to be called and the name of the .NET type that is going to be used to access the section information. This is done with an entry into the configSections area of the configuration file:

In this case the name of the configuration section in the configuration file will be CustomConfig and this will be loaded using the class MySection in the ConfigurationSample namespace. This class is located in the ConfigurationSample assembly. The next thing to do is to create the custom section in the configuration file. Initially the entry will just be an entry section:

Now that we have set up the configuration file we need to create the MySection class that will be used to load this information at runtime. Again initially this class will be very basic as there is no information to load:

Public Class MySection
Inherits ConfigurationSection
End Class

To access this section in code you simply use the ConfigurationManager (as will the appSettings information) but this time you use the GetSection method to retrieve the MySection object:

Dim sect As MySection = TryCast(System.Configuration.ConfigurationManager.GetSection(“CustomConfig”), MySection)

Now that we have the basics it is time to go back and gradually add information to the custom section. We will start with including a Name attribute in the section itself:

In the MySection class you simply define a property through which you can access this information:

Public Class MySection
   Inherits ConfigurationSection
   <ConfigurationProperty(“Name”, IsRequired:=True)> _
   Public Property Name() As String
      Get
         Return TryCast(Me(“Name”), String)
      End Get
      Set(ByVal value As String)
         Me(“Name”) = value
      End Set
   End Property
End Class

Accessing this in code is as simple as making a call to the Name property of the MySection object:

Dim sect As MySection = TryCast(System.Configuration.ConfigurationManager.GetSection(“CustomConfig”), MySection)
MsgBox(sect.Name)

Clearly this doesn’t read particularly well as it isn’t really the Name of the section you are after. What would be good is to be able to access sect.Person.Name. This can be done using a class that inherits from ConfigurationElement. The configuration file would be:

And the MySection class now looks like:

Public Class MySection
   Inherits ConfigurationSection
   <ConfigurationProperty(“Person”)> _
   Public Property Person() As Person
      Get
         Return TryCast(Me(“Person”), Person)
      End Get
      Set(ByVal value As Person)
         Me(“Person”) = value
      End Set
   End Property
End Class

Public Class Person
   Inherits ConfigurationElement
   <ConfigurationProperty(“Name”, IsRequired:=True)> _
   Public Property Name() As String
      Get
         Return TryCast(Me(“Name”), String)
      End Get
      Set(ByVal value As String)
         Me(“Name”) = value
      End Set
   End Property
End Class

And of course the code to access this information is now:

Dim sect As MySection = TryCast(System.Configuration.ConfigurationManager.GetSection(“CustomConfig”), MySection)
MsgBox(sect.Person.Name)

But what happens if we want to store multiple people in this section. Well there is a built in solution – all we need to do is inherit from the ConfigurationElementCollection. This would give us a configuration section as follows:

And the MySection now looks like (I haven’t included the Person class again as it is the same as before):

Public Class MySection
   Inherits ConfigurationSection
   <ConfigurationProperty(“People”)> _
   Public ReadOnly Property People() As PersonCollection
      Get
         Return TryCast(Me(“People”), PersonCollection)
      End Get
   End Property
End Class

Public Class PersonCollection
   Inherits ConfigurationElementCollection
   Protected Overloads Overrides Function CreateNewElement() As ConfigurationElement
      Return New Person
   End Function
   Protected Overrides Function GetElementKey(ByVal element As ConfigurationElement) As Object
      Return TryCast(element, Person).Name
   End Function
End Class

Now the access code would be:

Dim sect As MySection = TryCast(System.Configuration.ConfigurationManager.GetSection(“CustomConfig”), MySection)
For Each p As Person In sect.People
MsgBox(p.Name)
Next

I hope that gives you an overview of how you can build your own custom configuration sections. Of course your custom section is likely to be much more complex and make further use of the built in configuration support. If you are interested in using this on the mobile device you will have to look to the Mobile Client Software Factory for a configuration implementation as the .NET Compact Framework doesn’t have configuration support.

If you want more information on building custom sections, take a look at Professional Visual Studio 2005

Leave a comment Cancel reply