Table of Contents

Interface IFileManager

Namespace
NuvTools.Storage
Assembly
NuvTools.Storage.dll

Defines the contract for managing file storage operations.

public interface IFileManager

Methods

AddFileAsync(IFile, string?, CancellationToken)

Adds a single file to the storage repository.

Task<IFile> AddFileAsync(IFile file, string? rootDir = null, CancellationToken cancellationToken = default)

Parameters

file IFile

The file to add.

rootDir string

Optional root directory path where the file should be stored.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IFile>

A task representing the asynchronous operation, containing the added file with updated metadata.

AddFileAsync(Stream, string, string, CancellationToken)

Uploads a stream directly to storage at the specified path.

Task<IFile> AddFileAsync(Stream stream, string filePath, string contentType, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream containing the file content.

filePath string

The full path where the file should be stored in the repository.

contentType string

The MIME type of the file content.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IFile>

A task representing the asynchronous operation, containing the uploaded file metadata.

AddFilesAsync(IFile[], CancellationToken)

Adds multiple files to the storage repository.

Task<IReadOnlyList<IFile>> AddFilesAsync(IFile[] files, CancellationToken cancellationToken = default)

Parameters

files IFile[]

The array of files to add.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IReadOnlyList<IFile>>

A task representing the asynchronous operation, containing the collection of added files with updated metadata.

AddFilesAsync(string, IFile[], CancellationToken)

Adds multiple files to a specified root directory in the storage repository.

Task<IReadOnlyList<IFile>> AddFilesAsync(string rootDir, IFile[] files, CancellationToken cancellationToken = default)

Parameters

rootDir string

The root directory path where files should be stored.

files IFile[]

The array of files to add.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IReadOnlyList<IFile>>

A task representing the asynchronous operation, containing the collection of added files with updated metadata.

CopyFileAsync(string, string, CancellationToken)

Copies a file to another path in the same repository, replacing what is there.

Task<IFile> CopyFileAsync(string sourcePath, string targetPath, CancellationToken cancellationToken = default)

Parameters

sourcePath string

The path of the file to copy.

targetPath string

The path of the copy.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IFile>

A task representing the asynchronous operation, containing the metadata of the copy.

Exceptions

FileNotFoundException

Thrown when sourcePath does not exist.

ArgumentException

Thrown when both paths are the same.

DownloadFileAsync(string, Stream, CancellationToken)

Writes the content of a file to a stream.

Task<bool> DownloadFileAsync(string filePath, Stream destination, CancellationToken cancellationToken = default)

Parameters

filePath string

The path of the file in the repository.

destination Stream

The stream the content is written to. It is left open.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<bool>

A task representing the asynchronous operation, containing true if the file was downloaded, or false if it does not exist.

FileExistsAsync(string, CancellationToken)

Checks whether a file exists in the storage repository.

Task<bool> FileExistsAsync(string id, CancellationToken cancellationToken = default)

Parameters

id string

The unique identifier of the file.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<bool>

A task representing the asynchronous operation, containing true if the file exists; otherwise, false.

GetFileAsync(string, bool, CancellationToken)

Retrieves a file from the storage repository by its identifier.

Task<IFile?> GetFileAsync(string id, bool download = false, CancellationToken cancellationToken = default)

Parameters

id string

The unique identifier of the file.

download bool

If true, downloads the file content; otherwise, returns only metadata.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IFile>

A task representing the asynchronous operation, containing the file if found; otherwise, null.

GetFileSignedUri(string, TimeSpan, AccessPermissions)

Gets a signed URI for accessing a specific file with specified permissions.

Uri GetFileSignedUri(string filePath, TimeSpan validFor, AccessPermissions permissions = AccessPermissions.Read)

Parameters

filePath string

The path to the file in the repository.

validFor TimeSpan

The duration for which the signed URI should be valid.

permissions AccessPermissions

The access permissions to grant. Defaults to Read.

Returns

Uri

A signed URI that can be used to access the file with the specified permissions.

GetFilesAsync(int?, CancellationToken)

Retrieves a paginated list of files from the storage repository.

Task<IReadOnlyList<IFile>> GetFilesAsync(int? pageSize, CancellationToken cancellationToken = default)

Parameters

pageSize int?

The maximum number of files to retrieve per page. If null, all files are retrieved.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IReadOnlyList<IFile>>

A task representing the asynchronous operation, containing the collection of files.

GetRepositorySignedUri(AccessPermissions)

Gets a signed URI for accessing the storage repository with specified permissions.

Uri GetRepositorySignedUri(AccessPermissions permissions = AccessPermissions.Read)

Parameters

permissions AccessPermissions

The access permissions to grant. Defaults to Read.

Returns

Uri

A signed URI that can be used to access the repository with the specified permissions.

ListFilesAsync(string?, CancellationToken)

Lists the files whose path starts with a prefix, without downloading them.

IAsyncEnumerable<FileDescriptor> ListFilesAsync(string? prefix = null, CancellationToken cancellationToken = default)

Parameters

prefix string

The beginning of the paths to list, such as invoices/2026/. A repository has no real folders: a folder is the prefix its files share. null or empty lists every file.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

IAsyncEnumerable<FileDescriptor>

The files found, as the provider returns them, read page by page as the sequence is consumed.

MoveFileAsync(string, string, CancellationToken)

Moves a file to another path in the same repository, which is also how a file is renamed.

Task<IFile> MoveFileAsync(string sourcePath, string targetPath, CancellationToken cancellationToken = default)

Parameters

sourcePath string

The path of the file to move.

targetPath string

The new path of the file. What is there is replaced.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<IFile>

A task representing the asynchronous operation, containing the metadata of the file at its new path.

Remarks

The file is copied and then the original is removed. If the removal fails the file exists at both paths; it is never lost.

Exceptions

FileNotFoundException

Thrown when sourcePath does not exist.

ArgumentException

Thrown when both paths are the same.

MoveFilesAsync(string, string, CancellationToken)

Moves every file whose path starts with a prefix to another prefix, keeping the rest of each path — which is how a folder is renamed.

Task<int> MoveFilesAsync(string sourcePrefix, string targetPrefix, CancellationToken cancellationToken = default)

Parameters

sourcePrefix string

The beginning of the paths to move, such as drafts/.

targetPrefix string

What replaces sourcePrefix in each path, such as final/.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<int>

A task representing the asynchronous operation, containing the number of files moved.

Remarks

Files are moved one at a time. If it stops midway, the files already moved stay at the target and the others at the source; running it again finishes the move.

Exceptions

ArgumentException

Thrown when a prefix is empty or both are the same.

RemoveFileAsync(string, CancellationToken)

Removes a file from the storage repository.

Task RemoveFileAsync(string id, CancellationToken cancellationToken = default)

Parameters

id string

The unique identifier of the file to remove.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task

A task representing the asynchronous operation.

RemoveFilesAsync(string, CancellationToken)

Removes every file whose path starts with a prefix — which is how a folder is removed.

Task<int> RemoveFilesAsync(string prefix, CancellationToken cancellationToken = default)

Parameters

prefix string

The beginning of the paths to remove. It cannot be empty: emptying a repository is not done by accident.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<int>

A task representing the asynchronous operation, containing the number of files removed.

Exceptions

ArgumentException

Thrown when prefix is empty.