FileForge

High-performance .NET system engineering library for thread-safe streaming I/O, RFC 4180 delimited file writing, volume resolution, hardware performance detection, and directory synchronization.

📖 Framework Documentation: English Specification | Spécification en français

---

Key Capabilities

1. High-Performance Streaming I/O & Cryptography (FileForge.IO)

• FileCopier: Stream-based direct copy engine supporting cooperative cancellation (CancellationToken), dynamic buffer size calculation (64 KB to 16 MB), metadata and ACL preservation, and cryptographic integrity verification.
• PersistentDelimitedFileWriter: Thread-safe delimited file writer (CSV, TSV) with non-blocking shared access (FileShare.ReadWrite), dynamic deduplication cache rehydration, and RFC 4180 compliance (automatic escaping of commas, quotes, and line breaks).
• DelimitedRecordReader: RFC 4180 reader that returns each record with the line it starts on, quoted fields holding line breaks included.
• AtomicFileWriter: Replaces a file through a temporary file and a rename, so that a reader or a crash sees the previous content or the new one, with recovery of an interrupted write.
• ProtectedFileStore: Secure local secret storage using Windows DPAPI (ProtectedData under CurrentUser) with AES-256 fallback and application-specific entropy.
• Cryptographic Hashing: Synchronous and asynchronous SHA-256 and SHA-512 hashing for disk files, memory streams, and magic byte file header inspections.

2. Physical & Network Storage Resolution (FileForge.Storage)

• VolumeIdentityResolver: Extracts and normalizes Windows physical volume serial numbers (VOL:XXXXXXXX) and network root shares (UNC:\\server\share), enabling reliable disk identification across drive letter changes.
• HardwarePerformanceAdvisor: Queries disk hardware characteristics (SSD vs. HDD magnetic media), calculates optimal copy thread parallelism based on CPU core counts and storage bus throughput, and evaluates available physical RAM.

3. Directory Synchronization Engine (FileForge.Sync)

• DirectorySynchronizer: Exact 1:1 directory mirroring with orphan deletion, incremental catalog-driven backups, and high-speed parallel file discovery.

---

Installation

Add the package via the .NET CLI:

dotnet add package FileForge.Core --version 1.4.1

---

Code Example

using System.Text;
using FileForge.IO;

// Appends to audit.csv with shared read/write access; the header is written only when the file is created.
await using (var writer = new PersistentDelimitedFileWriter("audit.csv", "Timestamp,Host,Port,Process"))
{
    await writer.InitializeAsync();

    string[] fields = ["2026-10-24T12:00:00Z", "nas.home.arpa", "443", "=cmd|' /C calc'!A0"];

    // neutralizeFormulas: true keeps a spreadsheet from evaluating a field that starts with =, +, - or @.
    var line = string.Join(',', fields.Select(field => PersistentDelimitedFileWriter.EscapeField(field, ',', neutralizeFormulas: true)));
    await writer.AppendLineAsync(line);
}

// Reads the file back record by record; quoted fields may hold delimiters and line breaks.
using var reader = new StreamReader("audit.csv");
await foreach (var record in DelimitedRecordReader.ReadRecordsAsync(reader))
{
    Console.WriteLine($"{record.LineNumber}: {string.Join(" | ", record.Fields)}");
}

// NDJSON without a byte order mark, which some JSON Lines readers reject.
await using var ndjson = new PersistentDelimitedFileWriter("audit.ndjson", string.Empty, new UTF8Encoding(false));
await ndjson.InitializeAsync();
await ndjson.AppendLineAsync("""{"host":"nas.home.arpa","port":443}""");

// Replaces a file so that a reader or a crash sees the previous content or the new one, never a mix.
await AtomicFileWriter.WriteAllTextAsync("settings.json", """{"interval":30}""");

---

License

This project is licensed under the MIT License.