PathOptions

PathOptions is a flags enum that controls how strictly path strings are validated during parsing. Every parse method, every IDirectoryPath.CombineDirectory / IDirectoryPath.CombineFile overload that takes a string, and every extension-related method accepts a PathOptions value and uses NoUnfriendlyNames when none is given. That default exists to protect you from path strings that are technically valid in some file systems but reliably cause trouble in real-world code, so loosen it only when you have a clear reason.

Default: NoUnfriendlyNames

NoUnfriendlyNames is the recommended default for almost all application code. It is a combination of:

Any of those patterns will cause parsing to throw ArgumentException with a precise message about why the path was rejected (the Try parse methods return false instead).

FilePath.ParseAbsolute(@"C:\data \report.pdf");   // throws: entry name "data " ends with a space
FilePath.ParseAbsolute(@"C:\nul");                // throws: reserved device name
FilePath.ParseAbsolute(@"C:\data\file.");         // throws: entry name ends with a dot
Tip

If your code is rejecting valid-looking paths and you don't know why, the exception message names the exact rule that fired. Use that to decide whether to fix the input or relax the option.

Individual Flags

None

PathOptions.None allows every path that is technically valid for the given format. Use this when you must work with whatever the file system contains, for example, paths returned by an OS file picker or paths read directly from an existing file system.

string filePathString = openFileDialog.FileName;
var file = FilePath.ParseAbsolute(filePathString, PathOptions.None);
file.OpenStream();
Caution

Don't store user-supplied "unfriendly" paths and re-display them later without care. Leading and trailing spaces are invisible in most UI; round-tripping a path string through a control that trims whitespace will produce a different path that points at a different file.

AllowEmptyDirectories

By default, a//b (two consecutive separators producing an empty segment) is rejected because it is almost always a bug, for example a missing variable expansion. Set AllowEmptyDirectories to silently collapse the empty segment instead:

DirectoryPath.ParseRelative("path/to//some/dir");                                    // throws
DirectoryPath.ParseRelative("path/to//some/dir", PathOptions.AllowEmptyDirectories); // "path/to/some/dir/"

NoReservedDeviceNames

NoReservedDeviceNames rejects entry names that match Windows reserved device names: CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9. Has no effect when parsing with PathFormat.Unix.

NoLeadingSpaces / NoTrailingSpaces

NoLeadingSpaces and NoTrailingSpaces reject entry names with a leading or trailing space. These names break Windows File Explorer, are difficult to handle in UI/serialization, and are a frequent source of silent failures in System.IO.

Only the very start and end of each entry name are checked. A space before the extension, as in report .pdf, is neither leading nor trailing and is accepted.

NoTrailingDots

NoTrailingDots rejects entry names ending in .. Same rationale as above: Windows applications typically can't handle these reliably.

NoNavigation

NoNavigation rejects any path that contains . or .. segments and rejects rooted-relative paths (e.g. \Some\Path on Windows). Use this when you parse paths from untrusted input that must remain inside a known directory:

// Reject "../../etc/passwd" style inputs up front:
var safe = FilePath.ParseRelative(userInput, PathOptions.NoUnfriendlyNames | PathOptions.NoNavigation);
Important

NoNavigation is a parse-time check. It does not by itself sandbox a path. Combine the parsed relative path with a known-safe absolute base directory before doing any I/O.

NoControlCharacters

NoControlCharacters rejects characters with ASCII codes 1-31 in entry names. Has no effect on PathFormat.Windows (where these are always disallowed).

PathFormatDependent

PathFormatDependent is a modifier flag. When set, the NoUnfriendlyNames rules get appended when the path's format is PathFormat.Windows or PathFormat.Universal, and are left out for PathFormat.Unix. Use this when you want your code to be friendly to Unix's more permissive file system without losing protection on Windows or in stored cross-platform data.

// Strict on Windows / Universal, lenient on Unix:
var opts = PathOptions.PathFormatDependent;
Note

Use the flag on its own (or with flags other than the unfriendly-name ones) to get this behavior. Combining it with NoUnfriendlyNames makes parsing strict on every format, because those rules are then requested explicitly.

Choosing the Right Options

Scenario Recommended options
App-defined path or user-typed input you'll store PathOptions.NoUnfriendlyNames (default)
Path returned from an OS file picker that you'll open and discard PathOptions.None
Path read from a file system enumeration PathOptions.None
Untrusted user input that must stay inside a known directory PathOptions.NoUnfriendlyNames + PathOptions.NoNavigation
Cross-platform data that should be strict on Windows but accept everything Unix accepts PathOptions.PathFormatDependent

Storage and Round-Tripping

When you store paths, the options used to parse them later must accept everything they accepted originally; otherwise round-trips will fail:

// At save time:
var path = FilePath.ParseAbsolute(input, PathOptions.None);
File.WriteAllText("path.txt", path.PathDisplay);

// At load time (must use the same options):
var loaded = FilePath.ParseAbsolute(File.ReadAllText("path.txt"), PathOptions.None);
Warning

If your storage layer trims whitespace (a database column with TRIM, an INI parser, etc.), do not use PathOptions.None; the round-tripped string won't match the original path on the file system. Either constrain inputs to PathOptions.NoUnfriendlyNames or guarantee verbatim storage.

Next Steps

Continue with these related guides: