Zhomfr.Storage.Abstractions 0.7.1

.NET 10.0

dotnet add package Zhomfr.Storage.Abstractions --version 0.7.1

NuGet\Install-Package Zhomfr.Storage.Abstractions -Version 0.7.1

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Zhomfr.Storage.Abstractions" Version="0.7.1" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Zhomfr.Storage.Abstractions" Version="0.7.1" />
                    

                            Directory.Packages.props

<PackageReference Include="Zhomfr.Storage.Abstractions" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Zhomfr.Storage.Abstractions --version 0.7.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Zhomfr.Storage.Abstractions, 0.7.1"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Zhomfr.Storage.Abstractions@0.7.1

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Zhomfr.Storage.Abstractions&version=0.7.1
                    

                            Install as a Cake Addin

#tool nuget:?package=Zhomfr.Storage.Abstractions&version=0.7.1
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Abstractions for Unified Work with Storage.

⚠️ Warning: Active Development (< 1.0.0)

Prior to the release of stable version 1.0.0, this library follows SemVer for initial development. This means breaking changes may occur even in minor releases (0.x).

We strongly recommend pinning the package version in your .csproj to avoid unexpected build errors.

A lightweight and flexible .NET library providing a unified contract for storage functions. It completely decouples your business logic from specific storage driver or third-party implementations.

💡 Core Concept

Your code interacts exclusively with a standardized interface. The underlying drivers is determined at the dependency injection composition root. If you ever need to change the provider tomorrow, you won't need to rewrite your business logic.

Available Drivers:

Local see GitHub NuGet
Ftp see GitHub NuGet
SFtp see GitHub NuGet
S3 see GitHub NuGet

Development Custom Driver

📦 Installation

Install package:

dotnet add package Zhomfr.Storage.Abstractions

For example, you can use code of available drivers in GitHub.

Configuration Convention

All settings are located in appsettings.json under the Zhomfr:Storage section:

The default service uses the Zhomfr:Storage:Default subsection.
Keyed services use subsections where the name matches the service key, resulting in Zhomfr:Storage:KeyName.

For instance, given the following registrations:

builder.Services.AddDefaultStorage<MyAwesomeStorage, MyAwesomeStorageConfig>();
builder.Services.AddKeyedStorage<MyAwesomeStorage, MyAwesomeStorageConfig>("AwesomeKey");

Your appsettings.json file should follow this structure:

{
  "Zhomfr": {
    "Storage": {
      "Default": {
        "BaseUrl": "http://my-awesome.com/storage",
        "RootDir": "/storage/root/dir",
        // ... other configuration properties
      },
      "AwesomeKey": {
        "BaseUrl": "http://my-awesome.com/storage",
        "RootDir": "/storage/root/dir",
        // ... other configuration properties
      }
    }
  }
}

IFileSystemTypeInspector

IStorage

IConfig

Namespace: Zhomfr.Storage.Abstractions

Abstract configuration for storage driver.

public interface IConfig

IDirectoryManager

Namespace: Zhomfr.Storage.Abstractions

Manages directories with support for synchronous and asynchronous operations.

public interface IDirectoryManager

Attributes NullableContextAttribute

Methods

MakeDirectory (String, Boolean)

Create a directory.

bool MakeDirectory(string path, bool recursive = true)

Parameters

path String The directory path.

recursive Boolean Whether to create parent directories.

Returns

Boolean True on success, false on failure.

MakeDirectoryAsync (String, Boolean, CancellationToken)

Asynchronously create a directory.

Task<bool> MakeDirectoryAsync(string path, bool recursive = true, CancellationToken ct = null)

Parameters

path String The directory path.

recursive Boolean Whether to create parent directories.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing the operation success.

DeleteDirectory (String)

Recursively delete a directory.

bool DeleteDirectory(string directory)

Parameters

directory String The directory path.

Returns

Boolean True on success, false on failure.

DeleteDirectoryAsync (String, CancellationToken)

Asynchronously delete a directory.

Task<bool> DeleteDirectoryAsync(string directory, CancellationToken ct = null)

Parameters

directory String The directory path.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing the operation success.

CleanDirectory (String)

Empty the specified directory of all files and folders.

bool CleanDirectory(string directory)

Parameters

directory String The directory path.

Returns

Boolean True on success, false on failure.

CleanDirectoryAsync (String, CancellationToken)

Asynchronously empty the specified directory.

Task<bool> CleanDirectoryAsync(string directory, CancellationToken ct = null)

Parameters

directory String The directory path.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing the operation success.

IsEmptyDirectory (String)

Determine if the given path is an empty directory.

bool IsEmptyDirectory(string directory)

Parameters

directory String The directory path.

Returns

Boolean True if the directory is empty, false otherwise.

IsEmptyDirectoryAsync (String, CancellationToken)

Asynchronously determine if the given path is an empty directory.

Task<bool> IsEmptyDirectoryAsync(string directory, CancellationToken ct = null)

Parameters

directory String The directory path.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing whether the directory is empty.

IDirectoryScanner

Namespace: Zhomfr.Storage.Abstractions

Scan directories with support for synchronous and asynchronous operations.

public interface IDirectoryScanner

Attributes NullableContextAttribute

Methods

Files (String, Boolean)

Get files in the given directory.

IEnumerable<string> Files(string directory, bool hidden = false)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

Returns

IEnumerable<String> A file paths enumerable.

FilesAsync (String, Boolean, CancellationToken)

Asynchronously get files in the given directory.

IAsyncEnumerable<string> FilesAsync(string directory, bool hidden = false, CancellationToken ct = null)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

ct CancellationToken The cancellation token.

Returns

IAsyncEnumerable<String> An asynchronous enumerable of file paths.

AllFiles (String, Boolean)

Get all files from the given directory recursively.

IEnumerable<string> AllFiles(string directory, bool hidden = false)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

Returns

IEnumerable<String> All recursive file paths enumerable.

AllFilesAsync (String, Boolean, CancellationToken)

Asynchronously get all files from the given directory recursively.

IAsyncEnumerable<string> AllFilesAsync(string directory, bool hidden = false, CancellationToken ct = null)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

ct CancellationToken The cancellation token.

Returns

IAsyncEnumerable<String> An asynchronous enumerable of all recursive file paths.

Directories (String, Boolean)

Get directories within a given directory.

IEnumerable<string> Directories(string directory, bool hidden = false)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

Returns

IEnumerable<String> Directory paths enumerable.

DirectoriesAsync (String, Boolean, CancellationToken)

Asynchronously iterate through directories in the given directory.

IAsyncEnumerable<string> DirectoriesAsync(string directory, bool hidden = false, CancellationToken ct = null)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

ct CancellationToken The cancellation token.

Returns

IAsyncEnumerable<String> An asynchronous enumerable of directory paths.

AllDirectories (String, Boolean)

Get all directories from the given directory recursively.

IEnumerable<string> AllDirectories(string directory, bool hidden = false)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

Returns

IEnumerable<String> Directory paths enumerable.

AllDirectoriesAsync (String, Boolean, CancellationToken)

Asynchronously get all directories from the given directory recursively.

IAsyncEnumerable<string> AllDirectoriesAsync(string directory, bool hidden = false, CancellationToken ct = null)

Parameters

directory String The directory path.

hidden Boolean Whether to include hidden files.

ct CancellationToken The cancellation token.

Returns

IAsyncEnumerable<String> An asynchronous enumerable of directory paths.

IFileManager

Namespace: Zhomfr.Storage.Abstractions

Provides high-level file management operations including moving, copying, and deleting files. All operations support both synchronous and asynchronous execution for local and remote storage compatibility.

public interface IFileManager

Attributes NullableContextAttribute

Methods

Get (String)

Retrieve a file from the storage at the given path.

SmartFile? Get(string path)

Parameters

path String The path to the file.

Returns

SmartFile? An Zhomfr.Helpers.SmartFile.SmartFile instance for data access.

GetAsync (String, CancellationToken)

Asynchronously retrieve a file from the storage.

Task<SmartFile?> GetAsync(string path, CancellationToken ct = null)

Parameters

path String The path to the file.

ct CancellationToken The cancellation token.

Returns

Task<SmartFile> A task representing the retrieved Zhomfr.Helpers.SmartFile.SmartFile.

Put (String, SmartFile)

Write an Zhomfr.Helpers.SmartFile.SmartFile object to the specified path. This method consumes the stream from the provided file object.

bool Put(string path, SmartFile storageFile)

Parameters

path String The destination path.

storageFile SmartFile The file object to persist.

Returns

Boolean True if the file was stored successfully.

PutAsync (String, SmartFile, CancellationToken)

Asynchronously write an Zhomfr.Helpers.SmartFile.SmartFile object to the specified path.

Task<bool> PutAsync(string path, SmartFile storageFile, CancellationToken ct = null)

Parameters

path String The destination path.

storageFile SmartFile The file object to persist.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing the operation success.

Delete (String)

Delete the file at the given path.

bool Delete(string path)

Parameters

path String The path to the file to be deleted.

Returns

Boolean True if the file was successfully deleted, false otherwise.

DeleteAsync (String, CancellationToken)

Asynchronously delete the file at the given path.

Task<bool> DeleteAsync(string path, CancellationToken ct = null)

Parameters

path String The path to the file to be deleted.

ct CancellationToken The cancellation token to cancel the operation.

Returns

Task<Boolean> A task representing the operation success.

Move (String, String)

Move a file to a new location.

bool Move(string path, string target)

Parameters

path String The current source path of the file.

target String The destination path where the file should be moved.

Returns

Boolean True if the file was successfully moved, false otherwise.

MoveAsync (String, String, CancellationToken)

Asynchronously move a file to a new location.

Task<bool> MoveAsync(string path, string target, CancellationToken ct = null)

Parameters

path String The current source path of the file.

target String The destination path where the file should be moved.

ct CancellationToken The cancellation token to cancel the operation.

Returns

Task<Boolean> A task representing the operation success.

Copy (String, String)

Copy a file to a new location.

bool Copy(string path, string target)

Parameters

path String The source path of the file.

target String The destination path where the file should be copied.

Returns

Boolean True if the file was successfully copied, false otherwise.

CopyAsync (String, String, CancellationToken)

Asynchronously copy a file to a new location.

Task<bool> CopyAsync(string path, string target, CancellationToken ct = null)

Parameters

path String The source path of the file.

target String The destination path where the file should be copied.

ct CancellationToken The cancellation token to cancel the operation.

Returns

Task<Boolean> A task representing the operation success.

IFileSystemMetadata

Namespace: Zhomfr.Storage.Abstractions

Provides methods for inspecting metadata of files and directories. Supports synchronous and asynchronous execution for local and remote storage compatibility.

public interface IFileSystemMetadata

Attributes NullableContextAttribute

Methods

Size (String)

Gets the total logical size of the file (s) at the specified path in bytes.

long Size(string path)

Parameters

path String The path to the file or directory.

Returns

Int64 The total size in bytes based on the content length.

Remarks:

This returns the actual length of the file content (the sum of raw data bytes). It does NOT reflect the "Size on disk," as it excludes file system metadata, directory structures (MFT/inodes), and physical allocation overhead such as cluster padding, disk compression, or sparse file optimization.

SizeAsync (String, CancellationToken)

Asynchronously gets the total logical size of the file (s) at the specified path in bytes.

Task<long> SizeAsync(string path, CancellationToken ct = null)

Parameters

path String The path to the file or directory.

ct CancellationToken The cancellation token.

Returns

Task<Int64> The total size in bytes based on the content length.

Remarks:

CreatedAt (String)

Get creation time of file or directory.

DateTimeOffset CreatedAt(string path)

Parameters

path String The file or directory path.

Returns

DateTimeOffset A DateTime representing created time.

Remarks:

⚠️ WARNING: File creation and modification timestamps depend entirely on the underlying storage driver and server filesystem capabilities (e.g., remote FTP/SFTP often lacks reliable creation time or birthtime support). Use dedicated metadata storage if strict timestamp consistency is required.

CreatedAtAsync (String, CancellationToken)

Asynchronously get creation time of file or directory.

Task<DateTimeOffset> CreatedAtAsync(string path, CancellationToken ct = null)

Parameters

path String The file or directory path.

ct CancellationToken The cancellation token.

Returns

Task<DateTimeOffset> A task representing the created time.

Remarks:

LastModified (String)

Get last modification time of file or directory.

DateTimeOffset LastModified(string path)

Parameters

path String The file or directory path.

Returns

DateTimeOffset A DateTime representing last modification time.

Remarks:

LastModifiedAsync (String, CancellationToken)

Asynchronously get last modification time of file or directory.

Task<DateTimeOffset> LastModifiedAsync(string path, CancellationToken ct = null)

Parameters

path String The file or directory path.

ct CancellationToken The cancellation token.

Returns

Task<DateTimeOffset> A task representing the last modification time.

Remarks:

IFileSystemState

Namespace: Zhomfr.Storage.Abstractions

Provides methods for inspecting state of files and directories. Supports synchronous and asynchronous execution for local and remote storage compatibility.

public interface IFileSystemState

Attributes NullableContextAttribute

Methods

Exists (String)

Determine if file or directory exists at the given path.

bool Exists(string path)

Parameters

path String The path to check.

Returns

Boolean True if path exists, false otherwise.

ExistsAsync (String, CancellationToken)

Asynchronously determine if file or directory exists at the given path.

Task<bool> ExistsAsync(string path, CancellationToken ct = null)

Parameters

path String The path to check.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing whether path exists.

Missing (String)

Determine if file or directory is missing at the given path.

bool Missing(string path)

Parameters

path String The path to check.

Returns

Boolean True if path does not exist, false otherwise.

MissingAsync (String, CancellationToken)

Asynchronously determine if file or directory is missing at the given path.

Task<bool> MissingAsync(string path, CancellationToken ct = null)

Parameters

path String The path to check.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing whether path is missing.

IFileSystemTypeInspector

Namespace: Zhomfr.Storage.Abstractions

Provides methods for inspecting type of filesystem objects. Supports synchronous and asynchronous execution for local and remote storage compatibility.

public interface IFileSystemTypeInspector

Attributes NullableContextAttribute

Methods

IsDirectory (String)

Determine if the given path is a directory.

bool IsDirectory(string path)

Parameters

path String The path to check.

Returns

Boolean True if path is a directory, false otherwise.

IsDirectoryAsync (String, CancellationToken)

Asynchronously determine if the given path is a directory.

Task<bool> IsDirectoryAsync(string path, CancellationToken ct = null)

Parameters

path String The path to check.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing whether path is a directory.

IsFile (String)

Determine if the given path is a file.

bool IsFile(string path)

Parameters

path String The path to check.

Returns

Boolean True if path is a file, false otherwise.

IsFileAsync (String, CancellationToken)

Asynchronously determine if the given path is a file.

Task<bool> IsFileAsync(string path, CancellationToken ct = null)

Parameters

path String The path to check.

ct CancellationToken The cancellation token.

Returns

Task<Boolean> A task representing whether path is a file.

IStorage

Namespace: Zhomfr.Storage.Abstractions

A unified filesystem contract that aggregates specific functional interfaces. Provides a Laravel-like API.

public interface IStorage : IDirectoryManager, IDirectoryScanner, IFileManager, IFileSystemMetadata, IFileSystemState, IFileSystemTypeInspector

Implements IDirectoryManager, IDirectoryScanner, IFileManager, IFileSystemMetadata, IFileSystemState, IFileSystemTypeInspector

Fields

Default

Default datetime if object not exists.

public static DateTimeOffset Default;

DIRECTORY_SEPARATOR

Unified Path Separator: The contract uses a standardized path separator format. The underlying driver will automatically translate it to match the target filesystem. Using Windows-specific separators (\) may lead to unpredictable behavior.

public static string DIRECTORY_SEPARATOR;

Methods

GetUrl (String)

Gets the full public URL for the file at the given path.

string? GetUrl(string path)

Parameters

path String The relative path to the file.

Returns

String? A string representing the public URL of the file.

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- Zhomfr.Helpers.SmartFile (>= 0.7.1)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Zhomfr.Storage.Abstractions:

Package	Downloads
Zhomfr.Storage.Local Package Description	48

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
0.7.1	49	11/7/2026