NuvTools.Storage

A suite of .NET libraries for abstracting and simplifying storage operations, with comprehensive support for Microsoft Azure Blob Storage.

Overview
Features
Installation
Quick Start
Usage Examples
Target Frameworks
Building from Source
Documentation
License

Overview

NuvTools.Storage provides a clean, intuitive abstraction layer for file storage operations. The library follows a provider pattern, allowing you to implement custom storage solutions while maintaining a consistent API.

Libraries

NuvTools.Storage (Core)

The core library defines the foundational abstractions:

IFileManager - Interface for managing file storage operations (add, get, remove, list, SAS URI generation)
IFile - Represents a file with metadata and content in multiple formats (URI, Stream, Base64)
File - Concrete implementation supporting three initialization modes
AccessPermissions - Enum for fine-grained access control (Read, Write, Delete, List, etc.)
Extension methods for seamless conversion between Stream and Base64 formats

NuvTools.Storage.Azure

Azure Blob Storage implementation:

AzureFileManager - Full IFileManager implementation for Azure Blob Storage
Security - Helper class for generating signed tokens for Azure Storage
Automatic conversion between Azure SDK types and NuvTools abstractions
Support for paginated file listing
Parallel batch file uploads
Direct stream uploads to specific blob paths
File-level signed URI generation with custom expiration
Built on Azure.Storage.Blobs SDK

Features

✅ Provider Pattern - Easy to implement custom storage providers ✅ Async/Await - Fully asynchronous API with CancellationToken support ✅ Multiple Content Formats - Work with files as URIs, Streams, or Base64 strings ✅ Azure Integration - Production-ready Azure Blob Storage implementation ✅ Signed URI Generation - Container-level and file-level signed URIs with custom expiration ✅ Batch Operations - Upload multiple files in parallel with Task.WhenAll ✅ Direct Stream Uploads - Upload streams directly to specific blob paths ✅ Comprehensive Documentation - Full XML documentation for IntelliSense ✅ Multi-Targeting - Supports .NET 8, 9, and 10

Installation

Install via NuGet Package Manager:

# Core library
dotnet add package NuvTools.Storage

# Azure Blob Storage implementation
dotnet add package NuvTools.Storage.Azure

Or via Package Manager Console:

Install-Package NuvTools.Storage
Install-Package NuvTools.Storage.Azure

Quick Start

Azure Blob Storage Example

using NuvTools.Storage;
using NuvTools.Storage.Azure;

// Initialize the Azure file manager
var fileManager = new AzureFileManager(
    connectionString: "your-azure-storage-connection-string",
    repositoryName: "my-container"
);

// Upload a file from a stream
using var stream = File.OpenRead("document.pdf");
var file = new File("document.pdf", "application/pdf", stream);
var uploadedFile = await fileManager.AddFileAsync(file);

Console.WriteLine($"File uploaded: {uploadedFile.Uri}");

Usage Examples

Working with Files

// Create a file from Base64 string
var file = new File("image.jpg", "image/jpeg", base64String);

// Create a file from stream
using var stream = new MemoryStream(bytes);
var file = new File("data.bin", "application/octet-stream", stream);

// Create a file reference with URI only (no content)
var file = new File("remote.txt", "text/plain", new Uri("https://..."));

Uploading Files

// Upload a single file to a specific directory
var uploadedFile = await fileManager.AddFileAsync(file, rootDir: "documents");

// Upload directly from a stream with explicit path
await using var stream = File.OpenRead("report.pdf");
var uploadedFile = await fileManager.AddFileAsync(
    stream,
    filePath: "reports/2026/report.pdf",
    contentType: "application/pdf"
);

// Batch upload multiple files in parallel
var files = new[] { file1, file2, file3 };
var uploadedFiles = await fileManager.AddFilesAsync(files);

Retrieving Files

// Get file metadata only (no download)
var file = await fileManager.GetFileAsync("document.pdf", download: false);
Console.WriteLine($"File URI: {file.Uri}");

// Download file content
var file = await fileManager.GetFileAsync("document.pdf", download: true);
await using var stream = file.Content;
// Process the stream...

// List all files with pagination
var files = await fileManager.GetFilesAsync(pageSize: 100);
foreach (var file in files)
{
    Console.WriteLine($"{file.Name} - {file.Type}");
}

Managing Files

// Check if a file exists
bool exists = await fileManager.FileExistsAsync("document.pdf");

// Remove a file
await fileManager.RemoveFileAsync("document.pdf");

Generating Signed URIs

// Generate a read-only signed URI for the entire container (valid for 24 hours)
var containerSignedUri = fileManager.GetRepositorySignedUri(AccessPermissions.Read);

// Generate a signed URI for a specific file with custom expiration
var fileSignedUri = fileManager.GetFileSignedUri(
    filePath: "documents/report.pdf",
    validFor: TimeSpan.FromHours(1),
    permissions: AccessPermissions.Read
);

// Generate signed token with custom permissions
var signedToken = Security.GetAccountSignedToken(
    accountName: "myaccount",
    accountKey: "key",
    permissions: AccessPermissions.Read | AccessPermissions.List
);

Target Frameworks

.NET 8.0
.NET 9.0
.NET 10.0

All libraries use C# 12 features and enable nullable reference types for improved null safety.

Building from Source

This solution uses the modern .slnx (XML-based) solution format.

Prerequisites

.NET 10 SDK or later
Visual Studio 2022 17.0+ or Visual Studio Code with C# extension

Build Commands

# Clone the repository
git clone https://github.com/nuvtools/nuvtools-storage.git
cd nuvtools-storage

# Build the solution
dotnet build NuvTools.Storage.slnx

# Run tests
dotnet test NuvTools.Storage.slnx

# Create NuGet packages
dotnet pack NuvTools.Storage.slnx -c Release

The solution structure:

nuvtools-storage/
├── src/
│   ├── NuvTools.Storage/           # Core library
│   └── NuvTools.Storage.Azure/     # Azure implementation
├── tests/
│   └── NuvTools.Storage.Azure.Test/ # NUnit tests
└── NuvTools.Storage.slnx           # Solution file

Documentation

All public APIs include comprehensive XML documentation comments. IntelliSense in Visual Studio, Visual Studio Code, and Rider will display:

Detailed descriptions of all types, methods, and properties
Parameter information with expected values
Return value descriptions
Exception documentation
Usage examples and best practices

XML documentation files are included in the NuGet packages for seamless integration.

License

Licensed under the MIT License.

NuvTools.Storage

A suite of .NET libraries for abstracting and simplifying storage operations, with comprehensive support for Microsoft Azure Blob Storage.

Overview
Features
Installation
Quick Start
Usage Examples
Target Frameworks
Building from Source
Documentation
License

Overview

Libraries

NuvTools.Storage (Core)

The core library defines the foundational abstractions:

IFileManager - Interface for managing file storage operations (add, get, remove, list, SAS URI generation)
IFile - Represents a file with metadata and content in multiple formats (URI, Stream, Base64)
File - Concrete implementation supporting three initialization modes
AccessPermissions - Enum for fine-grained access control (Read, Write, Delete, List, etc.)
Extension methods for seamless conversion between Stream and Base64 formats

NuvTools.Storage.Azure

Azure Blob Storage implementation:

AzureFileManager - Full IFileManager implementation for Azure Blob Storage
Security - Helper class for generating signed tokens for Azure Storage
Automatic conversion between Azure SDK types and NuvTools abstractions
Support for paginated file listing
Parallel batch file uploads
Direct stream uploads to specific blob paths
File-level signed URI generation with custom expiration
Built on Azure.Storage.Blobs SDK

Features

Installation

Install via NuGet Package Manager:

# Core library
dotnet add package NuvTools.Storage

# Azure Blob Storage implementation
dotnet add package NuvTools.Storage.Azure

Or via Package Manager Console:

Install-Package NuvTools.Storage
Install-Package NuvTools.Storage.Azure

Quick Start

Azure Blob Storage Example

using NuvTools.Storage;
using NuvTools.Storage.Azure;

// Initialize the Azure file manager
var fileManager = new AzureFileManager(
    connectionString: "your-azure-storage-connection-string",
    repositoryName: "my-container"
);

// Upload a file from a stream
using var stream = File.OpenRead("document.pdf");
var file = new File("document.pdf", "application/pdf", stream);
var uploadedFile = await fileManager.AddFileAsync(file);

Console.WriteLine($"File uploaded: {uploadedFile.Uri}");

Usage Examples

Working with Files

// Create a file from Base64 string
var file = new File("image.jpg", "image/jpeg", base64String);

// Create a file from stream
using var stream = new MemoryStream(bytes);
var file = new File("data.bin", "application/octet-stream", stream);

// Create a file reference with URI only (no content)
var file = new File("remote.txt", "text/plain", new Uri("https://..."));

Uploading Files

// Upload a single file to a specific directory
var uploadedFile = await fileManager.AddFileAsync(file, rootDir: "documents");

// Upload directly from a stream with explicit path
await using var stream = File.OpenRead("report.pdf");
var uploadedFile = await fileManager.AddFileAsync(
    stream,
    filePath: "reports/2026/report.pdf",
    contentType: "application/pdf"
);

// Batch upload multiple files in parallel
var files = new[] { file1, file2, file3 };
var uploadedFiles = await fileManager.AddFilesAsync(files);

Retrieving Files

// Get file metadata only (no download)
var file = await fileManager.GetFileAsync("document.pdf", download: false);
Console.WriteLine($"File URI: {file.Uri}");

// Download file content
var file = await fileManager.GetFileAsync("document.pdf", download: true);
await using var stream = file.Content;
// Process the stream...

// List all files with pagination
var files = await fileManager.GetFilesAsync(pageSize: 100);
foreach (var file in files)
{
    Console.WriteLine($"{file.Name} - {file.Type}");
}

Managing Files

// Check if a file exists
bool exists = await fileManager.FileExistsAsync("document.pdf");

// Remove a file
await fileManager.RemoveFileAsync("document.pdf");

Generating Signed URIs

// Generate a read-only signed URI for the entire container (valid for 24 hours)
var containerSignedUri = fileManager.GetRepositorySignedUri(AccessPermissions.Read);

// Generate a signed URI for a specific file with custom expiration
var fileSignedUri = fileManager.GetFileSignedUri(
    filePath: "documents/report.pdf",
    validFor: TimeSpan.FromHours(1),
    permissions: AccessPermissions.Read
);

// Generate signed token with custom permissions
var signedToken = Security.GetAccountSignedToken(
    accountName: "myaccount",
    accountKey: "key",
    permissions: AccessPermissions.Read | AccessPermissions.List
);

Target Frameworks

.NET 8.0
.NET 9.0
.NET 10.0

All libraries use C# 12 features and enable nullable reference types for improved null safety.

Building from Source

This solution uses the modern .slnx (XML-based) solution format.

Prerequisites

.NET 10 SDK or later
Visual Studio 2022 17.0+ or Visual Studio Code with C# extension

Build Commands

# Clone the repository
git clone https://github.com/nuvtools/nuvtools-storage.git
cd nuvtools-storage

# Build the solution
dotnet build NuvTools.Storage.slnx

# Run tests
dotnet test NuvTools.Storage.slnx

# Create NuGet packages
dotnet pack NuvTools.Storage.slnx -c Release

The solution structure:

nuvtools-storage/
├── src/
│   ├── NuvTools.Storage/           # Core library
│   └── NuvTools.Storage.Azure/     # Azure implementation
├── tests/
│   └── NuvTools.Storage.Azure.Test/ # NUnit tests
└── NuvTools.Storage.slnx           # Solution file

Documentation

All public APIs include comprehensive XML documentation comments. IntelliSense in Visual Studio, Visual Studio Code, and Rider will display:

Detailed descriptions of all types, methods, and properties
Parameter information with expected values
Return value descriptions
Exception documentation
Usage examples and best practices

XML documentation files are included in the NuGet packages for seamless integration.

License

Licensed under the MIT License.

nuvtools/NuvTools.Storage.Azurev10.1.0

Get Started

Readme

NuvTools.Storage

Table of Contents

Overview

Libraries

NuvTools.Storage (Core)

NuvTools.Storage.Azure

Features

Installation

Quick Start

Azure Blob Storage Example

Usage Examples

Working with Files

Uploading Files

Retrieving Files

Managing Files

Generating Signed URIs

Target Frameworks

Building from Source

Prerequisites

Build Commands

Documentation

License

nuvtools/NuvTools.Storage.Azurev10.1.0

Get Started

Readme

NuvTools.Storage

Table of Contents

Overview

Libraries

NuvTools.Storage (Core)

NuvTools.Storage.Azure

Features

Installation

Quick Start

Azure Blob Storage Example

Usage Examples

Working with Files

Uploading Files

Retrieving Files

Managing Files

Generating Signed URIs

Target Frameworks

Building from Source

Prerequisites

Build Commands

Documentation

License