Configure your .NET application with C# config files. Config files are C# source files, managed by Visual Studio like any other code file, intellisensed, refactorable, resharpered, syntax checked, compiled, type safe.
Write real code with control structures and classes in config files. Include other local or remote (HTTP) config files.
No more key-value lists of string based app settings from XML. These settings are typed properties of CLR objects, even aggregated types. No more workarounds for complex settings, which do not fit properly in strings.
Devops friendly, because admins can program their config files. Developers can document settings with examples in their own code, which is also the admins's config file.
nuget download: https://www.nuget.org/packages/ConfigSharp/
You have a config class which contains your app settings. An instance is populated by loading/executing C# based config files. You can then use properties of the config object anywhere in your app.
Your config file is C#: ConfigFile.cs:
namespace MyProgram.Configuration // any namespace
{
class ConfigFile : MyProgram.MyConfig // Any class name derived from your config class
{
public void Load()
{
SomeProperty = "42";
Include("OtherConfigFile.cs");
}
}
}
ConfigSharp will execute the Load() method of your config file.
Your program: Program.cs:
static void Main(string[] args)
{
var config = new MyConfig();
config.Include("ConfigFile.cs");
...
var prop1 = config.SomeProperty;
}
public class MyConfig : ConfigSharp.Container
{
public string SomeProperty { get; set; }
public int OrAsMemberVariable = 41;
public DateTime OrPlainOldCLRTypes;
public string DatabasePassword { get; set; }
public string SetupName { get; set; }
}
Usually you want a globally available config accessor, not just a variable like the var config above. ConfigSharp has a global instance which can be used. Also, depending on your environment, the location of the config file may need a path relative to the project or the binary.
ConfigSharp.Global.Instance = new MyConfig();
ConfigSharp.Global.Instance.Include("bin/Configuration/ConfigFile.cs");
...
var prop1 = ConfigSharp.Global.Instance.SomeProperty;
Since I don't like the writing ConfigSharp.Global.Instance all the time, I shorten this by defining my own global wrapper:
public class Global
{
public static MyConfig Config { get { return (MyConfig)ConfigSharp.Global.Instance; } }
}
Then I can use everywhere in my program:
var prop1 = Global.Config.ApplicationName;
(Usually I add more global instances of other libraries to my global wrapper, like a logger.)
You might also call it:
public class App
{
public static MyConfig Settings { get { return (MyConfig)ConfigSharp.Global.Instance; } }
}
and use it like:
var prop1 = App.Settings.ApplicationName;
The goal of ConfigSharp is to edit config files like code files. But config files will not be compiled into the application. They must be copied as files to the binaries. In the properties of all config files change Copy to Output Directory from Do not copy to Copy if newer.
You might put all config files into a Configuration folder. The folder will appear in the output and all config files (if there are more than one) will be available in bin/Configuration.
You might also put your config base class (MyConfig.cs) into the Configuration folder and also Copy if newer to the output folder. This might serve as a reference of available config parameters for devops.
Putting MyConfig.cs into the Configuration folder also allows to get rid of a namespace in config files. Config classes are derived from the base config (MyConfig) and they are siblings in the Configuration folder. ConfigFile.cs:
namespace MyProgram.Configuration // Named by the folder
{
class ConfigFile : MyConfig // Because the base config class is a sibling in the folder (=namespace)
{
public void Load()
{
SomeProperty = "42";
Include("OtherConfigFile.cs");
}
}
}
After loading the settings into the config object...
new MyConfig().Include("../../ConfigFile.cs");
...you will use the properties. Your app settings / config properties / members of the config object can be accessed in different ways:
var serverAddress = config.ServerAddress;
var serverAddress = Config.Global.ServerAddress;
// or:
var serverAddress = App.Settings.ApiAddress;
This needs a wrapper in your app code like:
public class App : ConfigSharp.Global
{
public static MyConfig Settings { get { return (MyConfig)ConfigSharp.Global.Instance; } }
}
Without this wrapper you'd use:
var serverAddress = ConfigSharp.Global.Instance.ServerAddress;
var serverAddress = Config.Global.Get("ServerAddress", "http://localhost:8080/");
var maxSize = Config.Global.Get("MaxMessageSize", 100 * 1024 * 1024);
var formatJson = Config.Global.Get("FormatResponseJson", true);
// Complex properties with type:
var endDate = Config.Global.Get<DateTime>("ServiceEndDate");
You could also omit the Global. and do
var serverAddress = Config.Get("ServerAddress", "http://localhost:8080/");
// or
var serverAddress = AppSettings.Get("ServerAddress", "http://localhost:8080/");
// Your choice
If you augment the your wrapper with a getter:
public static string Get(string key, string defaultValue)
{
return ConfigSharp.Global.Instance.Get(key, defaultValue);
}
The first config.Include() must point to the include file relative to the working directory or must be an absolute path. Include()s inside config files will take file names relative to the first include file. The config object has a BaseFolder property. If it is set, then it is used a s a base for relative paths instead of the app's working directory.
Example (in the debug environment the first call might be):
config.Include("../../ConfigFile.cs");
Example (first call in the production environment):
config.Include("Configuration/ConfigFile.cs");
// or
config.Include(@"D:\MyApp\ConfigFile.cs");
Example (inside config file relative to parent but no "config" instance, because "this" is the instance):
Include("AdditionalConfigFile.cs");
The Include() method also digests http:// and https:// URLs. Example:
Include("https://my.config.server/MyApp/Configuration");
Config Sharp addes references to mscorelib and System.dll. That's enough for property assignments. If your config class or your config file code needs additional types, then the assemblies have to be referenced in the config file.
Example (with absolute path):
//reference "C:\Windows\Microsoft.Net\assembly\GAC_MSIL\System\v4.0_4.0.0.0__b77a5c561934e089\System.dll"
Example (with an Assembly Qualified Name of any type of the assembly):
//reference "System.Uri, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
The //reference looks like a comment. It actually is a comment for the Visual Studio compiler. But //reference is recognized by ConfigSharp.
Example config file:
//reference "System.UriBuilder, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
namespace MyProgram.Configuration
{
class ConfigFile : MyProgram.MyConfig
{
public void Load()
{
HomePageUrl = new UriBuilder("http", "blog.wolfspelz.de");
}
}
}
Remark: unfortunately, the #r notation of C#-Script is not possible, because the code will be managed by Visual Studio, which will complain about an unknown preprocessor directive. Even #pragma reference gives a warning.
Many libraries are opinionated. They require you to do things in certain ways. ConfigSharp has a very small API and it gives a lot of freedom with respect to naming and policies. Here are the things you can change:
- namespace in config files
- class names in config files
- config object class name, e.g. MyConfig
- property names (of course)
- C# properties or memeber variables with initialization
- global config accessor name, e.g. Config.Global.MyProperty or App.Settings.MyProperty
- configuration management policy, because it is implemented by your config files
- value of the BaseFolder property of the config object from inside the config file
When running in different environments (Debug, Build, Production), then you need different config files. There are debug only settings, user names, passwords, and Web service addresses, which depend on the environment. The operating department might keep a few secrets with respect to production database passwords and payment provider accounts. We need a way to switch easily and automatically between environments. That's where a configuration management policy comes in.
Configuration management should
- make switching setups easy,
- encourage developers to set default values when adding properties,
- allow developers to assign probable production values for new properties,
- allow admins to overwrite default values easily,
- enable binary repository checkout based ready to run deployment (svn update, git pull),
- default to a working production configuration.
The recommended policy is to
- have a Configuration folder with all local config files
- as a folder in the Visual Studio project, then
- include Root.cs, which
- sets default values for all properties, then
- includes a Setup.cs, which
- sets a SetupName property, which
- is evaluated by a switch/case statement in Root.cs, which
- includes another config file with specific settings for Debug, Build, or Production, where
- Production.cs will not be in the source repository to protected sensitive data, and
- Setup.cs will not be in the source repository, because it will be different for each setup, and
- let the build process copy the entire folder to the bin output.
Root.cs:
namespace MyProgram.Configuration
{
class Root : MyProgram.MyConfig
{
public void Load()
{
// Initialize all settings
// This is a kind of config reference, which lists all settings with examples
// especially for admins who do not check the source code, but read/write config files
SomeProperty = "http://localhost:8080/";
OrAsMemberVariable = 42;
OrPlainOldCLRTypes = DateTime.Now;
DatabasePassword = "-empty-";
// Setup.cs just sets SetupName
Include("Setup.cs");
// Overwrite settings for the environment
switch (SetupName) {
case "Debug": Include("Debug.cs"); break;
case "Production": Include("Production.cs"); break;
}
}
}
}
Setup.cs (of a production/live system):
namespace MyProgram.Configuration
{
class Setup : MyProgram.MyConfig
{
public void Load()
{
//SetupName == "Debug") {
//SetupName == "Build") {
SetupName == "Production") {
}
}
}
Production.cs:
namespace MyProgram.Configuration
{
class Production : MyProgram.MyConfig
{
public void Load()
{
DatabasePassword = "jDf2o3Gzdt6iZk"; // Real production DB password
}
}
}
This is just a BCP (best current practice). It is not hard coded in the library. You can roll your own policy. After all it's plain C# and you write it. You could also:
- omit the Setup.cs and check the host name to find the proper configuration,
- have settings for all environments in one config file, except a few production secrets,
- implement settings as member variables of your config class with default values and have only the overrides in the config file.