Cinchoo - Using AppSettings as Configuration Source

• Download sample - 4.5 KB

1. Introduction

Cinchoo is an application framework for .NET. One of the main functionalities it provides to users is the application configuration management. Application configuration is information that an application reads and/or writes at run-time from the source.

Please visit jump start article [Cinchoo - Simplified Configuration Manager] for more information about Cinchoo configuration manager.

In this section, I'll show you with sample in reading/writing AppSettings using the Cinchoo configuration framework. It gives the opportunity for loading and using application settings values in your .NET applications.

Let's start this exercise using the below appSettings values (FYI, this section is not mandatory to present in App.Config when using Cinchoo framework. It will be created automatically the very first time the application starts.)

Listing 1.1 Sample AppSettings values in App.Config

<?xml version="1.0"?>
<configuration>
<appSettings>
    <add key="name" value="Mark" />
    <add key="address" value="21 River Road, New York, NY 10010" />
    <add key="invoiceAmount" value="11.2120001" />
</appSettings>
</configuration>

Usually, you can consume these values using .NET API as follows:

Listing 1.2 Consume appSettings using .NET API

class Program
{
    static void Main(string[] args)
    {
        string name = ConfigurationManager.AppSettings["name"];
        string address = ConfigurationManager.AppSettings["address"];
        double invoiceAmount = Convert.ToDouble(ConfigurationManager.AppSettings["invoiceAmount"]);
    }
}

Accessing appSettings using the above approach lacks the below features:

1. Automatic type conversion
2. Change notification of values in the source
3. Auto saving of changes values back to source
4. Type-safe mechanism
5. Defining and using Default values
6. Auto creation of key-values if missing

Cinchoo offers the above features out of the box. Just by simply declaring a class with appropriate members should be sufficient to consume the appSettings values. Read further on how to do it.

2. How to Use

• Download the latest Cinchoo binary here. (Nuget Command: Install-Package Cinchoo)
• Open VS.NET 2010 or higher
• Create a sample VS.NET (.NET Framework 4) Console Application project
• Add reference to Cinchoo.Core.dll
• Use the Cinchoo.Core.Configuration namespace
• Define a configuration object 'ApplicationSettings' as below

Listing 2.1 Defining Configuration Object

[ChoStandardAppSettingsConfigurationSection]
public class ApplicationSettings : ChoConfigurableObject
{
    [ChoPropertyInfo("name", DefaultValue="Mark")]
    public string Name;

    [ChoPropertyInfo("address", DefaultValue = "21 River Road, New York, NY 10010")]
    public string Address;

    [ChoPropertyInfo("invoiceAmount", DefaultValue = "11.21201")]
    public double InvoiceAmount;

    protected override void OnAfterConfigurationObjectLoaded()
    {
        Console.WriteLine(ToString());
    }
}

The code above illustrates about defining configuration object. First thing defines a configuration object (ex. ApplicationSettings) class from ChoConfigurableObject, it indicates that this object is a configuration object. And it must be decorated with ChoStandardAppSettingsConfigurationSectionAttribute to complete the definition. This attribute enables the configuration object to read and write configuration values under 'appSettings' section in App.Config file.

Define three members Name, Address and InvoiceAmount as public fields or properties with get and set in it. Decorate them with ChoPropertyInfo attribute to indicate that they are configuration members. In this sample, Name property is given name as property name with defaultvalue as 'Mark'. It means that this member will be defaulted to default value when the value is missing in the configuration file. Respectively declare other members for each appSettings key. It is a very simple and clear way of specifying configuration members using attributes.

Once you have class declared as above, it is now ready to consume appSettings values as simple as creating object out of it. Any changes made to this object and/or in the app.Config file will be exchanged automatically. The sample code is as below:

Listing 2.2 Main method

static void Main(string[] args)
{
    ApplicationSettings applicationSettings = new ApplicationSettings();
    ChoConsole.PauseLine();
} 

We start by creating a new instance of ApplicationSettings object. That's all. All the heavy lifting of loading appSettings values to the object is done by the Cinchoo framework under the hood.

Just compile and run the above sample, it will output as below:

Listing 2.3 Output of Test1.exe

-- ChoStandardAppSettingsConfig.Test.ApplicationSettings State --
        Name: Mark
        Address: 21 River Road, New York, NY 10010
        InvoiceAmount: 11.21201

Press ENTER key to continue...

Now let's see how the application picks up the changes made to the [AppExeName].Config file reflected in the output. Open [AppExeName].config file, edit the name from 'Mark' to 'Tom' and save the file.

Listing 2.4 Output of Test1.exe when changing the values in the App.Config file

-- ChoStandardAppSettingsConfig.Test.ApplicationSettings State --
        Name: Mark
        Address: 21 River Road, New York, NY 10010
        InvoiceAmount: 11.21201

Press ENTER key to continue...
-- ChoStandardAppSettingsConfig.Test.ApplicationSettings State --
        Name: Tom
        Address: 21 River Road, New York, NY 10010
        InvoiceAmount: 11.21201

2. Advanced Settings

2.1 Override ConfigurationManager

Cinchoo automatically instantiates and uses appropriate ConfigurationManager depending on the type of the application. Your application works seamlessly out of the box to read and write appSettings. Rarely, you may want to override this behaviour to take control of specifying configuration files location by using ChoConfigurationManager. You can do so as below:

Listing 2.1.1 Overriding ConfigurationManager

class Program
{
    static void Main(string[] args)
    {
        ChoApplication.AfterConfigurationManagerInitialized += 
            ChoApplication_AfterConfigurationManagerInitialized;
    }

    static void ChoApplication_AfterConfigurationManagerInitialized(object sender, EventArgs e)
    {
        ChoConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.PerUserRoaming);
    }
}

2.2 External AppSettings file

Many of you are aware that you can specify external file containing application settings to your application via File attribute. Cinchoo framework works with this external file as well. Any filepath specified as appSettings external filepath will be automatically created if not present, watch for any changes and save the changes to them, etc. The filepath can be either relative or absolute path. The path specified is relative to the application configuration folder. By default, for a Windows Forms application, this would be the binary folder (such as /bin/debug), not the location of the application configuration file. For Web Forms applications, the path is relative to the application root, where the web.config file is located. You can control the configuration file location by using ChoConfigurationManager.OpenExeConfiguration() method as stated in the previous section.

Note that the runtime ignores the attribute if the specified file cannot be found.

Listing 2.2.1 Sample AppSettings section with file attribute

<configuration>
    <appSettings file="appSettings.xml">
    </appSettings>
</configuration>

That's all. A sample project is attached. Download and try for yourself.