API Documentation BepInEx.Configuration ConfigFile

Class ConfigFile

A helper class to handle persistent data. All public methods are thread-safe.

Inheritance
System.Object ConfigFile
Implements
System.Collections.Generic.IDictionary<ConfigDefinition, ConfigEntryBase> System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase>> System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase>> System.Collections.IEnumerable
Inherited Members
System.Object.ToString() System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.ReferenceEquals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone()
Namespace: BepInEx.Configuration
Assembly: BepInEx.Core.dll
Syntax
public class ConfigFile : IDictionary<ConfigDefinition, ConfigEntryBase>, ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>, IEnumerable<KeyValuePair<ConfigDefinition, ConfigEntryBase>>, IEnumerable

Constructors

ConfigFile(String, Boolean)

Improve this Doc View Source
Declaration
public ConfigFile(string configPath, bool saveOnInit)
Parameters
Type Name Description
System.String configPath
System.Boolean saveOnInit

ConfigFile(String, Boolean, BepInPlugin)

Improve this Doc View Source

Create a new config file at the specified config path.

Declaration
public ConfigFile(string configPath, bool saveOnInit, BepInPlugin ownerMetadata)
Parameters
Type Name Description
System.String configPath

Full path to a file that contains settings. The file will be created as needed.
System.Boolean saveOnInit

If the config file/directory doesn't exist, create it immediately.
BepInPlugin ownerMetadata

Information about the plugin that owns this setting file.

Properties

ConfigDefinitions

Improve this Doc View Source

Create a list with all config entries inside of this config file.

Declaration
[Obsolete("Use Keys instead")]
public ReadOnlyCollection<ConfigDefinition> ConfigDefinitions { get; }
Property Value
Type Description
System.Collections.ObjectModel.ReadOnlyCollection<ConfigDefinition>

ConfigFilePath

Improve this Doc View Source

Full path to the config file. The file might not exist until a setting is added and changed, or Save() is called.

Declaration
public string ConfigFilePath { get; }
Property Value
Type Description
System.String

CoreConfig

Improve this Doc View Source
Declaration
public static ConfigFile CoreConfig { get; }
Property Value
Type Description
ConfigFile

Count

Improve this Doc View Source
Declaration
public int Count { get; }
Property Value
Type Description
System.Int32

Entries

Improve this Doc View Source

All config entries inside

Declaration
protected Dictionary<ConfigDefinition, ConfigEntryBase> Entries { get; }
Property Value
Type Description
System.Collections.Generic.Dictionary<ConfigDefinition, ConfigEntryBase>

GenerateSettingDescriptions

Improve this Doc View Source

Generate user-readable comments for each of the settings in the saved .cfg file.

Declaration
public bool GenerateSettingDescriptions { get; set; }
Property Value
Type Description
System.Boolean

IsReadOnly

Improve this Doc View Source
Declaration
public bool IsReadOnly { get; }
Property Value
Type Description
System.Boolean

Item[ConfigDefinition]

Improve this Doc View Source
Declaration
public ConfigEntryBase this[ConfigDefinition key] { get; }
Parameters
Type Name Description
ConfigDefinition key
Property Value
Type Description
ConfigEntryBase

Item[String, String]

Improve this Doc View Source
Declaration
public ConfigEntryBase this[string section, string key] { get; }
Parameters
Type Name Description
System.String section
System.String key
Property Value
Type Description
ConfigEntryBase

Keys

Improve this Doc View Source

Returns the ConfigDefinitions that the ConfigFile contains.

Creates a new array when the property is accessed. Thread-safe.

Declaration
public ICollection<ConfigDefinition> Keys { get; }
Property Value
Type Description
System.Collections.Generic.ICollection<ConfigDefinition>

SaveOnConfigSet

Improve this Doc View Source

If enabled, writes the config to disk every time a value is set. If disabled, you have to manually use Save() or the changes will be lost!

Declaration
public bool SaveOnConfigSet { get; set; }
Property Value
Type Description
System.Boolean

Values

Improve this Doc View Source

Returns the ConfigEntryBase values that the ConfigFile contains.

Creates a new array when the property is accessed. Thread-safe.

Declaration
public ICollection<ConfigEntryBase> Values { get; }
Property Value
Type Description
System.Collections.Generic.ICollection<ConfigEntryBase>

Methods

Add(ConfigDefinition, ConfigEntryBase)

Improve this Doc View Source
Declaration
public void Add(ConfigDefinition key, ConfigEntryBase value)
Parameters
Type Name Description
ConfigDefinition key
ConfigEntryBase value

AddSetting<T>(ConfigDefinition, T, ConfigDescription)

Improve this Doc View Source

Create a new setting. The setting is saved to drive and loaded automatically. Each definition can be used to add only one setting, trying to add a second setting will throw an exception.

Declaration
[Obsolete("Use Bind instead")]
public ConfigEntry<T> AddSetting<T>(ConfigDefinition configDefinition, T defaultValue, ConfigDescription configDescription = null)
Parameters
Type Name Description
ConfigDefinition configDefinition

Section and Key of the setting.
T defaultValue

Value of the setting if the setting was not created yet.
ConfigDescription configDescription

Description of the setting shown to the user and other metadata.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

AddSetting<T>(String, String, T, ConfigDescription)

Improve this Doc View Source

Create a new setting. The setting is saved to drive and loaded automatically. Each section and key pair can be used to add only one setting, trying to add a second setting will throw an exception.

Declaration
[Obsolete("Use Bind instead")]
public ConfigEntry<T> AddSetting<T>(string section, string key, T defaultValue, ConfigDescription configDescription = null)
Parameters
Type Name Description
System.String section

Section/category/group of the setting. Settings are grouped by this.
System.String key

Name of the setting.
T defaultValue

Value of the setting if the setting was not created yet.
ConfigDescription configDescription

Description of the setting shown to the user and other metadata.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

AddSetting<T>(String, String, T, String)

Improve this Doc View Source

Create a new setting. The setting is saved to drive and loaded automatically. Each section and key pair can be used to add only one setting, trying to add a second setting will throw an exception.

Declaration
[Obsolete("Use Bind instead")]
public ConfigEntry<T> AddSetting<T>(string section, string key, T defaultValue, string description)
Parameters
Type Name Description
System.String section

Section/category/group of the setting. Settings are grouped by this.
System.String key

Name of the setting.
T defaultValue

Value of the setting if the setting was not created yet.
System.String description

Simple description of the setting shown to the user.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

Bind<T>(ConfigDefinition, T, ConfigDescription)

Improve this Doc View Source

Create a new setting. The setting is saved to drive and loaded automatically. Each definition can be used to add only one setting, trying to add a second setting will throw an exception.

Declaration
public ConfigEntry<T> Bind<T>(ConfigDefinition configDefinition, T defaultValue, ConfigDescription configDescription = null)
Parameters
Type Name Description
ConfigDefinition configDefinition

Section and Key of the setting.
T defaultValue

Value of the setting if the setting was not created yet.
ConfigDescription configDescription

Description of the setting shown to the user and other metadata.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

Bind<T>(String, String, T, ConfigDescription)

Improve this Doc View Source

Create a new setting. The setting is saved to drive and loaded automatically. Each section and key pair can be used to add only one setting, trying to add a second setting will throw an exception.

Declaration
public ConfigEntry<T> Bind<T>(string section, string key, T defaultValue, ConfigDescription configDescription = null)
Parameters
Type Name Description
System.String section

Section/category/group of the setting. Settings are grouped by this.
System.String key

Name of the setting.
T defaultValue

Value of the setting if the setting was not created yet.
ConfigDescription configDescription

Description of the setting shown to the user and other metadata.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

Bind<T>(String, String, T, String)

Improve this Doc View Source

Create a new setting. The setting is saved to drive and loaded automatically. Each section and key pair can be used to add only one setting, trying to add a second setting will throw an exception.

Declaration
public ConfigEntry<T> Bind<T>(string section, string key, T defaultValue, string description)
Parameters
Type Name Description
System.String section

Section/category/group of the setting. Settings are grouped by this.
System.String key

Name of the setting.
T defaultValue

Value of the setting if the setting was not created yet.
System.String description

Simple description of the setting shown to the user.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

Clear()

Improve this Doc View Source
Declaration
public void Clear()

Contains(KeyValuePair<ConfigDefinition, ConfigEntryBase>)

Improve this Doc View Source
Declaration
public bool Contains(KeyValuePair<ConfigDefinition, ConfigEntryBase> item)
Parameters
Type Name Description
System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase> item
Returns
Type Description
System.Boolean

ContainsKey(ConfigDefinition)

Improve this Doc View Source
Declaration
public bool ContainsKey(ConfigDefinition key)
Parameters
Type Name Description
ConfigDefinition key
Returns
Type Description
System.Boolean

GetConfigEntries()

Improve this Doc View Source

Create an array with all config entries inside of this config file. Should be only used for metadata purposes. If you want to access and modify an existing setting then use AddSetting<T>(ConfigDefinition, T, ConfigDescription) instead with no description.

Declaration
[Obsolete("Use Values instead")]
public ConfigEntryBase[] GetConfigEntries()
Returns
Type Description
ConfigEntryBase[]

GetEnumerator()

Improve this Doc View Source
Declaration
public IEnumerator<KeyValuePair<ConfigDefinition, ConfigEntryBase>> GetEnumerator()
Returns
Type Description
System.Collections.Generic.IEnumerator<System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase>>

GetSetting<T>(ConfigDefinition)

Improve this Doc View Source

Access one of the existing settings. If the setting has not been added yet, null is returned. If the setting exists but has a different type than T, an exception is thrown. New settings should be added with AddSetting<T>(ConfigDefinition, T, ConfigDescription).

Declaration
[Obsolete("Use ConfigFile[key] or TryGetEntry instead")]
public ConfigEntry<T> GetSetting<T>(ConfigDefinition configDefinition)
Parameters
Type Name Description
ConfigDefinition configDefinition

Section and Key of the setting.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

GetSetting<T>(String, String)

Improve this Doc View Source

Access one of the existing settings. If the setting has not been added yet, null is returned. If the setting exists but has a different type than T, an exception is thrown. New settings should be added with AddSetting<T>(ConfigDefinition, T, ConfigDescription).

Declaration
[Obsolete("Use ConfigFile[key] or TryGetEntry instead")]
public ConfigEntry<T> GetSetting<T>(string section, string key)
Parameters
Type Name Description
System.String section

Section/category/group of the setting. Settings are grouped by this.
System.String key

Name of the setting.
Returns
Type Description
ConfigEntry<T>
Type Parameters
Name Description
T

Type of the value contained in this setting.

Reload()

Improve this Doc View Source

Reloads the config from disk. Unsaved changes are lost.

Declaration
public void Reload()

Remove(ConfigDefinition)

Improve this Doc View Source
Declaration
public bool Remove(ConfigDefinition key)
Parameters
Type Name Description
ConfigDefinition key
Returns
Type Description
System.Boolean

Save()

Improve this Doc View Source

Writes the config to disk.

Declaration
public void Save()

TryGetEntry<T>(ConfigDefinition, out ConfigEntry<T>)

Improve this Doc View Source

Access one of the existing settings. If the setting has not been added yet, false is returned. Otherwise, true. If the setting exists but has a different type than T, an exception is thrown. New settings should be added with Bind<T>(ConfigDefinition, T, ConfigDescription).

Declaration
public bool TryGetEntry<T>(ConfigDefinition configDefinition, out ConfigEntry<T> entry)
Parameters
Type Name Description
ConfigDefinition configDefinition

Section and Key of the setting.
ConfigEntry<T> entry

The ConfigEntry value to return.
Returns
Type Description
System.Boolean
Type Parameters
Name Description
T

Type of the value contained in this setting.

TryGetEntry<T>(String, String, out ConfigEntry<T>)

Improve this Doc View Source

Access one of the existing settings. If the setting has not been added yet, null is returned. If the setting exists but has a different type than T, an exception is thrown. New settings should be added with Bind<T>(ConfigDefinition, T, ConfigDescription).

Declaration
public bool TryGetEntry<T>(string section, string key, out ConfigEntry<T> entry)
Parameters
Type Name Description
System.String section

Section/category/group of the setting. Settings are grouped by this.
System.String key

Name of the setting.
ConfigEntry<T> entry

The ConfigEntry value to return.
Returns
Type Description
System.Boolean
Type Parameters
Name Description
T

Type of the value contained in this setting.

Wrap<T>(ConfigDefinition, T)

Improve this Doc View Source

Access a setting. Use Bind instead.

Declaration
[Obsolete("Use Bind instead")]
public ConfigWrapper<T> Wrap<T>(ConfigDefinition configDefinition, T defaultValue = null)
Parameters
Type Name Description
ConfigDefinition configDefinition
T defaultValue
Returns
Type Description
ConfigWrapper<T>
Type Parameters
Name Description
T

Wrap<T>(String, String, String, T)

Improve this Doc View Source

Access a setting. Use Bind instead.

Declaration
[Obsolete("Use Bind instead")]
public ConfigWrapper<T> Wrap<T>(string section, string key, string description = null, T defaultValue = null)
Parameters
Type Name Description
System.String section
System.String key
System.String description
T defaultValue
Returns
Type Description
ConfigWrapper<T>
Type Parameters
Name Description
T

Events

ConfigReloaded

Improve this Doc View Source

An event that is fired every time the config is reloaded.

Declaration
public event EventHandler ConfigReloaded
Event Type
Type Description
System.EventHandler

SettingChanged

Improve this Doc View Source

Fired when one of the settings is changed.

Declaration
public event EventHandler<SettingChangedEventArgs> SettingChanged
Event Type
Type Description
System.EventHandler<SettingChangedEventArgs>

Explicit Interface Implementations

ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>.Add(KeyValuePair<ConfigDefinition, ConfigEntryBase>)

Improve this Doc View Source
Declaration
void ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>.Add(KeyValuePair<ConfigDefinition, ConfigEntryBase> item)
Parameters
Type Name Description
System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase> item

ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>.CopyTo(KeyValuePair<ConfigDefinition, ConfigEntryBase>[], Int32)

Improve this Doc View Source
Declaration
void ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>.CopyTo(KeyValuePair<ConfigDefinition, ConfigEntryBase>[] array, int arrayIndex)
Parameters
Type Name Description
System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase>[] array
System.Int32 arrayIndex

ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>.Remove(KeyValuePair<ConfigDefinition, ConfigEntryBase>)

Improve this Doc View Source
Declaration
bool ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>.Remove(KeyValuePair<ConfigDefinition, ConfigEntryBase> item)
Parameters
Type Name Description
System.Collections.Generic.KeyValuePair<ConfigDefinition, ConfigEntryBase> item
Returns
Type Description
System.Boolean

IDictionary<ConfigDefinition, ConfigEntryBase>.Item[ConfigDefinition]

Improve this Doc View Source
Declaration
ConfigEntryBase IDictionary<ConfigDefinition, ConfigEntryBase>.this[ConfigDefinition key] { get; set; }
Parameters
Type Name Description
ConfigDefinition key
Returns
Type Description
ConfigEntryBase

IDictionary<ConfigDefinition, ConfigEntryBase>.TryGetValue(ConfigDefinition, out ConfigEntryBase)

Improve this Doc View Source
Declaration
bool IDictionary<ConfigDefinition, ConfigEntryBase>.TryGetValue(ConfigDefinition key, out ConfigEntryBase value)
Parameters
Type Name Description
ConfigDefinition key
ConfigEntryBase value
Returns
Type Description
System.Boolean

IEnumerable.GetEnumerator()

Improve this Doc View Source
Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type Description
System.Collections.IEnumerator

Implements

System.Collections.Generic.IDictionary<TKey, TValue>
System.Collections.Generic.ICollection<T>
System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable

Extension Methods

ThreadingExtensions.RunParallel<TIn, TOut>(IEnumerable<TIn>, Func<TIn, TOut>, Int32)