Class Locations

Namespace

NanoByte.Common.Storage

Assembly

NanoByte.Common.dll

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

public static class Locations

Inheritance

object

Locations

Remarks

Uses System.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.

public const string PortableFlagName = "_portable"

Field Value

string

Properties

HomeDir

The home/profile directory of the current user.

public static string HomeDir { get; }

Property Value

string

InstallBase

The directory the application binaries are located in.

public static string InstallBase { get; }

Property Value

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.

public static bool IsPortable { get; }

Property Value

bool

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.

public static string PortableBase { get; }

Property Value

string

SystemCacheDir

The directory to store machine-wide non-essential data.

public static string SystemCacheDir { get; }

Property Value

string

Remarks

On Windows this is CommonApplicationData, on Linux it is /var/cache.

SystemConfigDirs

The directories to store machine-wide settings.

public static string SystemConfigDirs { get; }

Property Value

string

Directories separated by System.IO.Path.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).

public static string SystemDataDirs { get; }

Property Value

string

Directories separated by System.IO.Path.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).

public static string UserCacheDir { get; }

Property Value

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).

public static string UserConfigDir { get; }

Property Value

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).

public static string UserDataDir { get; }

Property Value

string

Remarks

On Windows this is %localappdata%, on Linux it usually is ~/.local/share.

Methods

GetCacheDirPath(string, bool, params string[])

Returns a path for a cache directory (should not roam across different machines).

public static string GetCacheDirPath(string appName, bool machineWide, params string[] resource)

Parameters

appName string

The name of application. Used as part of the path, unless IsPortable is true.

machineWide bool

true if the directory should be machine-wide.

resource string[]

The directory name of the resource to be stored.

Returns

string

A fully qualified directory path. The directory is guaranteed to already exist.

Exceptions

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.

public static string GetInstalledFilePath(string fileName)

Parameters

fileName string

The file name of the file to search for.

Returns

string

The fully qualified path of the first located instance of the file.

Exceptions

IOException

The file could not be found.

GetLoadConfigPaths(string, bool, params string[])

Returns a list of paths for loading a configuration resource.

public static IEnumerable<string> GetLoadConfigPaths(string appName, bool isFile, params string[] resource)

Parameters

appName string

The name of application. Used as part of the path, unless IsPortable is true.

isFile bool

true if the last part of resource refers to a file instead of a directory.

resource string[]

The path elements (directory and/or file names) of the resource to be loaded.

Returns

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, bool, params string[])

Returns a list of paths for loading a data resource (should not roam across different machines).

public static IEnumerable<string> GetLoadDataPaths(string appName, bool isFile, params string[] resource)

Parameters

appName string

The name of application. Used as part of the path, unless IsPortable is true.

isFile bool

true if the last part of resource refers to a file instead of a directory.

resource string[]

The path elements (directory and/or file names) of the resource to be loaded.

Returns

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, bool, params string[])

Returns a path for storing a configuration resource (can roam across different machines).

public static string GetSaveConfigPath(string appName, bool isFile, params string[] resource)

Parameters

appName string

The name of application. Used as part of the path, unless IsPortable is true.

isFile bool

true if the last part of resource refers to a file instead of a directory.

resource string[]

The path elements (directory and/or file names) of the resource to be stored.

Returns

string

A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not.

Exceptions

IOException

A problem occurred while creating a directory.

UnauthorizedAccessException

Creating a directory is not permitted.

GetSaveDataPath(string, bool, params string[])

Returns a path for storing a data resource (should not roam across different machines).

public static string GetSaveDataPath(string appName, bool isFile, params string[] resource)

Parameters

appName string

The name of application. Used as part of the path, unless IsPortable is true.

isFile bool

true if the last part of resource refers to a file instead of a directory.

resource string[]

The path elements (directory and/or file names) of the resource to be stored.

Returns

string

A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not.

Exceptions

IOException

A problem occurred while creating a directory.

UnauthorizedAccessException

Creating a directory is not permitted.

GetSaveSystemConfigPath(string, bool, params string[])

Returns a path for storing a system-wide configuration resource.

public static string GetSaveSystemConfigPath(string appName, bool isFile, params string[] resource)

Parameters

appName string

The name of application. Used as part of the path, unless IsPortable is true.

isFile bool

true if the last part of resource refers to a file instead of a directory.

resource string[]

The path elements (directory and/or file names) of the resource to be stored.

Returns

string

A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not.

Exceptions

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.

public static void OverrideInstallBase(string path)

Parameters

path string

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.

[MustDisposeResource]
public static IDisposable Redirect(string path)

Parameters

path string

The PortableBase value to set.

Returns

IDisposable

Call System.IDisposable.Dispose() to restore the original values of IsPortable and PortableBase.

Exceptions

InvalidOperationException

This method has already been called on this thread.