What is a configuration Tool

For the most part traditional configuration tools let you specify what you want the configuration to be and let the tool take care of getting the system from the state it is in to the state you want it to be in. FCE in this respect is no different.

What happens when you run FCE:

When you run FCE in either Apply or Test the following happens:

• Execution the config.csx file and build a graph of how you want the system configured.
• All the gathers defined in the config.csx file will run and store their data into the data store.
• The contents of any settings file passed in will be copied into the data store.
• FCE will then determine the order that config items will run based on their priorities.
• Configuration items will then run in that order. If test mode it will test all configuration items and report the status.
• In apply mode it will run the apply method on anything that isn't tested to be configured.
• The script will stop and return a 3010 on any reboot or 500 in the event a item wasn't configured.

Config Item

A configuration item is a deceleration of what you intend on how you want the system configured. In FCE you do this with the Config method.

Config("myconfigitem);

Each configuration item must have a unique name. You can name them whatever you like however I recommend naming them something descriptive so anyone who reads the script will understand what your intent is.

Then next thing a configuration item needs is a resource which tells the configuration item what you want to do. There are plenty of built in resources like File, Directory, etc.

You define a resource by using the Resource fluent method like the following:

Config("myconfig")
    .Resource("File");

Finally you have the ability to give data to the resource by using properties and rows. You can think of properties as setting individual settings on a config item and rows let you set properties for multiple items (i.e the registry resource lets you specify rows if you want to list multiple registry values in one go).

//Will delete c:\\myfile.txt if it exists.
Config("myconfig")
    .Resource("File")
    .Property("path", "c:\\myfile.txt")
    .Property("ensure", "absent");

Another useful concept is dependancy. You can specify another configuration item you want this item to be dependant on, what this does is makes FCE run the other configuration item before this one.

A key thing to remember is if a Dependant item has a criteria that returns false the dependant item will run anyway.

Config("myconfig")
    .Resource("File")
    .DependsOn("myotherconfig")
    .Property("path", "c:\\myfile.txt")
    .Property("ensure", "absent");

The next concept that you need to know about config items are Criteria. These let you specify a condition in which the ConfigItem will run or not. These are useful if combined with Gatherers as you can check for conditions in which you do or don't want the configuration item to run.

Config("myconfig")
    .Criteria(data => data.Read("OS").Get("Class") == "windows")
    .Resource("File")
    .Property("path", "c:\\myfile.txt")
    .Property("ensure", "absent");

Finally there are dynamic properties. These let you call a lambda function to set values on a config item. The reason you would want to do this is so you can use values from the data store that could have been collected by a Gatherer.

Config("myconfig")
    .Criteria(data => data.Read("OS").Get("Class") == "windows")
    .Resource("File")
    .Property("path", "c:\\myfile.txt")
    .Property("ensure", "absent")
    .Dynamic((data, cfg) => cfg.Properties.Set("MyProp", data.Read("OS").Get("Class"));

Resource

Resources are the things that do the actual work. They are created and stored in NuGet packages which can be referenced from your config.csx script.

You can get documentation on what resources are available and what properties they have here

Gathers

Gathers are similar to resources except their job is to gather information from the system and store it in the data store to be referenced by config items or written to a gather.json.

You can specify which gathers you want to run by using the Gather method.

Gather("OS");

You can also specify properties on some gathers if you want to control the scope of what they gather.

Gather("OS")
    .Property("Test", "Example");

Data Store

You might have heard this term used above. The data store is simply a series of hash tables that FCE uses to store information gathered from the system. Resources also use it to persist data between runs if they need to (like the restart resource).

Not all data stored in the data store is stored to disk, when resources and gathers deal with the data store they need to specify if this data is stored. When the tool is run in gather mode however all data is persisted to the gather.json file.