Usage Documentation

May 14, 2010 at 4:16 AM

I may just be being dense but did I miss an usage example on the site or in the docs?  I haven't really had much time to truly dive in yet but so far I have only seen the code that makes up the library so far.  Maybe after looking at it longer that will be enough but I figured I'd ask now just in case.

Thanks ahead of time for this.  For someone like me (inexperienced, solo programmer) these are God sends and my best learning method so far, outside of actually writing code.

 

Coordinator
May 14, 2010 at 3:34 PM

Actually I've yet to write usage documentation (First thing to know is I'm lazy and second thing to know is I'm actually writing another library that uses it that I was going to use as an example). But I'm bored this morning so I'll post one right here. Anyway there are two main classes that I need to go over, the Manager and the Config class. The Manager actually handles creation, registering, and grabbing individual config objects for you. The Config class is a base class that is used by your own config classes (it handles encryption, serialization, etc.). Anyway, to get started the first thing you need to do is create your own config class. This class actually holds your configuration data. This would be a simple example:

    [ConfigAttribute(Name="Example")]
    public class ExampleConfig:Gestalt.Config<ExampleConfig>
    {
        protected override string ConfigFileLocation
        {
            get
            {
                return @"C:\Config\MyConfig.cfg";
            }
        }

        protected override string EncryptionPassword
        {
            get
            {
                return "MyPassword";
            }
        }

        public virtual string Property1 { get; set; }
        public virtual int Property2 { get; set; }
    }

The first thing to note is it has a ConfigAttribute attribute. This names the config object so the manager knows what object to pull. The second thing is the Gestalt.Config class. It takes the class that inherits from it as a generic so that it knows what to serialize. Although you can actually do something like this:

    public class ExampleConfig<T>:Gestalt.Config<T>
    {
        protected override string ConfigFileLocation
        {
            get
            {
                return @"C:\Config\MyConfig.cfg";
            }
        }

        protected override string EncryptionPassword
        {
            get
            {
                return "MyPassword";
            }
        }

        public virtual string Property1 { get; set; }
        public virtual int Property2 { get; set; }
    }

[ConfigAttribute(Name="Example")]
public class ExampleConfig2:ExampleConfig<ExampleConfig2>
{
        protected virtual string Property3{get;set;}
}

And it will recognize Property3 as well as Property1 and Property2. Thus you can set up a default config class for a library or something and let users inherit from it. Anyway, there are two properties in the base class that can be overridden. The first is ConfigFileLocation. This determines the location that the system will save/load the config file to. The second one is EncryptionPassword. If this is overridden and told to return something other than an empty string, all entries in the config file (when saved) will be encrypted using 256 AES encryption using the password you set.

Once you've set up the config class, the next thing you need to do is set up the Manager class. If we were to use the ExampleConfig class from above we can simply do the following:

Gestalt.Manager.Instance.RegisterConfigFile(typeof(ExampleConfig).Assembly);

This creates the manager instance (it's a singleton) and registers all config classes inside the same assembly as the ExampleConfig class and if it finds the config files, loads the data for each config class (if it doesn't find one it just leaves the defaults). We can also register them individually or even DLLs that have yet to be loaded (only useful in dynamic loading situations). Once that is done you're ready to use it:

Gestalt.Manager.Instance.GetConfigFile<ExampleConfig>("Example").Property1="Property Value";
Gestalt.Manager.Instance.GetConfigFile<ExampleConfig>("Example").Save();

In the code above it calls GetConfigFile, sending in the name of the config file and the config type as a generic. The reason you have to send in the name are in cases where you register a config class individually as you must give it a name then (allowing you to have the same class type but just different names so you can pull each individually). The function returns a strongly typed (based off of the generic that you pass in) object back, so we can access the properties directly. The only other function of note is Save. It simply encrypts each property (if need be) and serializes it to an XML file (if you set a location). But that's all you need to do, if you run into issues just post and I'll try to help you out.