Skip to content
logo

SharpConfig

SharpConfig is an easy to use cfg/ini configuration library for .NET.

You can use SharpConfig to read, modify and save configuration files and streams, in either text or binary format.

Image Image

Installation

Choose one of:

  • .NET CLI: > dotnet add package sharpconfig
  • NuGet Package Manager: > NuGet\Install-Package sharpconfig
  • Latest Source Code (.zip)

Examples

# An example configuration:

[General]
# a comment
SomeString = Hello World!
SomeInteger = 10 # an inline comment
SomeFloat = 20.05
SomeBoolean = true
SomeArray = { 1, 2, 3 }
Day = Monday

[Person]
Name = Peter
Age = 50

To read these values, your C# code would look like:

var config = Configuration.LoadFromFile("sample.cfg");
var section = config["General"];

string someString = section["SomeString"].StringValue;
int someInteger = section["SomeInteger"].IntValue;
float someFloat = section["SomeFloat"].FloatValue;
bool someBool = section["SomeBoolean"].BoolValue;
int[] someIntArray = section["SomeArray"].IntValueArray;
string[] someStringArray = section["SomeArray"].StringValueArray;
DayOfWeek day = section["Day"].GetValue<DayOfWeek>();

// Entire user-defined objects can be created from sections and vice versa.
var person = config["Person"].ToObject<Person>();
// ...

Loading

1
2
3
4
5
var cfg1 = Configuration.LoadFromFile("myConfig.cfg");        // Load from a text-based file.
var cfg2 = Configuration.LoadFromStream(myStream);            // Load from a text-based stream.
var cfg3 = Configuration.LoadFromString(myString);            // Load from text (source code).
var cfg4 = Configuration.LoadFromBinaryFile("myConfig.cfg");  // Load from a binary file.
var cfg5 = Configuration.LoadFromBinaryStream(myStream);      // Load from a binary stream.

Iterating

1
2
3
4
5
6
7
8
9
// A configuration conforms to IEnumerable and therefore supports normal iteration.

foreach (var section in myConfig)
{
    foreach (var setting in section)
    {
        // ...
    }
}

Creating a configuration in memory

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// Create the configuration.
var myConfig = new Configuration();

// Set some values.
// This will automatically create the sections and settings.
myConfig["Video"]["Width"].IntValue = 1920;
myConfig["Video"]["Height"].IntValue = 1080;

// Set an array value.
myConfig["Video"]["Formats"].StringValueArray = new[] { "RGB32", "RGBA32" };

// Get the values just to test.
int width = myConfig["Video"]["Width"].IntValue;
int height = myConfig["Video"]["Height"].IntValue;
string[] formats = myConfig["Video"]["Formats"].StringValueArray;

// ...

Saving

1
2
3
4
myConfig.SaveToFile("myConfig.cfg");       // Save to a text-based file.
myConfig.SaveToStream(myStream);           // Save to a text-based stream.
myConfig.SaveToBinaryFile("myConfig.cfg"); // Save to a binary file.
myConfig.SaveToBinaryStream(myStream);     // Save to a binary stream.

Options

Sometimes a project has special configuration files or other needs, for example ignoring all comments in a file.

To allow for greater flexibility, SharpConfig's behavior is modifiable using static properties of the Configuration class.

The following properties are available:

Option Type Description
CultureInfo CultureInfo Gets or sets the CultureInfo that is used for value conversion in SharpConfig.
The default value is CultureInfo.InvariantCulture.
ValidCommentChars char[] Gets the array that contains all valid comment delimiting characters.
The default value is { '#', ';' }
PreferredCommentChar char Gets or sets the preferred comment char when saving configurations.
The default value is '#'.
ArrayElementSeparator char Gets or sets the array element separator character for settings.
The default value is ','.
Remember that after you change this value while Setting instances exist, to expect their ArraySize and other array-related values to return different values.
IgnoreInlineComments bool Gets or sets a value indicating whether inline comments should be ignored when parsing a configuration.
IgnorePreComments bool Gets or sets a value indicating whether pre-comments should be ignored when parsing a configuration.
SpaceBetweenEquals bool Gets or sets a value indicating whether space between equals should be added when saving a configuration.
OutputRawStringLiterals bool Gets or sets a value indicating whether string values are written without quotes, but including everything in between.
For example, a setting MySetting=" Example value" would be written to a file as MySetting= Example value.

Ignoring properties, fields and types

Suppose you have the following class:

1
2
3
4
5
6
7
8
class SomeClass
{
    public string Name { get; set; }
    public int Age { get; set; }

    [SharpConfig.Ignore]
    public int SomeInt { get; set; }
}

SharpConfig will now ignore the SomeInt property when creating sections from objects of type SomeClass and vice versa. Now suppose you have a type in your project that should always be ignored. You would have to mark every property that returns this type with a [SharpConfig.Ignore] attribute. An easier solution is to just apply the [SharpConfig.Ignore] attribute to the type.

Example
1
2
3
4
5
[SharpConfig.Ignore]
class ThisTypeShouldAlwaysBeIgnored
{
    // ...
}

instead of:

Redundant attributes
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[SharpConfig.Ignore]
class SomeClass
{
  [SharpConfig.Ignore]
  public ThisTypeShouldAlwaysBeIgnored T1 { get; set; }

  [SharpConfig.Ignore]
  public ThisTypeShouldAlwaysBeIgnored T2 { get; set; }

  [SharpConfig.Ignore]
  public ThisTypeShouldAlwaysBeIgnored T3 { get; set; }
}

Info

This ignoring mechanism works the same way for public fields.

Adding custom object converters

There may be cases where you want to implement conversion rules for a custom type, with specific requirements. This is easy and involves two steps, which are illustrated using the Person example:

1
2
3
4
5
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
}

Step 1: Create a custom converter class that derives from SharpConfig.TypeStringConverter<T>.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
using SharpConfig;

public class PersonStringConverter : TypeStringConverter<Person>
{
    // This method is responsible for converting a Person object to a string.
    public override string ConvertToString(object value)
    {
      var person = (Person)value;
      return string.Format("[{0};{1}]", person.Name, person.Age);
    }

    // This method is responsible for converting a string to a Person object.
    public override object ConvertFromString(string value, Type hint)
    {
      var split = value.Trim('[', ']').Split(';');

      var person = new Person();
      person.Name = split[0];
      person.Age = int.Parse(split[1]);

      return person;
    }
}

Step 2: Register the PersonStringConverter (anywhere you like):

1
2
3
using SharpConfig;

Configuration.RegisterTypeStringConverter(new PersonStringConverter());

That's it!

Whenever a Person object is used on a Setting (via GetValue() and SetValue()), your converter is selected to take care of the conversion. This also automatically works with SetValue() for arrays and GetValueArray().