Application Settings Services

MM .NET provides two main classes that allow you to save and retrieve settings for your application.

Option 1: The Application Settings Manager

mmAppSettingsManager is the default class used to read and write settings to an app.config or web.config file.

Referencing the Application Settings Manager

To reference this object from anywhere in your application, use the static AppSettingsMgr property of the mmAppBase class.

For example, in C#:

// Use namespace at the top of your source code file
using OakLeaf.MM.Main;

var securityOn = mmAppBase.AppSettingsMgr.GetSetting("UserSecurity", "false");

And in VB .NET:

'' Use namespace at the top of your source code file
Imports OakLeaf.MM.Main

Dim securityOn = mmAppBase.AppSettingsMgr.GetSetting("UserSecurity", "false")

Application Setting Object Members

Here is a description of the main properties and methods of mmAppSettingsManager (C# code is shown first and VB .NET second):

ConfigFileExists - This property specifies whether the application configuration file exists. This works for both Windows Forms and Web Forms configuration files.
GetSetting - This method has two overloads that allow you to retrieve settings from the <appSettings> section of the application configuration file:
- Returns the string value for the specified key located in the <appSettings> section of the configuration file. If the key isn't found, the method returns the value specified in the defaultValue parameter.
```
public virtual string GetSetting(string key, string defaultValue)
```
```
Public Overridable Function GetSetting(key As String, defaultValue As String) As String
```
- Returns the string value for the specified key located in the <appSettings> section of the config file. If the key isn't found, returns an empty string.
```
public virtual string GetSetting(string key)
```
```
Public Overridable Function GetSetting(key As String) As String
```

GetSectionSetting - This method has two overloads that allow you to retrieve settings from a specified section of the application configuraton file:

Returns the string value for the specified section and key. If the key isn't found, returns the value specified in the defaultValue parameter.

public virtual string GetSectionSetting(string section, string key, string defaultValue)

Public Overridable Function GetSectionSetting(section As String, key As String, defaultValue As String) As String

Returns the string value for the specified section and key. If the key isn't found, returns an empty string.

public virtual string GetSectionSetting(string section, string key)

Public Overridable Function GetSectionSetting(section As String, key As String) As String

GetSectionSettings - Returns a NameValueCollection containing all elements in the specified configuration file section.

public virtual NameValueCollection GetSectionSettings(string section)

Public Overridable Function GetSectionSettings(section As String) As NameValueCollection

Option 2: Strongly Typed Config Settings with mmAppConfiguration

The mmAppConfiguration class provides a base class from which you can create a custom subclass containing strongly typed properties...one property for each application setting. You can store and retrieve values from these properties and behind the scenes, the class reads and writes to an application config file.

Note: This class is .NET Standard 2.0 compliant!

This class can be used to:

Read/Write settings to an application configuration file such as app.config or web.config
Read/Write settings to a custom XML configuration file
Read/Write settings to an XML string
Encrypt configuration settings

Step 1: Create a Subclass of mmAppConfiguration

Your first step in using mmAppConfiguration is to create a subclass.

For example, in C#:

// Use namespace at the top of your source code file
using OakLeaf.MM.Main;

/// <summary>
/// mmBLGSettings class
/// </summary>
public class mmBLGSettings : mmAppConfiguration
{
 
}

And in VB .NET:

'' Import namespace at the top of your source code file
Imports OakLeaf.MM.Main

Public Class mmBLGSettings
	Inherits mmAppConfiguration
 
End Class

Step 2: Specifying the Configuration File

By default, this class reads and writes to a standard application configuration file (app.config or web.config). If you want to use the standard config file skip to the next step. If you want to use a custom configuration file instead, create a constructor that contains a call to the ReadKeysFromConfig() method, specifying the name of the config file.

Note: If you specify a configuration file that does not exist on disk, mmAppConfiguration automatically creates the config file for you.

In C#:

public class mmBLGSettings : mmAppConfiguration
{
	public mmBLGSettings() : base(false)
	{
		// Use a custom Config file
		this.ReadKeysFromConfig("d:\\projects\\wwWebStore\\MyConfig.config");
	}
}

In VB .NET:

Public Class mmBLGSettings
	Inherits mmAppConfiguration
 
	Public Sub New()
		MyBase.New(False)
		' Use a custom Config file
		Me.ReadKeysFromConfig("d:\projects\wwWebStore\MyConfig.config")
	End Sub
 
End Class

Step 3: Specifying Strongly Typed Settings

You can specify strongly typed application settings by adding public fields (class-level variables) or properties to the class. Every member you add to the class is persisted to the configuration file. You must specify a default value for all public fields and properties! On first use, the class also writes out these default values into the configuration file so the settings are always available.

For example, in C#:

public class mmBLGSettings : mmAppConfiguration
{
	// Example of a property
	public string ProjectName
	{
		get { return _projectName; }
		set { _projectName = value; }
	}
	private string _projectName = "";
 
	// Example of fields
	public string TableStripPrefix = "";
	public string DSLModelFile = "";
	public bool GenerateBizObj = true;
	public string BizObjBaseClass = "ABusinessObject";
	public string BizObjPrefix = "";
	public string BizObjSuffix = "";
	public bool SetDefaultCommandType = true;
 
	public mmBLGSettings() : base(false)
	{
		// Use a custom Config file
		this.ReadKeysFromConfig("BLG.config");
	}
}

And in VB .NET:

Public Class mmBLGSettings
	Inherits mmAppConfiguration
 
	'' Example of a property
	Public Property ProjectName() As String
		Get
			Return _projectName
		End Get
		Set(ByVal value As String)
			_projectName = value
		End Set
	End Property
	Private _projectName As String = ""
 
	'' Example of fields
	Dim TableStripPrefix As String
	Dim DSLModelFile As String
	Dim GenerateBizObj As Boolean
	Dim BizObjBaseClass As String
	Dim BizObjPrefix As String
	Dim BizObjSuffix As String
	Dim SetDefaultCommandType As Boolean
 
	Public Sub New()
		MyBase.New(False)
		' Use a custom Config file
		Me.ReadKeysFromConfig("d:\projects\wwWebStore\MyConfig.config")
	End Sub
 
End Class

Step 4: Using mmAppConfiguration's Services

By default, values are stored in the <appSettings> section of the configuration file and uses the .NET ApplicationSettings class internally to retrieve this data. However, the data is always returned in the proper type format rather than as a string. Null references are never a problem as there is always a default value returned. This reduces the amount of code that goes along with retrieving data from the configuration file. To retrieve the value of a setting you simply reference the associated object field or property.

SetConfigurationSection

Sets the Configuration File Section if the default section (appSettings) is not used.

public virtual void SetConfigurationSection(string ConfigurationFileSection)

Public Sub SetConfigurationSection(ConfigurationFileSection As String)

Example

In C#:

WebStoreConfig Config = new WebStoreConfig();
Config.SetConfigurationSection("WebStore");

And in VB .NET:

Dim Config As New WebStoreConfig()
Config.SetConfigurationSection("WebStore")

SetEncryption

Sets the encrypted field/property list and encryption key from the specified values.

public virtual void SetEncryption(string EncryptFields, string EncryptKey)

Public Sub SetEncryption(EncryptFields As String, EncryptKey As String)

ReadKeysFromConfig

Reads and writes an external .config file other than the standard app.config and web.config files. If the specified file doesn't exist it is created if permissions are available
```
public virtual void ReadKeysFromConfig(string Filename)
```
```
Public Sub ReadKeysFromConfig(Filename As String)
```

Static Factory methods of ReadKeysFromConfig that return an instance of a Config object. Note that the Constructor still fires on these!

public static mmAppConfiguration ReadKeysFromConfig(Type ConfigType)

Public Shared Function ReadKeysFromConfig(ConfigType As Type) As mmAppConfiguration

Static Factory methods of ReadKeysFromConfig that return an instance of a Config object from the specified configuration file. Note that the Constructor still fires on these!

public static mmAppConfiguration ReadKeysFromConfig(string Filename, Type ConfigType)

Public Shared Function ReadKeysFromConfig(Filename As String, ConfigType As Type) As mmAppConfiguration

WriteKeysToConfig

Writes all of the configuration file fields/properties to the default configuration file. The keys are written into the standard .Config files (web.config or YourApp.exe.config for example). In Web Application updating this call causes the Web application to reload itself as a change is made to web.config
```
public virtual bool WriteKeysToConfig()
```
```
Public Function WriteKeysToConfig() As Boolean
```

Writes all of the configuration file fields/properties to a custom configuration file. The format written is in standard .config file format.

public virtual bool WriteKeysToConfig(string Filename)

Public Function WriteKeysToConfig(Filename As String) As Boolean

WriteKeysToFile

Serializes the current object into a file in XML format on disk.

public virtual bool WriteKeysToFile(string FileName)

Public Function WriteKeysToFile(FileName As String) As Boolean

ReadKeysFromFile

Reads the configuration settings from an XML file created with WriteKeysToFile

public static mmAppConfiguration ReadKeysFromFile(string FileName, Type ConfigurationObjectType)

Public Shared Function ReadKeysFromFile(FileName As String, ConfigurationObjectType As Type) As mmAppConfiguration

WriteKeysToString

Serializes the current object into a string in XML format.

public virtual bool WriteKeysToString(out string XmlResultString)

Public Function WriteKeysToString(ByRef XmlResultString As String) As Boolean

ReadKeysFromString

Reads the configuration settings from an XML string created with WriteKeysToString.

public static mmAppConfiguration ReadKeysFromString(string Xml, Type ConfigurationObjectType)

Public Shared Function ReadKeysFromString(Xml As String, ConfigurationObjectType As Type) As mmAppConfiguration

Using mmAppConfiguration without Strong Typing

The following methods allow you to read from your application configuration file without using strong typing. They allow you to return a single string value from a specified config section or return a NameValueCollection of all keys/values in a specified section. This is useful in situations where you have a variable number of settings that can differ from one installation to another, such as database settings.

GetAllKeysFromConfigSection

Returns all the keys in the Configuration Section as string key value pairs. Internally uses Configurations class for default configuration and XML to retrieve in external files. Requires permissions to read the external file.
```
public virtual NameValueCollection GetAllKeysFromConfigSection(string Section, string Filename)
```
```
Public Function GetAllKeysFromConfigSection(Section As String) As NameValueCollection
```

Encrypting Configuration Settings

At times you may want to encrypt settings in your application configuration file. We recommend storing secure settings in a file other than the standard app.config file just to make it a little less obvious (to someone who knows a little bit about .NET) where the settings are stored.

Here is an example of encrypting a database connection string:

Create a subclass of mmAppConfiguration, for example, MyAppSettings.
Add a class-level variable (field) or property to the class for each of the settings you want to encrypt

In the constructor of the new class add code that calls the SetEncryption() method specifying the list of settings to be encrypted as well as the encryption key, then calls the ReadKeysFromConfig() method specifying the name of the config file.

For example, in C#:

public class MyAppSettings : mmAppConfiguration
{
	public string ConnectionString = "";
 
	/// <summary>
	/// Custom constructor that specifies  encyrption fields and key
	/// and reads the keys from the config file
	/// </summary>
	public MyAppSettings()
	{
		// Specify the settings to be encrypted, and the encryption key
		this.SetEncryption("ConnectionString", "oak_11");
		// Read the settings from the config file and store them in the class fields/properties
		this.ReadKeysFromConfig("xyz.config");
	}
}

And in VB .NET:

Public Class MyAppSettings
	Inherits mmAppConfiguration
 
	Public ConnectionString As String = ""
 
	'/ <summary>
	'/ Custom constructor that specifies  encyrption fields and key
	'/ and reads the keys from the config file
	'/ </summary>
	Public Sub New()
		' Specify the settings to be encrypted, and the encryption key
		Me.SetEncryption("ConnectionString", "oak_11")
		' Read the settings from the config file and store them in the class fields/properties
		Me.ReadKeysFromConfig("xyz.config")
	End Sub
 
End Class

To change the value of a setting, just set the value of the corresponding field/property then call its WriteKeysToConfig() method.

For example, in C#:

this.oAppSettings.ConnectionString = "server=(local);uid=sa;pwd=;database=Northwind;";
this.oAppSettings.WriteKeysToConfig();

And in VB .NET:

Me.oAppSettings.ConnectionString = "server=(local);uid=sa;pwd=;database=Northwind;"
Me.oAppSettings.WriteKeysToConfig()