DOCSEARCHbyAlgolia
Submit Docs

AlphaFS Documentation

repository·develop·Indexed 20 days ago

https://github.com/alphaleonis/alphafs

A .NET library that extends System.IO to provide full Win32 file system support. AlphaFS enables handling of extended length paths (up to 32,000 characters), advanced NTFS features like Junctions, Hardlinks, and Alternate Data Streams, and transactional file operations via the Kernel Transaction Manager (KTM). It provides namespaces for filesystem access (Alphaleonis.Win32.Filesystem), network resources (Alphaleonis.Win32.Network), and security/privilege management (Alphaleonis.Win32.Security).

Tokens
6.8K
Snippets
25
Records
38
Agent score
70%

What's inside AlphaFS

  1. What is AlphaFS and when should I use it?

    develop

    AlphaFS is a .NET library designed to provide more complete Win32 file system functionality than the standard System.IO classes.

    You should use AlphaFS if your application requires:

    • Extended length path support: Handling file or directory paths longer than the standard 260-character limit (up to 32,000 characters) to avoid System.IO.PathTooLongException.
    • Advanced NTFS features: Using Junctions, Hardlinks, or NTFS Alternate Data Streams.
    • Specialized file handling: Accessing hidden volumes, handling files/folders with leading or trailing spaces, or accessing network resources (SMB/DFS).
    • Transactional operations: Performing file operations using the Kernel Transaction Manager (KTM) on NTFS.
    • Enhanced enumeration: Using folder/file enumerators that support custom filtering and error recovery (e.g., handling 'access denied' exceptions during enumeration).

  2. Use the Alphaleonis.Win32.Filesystem namespace for extended filesystem access

    develop

    The Alphaleonis.Win32.Filesystem namespace provides classes for accessing and working with the local filesystem. It is designed as a drop-in replacement for the standard System.IO namespace, with many classes acting as replicas but offering enhanced functionality.

    A key feature is that all methods in this namespace support long Windows Unicode paths (paths starting with \?\), bypassing the traditional MAX_PATH limitations found in standard .NET System.IO implementations.

  3. Differences in Directory.GetDirectoryRoot() for long paths

    develop

    AlphaFS handles long path notation in GetDirectoryRoot() where System.IO fails.

    For example, when querying the root of a long path like \\?\C:\, System.IO throws a System.ArgumentException or returns null. AlphaFS correctly returns C:\.

    Similarly, for UNC long paths like \\?\UNC\SERVER001\Share\folder2, System.IO throws an exception, while AlphaFS correctly returns the share root \\SERVER001\Share.

    // Input Path: [\\?\\UNC\\SERVER001\\Share\\folder2]

// System.IO behavior:
// Throws System.ArgumentException: [Illegal characters in path.] or returns null

// AlphaFS behavior:
// Returns [\\SERVER001\\Share]

  4. Perform transactional file operations with AlphaFS

    develop

    AlphaFS supports Transactional NTFS (TxF) via the Kernel Transaction Manager (KTM). Most methods in the Alphaleonis.Win32.Filesystem classes exist in two versions:

    1. Normal versions: Standard file operations.
    2. Transactional versions: Operations that can be performed within a transaction using the KTM interface.

    This allows you to perform lightweight, atomic file operations on NTFS file systems using an interface familiar to System.IO users.

  5. Use Alphaleonis.Win32.Security for permission and privilege management

    develop
    The Alphaleonis.Win32.Security namespace contains classes for handling security-related operations such as authentication, authorization, and privilege tokens. These are often required for specific file operations. For example, to modify the Security Access Control List (SACL) of a file, the process must hold the SE_SECURITY_NAME privilege.

  6. Use EnumerateXxx() instead of GetXxx() for memory efficiency

    develop

    When working with large numbers of files or directories, prefer EnumerateDirectories() and EnumerateFiles() over GetDirectories() and GetFiles().

    GetXxx() methods return a full array, which requires the entire collection to be loaded into memory before you can access any items. EnumerateXxx() methods allow you to start processing the collection immediately as items are discovered, significantly reducing memory overhead.

  7. Compare Path.GetPathRoot() behavior between AlphaFS and System.IO

    develop

    AlphaFS and System.IO behave identically for most standard drive letters (e.g., C:\), relative paths (e.g., . or ..), and standard UNC shares (e.g., \\SERVER001\Share).

    Identical Behaviors:

    • Drive Letters: C:\test.txt $\rightarrow$ C:\
    • Standard UNC: \\SERVER001\Share\d1 $\rightarrow$ \\SERVER001\Share
    • Volume GUIDs: \\?\Volume{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\path $\rightarrow$ \\?\Volume{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

    Key Differences:

    • Kernel Paths: AlphaFS supports \\?\GLOBALROOT paths; System.IO throws an exception.
    • UNC Prefix Paths: AlphaFS treats \\?\UNC\Server\Share as a full root; System.IO truncates it to \\?\UNC.

  9. How Directory.GetDirectoryRoot() behaves in AlphaFS vs System.IO

    develop

    AlphaFS's Directory.GetDirectoryRoot() provides more robust handling of various path formats compared to System.IO. Specifically, AlphaFS correctly resolves long path prefixes and UNC formats that cause System.IO to throw System.ArgumentException (e.g., "Illegal characters in path").

    Key differences include:

    • UNC Long Paths: For inputs like \?\UNC\SERVER001\Share, System.IO throws an exception, while AlphaFS correctly returns \SERVER001\Share.
    • Long Path Prefixes: For inputs like \?\C:\a\b, System.IO throws an exception, while AlphaFS correctly returns C:\.
    • Standard Paths: For standard relative paths (e.g., . or \) and standard absolute paths (e.g., C:\test.txt), AlphaFS behavior matches System.IO.
    // Example of AlphaFS handling a path that System.IO rejects
string longPath = @"\\?\UNC\SERVER001\Share";
// System.IO would throw System.ArgumentException
string root = AlphaFS.Directory.GetDirectoryRoot(longPath); 
// root is "\\SERVER001\Share"

  10. Optimize performance with PathFormat

    develop

    AlphaFS methods perform path resolution and validation by default. To increase performance when performing multiple operations on the same path, you can use the PathFormat parameter to skip these checks.

    This is most effective when combined with Alphaleonis.Win32.Filesystem.Path.GetLongPath(), which resolves the path once. When you pass the resulting long path to a method using [Alphaleonis.Win32.Filesystem.PathFormat]::LongFullPath, AlphaFS skips the redundant validation steps.

    # 1. Resolve the long path once
$longPath = [Alphaleonis.Win32.Filesystem.Path]::GetLongPath('\\host\c$\Data\test.txt')

# 2. Use the LongFullPath format to skip redundant checks
[Alphaleonis.Win32.Filesystem.File]::Delete($longPath, $True, [Alphaleonis.Win32.Filesystem.PathFormat]::LongFullPath)

  11. How Path.GetFullPath() differs from System.IO

    develop

    AlphaFS's Path.GetFullPath() provides significantly broader support for path formats than System.IO.Path.GetFullPath(), particularly regarding Windows-specific long path prefixes and kernel device paths.

    Key differences include:

    • Kernel Device Paths: AlphaFS successfully processes paths starting with \?\GLOBALROOT\device\..., whereas System.IO throws a System.ArgumentException stating these paths are internal to the kernel.
    • Volume GUID Paths: AlphaFS handles volume-based paths (e.g., \?\Volume{GUID}\...), while System.IO throws a System.ArgumentException due to perceived illegal characters.
    • UNC Long Path Prefixes: AlphaFS correctly resolves and normalizes various UNC long path formats (e.g., \?\UNC\Server\Share or \?\Server\Share), whereas System.IO often throws System.ArgumentException: [Illegal characters in path.].
    • Long Path Normalization: AlphaFS can resolve long path prefixes (like \?\C:\a\b) into standard absolute paths (like C:\a\b), which System.IO fails to do, throwing an exception instead.
    // Example of AlphaFS handling a path that System.IO rejects
string longPath = "\\?\C:\\a\\b";
string fullPath = AlphaFS.IO.Path.GetFullPath(longPath);
// Result: "C:\a\b"

  12. Compare AlphaFS DriveInfo with System.IO.DriveInfo

    develop

    AlphaFS provides an enhanced DriveInfo class that includes more detailed disk space and volume information than the standard System.IO.DriveInfo.

    Key differences in AlphaFS DriveInfo:

    • DiskSpaceInfo: Provides detailed metrics like AvailableFreeSpacePercent, ClusterSize, SectorsPerCluster, and UsedSpacePercent.
    • VolumeInfo: Provides detailed volume metadata such as Guid, FileSystemName, SupportsEncryption, SupportsHardLinks, and SupportsTransactions.

    Example usage:

    $driveInfo = [Alphaleonis.Win32.Filesystem.DriveInfo]('C')
$driveInfo.DiskSpaceInfo.UsedSpacePercent
$driveInfo.VolumeInfo.SupportsHardLinks