DevelopmentHelpers.Storage.Core 10.0.3

DevelopmentHelpers.Storage.Core

A small library to simplify working with Azure Blob Storage, Azure FileShare, and local filesystem directories. It provides an easy-to-use API for uploading, downloading and syncing entire directory structures and individual files. The library supports both local and Azure storage implementations and integrates with dependency injection.

Key features

• Unified IStorage interface with implementations for Azure Blob Storage and local filesystem.
• Azure FileShare support via IAzureFileStorage implementation.
• Upload/download entire directories and containers.
• Upload large files in chunks (resumable/large-file friendly).
• Container synchronization helpers (container-to-container and directory-to-container).
• Create ZIP archives from containers.
• Easy configuration using appsettings.json and dependency injection.

Prerequisites

• .NET 10
• Azure Storage account (when using Azure implementations)

Quick start

1. Add the project or NuGet package to your solution.
2. Configure storage settings in appsettings.json (example below).
3. Register services in Program.cs / Startup.cs.
4. Inject IStorage or IAzureFileStorage where needed and call methods.

Configuration (appsettings.json)

Keep the following structure in your appsettings.json under a DevelopmentHelpers section. The values shown are examples — replace them with your account details.

"DevelopmentHelpers": {
  "AzureConfiguration": {
    "AccountName": "Account-Name",
    "AccountKey": "Account-Key",
    "UseHttps": "True"
  },
  "AzureFileStorageConfiguration": {
    "ConnectionString": "Connection-String",
    "ShareName": "Share-Name"
  }
}

Registering services (dependency injection)

1. In Program.cs or Startup.cs register the library services so you can resolve IStorage and IAzureFileStorage from DI. The library exposes an extension method to register required services.

// in Program.cs
services.AddAzureStorage(Configuration);

Note: AddAzureStorage reads the DevelopmentHelpers section from configuration and registers the appropriate implementations.

Registering services using a connection string (no appsettings.json required)

New overloads of the DevelopmentHelpersStorageExtensions allow registering storage services by passing a connection string directly. This is useful when you don't want to rely on IConfiguration or when the connection string is obtained at runtime (environment variable, secret store, etc.).

// Example: register using a full Azure Storage connection string
var connectionString = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net";

// Register both blob and file storage implementations using the connection string
services.AddAzureStorage(connectionString);

// If you only need blob or file storage, use the specific overloads (if available):
// services.AddAzureBlobStorage(connectionString);
// services.AddAzureFileStorage(connectionString, shareName: "my-share");

2. Register Services in Program.cs

    var builder = WebApplication.CreateBuilder(args);

    // Add Azure Blob Storage (IStorage)
    builder.Services.AddAzureBlobStorage(builder.Configuration);

    // Add Azure File Storage (IAzureFileStorage)
    builder.Services.AddAzureFileStorage(builder.Configuration);

    var app = builder.Build();

3. Register Using Connection String for both Blob and File Storage

    var builder = WebApplication.CreateBuilder(args);
    var connectionString = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net";
    // Add Azure Blob and File Storage using connection string
    builder.Services.AddAzureStorage(connectionString);
    var app = builder.Build();

4. Register Using Connection String for Blob Storage Only

    var builder = WebApplication.CreateBuilder(args);
    var connectionString = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net";
    // Add Azure Blob Storage using connection string
    builder.Services.AddAzureBlobStorage(connectionString);
    var app = builder.Build();

5. Register Using Strongly Typed Configuration Objects

    var azureConfig = new AzureConfiguration
    {
        AccountName = "devstoreaccount1",
        AccountKey = "...",
        UseHttps = false,
        AllowPublicAccess = false
    };

builder.Services.AddAzureBlobStorage(azureConfig);

These overloads will internally parse the connection string and initialize AzureConfiguration and AzureFileStorageConfiguration equivalents so the library components are ready to use without any JSON configuration.

Advanced registration using options

If you need to customize settings, there are also overloads that accept option builders:

services.AddAzureStorage(options =>
{
    options.ConnectionString = connectionString;
    options.FileShareName = "my-share"; // when relevant
    // other option properties as exposed by the library
});

Notes:

• Using connection strings is convenient for ephemeral or CI scenarios; prefer managed identities or secure secrets stores in production when possible.
• The connection-string-based registration behaves equivalently to the configuration-based registration; only the initialization source differs.

Basic usage examples

Create storage instances (examples)

// Using DI (recommended)
public class MyService
{
    private readonly IStorage _storage;
    private readonly IAzureFileStorage _fileStorage;
    public MyService(IStorage storage, IAzureFileStorage fileStorage)
    {
        _storage = storage;
        _fileStorage = fileStorage;
    }
}

// Or instantiate manually for quick testing
var azureConfig = new Models.AzureConfiguration
{
    AccountName = "...",
    AccountKey = "...",
    UseHttps = true
};
var logger = ConfigHelper.Instance.LoggerFactory.CreateLogger<AzureStorage>();
IStorage storage = new AzureStorage(azureConfig, logger);
IStorage localStorage = new FileSystemStorage(azureConfig /* or local config */, logger);
IAzureFileStorage fileStorage = new AzureFileStorage(/* AzureFileStorageConfiguration */, logger);

Uploading and downloading

// Upload a single file
var fileInfo = new FileInfo("/path/to/file.txt");
var blobUrl = await _storage.UploadFileAsync(fileInfo, MimeTypes.txt, "my-container");

// Upload a Directory
await _storage.UploadDirectoryAsync(new DirectoryInfo("/path/to/folder"), "my-container");

// Download a file (by blob URL)
var downloaded = await _storage.DownloadToFileAsync(blobUrl, "/local/download/path");

// Download entire container to local folder
await _storage.DownloadContainer("my-container", "/local/download/path");

// Create a zip from a container
var zipPath = await _storage.CreateZipFromContainerAsync("my-container", "/tmp", "archive.zip");

Chunked uploads (large files)

// Upload large file in chunks
var uri = await _storage.UploadInChunks(fullFilePath, "container-name", "file-name.txt", MimeTypes.txt);

Checking blobs and containers

// Check existence
bool exists = await _storage.BlobExistsAsync(blobUrl);

// Create a container if not exists
var response = await _storage.CreateContainerAsync("container-name", publicAccess: false);

// List containers
var containers = await _storage.GetContainersAsync();

Sync helpers

The library includes helpers for synchronizing between containers or from a directory to a container.

// Container to container sync
var syncHelper = new ContainerToContainerSyncHelper(sourceStorage, targetStorage);
var (success, message) = await syncHelper.SyncContainersAsync("source", "target", deleteExtraFiles: false, localTempPath: "/tmp");

// Directory to container sync helper
var directorySyncHelper = new DirectoryToContainerSyncHelper(storage);
var result = await directorySyncHelper.GetBlobUrlListExistInTargetButNotInSourceAsync(sourceDirectoryPath, "target-container");

Tips and best practices

• Use UploadInChunks for large files to avoid memory issues.
• Keep container names lowercase when interacting with Azure Blob Storage.
• When uploading directories with nested folders, use consistent path separators (/) for blob names.
• Clean up temporary local directories after operations to avoid consuming disk space.

Testing

The DevelopmentHelpers.Storage.Core.Tests project includes a comprehensive set of integration tests that exercise common flows such as uploading/downloading files, chunked uploads, container sync and zip creation. The tests expect an Azure Storage account configured via ConfigHelper in test settings. You can inspect the test project for sample usage patterns.

Contributing

Contributions and issues are welcome. Please open an issue describing the problem or the feature request and submit pull requests for fixes.

License

Include your license information here (e.g., MIT) or a note about internal use.

If you need a targeted example or the exact code snippet for a specific scenario, describe the scenario and I will add a short sample.