Virtual File System

Test filesystem code without touching the real disk — fast, deterministic, and disposable.

---

Table of Contents

• The Problem
• The Solution
• Features
• Tech Stack
• Getting Started
• Usage
• Demo Applications
• Architecture
• Project Structure
• Documentation
• Roadmap
• Contributing
• License
• Acknowledgments

The Problem

When writing .NET applications, you often need to read or write files. The standard System.IO namespace handles this well at runtime, but testing becomes painful. Unit tests that depend on the real filesystem are slow, brittle, leave temp files behind, and break in CI when paths differ across machines. Mocking System.IO is verbose and error-prone — you end up testing mock wiring instead of actual logic.

The Solution

Virtual File System provides a complete in-memory filesystem that's fast, deterministic, and disposable. Create files and directories, read and write content, subscribe to change events, and even undo/redo operations — all without touching the real disk.

// Create a virtual file system and add some files
IVirtualFileSystem vfs = new VFS()
    .CreateFile("src/Program.cs", "Console.WriteLine(\"Hello!\");")
    .CreateFile("src/Utils.cs")
    .CreateFile("tests/ProgramTests.cs");

// Print the tree
Console.WriteLine(vfs.GetTree());
// vfs://
// ├── src
// │   ├── Program.cs
// │   └── Utils.cs
// └── tests
//     └── ProgramTests.cs

Features

• Create a virtual file system
• Create, read, update, and delete virtual files and directories
• Print the contents of a virtual file system as a tree
• Move and rename virtual files and directories
• Check if a virtual file or directory exists (TryGetFile, TryGetDirectory)
• Get the size of a virtual file or directory
• Get the creation, access, and modification times
• Event-driven architecture (file created, deleted, moved, etc.)
• Undo/redo operations with change history
• Advanced search capabilities (by name, content, regex patterns)
• File system analytics and insights
• GitHub repository loading extension (via Atypical.VirtualFileSystem.GitHub)

Tech Stack

Layer	Technology
Language	C# 13
Runtime	.NET 9.0 / .NET 10.0
UI (Demo)	Blazor Server + Tailwind CSS
GitHub Integration	Octokit 14.x
DI	Microsoft.Extensions.DependencyInjection
CLI (Demo)	Spectre.Console
Testing	xUnit
Build	dotnet CLI / Nuke

Getting Started

Prerequisites

• .NET 9.0 or higher (.NET 10.0 recommended)
• A C# IDE (Visual Studio, Rider, VS Code)

Installation

Option 1 — NuGet (recommended)

dotnet add package Atypical.VirtualFileSystem

Or add a package reference to your project file:

<PackageReference Include="Atypical.VirtualFileSystem" Version="0.5.0" />

Option 2 — From Source

git clone https://github.com/Atypical-Consulting/VirtualFileSystem.git
cd VirtualFileSystem
dotnet build

Usage

Basic Example

// Create a virtual file system and populate it
IVirtualFileSystem vfs = new VFS()
    .CreateFile("superheroes/batman.txt")
    .CreateFile("superheroes/superman.txt")
    .CreateFile("superheroes/wonderwoman.txt")
    .CreateFile("villains/joker.txt")
    .CreateFile("villains/lexluthor.txt")
    .CreateFile("villains/penguin.txt")
    .CreateFile("world/gotham.txt")
    .CreateFile("world/metropolis.txt")
    .CreateFile("world/themyscira.txt");

// Get the string representation of the virtual file system
string tree = vfs.GetTree();

Expected output:

vfs://
├── superheroes
│   ├── batman.txt
│   ├── superman.txt
│   └── wonderwoman.txt
├── villains
│   ├── joker.txt
│   ├── lexluthor.txt
│   └── penguin.txt
└── world
    ├── gotham.txt
    ├── metropolis.txt
    └── themyscira.txt

Demo Applications

The library includes comprehensive demo applications that showcase its capabilities.

Blazor Server Demo

A full-featured web application built with Blazor Server and Tailwind CSS providing an interactive demonstration of all VFS features.

cd src/Atypical.VirtualFileSystem.DemoBlazorApp
dotnet run
# Open your browser to https://localhost:5040

Demo features: Dashboard with file system overview, file operations with real-time feedback, advanced multi-criteria search, full-featured file editor, analytics and insights, undo/redo history management, real-time event monitoring, and responsive design.

Console Demo

A command-line demonstration showcasing basic VFS operations:

cd src/Atypical.VirtualFileSystem.DemoCli
dotnet run

Architecture

┌─────────────────────────────────────────────────────┐
│                   Consumer Code                      │
│            (Your app / tests / demos)                │
└──────────────────────┬──────────────────────────────┘
                       │
         ┌─────────────▼─────────────┐
         │   IVirtualFileSystem      │
         │   (Core Interface)        │
         └─────────────┬─────────────┘
                       │
         ┌─────────────▼─────────────┐
         │   VFS (Implementation)    │
         │                           │
         │  ┌─────────────────────┐  │
         │  │  VirtualDirectory   │  │
         │  │  VirtualFile        │  │
         │  │  (Node Tree)        │  │
         │  └─────────────────────┘  │
         │                           │
         │  ┌─────────────────────┐  │
         │  │  UndoRedo Manager   │  │
         │  │  (Change History)   │  │
         │  └─────────────────────┘  │
         │                           │
         │  ┌─────────────────────┐  │
         │  │  Event System       │  │
         │  │  (Change Notifications)│
         │  └─────────────────────┘  │
         └─────────────┬─────────────┘
                       │
    ┌──────────────────▼──────────────────┐
    │   Extensions                         │
    │  ┌──────────────────────────────┐   │
    │  │  VirtualFileSystem.GitHub    │   │
    │  │  (Load repos into VFS)       │   │
    │  └──────────────────────────────┘   │
    └─────────────────────────────────────┘

Project Structure

VirtualFileSystem/
├── src/
│   ├── Atypical.VirtualFileSystem.Core/       # Core library (IVirtualFileSystem, VFS, models)
│   │   ├── Contracts/                         # Interfaces and abstractions
│   │   ├── Models/                            # VirtualFile, VirtualDirectory, paths
│   │   ├── Services/                          # Search, analytics services
│   │   ├── SystemOperations/                  # File system operations
│   │   ├── UndoRedo/                          # Undo/redo infrastructure
│   │   └── Extensions/                        # Extension methods
│   ├── Atypical.VirtualFileSystem.GitHub/     # GitHub repo loader extension
│   ├── Atypical.VirtualFileSystem.DemoBlazorApp/  # Blazor Server demo
│   └── Atypical.VirtualFileSystem.DemoCli/    # Console demo
├── tests/
│   ├── Atypical.VirtualFileSystem.UnitTests/  # Unit tests
│   ├── Atypical.VirtualFileSystem.GitHub.Tests/ # GitHub extension tests
│   └── Atypical.VirtualFileSystem.Benchmarks/ # Performance benchmarks
├── docs/                                      # Auto-generated API documentation
├── build/                                     # Build scripts
└── .github/workflows/                         # CI/CD pipelines

Documentation

Virtual File System provides complete API documentation generated automatically using DefaultDocumentation.

Roadmap

• Copy a virtual file or directory
• Support for custom metadata on files and directories
• Support for file and directory permissions
• Support for symbolic links

Want to contribute? Pick any roadmap item and open a PR!

Stats

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit using conventional commits (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

BSD-3-Clause © 2022-2025 Atypical Consulting

Acknowledgments

• All Contributors
• Atypical Consulting
• DefaultDocumentation for API doc generation
• Spectre.Console for beautiful CLI output
• Octokit for GitHub integration

---

Built with care by Atypical Consulting — opinionated, production-grade open source.