• Marked the Comment struct as obsolete, because it has been replaced by System.String. The Comment struct will be removed with the next release.
• Removed ' (apostrophe) from the list of valid comment chars.
• Fixed a bug that prevented enums from being converted by the TypeStringConverter subsystem (issue #51).
• Added TypeConverter functionality to the fallback TypeStringConverter.
• Added "n" and "y" values to BoolStringConverter, meaning that y and n are now accepted as setting values for true and false, respectively.

Fixed a bug that caused pre-comments to only be split by Environment.NewLine instead of \r\n and \n (issue #45).

CONTAINS API BREAKING CHANGES

This release focuses on a slightly simplified API, better documentation and a few bug fixes. Due to API changes, upgrading from a previous version may require code adjustment on your part. Loading existing configuration files however is still compatible and requires no changes.

Features

• Improved documentation, especially regarding what exceptions are thrown.

• Removed the Comment struct. Every occurrence of Comment has been replaced by string.

  Config elements now only have a single pre-comment instead of a List<Comment>.

  • This simplifies the handling of comments and also allows a config element to have multi-line comments. Example:

# Comment Line 1
# Comment Line 2
[MySection]

When such a configuration is loaded, MySection's PreComment property will return the value "Comment Line 1\nComment Line 2". Such a value can also be set, respectively.

• Added a Configuration.Contains overload that takes a section and setting name as parameters.
  • Example: if (cfg.Contains("MySection") && cfg["MySection"].Contains("MySetting"))
  • This can now be written as: if (cfg.Contains("MySection", "MySetting"))
• Removed the setter of Configuration.ValidCommentChars. The only valid comment chars are # and ;.
• Added the static Configuration.PreferredCommentChar property which dictates what char to use for comments when saving configurations. This may only be one of the valid comment chars.
• Improved parsing of array values. It is now possible to declare braced and quoted elements. Example:

MySetting1 = { {1,2}, {3,4} }     # Will be parsed as two elements {1,2} and {3,4}.
MySetting2 = { "1,2", "3,4" }     # Will also be parsed as two elements "1,2" and "3,4".
MySetting3 = { "{1,2}", "{3,4}" } # Will also be parsed as two elements "{1,2}" and "{3,4}".

• Fixed a bug that caused string values not to be trimmed when applying them to settings manually.

Added Exceptions

• Configuration.Contains(Section) now throws an ArgumentNullException if section is null.
• Configuration.Contains(string) now throws an ArgumentNullException if sectionName is null.
• Section.Contains(Setting) now throws an ArgumentNullException if setting is null.
• Section.Contains(string) now throws an ArgumentNullException if settingName is null.

• Better exception messages in GetValueArray().
• Fixed a potential bug in (de)serialization that caused the stream to always close after the operation.
• Removed all methods that were marked as obsolete.
• Changed the following methods of the Section class to be non-generic (@dittodhole):
  • FromObject
  • GetValuesFrom
  • SetValuesTo
• Added a non-generic version of Section.ToObject(). (@dittodhole)
• Fixed a bug in Setting.SetValue(object) that caused a NullReferenceException to be thrown when a null object was passed in. (@dittodhole)
  • Calling Setting.SetValue() with a null object is valid.
• Fixed a bug in Setting.SetValue(object[]) that caused ',' to be used as the element separator, instead of Configuration.ArrayElementSeparator. (issue #38)
• Configuration.Remove() and Section.Remove() are now non-throwing when trying to remove a non-existent element. Instead, they return a bool that indicates whether the specified element was removed. (issue #39)
• Removed the generic overloads of Setting.SetValue(), as they provided no benefit.
• Removed Setting.SetValue(object[]), as Setting.SetValue(object) is the same and is almost always selected in overload resolution.

• Added a new property ArrayElementSeparator to the Configuration class. (issue #30)
  • This allows you to specify any other char as an array separator than the default ','.
• Changed the visibility of all stock converters from public to internal.
  • These shouldn't have been public in the first place.
• Improved the documentation.

This release features major bug fixes, stability and performance improvements. NOTE: this release removes all methods that were marked as obsolete in the previous version (1.5.6).

• Added a caching mechanism for array size calculation in Setting.
  • when a value was set on a setting, it checked whether it's an array. This check took some time, as the array size was determined (parsed) from the string value. This calculation is now deferred until an array value is set using a dirty flag.
• Replaced the use of Convert.ChangeType by a custom type/string conversion mechanism that's not only faster, but allows the user to intercept the setting value conversion routine. Because of this:
  • A new interface ITypeStringConverter and class TypeStringConverter have been added.
  • The static methods RegisterTypeStringConverter() and DeregisterTypeStringConverter() have been added to the Configuration class.
  • See How to add custom object string conversions
• Renamed the following methods in the Section class:
  • CreateObject() -> ToObject()
  • MapFrom() -> GetValuesFrom()
  • MapTo() -> SetValuesTo()
  • The former methods still exist, but have been marked as obsolete and will be removed in the next release.
• Added a type constraint "where T : new()" on Section.CreateObject() / Section.ToObject()
  • this means that the specified type must be default-constructible
• Fixed a bug in Section.MapFrom()/Section.GetValuesFrom() that prevented readable properties/fields from being read from.
• Added array value properties to the Setting class:
  • StringValueArray, IntValueArray, FloatValueArray, DoubleValueArray, BoolValueArray, DateTimeValueArray
• Fixed a bug in section/object mapping that caused an exception to be thrown for array properties/fields.
• Fixed a bug in setting value conversion that ignored arrays
  • for example, storing an int[] in a setting using section/object mapping resulted in the array being stored as a string "Int32[]".

Fixed a bug that caused an ArgumentNullException to be thrown when loading empty configurations. (issue #29)

• Removed properties IgnoreDuplicateSections and IgnoreDuplicateSettings from the Configuration class.
  • SharpConfig now always allows sections and settings that have the same name.
• Added corresponding methods for handling duplicate sections and settings:
  • Configuration.GetSectionsNamed(string)
  • Section.GetSettingsNamed(string)
  • Configuration.RemoveAllNamed(string)
  • Section.RemoveAllNamed(string)

• Improved configuration serialization.
  • Pre-comments and sections/settings were parted by only a line-feed (\n), rather than CR/LF (\r\n) on Windows. This is fixed now, by inserting Environment.NewLine. (issue #24)
  • Setting assignments now have the format of {name} = {value}, instead of {name}={value}. SharpConfig is still able to read configurations that have the old format.
  • When saving text-based configuration files, the files will now have a single new-line at the end, instead of two. The extra new-line at the end is necessary for compatibility with other programs that parse configuration files.
• Added a constructor overload to Comment which accepts only the comment string. The symbol of the comment will be the first symbol that is in Configuration.ValidCommentsChars at the time of creation.
• Improved the documentation.

• Removed the setters of the accessor properties in Configuration and Section. (issue #19)
• Removed the Name setter of ConfigurationElement (and thus of Section and Setting), as config elements should have an immutable name.
• Removed the DateTime constructor overload of Setting, as it was unnecessary. The object overload offers the same functionality, so this is a non-code-breaking change.
• Fixed a bug in the Setting class that caused an exception when trying to obtain the setting value as a bool. (issue #21)
• Improved the documentation.