VirtualFS/docs/development.md

Development

Repository Layout

Main folders:

• VirtualFS/
• VirtualFS/Implementation/
• VirtualFS/Physical/
• VirtualFS/Memory/
• VirtualFS/Compressed/
• VirtualFS/EmbeddedResource/
• VirtualFS.Tests/

Important files:

• VirtualFS.sln
• VirtualFS/VirtualFS.csproj
• VirtualFS.Tests/VirtualFS.Tests.csproj
• Dockerfile
• .github/workflows/docker.yml

Target Frameworks

Library targets:

• netstandard2.0
• net472
• net6.0
• net8.0
• net10.0

Tests target:

• net10.0

Build and Test

The repository uses a Docker-based build/test flow with the official .NET 10 SDK image.

Run the full containerized verification:

docker build --target test -t virtualfs:test .

This performs:

• restore
• build
• test

Test Stack

The test project currently uses:

• xUnit v3
• Microsoft.NET.Test.Sdk
• coverlet.collector

CI

The repository workflow is:

• .github/workflows/docker.yml

It runs the same Docker build/test path on:

• pushes
• pull requests

Adding a New Backend

The expected implementation approach is:

1. derive from BaseFileSystem
2. implement the abstract operations required by IFileSystem
3. return VirtualStream for open file handles
4. populate entry metadata consistently
5. respect read-only semantics
6. add focused tests for backend-specific behavior

Backend responsibilities generally include:

• existence checks
• metadata lookup
• enumeration
• create/delete
• read/write stream opening
• rename/move/copy where backend-specific optimization is useful

Design Characteristics to Keep in Mind

These are important when changing the library:

• path semantics are custom and intentionally /-based
• directory vs file is determined by trailing slash
• RootFileSystem composes mounted backends but is not itself writable
• Entry.Path is backend-local, Entry.FullPath is root-visible
• EntryRealPath may be unavailable for some backends
• unmounting depends on IsBusy
• generic copy/move logic may be correct but not optimal for remote backends

Documentation Structure

Current documentation:

• top-level overview: README.md
• architecture details: docs/architecture.md
• usage examples: docs/usage.md
• backend summary: docs/backends.md
• development notes: docs/development.md