QDM.FileManager (1.0.0)
Installation
dotnet nuget add source --name pascal --username your_username --password your_token https://gitea.2mets.be/api/packages/pascal/nuget/index.jsondotnet add package --source pascal --version 1.0.0 QDM.FileManagerAbout this package
File management
FileManager — Robust File I/O Utilities for .NET
FileManager is a production‑grade utility class that provides safe, efficient, and concurrency‑friendly file operations for .NET applications. It includes synchronous and asynchronous methods for reading, writing, appending, atomic updates, binary operations, metadata access, lock detection, and retry logic.
This class is ideal for:
- Logging systems
- Configuration/state files
- Concurrent file access
- Crash‑safe updates
- High‑throughput async pipelines
Features
- Streaming text reads (
IEnumerable/IAsyncEnumerable) - Full‑file reads (sync + async)
- Atomic writes (text + binary)
- Append operations (single + multiple lines)
- Binary read/write support
- Directory‑safety helpers
- File deletion & truncation
- Metadata helpers (size, timestamps)
- File lock detection
- Try‑pattern safe wrappers
- Retry helpers for transient I/O failures
- UTF‑8 (no BOM) encoding
- Concurrency‑safe (
FileShare.ReadWrite) - Optimized file access (
SequentialScan, async I/O)
Constructor
var fm = new FileManager("path/to/file.txt");
Optional buffer size:
var fm = new FileManager("file.log", bufferSize: 8192);
Reading Methods
ReadLines
Lazily streams lines from the file.
- Does not load the entire file into memory
- Safe for large files
- Allows concurrent readers/writers
foreach (var line in fm.ReadLines())
{
Console.WriteLine(line);
}
ReadLinesAsync
Asynchronous streaming line reader.
await foreach (var line in fm.ReadLinesAsync())
{
Console.WriteLine(line);
}
Read
Reads the entire file into a string.
string content = fm.Read();
ReadAsync
Async full‑file read.
string content = await fm.ReadAsync();
ReadBytes / ReadBytesAsync
Binary read operations.
byte[] data = fm.ReadBytes();
byte[] dataAsync = await fm.ReadBytesAsync();
Writing Methods
WriteAtomic
Crash‑safe atomic write using a temp file + File.Replace.
fm.WriteAtomic("new content");
Guarantees:
- No partial writes
- Safe during crashes
- Safe with concurrent readers
WriteAtomicAsync
Async version of atomic write.
await fm.WriteAtomicAsync("new content");
WriteBytesAtomic / WriteBytesAtomicAsync
Binary atomic write.
fm.WriteBytesAtomic(data);
await fm.WriteBytesAtomicAsync(data);
Append Methods
AppendLine / AppendLineAsync
Appends a single line to the file.
fm.AppendLine("hello");
await fm.AppendLineAsync("hello");
AppendLines / AppendLinesAsync
Appends multiple lines efficiently.
fm.AppendLines(new[] { "a", "b", "c" });
await fm.AppendLinesAsync(new[] { "a", "b", "c" });
File & Directory Helpers
FileExists
if (fm.FileExists()) { ... }
EnsureDirectoryExists
Creates the directory if missing.
fm.EnsureDirectoryExists();
Delete / DeleteAsync
Deletes the file if it exists.
fm.Delete();
await fm.DeleteAsync();
Clear
Truncates the file without deleting it.
fm.Clear();
GetSize
Returns file size in bytes.
long size = fm.GetSize();
GetLastWriteTimeUtc
Returns last write timestamp.
DateTime? ts = fm.GetLastWriteTimeUtc();
Lock Detection
IsLocked
Detects whether another process has the file open with exclusive access.
bool locked = fm.IsLocked();
Try‑Pattern Safe Wrappers
TryRead
if (fm.TryRead(out var content))
{
Console.WriteLine(content);
}
TryReadLines
if (fm.TryReadLines(out var lines))
{
foreach (var line in lines)
Console.WriteLine(line);
}
Retry Helpers
WithRetries
Retries an action on IOException.
FileManager.WithRetries(() => fm.WriteAtomic("data"));
WithRetriesAsync
Async retry helper.
await FileManager.WithRetriesAsync(() => fm.WriteAtomicAsync("data"));
Atomic File Writes Explained
Atomic writes ensure:
- The file is either fully written or not written at all
- No partial or corrupted files appear
- Crashes cannot leave the file in an inconsistent state
- Concurrent readers never see half‑written data
This is achieved by:
- Writing to a temporary file
- Closing and flushing it
- Atomically replacing the original file using
File.Replace
This operation is atomic on NTFS and POSIX filesystems when the temp file is in the same directory.
Summary
FileManager is a complete, production‑ready file utility class designed for reliability, safety, and performance.
It covers nearly every file operation needed in real‑world .NET applications.