Show / Hide Table of Contents

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.

In This Article
Back to top Copyright Bastian Eicher