Class Locations
Provides easy access to platform-specific common directories for storing settings and application data.
Namespace: NanoByte.Common.Storage
Assembly: NanoByte.Common.dll
Syntax
public static class Locations : Object
Remarks
Uses Environment.SpecialFolder on Windows and the freedesktop.org basedir spec (XDG) on Linux. See http://freedesktop.org/wiki/Standards/basedir-spec
Fields
PortableFlagName
The name of the flag file whose existence determines whether IsPortable is set to true
.
Declaration
public const string PortableFlagName = "_portable"
Field Value
Type | Description |
---|---|
String |
Properties
HomeDir
The home/profile directory of the current user.
Declaration
public static string HomeDir { get; }
Property Value
Type | Description |
---|---|
String |
InstallBase
The directory the application binaries are located in.
Declaration
public static string InstallBase { get; }
Property Value
Type | Description |
---|---|
String |
Remarks
Uses the location of the NanoByte.Common DLL, not the calling EXE. Walks up one directory level if placed within a dir called "lib". Works with ngened and shadow copied assemblies. Does not work with GACed assemblies.
IsPortable
Indicates whether the application is currently operating in portable mode.
Declaration
public static bool IsPortable { get; }
Property Value
Type | Description |
---|---|
Boolean |
Remarks
Portable mode is activated by placing a file named PortableFlagName in InstallBase.
When portable mode is active files are stored and loaded from PortableBase instead of the user profile and system directories.
PortableBase
The directory used for storing files if IsPortable is true
.
Declaration
public static string PortableBase { get; }
Property Value
Type | Description |
---|---|
String |
SystemCacheDir
The directory to store machine-wide non-essential data.
Declaration
public static string SystemCacheDir { get; }
Property Value
Type | Description |
---|---|
String |
Remarks
On Windows this is CommonApplicationData
, on Linux it is /var/cache
.
SystemConfigDirs
The directories to store machine-wide settings.
Declaration
public static string SystemConfigDirs { get; }
Property Value
Type | Description |
---|---|
String | Directories separated by PathSeparator sorted by decreasing importance. |
Remarks
On Windows this is CommonApplicationData
, on Linux it usually is /etc/xdg
.
SystemDataDirs
The directories to store machine-wide data files (should not roam across different machines).
Declaration
public static string SystemDataDirs { get; }
Property Value
Type | Description |
---|---|
String | Directories separated by PathSeparator sorted by decreasing importance. |
Remarks
On Windows this is CommonApplicationData
, on Linux it usually is /usr/local/share:/usr/share
.
UserCacheDir
The directory to store per-user non-essential data (should not roam across different machines).
Declaration
public static string UserCacheDir { get; }
Property Value
Type | Description |
---|---|
String |
Remarks
On Windows this is %localappdata%
, on Linux it usually is ~/.cache
.
UserConfigDir
The directory to store per-user settings (can roam across different machines).
Declaration
public static string UserConfigDir { get; }
Property Value
Type | Description |
---|---|
String |
Remarks
On Windows this is %appdata%
, on Linux it usually is ~/.config
.
UserDataDir
The directory to store per-user data files (should not roam across different machines).
Declaration
public static string UserDataDir { get; }
Property Value
Type | Description |
---|---|
String |
Remarks
On Windows this is %localappdata%
, on Linux it usually is ~/.local/share
.
Methods
GetCacheDirPath(String, Boolean, String[])
Returns a path for a cache directory (should not roam across different machines).
Declaration
public static string GetCacheDirPath(string appName, bool machineWide, params string[] resource)
Parameters
Type | Name | Description |
---|---|---|
String | appName | The name of application. Used as part of the path, unless IsPortable is |
Boolean | machineWide |
|
String[] | resource | The directory name of the resource to be stored. |
Returns
Type | Description |
---|---|
String | A fully qualified directory path. The directory is guaranteed to already exist. |
Exceptions
Type | Condition |
---|---|
IOException | A problem occurred while creating a directory. |
UnauthorizedAccessException | Creating a directory is not permitted. |
GetInstalledFilePath(String)
Tries to locate a file either in InstallBase, the location of the NanoByte.Common.dll or in the PATH.
Declaration
public static string GetInstalledFilePath(string fileName)
Parameters
Type | Name | Description |
---|---|---|
String | fileName | The file name of the file to search for. |
Returns
Type | Description |
---|---|
String | The fully qualified path of the first located instance of the file. |
Exceptions
Type | Condition |
---|---|
IOException | The file could not be found. |
GetLoadConfigPaths(String, Boolean, String[])
Returns a list of paths for loading a configuration resource.
Declaration
public static IEnumerable<string> GetLoadConfigPaths(string appName, bool isFile, params string[] resource)
Parameters
Type | Name | Description |
---|---|---|
String | appName | The name of application. Used as part of the path, unless IsPortable is |
Boolean | isFile |
|
String[] | resource | The path elements (directory and/or file names) of the resource to be loaded. |
Returns
Type | Description |
---|---|
IEnumerable<String> | A list of fully qualified paths to use to load the resource sorted by decreasing importance. This list will always reflect the current state in the filesystem and can not be modified! It may be empty. |
GetLoadDataPaths(String, Boolean, String[])
Returns a list of paths for loading a data resource (should not roam across different machines).
Declaration
public static IEnumerable<string> GetLoadDataPaths(string appName, bool isFile, params string[] resource)
Parameters
Type | Name | Description |
---|---|---|
String | appName | The name of application. Used as part of the path, unless IsPortable is |
Boolean | isFile |
|
String[] | resource | The path elements (directory and/or file names) of the resource to be loaded. |
Returns
Type | Description |
---|---|
IEnumerable<String> | A list of fully qualified paths to use to load the resource sorted by decreasing importance. This list will always reflect the current state in the filesystem and can not be modified! It may be empty. |
GetSaveConfigPath(String, Boolean, String[])
Returns a path for storing a configuration resource (can roam across different machines).
Declaration
public static string GetSaveConfigPath(string appName, bool isFile, params string[] resource)
Parameters
Type | Name | Description |
---|---|---|
String | appName | The name of application. Used as part of the path, unless IsPortable is |
Boolean | isFile |
|
String[] | resource | The path elements (directory and/or file names) of the resource to be stored. |
Returns
Type | Description |
---|---|
String | A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not. |
Exceptions
Type | Condition |
---|---|
IOException | A problem occurred while creating a directory. |
UnauthorizedAccessException | Creating a directory is not permitted. |
GetSaveDataPath(String, Boolean, String[])
Returns a path for storing a data resource (should not roam across different machines).
Declaration
public static string GetSaveDataPath(string appName, bool isFile, params string[] resource)
Parameters
Type | Name | Description |
---|---|---|
String | appName | The name of application. Used as part of the path, unless IsPortable is |
Boolean | isFile |
|
String[] | resource | The path elements (directory and/or file names) of the resource to be stored. |
Returns
Type | Description |
---|---|
String | A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not. |
Exceptions
Type | Condition |
---|---|
IOException | A problem occurred while creating a directory. |
UnauthorizedAccessException | Creating a directory is not permitted. |
GetSaveSystemConfigPath(String, Boolean, String[])
Returns a path for storing a system-wide configuration resource.
Declaration
public static string GetSaveSystemConfigPath(string appName, bool isFile, params string[] resource)
Parameters
Type | Name | Description |
---|---|---|
String | appName | The name of application. Used as part of the path, unless IsPortable is |
Boolean | isFile |
|
String[] | resource | The path elements (directory and/or file names) of the resource to be stored. |
Returns
Type | Description |
---|---|
String | A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not. |
Exceptions
Type | Condition |
---|---|
IOException | A problem occurred while creating a directory. |
UnauthorizedAccessException | Creating a directory is not permitted. |
OverrideInstallBase(String)
Override the automatically determined InstallBase with a custom path
.
Declaration
public static void OverrideInstallBase(string path)
Parameters
Type | Name | Description |
---|---|---|
String | path |
Remarks
Use with caution. Be aware of possible race conditions. Intended for unit testing, runtime relocation, etc..
Redirect(String)
Temporarily overrides IsPortable and PortableBase for the current thread or async flow. Useful for unit tests.
Declaration
public static IDisposable Redirect(string path)
Parameters
Type | Name | Description |
---|---|---|
String | path | The PortableBase value to set. |
Returns
Type | Description |
---|---|
IDisposable | Call Dispose() to restore the original values of IsPortable and PortableBase. |
Exceptions
Type | Condition |
---|---|
InvalidOperationException | This method has already been called on this thread. |