155 lines
3.3 KiB
Markdown
155 lines
3.3 KiB
Markdown
# Backends
|
|
|
|
This page summarizes the built-in filesystem implementations in VirtualFS.
|
|
|
|
## `PhysicalFileSystem`
|
|
|
|
Backs a virtual subtree with a real local directory.
|
|
|
|
Characteristics:
|
|
|
|
- writable
|
|
- creates the root directory if it does not exist
|
|
- maps virtual `/` separators to host-native separators internally
|
|
- supports native file and directory metadata
|
|
|
|
Good fit for:
|
|
|
|
- local content directories
|
|
- writable application storage
|
|
- test fixtures backed by temporary directories
|
|
|
|
## `MemoryFileSystem`
|
|
|
|
Stores entries entirely in memory.
|
|
|
|
Characteristics:
|
|
|
|
- writable
|
|
- no physical path
|
|
- lightweight and fast for temporary content
|
|
|
|
Good fit for:
|
|
|
|
- generated content
|
|
- overlays
|
|
- temporary runtime state
|
|
- tests
|
|
|
|
## `ZipReadFileSystem`
|
|
|
|
Exposes a ZIP archive as a read-only virtual filesystem.
|
|
|
|
Characteristics:
|
|
|
|
- read-only
|
|
- backed by `SharpZipLib`
|
|
- requires a seekable stream
|
|
- optional path scoping to a ZIP subdirectory
|
|
- optional regex filtering
|
|
|
|
Good fit for:
|
|
|
|
- packaged assets
|
|
- static content bundles
|
|
- immutable deployment artifacts
|
|
|
|
## `EmbeddedResourceFileSystem`
|
|
|
|
Exposes assembly embedded resources as a read-only filesystem.
|
|
|
|
Characteristics:
|
|
|
|
- read-only
|
|
- backed by manifest resources
|
|
- optional root namespace trimming
|
|
- optional regex filtering
|
|
|
|
Good fit for:
|
|
|
|
- embedded templates
|
|
- application assets bundled in assemblies
|
|
- shipping immutable defaults inside an executable or library
|
|
|
|
## `FtpFileSystem`
|
|
|
|
FTP-backed implementation using `FluentFTP`.
|
|
|
|
Characteristics:
|
|
|
|
- writable
|
|
- supports file, directory, and symlink listings
|
|
- supports recursive directory deletion
|
|
- opens a fresh FTP connection per operation
|
|
|
|
Good fit for:
|
|
|
|
- remote FTP stores where a fuller client implementation is needed
|
|
|
|
Notes:
|
|
|
|
- network operations are naturally slower than local backends
|
|
- deep copy/move operations may become expensive
|
|
|
|
## `SimpleFtpFileSystem`
|
|
|
|
Minimal FTP implementation based on `FtpWebRequest`.
|
|
|
|
Characteristics:
|
|
|
|
- writable
|
|
- simpler than `FtpFileSystem`
|
|
- recursive delete is implemented in library code
|
|
|
|
Good fit for:
|
|
|
|
- compatibility scenarios
|
|
- cases where the simpler implementation is sufficient
|
|
|
|
## `SimpleFtpCachedFileSystem`
|
|
|
|
Caching layer on top of `SimpleFtpFileSystem`.
|
|
|
|
Characteristics:
|
|
|
|
- caches directory listings by path
|
|
- updates cache on some mutations
|
|
- reduces repeated directory enumeration cost
|
|
|
|
Good fit for:
|
|
|
|
- FTP trees with repeated read-heavy directory access
|
|
|
|
## `SFtpFileSystem`
|
|
|
|
SFTP-backed implementation using `SSH.NET`.
|
|
|
|
Characteristics:
|
|
|
|
- writable
|
|
- supports password authentication
|
|
- supports private key authentication
|
|
- can validate host fingerprint
|
|
- can forward exceptions to a callback
|
|
|
|
Good fit for:
|
|
|
|
- secure remote filesystem access over SFTP
|
|
|
|
## Backend Selection Guidance
|
|
|
|
Choose a backend based on the shape of the content:
|
|
|
|
- use `PhysicalFileSystem` for local writable data
|
|
- use `MemoryFileSystem` for generated or ephemeral data
|
|
- use `ZipReadFileSystem` for immutable packaged assets
|
|
- use `EmbeddedResourceFileSystem` for assembly-bundled assets
|
|
- use `FtpFileSystem` or `SFtpFileSystem` for remote stores
|
|
- use `SimpleFtpCachedFileSystem` when FTP directory reads are repetitive
|
|
|
|
Common combinations:
|
|
|
|
- ZIP as a low-priority base layer + physical overrides as high priority
|
|
- physical content + memory-generated overlay
|
|
- embedded resources + memory patch layer
|