NanoByte.Common
Static Public Member Functions | Static Public Attributes | Properties | List of all members
NanoByte.Common.Storage.Locations Class Reference

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

Static Public Member Functions

static void OverrideInstallBase (string path)
 Override the automatically determined InstallBase with a custom path . More...
 
static string GetCacheDirPath ([Localizable(false)] string appName, bool machineWide, params string[] resource)
 Returns a path for a cache directory (should not roam across different machines). More...
 
static string GetIntegrationDirPath ([Localizable(false)] string appName, bool machineWide, params string[] resource)
 Returns a path for a directory that can safely be used for desktop integration. It ignores IsPortable. More...
 
static string GetSaveConfigPath ([Localizable(false)] string appName, bool isFile, params string[] resource)
 Returns a path for storing a configuration resource (can roam across different machines). More...
 
static string GetSaveSystemConfigPath ([Localizable(false)] string appName, bool isFile, params string[] resource)
 Returns a path for storing a system-wide configuration resource. More...
 
static IEnumerable< string > GetLoadConfigPaths ([Localizable(false)] string appName, bool isFile, params string[] resource)
 Returns a list of paths for loading a configuration resource. More...
 
static string GetSaveDataPath ([Localizable(false)] string appName, bool isFile, params string[] resource)
 Returns a path for storing a data resource (should not roam across different machines). More...
 
static IEnumerable< string > GetLoadDataPaths ([Localizable(false)] string appName, bool isFile, params string[] resource)
 Returns a list of paths for loading a data resource (should not roam across different machines). More...
 
static string GetInstalledFilePath ([Localizable(false)] string fileName)
 Tries to locate a file either in InstallBase, the location of the NanoByte.Common.dll or in the PATH. More...
 

Static Public Attributes

const string PortableFlagName = "_portable"
 The name of the flag file whose existence determines whether IsPortable is set to true. More...
 
static string HomeDir => Environment.GetEnvironmentVariable(WindowsUtils.IsWindows ? "userprofile" : "HOME") ?? ""
 The home/profile directory of the current user. More...
 
static string UserConfigDir
 The directory to store per-user settings (can roam across different machines). More...
 
static string UserDataDir
 The directory to store per-user data files (should not roam across different machines). More...
 
static string UserCacheDir
 The directory to store per-user non-essential data (should not roam across different machines). More...
 
static string SystemConfigDirs
 The directories to store machine-wide settings. More...
 
static string SystemDataDirs
 The directories to store machine-wide data files (should not roam across different machines). More...
 
static string SystemCacheDir
 The directory to store machine-wide non-essential data. More...
 

Properties

static string InstallBase = GetInstallBase() [get]
 The directory the application binaries are located in. More...
 
static bool IsPortable = File.Exists(Path.Combine(InstallBase, PortableFlagName)) [get, set]
 Indicates whether the application is currently operating in portable mode. More...
 
static string PortableBase = InstallBase [get, set]
 The directory used for storing files if IsPortable is true. Defaults to InstallBase. More...
 

Detailed Description

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

Uses Environment.SpecialFolder on Windows and the freedesktop.org basedir spec (XDG) on Linux. See http://freedesktop.org/wiki/Standards/basedir-spec

Member Function Documentation

◆ GetCacheDirPath()

static string NanoByte.Common.Storage.Locations.GetCacheDirPath ( [Localizable(false)] string  appName,
bool  machineWide,
params string[]  resource 
)
inlinestatic

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

Parameters
appNameThe name of application. Used as part of the path, unless IsPortable is true.
machineWidetrue if the directory should be machine-wide.
resourceThe directory name of the resource to be stored.
Returns
A fully qualified directory path. The directory is guaranteed to already exist.
Exceptions
IOExceptionA problem occurred while creating a directory.
UnauthorizedAccessExceptionCreating a directory is not permitted.

◆ GetInstalledFilePath()

static string NanoByte.Common.Storage.Locations.GetInstalledFilePath ( [Localizable(false)] string  fileName)
inlinestatic

Tries to locate a file either in InstallBase, the location of the NanoByte.Common.dll or in the PATH.

Parameters
fileNameThe file name of the file to search for.
Returns
The fully qualified path of the first located instance of the file.
Exceptions
IOExceptionThe file could not be found.

◆ GetIntegrationDirPath()

static string NanoByte.Common.Storage.Locations.GetIntegrationDirPath ( [Localizable(false)] string  appName,
bool  machineWide,
params string[]  resource 
)
inlinestatic

Returns a path for a directory that can safely be used for desktop integration. It ignores IsPortable.

Parameters
appNameThe name of application. Used as part of the path.
machineWidetrue if the directory should be machine-wide and machine-specific instead of roaming with the user profile.
resourceThe directory name of the resource to be stored.
Returns
A fully qualified directory path. The directory is guaranteed to already exist.
Exceptions
IOExceptionA problem occurred while creating a directory.
UnauthorizedAccessExceptionCreating a directory is not permitted.

If a new directory is created with machineWide set to true on Windows, ACLs are set to deny write access for non-Administrator users.

◆ GetLoadConfigPaths()

static IEnumerable<string> NanoByte.Common.Storage.Locations.GetLoadConfigPaths ( [Localizable(false)] string  appName,
bool  isFile,
params string[]  resource 
)
inlinestatic

Returns a list of paths for loading a configuration resource.

Parameters
appNameThe name of application. Used as part of the path, unless IsPortable is true.
isFiletrue if the last part of resource refers to a file instead of a directory.
resourceThe path elements (directory and/or file names) of the resource to be loaded.
Returns
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()

static IEnumerable<string> NanoByte.Common.Storage.Locations.GetLoadDataPaths ( [Localizable(false)] string  appName,
bool  isFile,
params string[]  resource 
)
inlinestatic

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

Parameters
appNameThe name of application. Used as part of the path, unless IsPortable is true.
isFiletrue if the last part of resource refers to a file instead of a directory.
resourceThe path elements (directory and/or file names) of the resource to be loaded.
Returns
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()

static string NanoByte.Common.Storage.Locations.GetSaveConfigPath ( [Localizable(false)] string  appName,
bool  isFile,
params string[]  resource 
)
inlinestatic

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

Parameters
appNameThe name of application. Used as part of the path, unless IsPortable is true.
isFiletrue if the last part of resource refers to a file instead of a directory.
resourceThe path elements (directory and/or file names) of the resource to be stored.
Returns
A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not.
Exceptions
IOExceptionA problem occurred while creating a directory.
UnauthorizedAccessExceptionCreating a directory is not permitted.

◆ GetSaveDataPath()

static string NanoByte.Common.Storage.Locations.GetSaveDataPath ( [Localizable(false)] string  appName,
bool  isFile,
params string[]  resource 
)
inlinestatic

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

Parameters
appNameThe name of application. Used as part of the path, unless IsPortable is true.
isFiletrue if the last part of resource refers to a file instead of a directory.
resourceThe path elements (directory and/or file names) of the resource to be stored.
Returns
A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not.
Exceptions
IOExceptionA problem occurred while creating a directory.
UnauthorizedAccessExceptionCreating a directory is not permitted.

◆ GetSaveSystemConfigPath()

static string NanoByte.Common.Storage.Locations.GetSaveSystemConfigPath ( [Localizable(false)] string  appName,
bool  isFile,
params string[]  resource 
)
inlinestatic

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

Parameters
appNameThe name of application. Used as part of the path, unless IsPortable is true.
isFiletrue if the last part of resource refers to a file instead of a directory.
resourceThe path elements (directory and/or file names) of the resource to be stored.
Returns
A fully qualified path to use to store the resource. Directories are guaranteed to already exist; files are not.
Exceptions
IOExceptionA problem occurred while creating a directory.
UnauthorizedAccessExceptionCreating a directory is not permitted.

◆ OverrideInstallBase()

static void NanoByte.Common.Storage.Locations.OverrideInstallBase ( string  path)
static

Override the automatically determined InstallBase with a custom path .

Use with caution. Be aware of possible race conditions. Intended for unit testing, runtime relocation, etc..

Member Data Documentation

◆ HomeDir

string NanoByte.Common.Storage.Locations.HomeDir => Environment.GetEnvironmentVariable(WindowsUtils.IsWindows ? "userprofile" : "HOME") ?? ""
static

The home/profile directory of the current user.

◆ PortableFlagName

const string NanoByte.Common.Storage.Locations.PortableFlagName = "_portable"
static

The name of the flag file whose existence determines whether IsPortable is set to true.

◆ SystemCacheDir

string NanoByte.Common.Storage.Locations.SystemCacheDir
static
Initial value:
=> WindowsUtils.IsWindows
? Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)
: "/var/cache"

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

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

◆ SystemConfigDirs

string NanoByte.Common.Storage.Locations.SystemConfigDirs
static
Initial value:
=> GetEnvironmentVariable("XDG_CONFIG_DIRS", WindowsUtils.IsWindows
? Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)
: "/etc/xdg")

The directories to store machine-wide settings.

Returns
Directories separated by Path.PathSeparator sorted by decreasing importance.

On Windows this is CommonApplicationData, on Linux it usually is /etc/xdg.

◆ SystemDataDirs

string NanoByte.Common.Storage.Locations.SystemDataDirs
static
Initial value:
=> GetEnvironmentVariable("XDG_DATA_DIRS", WindowsUtils.IsWindows
? Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)
: "/usr/local/share" + Path.PathSeparator + "/usr/share")

The directories to store machine-wide data files (should not roam across different machines).

Returns
Directories separated by Path.PathSeparator sorted by decreasing importance.

On Windows this is CommonApplicationData, on Linux it usually is /usr/local/share:/usr/share.

◆ UserCacheDir

string NanoByte.Common.Storage.Locations.UserCacheDir
static
Initial value:
=> GetEnvironmentVariable("XDG_CACHE_HOME", WindowsUtils.IsWindows
? Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)
: Path.Combine(HomeDir, ".cache"))

The directory to store per-user non-essential data (should not roam across different machines).

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

◆ UserConfigDir

string NanoByte.Common.Storage.Locations.UserConfigDir
static
Initial value:
=> GetEnvironmentVariable("XDG_CONFIG_HOME", WindowsUtils.IsWindows
? Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData)
: Path.Combine(HomeDir, ".config"))

The directory to store per-user settings (can roam across different machines).

On Windows this is appdata%, on Linux it usually is ~/.config.

◆ UserDataDir

string NanoByte.Common.Storage.Locations.UserDataDir
static
Initial value:
=> GetEnvironmentVariable("XDG_DATA_HOME", WindowsUtils.IsWindows
? Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)
: Path.Combine(HomeDir, ".local/share"))

The directory to store per-user data files (should not roam across different machines).

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

Property Documentation

◆ InstallBase

string NanoByte.Common.Storage.Locations.InstallBase = GetInstallBase()
staticget

The directory the application binaries are located in.

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

bool NanoByte.Common.Storage.Locations.IsPortable = File.Exists(Path.Combine(InstallBase, PortableFlagName))
staticgetset

Indicates whether the application is currently operating in portable mode.

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

string NanoByte.Common.Storage.Locations.PortableBase = InstallBase
staticgetset

The directory used for storing files if IsPortable is true. Defaults to InstallBase.


The documentation for this class was generated from the following files:
NanoByte.Common.Storage.Locations.HomeDir
static string HomeDir
The home/profile directory of the current user.
Definition: Locations.Directories.cs:17