Home

Rheo.Storage Wiki

Intelligent file system operations with content-based analysis, real-time progress tracking, and built-in change monitoring.

Rheo.Storage enriches .NET file system programming with signature-based file type detection, comprehensive async operations with progress reporting, and automated event-driven monitoring—bringing modern capabilities to everyday file operations.

---

What Makes Rheo.Storage Different?

Modern Capabilities for File System Operations

Rheo.Storage delivers a unified, object-oriented API with capabilities that modern applications need:

Content Intelligence

• Signature-based file type detection - examine actual file content, not just extensions
• Standards-compliant MIME type detection
• Distinguish between declared and actual file types for security

Developer Experience

• Real-time progress reporting with transfer speeds and ETA calculations
• Complete async/await support with CancellationToken throughout
• Automatic rollback on operation failures
• Integrated change monitoring with configurable debouncing

Rich Metadata

• Human-readable formatted sizes (KB, MB, GB, TB)
• Platform-specific information for Windows and Unix systems
• Comprehensive file and directory statistics

Feature Comparison

Capabilities Rheo.Storage delivers that built-in .NET APIs don't:

Feature	Built-in .NET	Rheo.Storage
File Type Detection	Extension-based	✅ Signature-based content analysis
Progress Tracking	Not available	✅ Built-in with StorageProgress
Change Monitoring	Manual FileSystemWatcher	✅ Integrated with automatic debouncing
Async Coverage	Partial	✅ Complete with CancellationToken
MIME Types	Not available	✅ Standards-compliant detection
Formatted Sizes	Bytes only	✅ KB, MB, GB, TB with precision
Error Recovery	Manual	✅ Automatic rollback
Platform Metadata	Limited	✅ Windows & Unix structures
API Design	Static + instance mix	✅ Cohesive object-oriented

---

🚀 Quick Start

Installation

dotnet add package Rheo.Storage

Your First File Operation

using Rheo.Storage;

using var file = new FileObject("document.pdf");

// Rich metadata with content analysis
Console.WriteLine($"Actual Type: {file.Information.TypeName}");          // "PDF Document"
Console.WriteLine($"MIME Type: {file.Information.MimeType}");             // "application/pdf"
Console.WriteLine($"Actual Extension: {file.Information.ActualExtension}"); // ".pdf"
Console.WriteLine($"Size: {file.Information.FormattedSize}");             // "2.4 MB"

// Copy with real-time progress and cancellation
var progress = new Progress<StorageProgress>(p =>
    Console.WriteLine($"Copying: {p.ProgressPercentage:F1}% @ {p.BytesPerSecond/1024/1024:F2} MB/s"));

await file.CopyAsync("backup/document.pdf", progress, overwrite: true)

---

📚 Core Documentation

🗂️ Storage Objects

The foundation of Rheo.Storage - object-oriented abstractions over files and directories.

• IStorageObject Interface - Base contract defining the storage object model
• StorageObject Class - Abstract base with path validation, caching, and resource management
• FileObject Class - File operations with progress, cancellation, and automatic rollback
• DirectoryObject Class - Directory operations with integrated change monitoring

📊 Storage Information

Rich, intelligent metadata that goes far beyond FileInfo.Length and DirectoryInfo.CreationTime.

• StorageInformation Class - Base metadata with 1-second caching for performance
• FileInformation Class - Content-based type detection, MIME types, actual vs declared extensions
• DirectoryInformation Class - Recursive file counts, total sizes, and comprehensive statistics

📡 Progress & Events

Built-in progress reporting and event-driven change notifications.

• StorageProgress Class - Real-time operation progress with transfer speeds
• SyncProgress Class - Synchronous progress for console/background scenarios
• StorageChangedEventArgs Class - Change notification events (Created, Modified, Deleted, Relocated)

---

🎯 Key Capabilities

🔍 Intelligent Content Analysis

Verify file integrity with content analysis - Rheo.Storage examines actual file content using signature-based detection:

using var file = new FileObject("document.txt"); // Verify the actual type
Console.WriteLine(file.Information.Extension);       // ".txt" (declared extension)
Console.WriteLine(file.Information.ActualExtension); // ".pdf" (detected from content)
Console.WriteLine(file.Information.TypeName);        // "PDF Document"
Console.WriteLine(file.Information.MimeType);        // "application/pdf"

📈 Built-In Progress Reporting

Track long-running operations in real-time - every copy/move/write operation supports progress:

using var largeFile = new FileObject("bigdata.iso"); // 4.7 GB

var progress = new Progress<StorageProgress>(p =>
{
    Console.WriteLine($"Progress: {p.ProgressPercentage:F1}%");
    Console.WriteLine($"Speed: {p.BytesPerSecond / 1024 / 1024:F2} MB/s");
    Console.WriteLine($"Transferred: {p.BytesTransferred:N0} / {p.TotalBytes:N0} bytes");
});

// Full cancellation support
var cts = new CancellationTokenSource();
await largeFile.CopyAsync("D:/Backup/bigdata.iso", progress, cancellationToken: cts.Token);

👁️ Integrated Change Monitoring

DirectoryObject wraps FileSystemWatcher - simplified setup with automatic debouncing and cleanup:

using var projectDir = new DirectoryObject(@"C:\MyProject");

// Simple setup - subscribe and start
projectDir.Changed += (sender, e) =>
{
    Console.WriteLine($"{e.ChangeType}: {e.NewInfo?.FullName}");
};

projectDir.StartWatching();

// Features:
// - Automatic debouncing (500ms default) prevents event spam
// - Automatic cleanup on Dispose
// - Single unified Changed event for all change types

🛡️ Smart Error Handling

Automatic rollback on failures - operations clean up after themselves:

using var file = new FileObject("important.db");

try
{
    // If this fails midway (disk full, permission denied, etc.)
    await file.MoveAsync(@"D:\NewLocation\important.db");
}
catch
{
    // Rheo.Storage automatically rolls back the partial operation
    // The original file remains intact at the source
    // No partial operations or corrupted files left behind
}

⚡ Performance Optimizations

Built-in intelligence for efficient operations:

• Smart caching - Metadata cached for 1 second to avoid redundant I/O
• Adaptive buffer sizes - Automatically scales from 1KB to 16MB based on file size
• Same-volume detection - Uses fast rename for moves on the same drive
• Parallel directory operations - DirectoryObject processes files concurrently
• Deferred analysis - File type detection only runs when you access the property

🌐 Cross-Platform Metadata

Access platform-specific information with unified API:

using var file = new FileObject("/home/user/document.txt");

// Platform-agnostic
Console.WriteLine(file.Information.FormattedSize);  // "245 KB"

// Platform-specific details
if (file.Information.PlatformInfo is UnixStorageInfo unix)
{
    Console.WriteLine($"Inode: {unix.Inode}");
    Console.WriteLine($"Permissions: {unix.UnixFileMode}");
    Console.WriteLine($"UID: {unix.UserId}, GID: {unix.GroupId}");
}
else if (file.Information.PlatformInfo is WindowsStorageInfo win)
{
    Console.WriteLine($"Attributes: {win.FileAttributes}");
    Console.WriteLine($"Volume Serial: {win.VolumeSerialNumber}");
}

---

🔗 API Reference

Browse the complete API documentation:

• API Overview
• Storage Objects - Start here for file/directory operations
• Storage Information - Rich metadata and content analysis
• Progress Reporting - Track long-running operations

External Links:

• GitHub Repository
• NuGet Package
• Issue Tracker

---

🎓 Learning Path

New to Rheo.Storage? Follow this recommended progression:

1. Start with FileObject - Learn file operations, progress reporting, and async patterns
2. Explore FileInformation - Understand content analysis and metadata
3. Move to DirectoryObject - Master directory operations and change monitoring
4. Review StorageProgress - Implement custom progress displays
5. Dive into Architecture - Understand the base classes and design patterns

---

💡 Common Scenarios

Validate File Types Before Processing

using var upload = new FileObject(uploadedFilePath);

// User uploaded "photo.jpg" but it's actually an executable
if (upload.Information.ActualExtension != upload.Information.Extension)
{
    throw new SecurityException($"File type mismatch: claimed {upload.Information.Extension}, actually {upload.Information.ActualExtension}");
}

// Verify MIME type matches expected
if (upload.Information.MimeType != "image/jpeg")
{
    throw new InvalidOperationException($"Expected JPEG, got {upload.Information.MimeType}");
}

Backup with Progress and Cancellation

async Task BackupWithFeedback(string sourcePath, string destPath, CancellationToken ct)
{
    using var source = new FileObject(sourcePath);
    
    var progress = new Progress<StorageProgress>(p =>
    {
        var eta = p.BytesPerSecond > 0 
            ? TimeSpan.FromSeconds((p.TotalBytes - p.BytesTransferred) / p.BytesPerSecond)
            : TimeSpan.Zero;
            
        Console.Write($"\rBackup: {p.ProgressPercentage:F1}% | ETA: {eta:mm\\:ss}");
    });
    
    await source.CopyAsync(destPath, progress, cancellationToken: ct, overwrite: true);
    Console.WriteLine("\nBackup complete!");
}

Monitor Project Directory for Changes

using var projectDir = new DirectoryObject(@"C:\MyProject");

projectDir.Changed += async (sender, e) =>
{
    switch (e.ChangeType)
    {
        case StorageChangeType.Created:
            Console.WriteLine($"New file: {e.NewInfo.FullName}");
            await TriggerBuildAsync();
            break;
            
        case StorageChangeType.Modified:
            Console.WriteLine($"Modified: {e.NewInfo.FullName}");
            await TriggerBuildAsync();
            break;
            
        case StorageChangeType.Deleted:
            Console.WriteLine($"Deleted: {e.NewInfo?.FullName ?? "unknown"}");
            break;
            
        case StorageChangeType.Relocated:
            Console.WriteLine($"Moved/Renamed: {e.NewInfo.FullName}");
            break;
    }
};

projectDir.StartWatching(watchInterval: 300); // Custom 300ms debounce

---

Ready to modernize your file system code? Explore the FileObject and DirectoryObject classes to get started.