206 lines
3.8 KiB
Markdown
206 lines
3.8 KiB
Markdown
# Usage
|
|
|
|
## Quick Start
|
|
|
|
### Create a Root Filesystem
|
|
|
|
```csharp
|
|
using System.IO;
|
|
using VirtualFS;
|
|
using VirtualFS.Implementation;
|
|
using VirtualFS.Memory;
|
|
using VirtualFS.Physical;
|
|
|
|
var root = new RootFileSystem();
|
|
|
|
var physical = new PhysicalFileSystem(new DirectoryInfo("/srv/site"));
|
|
var generated = new MemoryFileSystem
|
|
{
|
|
Priority = FileSystemMountPriority.High
|
|
};
|
|
|
|
root.Mount(physical, "/");
|
|
root.Mount(generated, "/");
|
|
```
|
|
|
|
In this setup:
|
|
|
|
- files present in `generated` can override files from `physical`
|
|
- reads are resolved through the root
|
|
- writes go to the writable backend chosen for the path
|
|
|
|
## Creating and Reading Files
|
|
|
|
```csharp
|
|
var file = root.Root.FileCreate("hello.txt");
|
|
file.WriteAllText("Hello from VirtualFS");
|
|
|
|
string text = root.GetFile("/hello.txt").ReadAllText();
|
|
```
|
|
|
|
## Working Inside a Mounted Subtree
|
|
|
|
```csharp
|
|
root.Mount(new MemoryFileSystem(), "/cache/");
|
|
|
|
var cacheDir = root.GetDirectory("/cache/");
|
|
cacheDir.Create("images");
|
|
cacheDir.GetDirectory("images/").FileCreate("thumb.txt").WriteAllText("ok");
|
|
```
|
|
|
|
## Overlay Example
|
|
|
|
```csharp
|
|
using System.IO;
|
|
using VirtualFS;
|
|
using VirtualFS.Compressed;
|
|
using VirtualFS.Implementation;
|
|
using VirtualFS.Physical;
|
|
|
|
var root = new RootFileSystem();
|
|
|
|
var baseAssets = new ZipReadFileSystem(System.IO.File.OpenRead("base-assets.zip"))
|
|
{
|
|
Priority = FileSystemMountPriority.Low
|
|
};
|
|
|
|
var overrides = new PhysicalFileSystem(new DirectoryInfo("./overrides"))
|
|
{
|
|
Priority = FileSystemMountPriority.High
|
|
};
|
|
|
|
root.Mount(baseAssets, "/assets/");
|
|
root.Mount(overrides, "/assets/");
|
|
```
|
|
|
|
Reads under `/assets/` prefer files from `./overrides`, then fall back to the ZIP.
|
|
|
|
## Enumerating Entries
|
|
|
|
```csharp
|
|
foreach (var entry in root.Root.GetEntries())
|
|
{
|
|
Console.WriteLine($"{entry.FullPath} readonly={entry.IsReadOnly}");
|
|
}
|
|
```
|
|
|
|
You can also enumerate only files or only directories:
|
|
|
|
- `GetFiles()`
|
|
- `GetDirectories()`
|
|
|
|
All enumeration methods support an optional regular-expression filter.
|
|
|
|
## Using `Directory`
|
|
|
|
Common operations:
|
|
|
|
- `GetEntries()`
|
|
- `GetFiles()`
|
|
- `GetDirectories()`
|
|
- `Exists(name)`
|
|
- `GetEntry(name)`
|
|
- `GetFile(name)`
|
|
- `GetDirectory(name)`
|
|
- `Create(name)`
|
|
- `FileCreate(name)`
|
|
- `Delete(recursive)`
|
|
|
|
Example:
|
|
|
|
```csharp
|
|
var dir = root.GetDirectory("/content/");
|
|
|
|
if (!dir.Exists("images/"))
|
|
dir.Create("images");
|
|
|
|
var imageDir = dir.GetDirectory("images/");
|
|
```
|
|
|
|
## Using `File`
|
|
|
|
Common operations:
|
|
|
|
- `OpenRead()`
|
|
- `OpenWrite()`
|
|
- `ReadAllBytes()`
|
|
- `ReadAllLines()`
|
|
- `ReadAllText()`
|
|
- `WriteAllBytes()`
|
|
- `WriteAllLines()`
|
|
- `WriteAllText()`
|
|
- `AppendAllBytes()`
|
|
- `AppendAllLines()`
|
|
- `AppendAllText()`
|
|
- `Delete()`
|
|
|
|
Example:
|
|
|
|
```csharp
|
|
var file = root.GetFile("/config/appsettings.json");
|
|
var text = file.ReadAllText();
|
|
```
|
|
|
|
## `forceLocal`
|
|
|
|
Many `Directory` and `File` instance methods accept `forceLocal`.
|
|
|
|
Use it when:
|
|
|
|
- you explicitly want to bypass the root overlay behavior
|
|
- you want to operate only inside the backend that produced the entry
|
|
|
|
Example:
|
|
|
|
```csharp
|
|
var entry = root.GetFile("/assets/logo.png");
|
|
using var localStream = entry.OpenRead(forceLocal: true);
|
|
```
|
|
|
|
## Path Examples
|
|
|
|
```csharp
|
|
Path dir = "/docs/";
|
|
Path file = dir + "readme.txt"; // "/docs/readme.txt"
|
|
Path parent = ((Path)"/docs/api/").Parent; // "/docs/"
|
|
```
|
|
|
|
Normalization:
|
|
|
|
- `"/a/./b.txt"` becomes `"/a/b.txt"`
|
|
- `"/a/b/../c.txt"` becomes `"/a/c.txt"`
|
|
|
|
## Copy, Move, Rename
|
|
|
|
Available on `IFileSystem`:
|
|
|
|
- `Copy`
|
|
- `Move`
|
|
- `ReName`
|
|
|
|
Notes:
|
|
|
|
- copy and move may work across different mounted backends
|
|
- cross-backend operations may be slower
|
|
- directory destinations are expected to be directory paths
|
|
|
|
## Unmounting
|
|
|
|
`Umount` succeeds only if the filesystem is not busy.
|
|
|
|
That means:
|
|
|
|
- open file streams must be closed first
|
|
- callers should use `using` or explicit disposal
|
|
|
|
Example:
|
|
|
|
```csharp
|
|
using (var stream = root.GetFile("/data/report.txt").OpenRead())
|
|
{
|
|
// use stream
|
|
}
|
|
|
|
root.Umount(someFs);
|
|
```
|