ConfigFile Class
Definition
Section titled “Definition”A helper class to handle persistent data. All public methods are thread-safe.
public class ConfigFile : IDictionary<ConfigDefinition, ConfigEntryBase>, ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>, IEnumerable<KeyValuePair<ConfigDefinition, ConfigEntryBase>>, IEnumerableInheritance object
Implements IDictionary<ConfigDefinition, ConfigEntryBase>, ICollection<KeyValuePair<ConfigDefinition, ConfigEntryBase>>, IEnumerable<KeyValuePair<ConfigDefinition, ConfigEntryBase>>, IEnumerable
Constructors
Section titled “Constructors”ConfigFile(string, bool)
Section titled “ConfigFile(string, bool)”Create a new config file at the specified config path.
public ConfigFile(string configPath, bool saveOnInit)Parameters
Section titled “Parameters”configPath string
Full path to a file that contains settings. The file will be created as needed.
saveOnInit bool
If the config file/directory doesn’t exist, create it immediately.
ConfigFile(string, bool, BepInPlugin)
Section titled “ConfigFile(string, bool, BepInPlugin)”Create a new config file at the specified config path.
public ConfigFile(string configPath, bool saveOnInit, BepInPlugin ownerMetadata)Parameters
Section titled “Parameters”configPath string
Full path to a file that contains settings. The file will be created as needed.
saveOnInit bool
If the config file/directory doesn’t exist, create it immediately.
ownerMetadata BepInPlugin
Information about the plugin that owns this setting file.
Properties
Section titled “Properties”CoreConfig
Section titled “CoreConfig”public static ConfigFile CoreConfig { get; }Entries
Section titled “Entries”All config entries inside
protected Dictionary<ConfigDefinition, ConfigEntryBase> Entries { get; }ConfigDefinitions
Section titled “ConfigDefinitions”Create a list with all config entries inside of this config file.
[Obsolete("Use Keys instead")]public ReadOnlyCollection<ConfigDefinition> ConfigDefinitions { get; }ConfigFilePath
Section titled “ConfigFilePath”Full path to the config file. The file might not exist until a setting is added and changed, or Save() is called.
public string ConfigFilePath { get; }SaveOnConfigSet
Section titled “SaveOnConfigSet”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!
public bool SaveOnConfigSet { get; set; }this[ConfigDefinition]
Section titled “this[ConfigDefinition]”public ConfigEntryBase this[ConfigDefinition key] { get; }this[string, string]
Section titled “this[string, string]”public ConfigEntryBase this[string section, string key] { get; }Gets the number of elements contained in the ICollection<T>.
public int Count { get; }IsReadOnly
Section titled “IsReadOnly”Gets a value indicating whether the ICollection<T> is read-only.
public bool IsReadOnly { get; }Returns the ConfigDefinitions that the ConfigFile contains.
Creates a new array when the property is accessed. Thread-safe.
public ICollection<ConfigDefinition> Keys { get; }Values
Section titled “Values”Returns the ConfigEntryBase values that the ConfigFile contains.
Creates a new array when the property is accessed. Thread-safe.
public ICollection<ConfigEntryBase> Values { get; }GenerateSettingDescriptions
Section titled “GenerateSettingDescriptions”Generate user-readable comments for each of the settings in the saved .cfg file.
public bool GenerateSettingDescriptions { get; set; }Methods
Section titled “Methods”GetEnumerator()
Section titled “GetEnumerator()”Returns an enumerator that iterates through the collection.
public IEnumerator<KeyValuePair<ConfigDefinition, ConfigEntryBase>> GetEnumerator()Returns
Section titled “Returns”IEnumerator<KeyValuePair<ConfigDefinition, ConfigEntryBase>>
An enumerator that can be used to iterate through the collection.
Contains(KeyValuePair<ConfigDefinition, ConfigEntryBase>)
Section titled “Contains(KeyValuePair<ConfigDefinition, ConfigEntryBase>)”Determines whether the ICollection<T> contains a specific value.
public bool Contains(KeyValuePair<ConfigDefinition, ConfigEntryBase> item)Parameters
Section titled “Parameters”item KeyValuePair<ConfigDefinition, ConfigEntryBase>
The object to locate in the
Returns
Section titled “Returns”bool
true if item is found in the ICollection<T>; otherwise, false.
ContainsKey(ConfigDefinition)
Section titled “ContainsKey(ConfigDefinition)”Determines whether the IDictionary<TKey, TValue> contains an element with the specified key.
public bool ContainsKey(ConfigDefinition key)Parameters
Section titled “Parameters”key ConfigDefinition
The key to locate in the
Returns
Section titled “Returns”bool
true if the IDictionary<TKey, TValue> contains an element with the key; otherwise, false.
Exceptions
Section titled “Exceptions”ArgumentNullException
key is null.
Add(ConfigDefinition, ConfigEntryBase)
Section titled “Add(ConfigDefinition, ConfigEntryBase)”Adds an element with the provided key and value to the IDictionary<TKey, TValue>.
public void Add(ConfigDefinition key, ConfigEntryBase value)Parameters
Section titled “Parameters”key ConfigDefinition
The object to use as the key of the element to add.
value ConfigEntryBase
The object to use as the value of the element to add.
Exceptions
Section titled “Exceptions”ArgumentNullException
key is null.
ArgumentException
An element with the same key already exists in the IDictionary<TKey, TValue>.
NotSupportedException
The IDictionary<TKey, TValue> is read-only.
Remove(ConfigDefinition)
Section titled “Remove(ConfigDefinition)”Removes the element with the specified key from the IDictionary<TKey, TValue>.
public bool Remove(ConfigDefinition key)Parameters
Section titled “Parameters”key ConfigDefinition
The key of the element to remove.
Returns
Section titled “Returns”bool
true if the element is successfully removed; otherwise, false. This method also returns false if key was not found in the original IDictionary<TKey, TValue>.
Exceptions
Section titled “Exceptions”ArgumentNullException
key is null.
NotSupportedException
The IDictionary<TKey, TValue> is read-only.
Clear()
Section titled “Clear()”Removes all items from the ICollection<T>.
public void Clear()Exceptions
Section titled “Exceptions”NotSupportedException
The ICollection<T> is read-only.
GetConfigEntries()
Section titled “GetConfigEntries()”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 BepInEx.Configuration.ConfigFile.AddSetting``1(BepInEx.Configuration.ConfigDefinition%2c``0%2cBepInEx.Configuration.ConfigDescription) instead with no description.
[Obsolete("Use Values instead")]public ConfigEntryBase[] GetConfigEntries()Returns
Section titled “Returns”Reload()
Section titled “Reload()”Reloads the config from disk. Unsaved changes are lost.
public void Reload()Save()
Section titled “Save()”Writes the config to disk.
public void Save()GetSetting(ConfigDefinition)
Section titled “GetSetting(ConfigDefinition)”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 BepInEx.Configuration.ConfigFile.AddSetting``1(BepInEx.Configuration.ConfigDefinition%2c``0%2cBepInEx.Configuration.ConfigDescription).
[Obsolete("Use ConfigFile[key] or TryGetEntry instead")]public ConfigEntry<T> GetSetting<T>(ConfigDefinition configDefinition)Parameters
Section titled “Parameters”configDefinition ConfigDefinition
Section and Key of the setting.
Returns
Section titled “Returns”GetSetting(string, string)
Section titled “GetSetting(string, string)”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 BepInEx.Configuration.ConfigFile.AddSetting``1(BepInEx.Configuration.ConfigDefinition%2c``0%2cBepInEx.Configuration.ConfigDescription).
[Obsolete("Use ConfigFile[key] or TryGetEntry instead")]public ConfigEntry<T> GetSetting<T>(string section, string key)Parameters
Section titled “Parameters”section string
Section/category/group of the setting. Settings are grouped by this.
key string
Name of the setting.
Returns
Section titled “Returns”TryGetEntry(ConfigDefinition, out ConfigEntry)
Section titled “TryGetEntry(ConfigDefinition, out ConfigEntry)”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 BepInEx.Configuration.ConfigFile.Bind``1(BepInEx.Configuration.ConfigDefinition%2c``0%2cBepInEx.Configuration.ConfigDescription).
public bool TryGetEntry<T>(ConfigDefinition configDefinition, out ConfigEntry<T> entry)Parameters
Section titled “Parameters”configDefinition ConfigDefinition
Section and Key of the setting.
entry ConfigEntry<T>
The ConfigEntry value to return.
Returns
Section titled “Returns”TryGetEntry(string, string, out ConfigEntry)
Section titled “TryGetEntry(string, string, out ConfigEntry)”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 BepInEx.Configuration.ConfigFile.Bind``1(BepInEx.Configuration.ConfigDefinition%2c``0%2cBepInEx.Configuration.ConfigDescription).
public bool TryGetEntry<T>(string section, string key, out ConfigEntry<T> entry)Parameters
Section titled “Parameters”section string
Section/category/group of the setting. Settings are grouped by this.
key string
Name of the setting.
entry ConfigEntry<T>
The ConfigEntry value to return.
Returns
Section titled “Returns”Bind(ConfigDefinition, T, ConfigDescription)
Section titled “Bind(ConfigDefinition, T, ConfigDescription)”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.
public ConfigEntry<T> Bind<T>(ConfigDefinition configDefinition, T defaultValue, ConfigDescription configDescription = null)Parameters
Section titled “Parameters”configDefinition ConfigDefinition
Section and Key of the setting.
defaultValue T
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
Section titled “Returns”Bind(string, string, T, ConfigDescription)
Section titled “Bind(string, string, T, ConfigDescription)”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.
public ConfigEntry<T> Bind<T>(string section, string key, T defaultValue, ConfigDescription configDescription = null)Parameters
Section titled “Parameters”section string
Section/category/group of the setting. Settings are grouped by this.
key string
Name of the setting.
defaultValue T
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
Section titled “Returns”Bind(string, string, T, string)
Section titled “Bind(string, string, T, string)”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.
public ConfigEntry<T> Bind<T>(string section, string key, T defaultValue, string description)Parameters
Section titled “Parameters”section string
Section/category/group of the setting. Settings are grouped by this.
key string
Name of the setting.
defaultValue T
Value of the setting if the setting was not created yet.
description string
Simple description of the setting shown to the user.
Returns
Section titled “Returns”AddSetting(ConfigDefinition, T, ConfigDescription)
Section titled “AddSetting(ConfigDefinition, T, ConfigDescription)”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.
[Obsolete("Use Bind instead")]public ConfigEntry<T> AddSetting<T>(ConfigDefinition configDefinition, T defaultValue, ConfigDescription configDescription = null)Parameters
Section titled “Parameters”configDefinition ConfigDefinition
Section and Key of the setting.
defaultValue T
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
Section titled “Returns”AddSetting(string, string, T, ConfigDescription)
Section titled “AddSetting(string, string, T, ConfigDescription)”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.
[Obsolete("Use Bind instead")]public ConfigEntry<T> AddSetting<T>(string section, string key, T defaultValue, ConfigDescription configDescription = null)Parameters
Section titled “Parameters”section string
Section/category/group of the setting. Settings are grouped by this.
key string
Name of the setting.
defaultValue T
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
Section titled “Returns”AddSetting(string, string, T, string)
Section titled “AddSetting(string, string, T, string)”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.
[Obsolete("Use Bind instead")]public ConfigEntry<T> AddSetting<T>(string section, string key, T defaultValue, string description)Parameters
Section titled “Parameters”section string
Section/category/group of the setting. Settings are grouped by this.
key string
Name of the setting.
defaultValue T
Value of the setting if the setting was not created yet.
description string
Simple description of the setting shown to the user.
Returns
Section titled “Returns”Wrap(string, string, string, T)
Section titled “Wrap(string, string, string, T)”Access a setting. Use Bind instead.
[Obsolete("Use Bind instead")]public ConfigWrapper<T> Wrap<T>(string section, string key, string description = null, T defaultValue = default)Parameters
Section titled “Parameters”section string
key string
description string
defaultValue T
Returns
Section titled “Returns”Wrap(ConfigDefinition, T)
Section titled “Wrap(ConfigDefinition, T)”Access a setting. Use Bind instead.
[Obsolete("Use Bind instead")]public ConfigWrapper<T> Wrap<T>(ConfigDefinition configDefinition, T defaultValue = default)Parameters
Section titled “Parameters”configDefinition ConfigDefinition
defaultValue T
Returns
Section titled “Returns”Events
Section titled “Events”ConfigReloaded
Section titled “ConfigReloaded”An event that is fired every time the config is reloaded.
public event EventHandler ConfigReloadedEvent Type
Section titled “Event Type”SettingChanged
Section titled “SettingChanged”Fired when one of the settings is changed.
public event EventHandler<SettingChangedEventArgs> SettingChanged