Summary
Loads and saves application settings with a number of convenience and reliability features. See Remarks.
Generic type parameters
| TSettings |
The type to be used to store application settings. |
Remarks
Compared to a simple approach of using a serializer directly to load and save from a hard-coded file path, this
class offers the following benefits for the application settings scenario:
- The settings file path is chosen automatically based on SettingsLocation and the
appName. - A portable mode marker file can be placed in the application directory to make the app portable.
- File sharing violations are handled automatically; these are common with some backup software.
- No need to special-case first run; a default instance is returned if the settings file does not exist.
- A backup of the settings file is created if load fails and the application continues with default settings,
overwriting the faulty settings file.
- When saving, the settings are first saved to a temporary file, which only overwrites the original settings
file after a successful serialization.
- Unexpected I/O or parse errors can be toggled on/off, for applications wishing to trade between startup
reliability or preserving settings at the cost of a startup crash / additional error handling code.
- Supports scheduling a background save on a background thread, with debouncing of frequent calls.
Typical usage
private SettingsFile<Settings> AppSettingsFile;
...
// Load / initialise settings
AppSettingsFile = new SettingsFileXml<Settings>("MyApp"); // defined in RT.Serialization.Xml
...
// Use settings
Foobar = AppSettingsFile.Settings.Foobar;
AppSettingsFile.Settings.LastPos = MyWindow.Position;
...
// Save settings
AppSettingsFile.Save();
This minimal example will save the settings in User Profile under MyApp\MyApp.Settings.xml, and will support
portable mode automatically. It benefits from all the reliability features listed above. If the settings file is
corrupted this minimal example creates a backup of the corrupted file and resets the settings to defaults.
Settings-relative paths
To construct paths relative to the settings location, use SettingsFile<TSettings>.PathCombine(params string[]). This ensures that such paths
remain valid if the user chooses to configure portable mode (see below).
Portable mode
The goal of portable mode is to keep everything the application needs, including settings, in the application
directory. Conceptually this isn't actually a mode; it's simply a mechanism to select the appropriate path for the
settings file at settings load time (constructor call).
When loading settings, this class will check whether a portable mode marker file with the name
$"{appName}.IsPortable.txt" is present in the application directory (but see SettingsFile<TSettings>.GetPortableMarkerPath(string)). If present and empty, the settings file is stored in the application directory.
If not empty, the contents of the file specify the path to use. This path can be relative to the application
directory, or absolute, or use templates such as $(UserName), $(MachineName), $(UserDomainName), or $(member of
Environment.SpecialFolder).
Other notes
The absolute path and filename of the settings file is fully determined at settings load time (constructor call)
and remains unchanged for the lifetime of the SettingsFile<TSettings> instance. It is available via
SettingsFile<TSettings>.FileName.
Where necessary, the application can check whether a new default settings instance was created by checking the
SettingsFile<TSettings>.DefaultsLoaded property.
Constructors
|
Configures the location of the settings file and loads or initialises the settings. See Remarks on SettingsFile<TSettings>. |
|
Configures filename as the location of the settings file, bypassing all logic related to
portable mode, and loads the settings. Avoid where possible and use the other constructor. |
Instance methods
| string | |
Combines the directory containing this settings file with the specified path segments. Use this method to
reference additional files relative to the settings directory with correct support for portable mode marker file. |
| bool | Save(bool? throwOnError = null) |
Saves the settings object SettingsFile<TSettings>.Settings to the settings file. |
| bool | Save(string filename, bool? throwOnError = null) |
| void | |
Saves settings on a background thread after a short delay. See Remarks. |
Instance properties
| object | |
Take this lock before making changes to the SettingsFile<TSettings>.Settings object if you use SettingsFile<TSettings>.SaveInBackground(). See Remarks on SettingsFile<TSettings>.SaveInBackground() for specifics. |
| TimeSpan | |
Determines the maximum frequency at which calls to SettingsFile<TSettings>.SaveInBackground() actually perform the
(potentially expensive) save. The first background save is delayed by the amount specified here; subsequent
background saves only update the object to be saved but do not postpone the save. |
| bool | | true if a new default instance of the settings had to be constructed, otherwise false. When
false it's guaranteed that the settings were successfully loaded from the settings file. When true,
if throwOnError is true then it's guaranteed that the settings file was missing, but if throwOnError
is false then it's not possible to determine whether the file was present or a loading error has occurred. |
| string | |
Full path to the file from which the settings were loaded and to which they will be saved. This property is
populated on load even if the settings file did not exist as this is the path to which settings will be saved by
SettingsFile<TSettings>.Save(bool?). |
| TSettings | |
Settings stored in this settings file. This property is automatically populated by the constructor, which loads
the settings or constructs a new instance where necessary. Users should update this object as appropriate and call
SettingsFile<TSettings>.Save(bool?) to persist the settings. |
| TimeSpan | |
Specifies how long to keep retrying when settings cannot be saved due to a file sharing violation. Defaults to 5
seconds. |
Static properties
| TimeSpan | |
Specifies how long to keep retrying when settings cannot be loaded due to a file sharing violation. Defaults to 5
seconds. See Remarks. |