Class Locations

Provides easy access to platform-specific common directories for storing settings and application data.

Inheritance

Object

Locations

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 true.
Boolean	machineWide	true if the directory should be machine-wide.
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 true.
Boolean	isFile	true if the last part of resource refers to a file instead of a directory.
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 true.
Boolean	isFile	true if the last part of resource refers to a file instead of a directory.
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 true.
Boolean	isFile	true if the last part of resource refers to a file instead of a directory.
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 true.
Boolean	isFile	true if the last part of resource refers to a file instead of a directory.
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 true.
Boolean	isFile	true if the last part of resource refers to a file instead of a directory.
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.