ProjectedFileSystemBase Class

Namespace: Meziantou.Framework.Win32.ProjectedFileSystem
Assembly: Meziantou.Framework.Win32.ProjectedFileSystem.dll
Package: Meziantou.Framework.Win32.ProjectedFileSystem 3.0.11
Source: ProjectedFileSystemBase.cs
Available in package assets: net10.0net11.0

Supported on windows10.0.17763

Base class for creating a virtual file system using Windows Projected File System (ProjFS).

[SupportedOSPlatform("windows10.0.17763")]
public abstract class ProjectedFileSystemBase : IDisposable

Example

var rootPath = @"C:\MyVirtualFS";
Directory.CreateDirectory(rootPath);
using var vfs = new MyVirtualFileSystem(rootPath);
vfs.Start(options: null);

public class MyVirtualFileSystem(string rootFolder) : ProjectedFileSystemBase(rootFolder)
{
    protected override ValueTask<IEnumerable<ProjectedFileSystemEntry>> GetEntriesAsync(string path)
    {
        if (string.IsNullOrEmpty(path))
        {
            return ValueTask.FromResult<IEnumerable<ProjectedFileSystemEntry>>(
            [
                ProjectedFileSystemEntry.File("file.txt", length: 13),
                ProjectedFileSystemEntry.Directory("folder"),
            ]);
        }

        return ValueTask.FromResult(Enumerable.Empty<ProjectedFileSystemEntry>());
    }

    protected override ValueTask<Stream?> OpenReadAsync(string path)
    {
        if (AreFileNamesEqual(path, "file.txt"))
            return ValueTask.FromResult<Stream?>(new MemoryStream(Encoding.UTF8.GetBytes("Hello, World!")));

        return ValueTask.FromResult<Stream?>(null);
    }
}

Implements

IDisposable

Constructors

Name	Description
ProjectedFileSystemBase(string)	Initializes a new instance of the `ProjectedFileSystemBase` class.

ProjectedFileSystemBase(string)

ProjectedFileSystemBase.cs

Initializes a new instance of the ProjectedFileSystemBase class.

protected ProjectedFileSystemBase(string rootFolder)

Parameters

rootFolder string: The root folder path where the virtual file system will be mounted.

Exceptions

ArgumentNullException: Thrown when rootFolder is null.
NotSupportedException: Thrown when running in a 32-bit process.

Properties

Name	Description
BufferSize	Gets or sets the buffer size used for reading file data. Default is 4096 bytes.
RootFolder	Gets the root folder path where the virtual file system is mounted.

BufferSize

ProjectedFileSystemBase.cs

Gets or sets the buffer size used for reading file data. Default is 4096 bytes.

protected int BufferSize { get; set; }

Property value

int

Exceptions

ArgumentOutOfRangeException: Thrown when the value is zero or negative.

RootFolder

ProjectedFileSystemBase.cs

Gets the root folder path where the virtual file system is mounted.

public string RootFolder { get; }

Property value

string

Methods

Name	Description
AreFileNamesEqual(string, string)	Compares two file names for equality using case-insensitive Windows file name comparison rules.
ClearNegativePathCache()	Clears the negative path cache, which stores queries for non-existent paths.
CompareFileName(string, string)	Compares two file names using Windows file name comparison rules.
DeleteFile(string, PRJ_UPDATE_TYPES, PRJ_UPDATE_FAILURE_CAUSES)	Deletes a file from the virtual file system projection.
Dispose()
Dispose(bool)
FileNameMatch(string, string)	Determines whether a file name matches a pattern using Windows file name matching rules.
GetEntriesAsync(string)	When overridden in a derived class, returns the list of files and directories for the specified path.
GetEntryAsync(string)	Gets metadata for a specific file or directory at the specified path.
GetOnDiskFileState(string)	Gets the on-disk state of a file or directory in a virtual file system.
OpenReadAsync(string)	When overridden in a derived class, opens a stream to read the content of a file at the specified path.
Start(ProjectedFileSystemStartOptions?)	Starts the virtual file system with the specified options.
Stop()	Stops the virtual file system.

AreFileNamesEqual(string, string)

ProjectedFileSystemBase.cs

Compares two file names for equality using case-insensitive Windows file name comparison rules.

protected static bool AreFileNamesEqual(string fileName1, string fileName2)

Parameters

fileName1 string: The first file name to compare.
fileName2 string: The second file name to compare.

Returns

bool true if the file names are equal; otherwise, false.

ClearNegativePathCache()

ProjectedFileSystemBase.cs

Clears the negative path cache, which stores queries for non-existent paths.

protected void ClearNegativePathCache()

Exceptions

InvalidOperationException: Thrown when the virtual file system is not started.

CompareFileName(string, string)

ProjectedFileSystemBase.cs

Compares two file names using Windows file name comparison rules.

protected static int CompareFileName(string fileName1, string fileName2)

Parameters

fileName1 string: The first file name to compare.
fileName2 string: The second file name to compare.

Returns

int A value less than zero if fileName1 is less than fileName2, zero if they are equal, or a value greater than zero if fileName1 is greater than fileName2.

DeleteFile(string, PRJ_UPDATE_TYPES, PRJ_UPDATE_FAILURE_CAUSES)

ProjectedFileSystemBase.cs

Deletes a file from the virtual file system projection.

protected bool DeleteFile(string relativePath, PRJ_UPDATE_TYPES updateFlags, out PRJ_UPDATE_FAILURE_CAUSES failureReason)

Parameters

relativePath string: The relative path of the file to delete.
updateFlags PRJ_UPDATE_TYPES: Flags controlling which file states are allowed to be deleted.
failureReason PRJ_UPDATE_FAILURE_CAUSES: When the method returns false, contains the reason for the failure.

Returns

bool true if the file was deleted; otherwise, false.

Exceptions

InvalidOperationException: Thrown when the virtual file system is not started.

Dispose overloads

Dispose()

ProjectedFileSystemBase.cs

public void Dispose()

No documentation is available.

Dispose(bool)

ProjectedFileSystemBase.cs

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

No documentation is available.

FileNameMatch(string, string)

ProjectedFileSystemBase.cs

Determines whether a file name matches a pattern using Windows file name matching rules.

protected static bool FileNameMatch(string fileName, string pattern)

Parameters

fileName string: The file name to test.
pattern string: The pattern to match against. Supports wildcards (* and ?).

Returns

bool true if the file name matches the pattern; otherwise, false.

GetEntriesAsync(string)

When overridden in a derived class, returns the list of files and directories for the specified path.

protected abstract ValueTask<IEnumerable<ProjectedFileSystemEntry>> GetEntriesAsync(string path)

Parameters

path string: The relative path of the directory to enumerate. Empty string represents the root directory.

Returns

ValueTask<IEnumerable<ProjectedFileSystemEntry>> A ValueTask<TResult> resolving to an enumerable collection of ProjectedFileSystemEntry objects representing the files and directories.

GetEntryAsync(string)

ProjectedFileSystemBase.cs

Gets metadata for a specific file or directory at the specified path.

net10.0

protected virtual ValueTask<ProjectedFileSystemEntry?> GetEntryAsync(string path)

net11.0

protected virtual ValueTask<ProjectedFileSystemEntry?> GetEntryAsync(string path)

Parameters

path string: The relative path of the file or directory.

Returns

ValueTask<ProjectedFileSystemEntry?> A ValueTask<TResult> resolving to the ProjectedFileSystemEntry for the specified path, or null if not found.

GetOnDiskFileState(string)

ProjectedFileSystemBase.cs

Gets the on-disk state of a file or directory in a virtual file system.

public static PRJ_FILE_STATE GetOnDiskFileState(string path)

Parameters

path string: The full path to the file or directory.

Returns

PRJ_FILE_STATE The on-disk state of the specified file or directory.

OpenReadAsync(string)

When overridden in a derived class, opens a stream to read the content of a file at the specified path.

protected abstract ValueTask<Stream?> OpenReadAsync(string path)

Parameters

path string: The relative path of the file to read.

Returns

ValueTask<Stream?> A ValueTask<TResult> resolving to a Stream to read the file content, or null if the file does not exist.

Start(ProjectedFileSystemStartOptions?)

ProjectedFileSystemBase.cs

Starts the virtual file system with the specified options.

public void Start(ProjectedFileSystemStartOptions? options)

Parameters

options ProjectedFileSystemStartOptions?: Configuration options for the virtual file system. Can be null to use default settings.

Exceptions

NotSupportedException: Thrown when the Projected File System Windows feature is not installed.

Stop()

ProjectedFileSystemBase.cs

Stops the virtual file system.

public void Stop()