This post originated from an RSS feed registered with .NET Buzz
by Jonathan Crossland.
Original Post: Documenting is more Dynamic than you think
Feed Title: Jonathan Crossland Weblog
Feed URL: http://www.jonathancrossland.com/syndication.axd
Feed Description: Design, Frameworks, Patterns and Idioms
When we create objects and use config settings to ascertain context and things of that nature, it makes it harder to know what settings there are later on.
This is a significant fact across all things within software.
Don't be scared to create small utilities and tools to aid your development. (As long as it does not affect your timelines).
Have you never got to a point in a project when you are wondering why something is not working and it ends up being a config setting?
Here is a simple solution for simple key/value settings
Create an Attribute to house the "documentation".
[code:c#]
[AttributeUsage(AttributeTargets.Class)]
public sealed class ConfigurationRequiredAttribute : Attribute
{
private string[] _ConfiguratonNames;
public ConfigurationRequiredAttribute(params string[] configNames)
{
_ConfiguratonNames = configNames;
}
/// <summary>
///
/// </summary>
public string[] ConfiguratonNames
{
get
{
return _ConfiguratonNames;
}
set
{
_ConfiguratonNames = value;
}
}
}
[/code]
Next, mark your classes that use simple key/value pair config settings.
[code:c#]
[ConfigurationRequiredAttribute("CopyDestinationDirectory", "MyKey2")]
public class CopyDirectory : IAction
{}
[/code]
Then write yourself a CustomAttribute tool. Simply put, use reflection on all your classes, look for the Attribute and declare what the names of config settings you need across the app.
[code:c#]
public static class StaticValidator
{
private static bool ConfigKeyExists(string settingName, Configuration config)
{
AppSettingsSection appSettings = config.AppSettings;
if (appSettings != null)
{
if (appSettings.Settings != null)
{
if (appSettings.Settings.Count > 0)
{
KeyValueConfigurationElement setting =
appSettings.Settings[settingName];
if (setting != null)
{
return true;
}
}
}
}
return false;
}
public static bool HasConfigSettings(object toValidate, Configuration config)
{
//Check to make sure the object parameter is not null -
//if it is, throw an exception.
if (toValidate == null)
{
throw
new ArgumentNullException(
"toValidate", "Object not set");
}
bool ret = false;
ConfigurationRequiredAttribute[] required = null;
//Get all the property info for the properties on the object to validate
//that are instance and public properties.
required = (ConfigurationRequiredAttribute[])
toValidate.GetType().GetCustomAttributes(
typeof(ConfigurationRequiredAttribute), true);
//if any were found then...
if (required.Length > 0)
{
//Enumerate around the requiredTypes attribute that were found.
foreach (ConfigurationRequiredAttribute requiredType in required)
{
//Enumerate through all of the types that are required in the
// requiredType attribute.
foreach (string key in requiredType.ConfiguratonNames)
{
if (!ConfigKeyExists(key, config))
{
throw new Exception("The AppSettings.Key: " +
key + " does not exist");
}
else
ret = true;
}
return ret;
}
}
return ret;
}
}
Documentation is one thing, but dynamic documentation, or Code MetaData is required for us to move ahead in understanding code from the outside.
This example is a simple one, but hopefully demonstrates the importance of MetaData on code, which can lead to better inspection tools and more robustness.
Previous Topic
