NuvTools.Storage 10.1.0

NuvTools.Storage

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

Table of Contents

• 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.

Copyright © 2026 Nuv Tools