Handler File

Overview

VersaTul.Handler.File wraps common file-system operations and adds typed file models for working with text, CSV, custom extensions, zip content, and raw streams.

The package is useful when you want file operations behind interfaces for easier testing and when higher-level packages need to persist typed file content rather than manually coordinate paths, extensions, and stream writes.

When To Use This Package

Use this package when you want to:

  1. Read or write files through abstractions instead of calling System.IO directly.

  2. Save typed file content such as text, CSV, custom files, or zip streams.

  3. Add async wrappers around common file operations.

  4. Reuse path, extension, and directory helpers across the codebase.

  5. Support export workflows from Collection Streamers and archive workflows from Compression.

Installation

Install the package with the .NET CLI:

dotnet add package VersaTul.Handler.File

Or with the Package Manager Console:

PM> NuGet\Install-Package VersaTul.Handler.File -Version latest

Core Types And Concepts

IFileHandler

Combines file and directory wrappers plus helper operations such as extension handling, file discovery, and line-by-line reading.

IFileUtility and FileUtility

Higher-level file service for reading all content, saving typed files, and async wrappers.

IDirectoryWrapper and IFileWrapper

Thin abstractions over file-system APIs used by the higher-level handlers.

FileResult

Result model returned by reads, including existence and blank-file flags.

FileInfo and typed variants

File models such as TextFileInfo, CsvFileInfo, CustomFileInfo, StreamFileInfo, and ZipFileInfo.

Key Capabilities

  1. ReadAll() and ReadAllAsync() read text files into a FileResult.

  2. SaveOrUpdate() and SaveOrUpdateAsync() append or create text-based files.

  3. Save() and SaveAsync() persist stream-based files.

  4. Path and extension helpers simplify file naming and discovery.

  5. Directory creation is handled automatically before writes.

Save Text Example

using VersaTul.Handler.File;
using VersaTul.Handler.File.Types;

var directoryWrapper = new DirectoryWrapper();
var fileUtility = new FileUtility(directoryWrapper, directoryWrapper);

var file = new TextFileInfo("C:\\exports", "report", "Large amount of text to save");
fileUtility.SaveOrUpdate(file);

Read Example

var result = fileUtility.ReadAll("C:\\exports\\report.txt");

if (result.IsExists)
{
    foreach (var line in result.Content)
    {
        Console.WriteLine(line);
    }
}

Save Stream Example

using var memoryStream = new MemoryStream(System.Text.Encoding.UTF8.GetBytes("hello"));

var streamFile = new ZipFileInfo("C:\\exports", "archive", memoryStream);
await fileUtility.SaveAsync(streamFile);

Notes

  1. FileUtility uses a lock to serialize writes from the same process.

  2. The async methods are wrapper-based async, which is useful for consistency at the service boundary.

  3. The typed file models are the main value-add over direct System.IO usage.