Basic example

This tutorial will show you how to create a configuration file, store a setting, and read it back.

Go back

First Steps

Get a first look at using ConfigAdapter.

The first thing to do is decide which file format you need, and import the corresponding package into your project. All officially supported formats have the same capabilities and will behave the same way, so the difference is mostly cosmetic.

To open or create a configuration file, use the .From() method on one of the Config classes, like so: 

// Use XML file
var config = XmlConfig.From("settings.xml");

// Use INI file
var config = IniConfig.From("settings.ini");

// Use HJSON file
var config = HJsonConfig.From("settings.hjson");

Note that specifying the file extension is required.

This method call will open the file if it exists. Otherwise, it will create a new empty file.

A setting worth saving

Let's see now hot to save data to the config file.

To write a setting to a config instance, use the .Write() method. This method takes three parameters:

  • Key: Used to identify the setting. It shouldn't have spaces or special characters, nor start with a number.
  • Value: The content of the setting. This text can use spaces and most special characters.
  • Comment: An optional parameter that will add a comment to the setting. This comment is ignored by ConfigAdapter, and is only useful if the file is going to be read by a human.

The Write method also has a generic overload that allows to write struct values directly, such as primitive types. 

var config; // Assume initialized

// Write a string setting
config.Write("MySetting", "Hello, World!");

// Include a comment
config.Write("Continent", "Europe", "This contains a continent");

// Write primitive types
config.Write<int>("Age", 21);
config.Write<bool>("Validated", true);

// With type inference, the generic type can be skipped
config.Write("Age", 21);
config.Write("Validated", true);

If you attempt to write a setting with a key that corresponds to an already existing setting in the file, the new value will overwrite the existing one.

Illegal characters

Please avoid using these characters when writing to a settings file.

Depending on the file format being used, some of these characters are part of the syntax. For maximum portability, try to avoid using any of them, no matter what type of file you're writing to:

  • Colon (:)
  • Semicolon (;)
  • Angle brackets (< >)
  • Number sign (#)

Reading is important

Now let's read the saved settings.

To read an existing setting, use the .Read() method. It takes a setting key, and returns the value if it exists. Otherwise, it returns an empty string.

As with the Write method, Read also has a generic overload, that will convert the string value to the specified type. However, note that this overload will throw an exception if the setting is missing or has an incompatible type, so it's inherently less safe than the regular overload. 

var config; // Assume initialized

// Read a string value
string value = config.Read("Message");

// Read a primitive type. Watch the exceptions!
int age = config.Read<int>("UserAge");
double rate = config.Read<double>("DollarConversionRate");

Organize settings

It can be useful to categorize settings within a file.

ConfigAdapter supports organizing settings in categories. Each file format will implement categories in a unique way. Note that categories cannot be nested.

In addition, setting keys can be repeated, provided that they are in different categories.

Category support in ConfigAdapter is straightforward. Simply prepend the category name to the setting key separated by a colon, like this: 

var config; // Assume initialized

// Write categorized settings
config.Write("User1:Name", "Foo");
config.Write("User2:Name", "Bar"); // Different settings with the same key

// Read categorized settings
var name1 = config.Read("User1:Name"); // name1 is Foo
var name2 = config.Read("User2:Name"); // name2 is Bar

You're all done!

Now you should be able to use ConfigAdapter to persist settings in your apps.

Go back