MasLazu.AspNet.Storage 1.0.0-preview.1

MasLazu.AspNet.Storage

A unified, dependency injection-friendly storage abstraction library for ASP.NET Core applications that supports multiple cloud storage providers through a single, consistent API.

Features

• Unified API: Single interface for all storage providers
• Dependency Injection: Seamlessly integrates with ASP.NET Core DI container
• Configuration Validation: Built-in validation with helpful error messages
• Multiple Providers: Support for 13+ storage providers
• FluentStorage Integration: Powered by the robust FluentStorage library

About FluentStorage

This library is built on top of FluentStorage, a powerful and flexible storage abstraction library. While FluentStorage provides excellent functionality, it typically requires constructing connection strings manually. MasLazu.AspNet.Storage enhances this by providing a clean, strongly-typed configuration interface through appsettings.json, eliminating the need to build complex connection strings in your code.

Instead of:

string connectionString = "aws.s3://keyId=access;key=secret;bucket=mybucket;region=us-east-1";
var storage = StorageFactory.Blobs.FromConnectionString(connectionString);

You can simply configure in appsettings.json:

{
  "Storage": {
    "Provider": "S3",
    "S3": {
      "AccessKey": "access",
      "SecretKey": "secret",
      "BucketName": "mybucket",
      "Region": "us-east-1"
    }
  }
}

And inject IBlobStorage directly into your services.

Supported Storage Providers

• Amazon S3 - AWS Simple Storage Service
• MinIO - Self-hosted S3-compatible object storage
• DigitalOcean Spaces - S3-compatible object storage from DigitalOcean
• Azure Blob Storage - Microsoft's cloud blob storage
• Azure Data Lake Gen2 - Azure's big data analytics storage
• Azure Service Fabric - Distributed systems storage
• Google Cloud Storage - Google's cloud object storage
• Azure Key Vault - Secure key management and storage
• Databricks File System - Databricks unified data platform
• Local File System - Local disk storage for development
• In-Memory Storage - Volatile memory storage for testing
• ZIP Archives - Compressed file storage
• FTP - File Transfer Protocol
• SFTP - Secure File Transfer Protocol

Installation

dotnet add package MasLazu.AspNet.Storage

Quick Start

1. Configure your storage provider in appsettings.json:

{
  "Storage": {
    "Provider": "S3",
    "S3": {
      "AccessKey": "your-access-key",
      "SecretKey": "your-secret-key",
      "BucketName": "your-bucket",
      "Region": "us-east-1"
    }
  }
}

2. Register the service in Program.cs:

builder.Services.AddMasLazuStorage(builder.Configuration);

3. Inject and use IBlobStorage in your services:

public class FileService
{
    private readonly IBlobStorage _storage;

    public FileService(IBlobStorage storage)
    {
        _storage = storage;
    }

    public async Task UploadFileAsync(string fileName, Stream content)
    {
        await _storage.WriteAsync(fileName, content);
    }
}

Configuration

Amazon S3

{
  "Storage": {
    "Provider": "S3",
    "S3": {
      "AccessKey": "your-access-key",
      "SecretKey": "your-secret-key",
      "BucketName": "your-bucket-name",
      "Region": "us-east-1",
      "ServiceUrl": "https://s3.amazonaws.com"
    }
  }
}

MinIO

{
  "Storage": {
    "Provider": "MinIO",
    "MinIO": {
      "AccessKey": "your-access-key",
      "SecretKey": "your-secret-key",
      "BucketName": "your-bucket-name",
      "Endpoint": "http://localhost:9000"
    }
  }
}

DigitalOcean Spaces

{
  "Storage": {
    "Provider": "DigitalOceanSpaces",
    "DigitalOceanSpaces": {
      "AccessKey": "your-access-key",
      "SecretKey": "your-secret-key",
      "BucketName": "your-bucket-name",
      "Region": "nyc3"
    }
  }
}

Azure Blob Storage

{
  "Storage": {
    "Provider": "AzureBlob",
    "AzureBlob": {
      "ConnectionString": "AccountName=youraccount;AccountKey=yourkey;",
      "ContainerName": "your-container",
      "BlobServiceUrl": "https://youraccount.blob.core.windows.net"
    }
  }
}

Azure Data Lake Gen2

{
  "Storage": {
    "Provider": "AzureDataLake",
    "AzureDataLake": {
      "AccountName": "youraccount",
      "AccountKey": "yourkey",
      "FileSystem": "your-filesystem"
    }
  }
}

Google Cloud Storage

{
  "Storage": {
    "Provider": "GoogleCloud",
    "GoogleCloud": {
      "BucketName": "your-bucket-name",
      "CredentialsJson": "{ \"type\": \"service_account\", \"project_id\": \"your-project\", ... }",
      "ProjectId": "your-project-id"
    }
  }
}

Azure Key Vault

{
  "Storage": {
    "Provider": "AzureKeyVault",
    "AzureKeyVault": {
      "VaultName": "your-vault-name",
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "TenantId": "your-tenant-id"
    }
  }
}

Local File System

{
  "Storage": {
    "Provider": "Local",
    "Local": {
      "RootPath": "/path/to/storage/directory"
    }
  }
}

In-Memory Storage

{
  "Storage": {
    "Provider": "InMemory",
    "InMemory": {
      "Name": "my-memory-storage"
    }
  }
}

FTP

{
  "Storage": {
    "Provider": "Ftp",
    "Ftp": {
      "Host": "ftp.example.com",
      "Port": 21,
      "Username": "your-username",
      "Password": "your-password",
      "RootPath": "/optional/root/path"
    }
  }
}

SFTP

{
  "Storage": {
    "Provider": "Sftp",
    "Sftp": {
      "Host": "sftp.example.com",
      "Port": 22,
      "Username": "your-username",
      "Password": "your-password",
      "PrivateKeyPath": "/path/to/private/key",
      "RootPath": "/optional/root/path"
    }
  }
}

ZIP Archive

{
  "Storage": {
    "Provider": "Zip",
    "Zip": {
      "Path": "/path/to/archive.zip"
    }
  }
}

Databricks

{
  "Storage": {
    "Provider": "Databricks",
    "Databricks": {
      "Endpoint": "https://your-workspace.databricks.com",
      "Token": "your-databricks-token",
      "Path": "/your/storage/path"
    }
  }
}

Azure Service Fabric

{
  "Storage": {
    "Provider": "AzureServiceFabric",
    "AzureServiceFabric": {
      "ConnectionString": "fabric:/your/application/your/service"
    }
  }
}

Usage Examples

Basic File Operations

public class StorageService
{
    private readonly IBlobStorage _storage;

    public StorageService(IBlobStorage storage)
    {
        _storage = storage;
    }

    public async Task UploadFileAsync(string fileName, byte[] content)
    {
        using var stream = new MemoryStream(content);
        await _storage.WriteAsync(fileName, stream);
    }

    public async Task<byte[]> DownloadFileAsync(string fileName)
    {
        using var stream = new MemoryStream();
        await _storage.ReadToStreamAsync(fileName, stream);
        return stream.ToArray();
    }

    public async Task<bool> FileExistsAsync(string fileName)
    {
        return await _storage.ExistsAsync(fileName);
    }

    public async Task DeleteFileAsync(string fileName)
    {
        await _storage.DeleteAsync(fileName);
    }

    public async Task<IEnumerable<string>> ListFilesAsync(string prefix = "")
    {
        return await _storage.ListAsync(new ListOptions { Prefix = prefix });
    }
}

Advanced Operations

public class AdvancedStorageService
{
    private readonly IBlobStorage _storage;

    public AdvancedStorageService(IBlobStorage storage)
    {
        _storage = storage;
    }

    public async Task CopyFileAsync(string sourceFile, string destinationFile)
    {
        await _storage.CopyAsync(sourceFile, destinationFile);
    }

    public async Task MoveFileAsync(string sourceFile, string destinationFile)
    {
        await _storage.MoveAsync(sourceFile, destinationFile);
    }

    public async Task<Blob> GetFileInfoAsync(string fileName)
    {
        return await _storage.GetBlobAsync(fileName);
    }

    public async Task SetMetadataAsync(string fileName, Dictionary<string, string> metadata)
    {
        await _storage.SetBlobAsync(new Blob(fileName) { Metadata = metadata });
    }
}

Configuration Validation

The library includes comprehensive validation for all configuration options:

• Required fields are validated
• Format validation for URLs, GUIDs, and other structured data
• Provider-specific rules (e.g., S3 bucket naming, Azure container naming)
• Startup validation prevents application startup with invalid configuration

Invalid configurations will throw detailed validation errors at startup.

Error Handling

try
{
    await _storage.WriteAsync("file.txt", stream);
}
catch (StorageException ex)
{
    // Handle storage-specific errors
    _logger.LogError(ex, "Failed to upload file");
}
catch (ValidationException ex)
{
    // Handle configuration validation errors
    _logger.LogError(ex, "Invalid storage configuration");
}

Testing

The library is designed to be easily testable. For unit tests, you can mock IBlobStorage:

public class FileServiceTests
{
    [Fact]
    public async Task UploadFileAsync_Should_Call_Storage_Write()
    {
        // Arrange
        var mockStorage = new Mock<IBlobStorage>();
        var service = new FileService(mockStorage.Object);
        var content = new MemoryStream(Encoding.UTF8.GetBytes("test content"));

        // Act
        await service.UploadFileAsync("test.txt", content);

        // Assert
        mockStorage.Verify(s => s.WriteAsync("test.txt", content), Times.Once);
    }
}

For integration tests, use the In-Memory provider:

{
  "Storage": {
    "Provider": "InMemory",
    "InMemory": {
      "Name": "test-storage"
    }
  }
}

Building and Testing

# Build the solution
dotnet build

# Run tests
dotnet test

# Run specific test project
dotnet test test/MasLazu.AspNet.Storage.Test/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/MasLazu/MasLazu.AspNet.Storage.git
cd MasLazu.AspNet.Storage

# Build and test
dotnet build
dotnet test

License

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

Dependencies

• FluentStorage (5.6.0) - Core storage abstraction
• FluentStorage.AWS (5.5.0) - AWS S3 support
• FluentStorage.GCP (5.3.0) - Google Cloud Storage support
• FluentStorage.FTP (5.4.0) - FTP/SFTP support
• FluentValidation.AspNetCore (11.3.1) - Configuration validation
• SSH.NET (2025.0.0) - SFTP implementation

Version History

1.0.0

• Initial release with support for 13 storage providers
• Comprehensive configuration validation
• Full test coverage
• ASP.NET Core dependency injection integration