Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Production-ready file system utilities for .NET with automatic error recovery and multi-platform support.
- 🛡️ Resilient File System Monitoring - Production-ready FileSystemWatcher with automatic fallback
- 🔄 Auto-Recovery - Handles directory disappearing/reappearing, permission errors, watcher crashes
- ⚡ Efficient & Reliable - Automatic switching between FileSystemWatcher (efficient) and polling (resilient)
- 🎯 Debouncing - Built-in debouncing to reduce noise from rapid file changes
- 🚀 High-Performance File Search - Fast directory traversal with lazy evaluation
- 🔐 Secure File Reading - Read files as bytes with shared access support (prevent immutable strings in memory)
- 🌍 Cross-Platform - Tested on Windows, Linux, and macOS
- 📦 Zero Dependencies - Lightweight with no external dependencies
dotnet add package Cocoar.FileSystemMonitor directories with automatic error recovery and fallback:
using Cocoar.FileSystem;
var monitor = ResilientFileSystemMonitor
.Watch(@"C:\configs", "*.json")
.WithDebounce(500) // Optional: reduce noise from rapid changes
.OnChanged((sender, e) => Console.WriteLine($"Changed: {e.Name}"))
.OnCreated((sender, e) => Console.WriteLine($"Created: {e.Name}"))
.Build();
// Multiple file patterns (certificates example):
var monitor = ResilientFileSystemMonitor
.Watch(@"C:\certs")
.WithFilter("*.pfx", "*.p12", "*.cer") // Monitor multiple extensions
.OnChanged((sender, e) => Console.WriteLine($"Certificate changed: {e.Name}"))
.Build();
// With subdirectory monitoring (depth control):
var monitor = ResilientFileSystemMonitor
.Watch(@"C:\configs", "*.json")
.IncludeSubdirectories(2) // Monitor up to 2 levels deep
.OnChanged((sender, e) => Console.WriteLine($"Changed: {e.FullPath}"))
.Build();
// Detect folder renames (certificate rotation scenario):
var monitor = ResilientFileSystemMonitor
.Watch(@"C:\certs")
.WithFilter("*.pfx")
.IncludeSubdirectories()
.OnRenamed((sender, e) =>
{
// Fires when folders containing .pfx files are renamed
// OR when individual .pfx files are renamed
Console.WriteLine($"Renamed: {e.OldFullPath} -> {e.FullPath}");
})
.Build();Key Features: Auto-recovery, debouncing, depth control, reactive streams, health checks
📖 Full Guide | Reactive Examples
Fast, lazy-evaluated directory traversal with fluent API:
using Cocoar.FileSystem;
// Find all C# files in a project (excluding build folders)
var codeFiles = FileSearcher
.Search(@"C:\repos\myproject", "*.cs")
.Excluding("bin", "obj", "node_modules")
.WithMaxDepth(5)
.ToList();
// Multiple file patterns (harmonized with ResilientFileSystemMonitor API)
var projectFiles = FileSearcher
.InDirectory(@"C:\repos\myapp")
.WithFilter("*.cs", "*.csproj", "*.json")
.IncludeSubdirectories(2) // Search 2 levels deep
.ToList();
// Lazy evaluation with LINQ
var largeFiles = FileSearcher
.InDirectory(@"C:\data")
.WithPattern("*.log")
.Recursively()
.Where(file => new FileInfo(file).Length > 1_000_000)
.Take(10);
// Search only current directory (no recursion)
var configs = FileSearcher
.Search(@"C:\app", "*.json")
.WithMaxDepth(0) // Current directory only
.ToArray();Key Features: Lazy evaluation, depth limits, exclusion patterns, LINQ support, efficient for large directories
📖 Examples
Read files with shared access and security features:
using Cocoar.FileSystem;
byte[] content = FileReader.ReadAllBytes(@"C:\config.dat");
try
{
ProcessSensitiveData(content);
}
finally
{
Array.Clear(content, 0, content.Length); // Zero out when done
}Key Features: Shared read/write access, BOM stripping, try-pattern, byte array zeroing
📖 Full Guide
- ResilientFileSystemMonitor Guide - Detailed usage guide
- Subdirectory Depth Control - Fine-grained recursive monitoring
- FileReader Guide - Secure file reading with shared access
- Examples - More usage examples
- Reactive Examples - Advanced reactive patterns with Rx.NET
- Event Ordering Guarantees - Thread-safety and event ordering
- Test Coverage - Comprehensive test documentation
- ✅ No crashes when directory doesn't exist initially
- ✅ No silent failures when watcher encounters errors
- ✅ Handles Docker volume mounts appearing after container start
- ✅ Handles network share availability issues
- ✅ Built-in debouncing (no need for manual throttling)
- ✅ Production-ready error handling
- ✅ Cross-platform compatibility
| Option | Type | Default | Description |
|---|---|---|---|
| Path | string | (required) | Directory path to monitor |
| Filter | string | "*" | File filter pattern (e.g., ".json", ".txt") - supports multiple patterns |
| IncludeSubdirectories | bool | false | Monitor subdirectories recursively |
| MaxDepth | int | 0 | Maximum subdirectory depth (0=root only, -1=unlimited) |
| NotifyFilter | NotifyFilters | LastWrite | FileName | Size | Types of changes to watch for |
| EnablePollingFallback | bool | true | Enable automatic polling fallback |
| PollingInterval | TimeSpan | 5 seconds | How often to poll when in fallback mode |
| AutoRecoverFromErrors | bool | true | Automatically switch to polling on errors |
| DebounceTime | TimeSpan? | null | Optional debouncing to reduce event noise |
Control how deep to monitor subdirectories:
// Don't monitor subdirectories (default)
.Watch(@"C:\certs") // Only watches C:\certs\*.pfx
// Monitor all subdirectories (unlimited depth)
.Watch(@"C:\certs")
.IncludeSubdirectories() // or .IncludeSubdirectories(true) or .IncludeSubdirectories(-1)
// Monitor with depth limit
.Watch(@"C:\certs")
.IncludeSubdirectories(1) // Only direct children: C:\certs\prod\*.pfx
.IncludeSubdirectories(2) // Two levels: C:\certs\prod\2025\*.pfxAll operations are thread-safe. Events are raised sequentially on a background thread, guaranteeing:
- ✅ Events are delivered in the order they occurred
- ✅ No concurrent event handler invocations (unless you subscribe multiple handlers)
- ✅ When using the Events channel, you have full control over concurrency
Always dispose when done:
using var monitor = ResilientFileSystemMonitor
.Watch(@"C:\data")
.Build();
// Use monitor...
// Automatically disposed at end of scope- SemVer (additive MINOR, breaking MAJOR)
- PRs & issues welcome
This project is licensed under the Apache License, Version 2.0. See NOTICE for attribution.
"Cocoar" and related marks are trademarks of COCOAR e.U. Use of the name in forks or derivatives should preserve attribution and avoid implying official endorsement. See TRADEMARKS for permitted and restricted uses.