Oakrey.Applications.Files 3.0.2

Oakrey.Applications.Files

A .NET 10 class library that provides file and directory management through a single injectable service interface. It supports synchronous and asynchronous operations, thread-safe file access via SemaphoreSlim, age-based cleanup, and full OpenTelemetry tracing and structured logging on every operation.

Main features

• Read file content as a string, synchronously or asynchronously with CancellationToken support
• Read and write files via FileStream
• Save text content to a file with automatic intermediate directory creation
• Create directories on demand
• Delete a single file by path
• Delete files in a directory that are older than a given TimeSpan, with optional extension filter
• Enumerate all file paths in a directory tree by extension
• Thread-safe async load and save backed by SemaphoreSlim
• Every operation emits an OpenTelemetry activity span and structured log entries via Oakrey.Log

Architecture

classDiagram
    class IFileService {
        +CreateFolder(folderName)
        +CreateSaveStream(fileName) FileStream
        +DeleteFile(fileName)
        +DeleteFileOlderThan(path, timeSpan, extension, ct) Task
        +GetFilesPaths(folder, extension) string[]
        +LoadFile(fileName) string
        +LoadFileAsync(fileName, ct) Task~string~
        +LoadFileStream(fileName) FileStream
        +SaveFile(fileName, value)
    }

    class FileService {
        -ILogger logger
        -ITracing tracer
        -SemaphoreSlim semaphoreSlim
        +FileService()
    }

    IFileService <|.. FileService

Requirements

• .NET 10 or higher
• Oakrey.Log 2.0.0 or higher
• Oakrey.Telemetry 2.0.1 or higher

Installation

NuGet Package Manager

1. In Visual Studio open Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
2. Search for Oakrey.Applications.Files and click Install.

.NET CLI

dotnet add package Oakrey.Applications.Files

Package Manager Console

Install-Package Oakrey.Applications.Files

Configuration

FileService has no required configuration. Register it with the DI container of your choice:

// Microsoft.Extensions.DependencyInjection
services.AddSingleton<IFileService, FileService>();

Oakrey.Log and Oakrey.Telemetry must be configured separately according to their own documentation before FileService is resolved.

Example usage

public class ReportExporter(IFileService fileService)
{
    // Save a text report, directories are created automatically
    public async Task SaveReportAsync(string path, string content, CancellationToken ct)
    {
        fileService.SaveFile(path, content);
    }

    // Load a text report asynchronously
    public async Task<string> LoadReportAsync(string path, CancellationToken ct)
    {
        return await fileService.LoadFileAsync(path, ct);
    }

    // Write binary output via stream
    public FileStream OpenWriteStream(string path)
    {
        return fileService.CreateSaveStream(path);
    }

    // Remove log files older than 30 days
    public Task CleanupLogsAsync(string logDirectory, CancellationToken ct)
    {
        return fileService.DeleteFileOlderThan(logDirectory, TimeSpan.FromDays(30), "log", ct);
    }

    // List all CSV files in a directory tree
    public string[] GetCsvFiles(string root)
    {
        return fileService.GetFilesPaths(root, "csv");
    }
}

Development notes

• SaveFile and LoadFileAsync share a single SemaphoreSlim(1,1) instance to prevent concurrent read/write collisions on the same FileService instance. Register the service as a singleton to benefit from this guarantee.
• DeleteFileOlderThan uses file.LastWriteTime for age comparison and respects CancellationToken between file deletions.
• Every public method wraps its body in a try/catch, logs the error via Oakrey.Log, and re-throws so callers receive the original exception with full context.
• All operations start an OpenTelemetry Activity via Oakrey.Telemetry.Tracing; configure an exporter in the host to capture traces.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author: Oakrey
Repository: https://dev.azure.com/oakrey/OpenPackages/_git/ApplicationServices
Project URL: http://www.oakrey.cz/opkg_applications