faysilalshareef/file-storage

File Storage — Azure Blob & Local Abstraction

Core Principles

• IFileStorage abstracts storage provider from application logic
• Support Azure Blob Storage (production) and local file system (development)
• SAS tokens for secure, time-limited file access
• Structured paths: {container}/{entity-type}/{entity-id}/{filename}
• Content type detection and validation
• Maximum file size enforcement

Key Patterns

File Storage Interface

namespace {Company}.{Domain}.Application.Interfaces;

public interface IFileStorage
{
    Task<string> UploadAsync(string path, Stream content,
        string contentType, CancellationToken ct = default);
    Task<Stream> DownloadAsync(string path, CancellationToken ct = default);
    Task DeleteAsync(string path, CancellationToken ct = default);
    Task<bool> ExistsAsync(string path, CancellationToken ct = default);
    string GetPublicUrl(string path, TimeSpan? expiry = null);
}

Azure Blob Storage Implementation

namespace {Company}.{Domain}.Infrastructure.Storage;

public sealed class AzureBlobFileStorage(
    BlobServiceClient blobClient,
    IOptions<StorageOptions> options) : IFileStorage
{
    public async Task<string> UploadAsync(string path, Stream content,
        string contentType, CancellationToken ct)
    {
        var container = blobClient.GetBlobContainerClient(
            options.Value.ContainerName);
        await container.CreateIfNotExistsAsync(cancellationToken: ct);

        var blob = container.GetBlobClient(path);
        await blob.UploadAsync(content, new BlobHttpHeaders
        {
            ContentType = contentType
        }, cancellationToken: ct);

        return blob.Uri.ToString();
    }

    public async Task<Stream> DownloadAsync(string path, CancellationToken ct)
    {
        var container = blobClient.GetBlobContainerClient(
            options.Value.ContainerName);
        var blob = container.GetBlobClient(path);
        var response = await blob.DownloadStreamingAsync(cancellationToken: ct);
        return response.Value.Content;
    }

    public async Task DeleteAsync(string path, CancellationToken ct)
    {
        var container = blobClient.GetBlobContainerClient(
            options.Value.ContainerName);
        var blob = container.GetBlobClient(path);
        await blob.DeleteIfExistsAsync(cancellationToken: ct);
    }

    public async Task<bool> ExistsAsync(string path, CancellationToken ct)
    {
        var container = blobClient.GetBlobContainerClient(
            options.Value.ContainerName);
        var blob = container.GetBlobClient(path);
        return await blob.ExistsAsync(ct);
    }

    public string GetPublicUrl(string path, TimeSpan? expiry = null)
    {
        var container = blobClient.GetBlobContainerClient(
            options.Value.ContainerName);
        var blob = container.GetBlobClient(path);

        var sasBuilder = new BlobSasBuilder
        {
            BlobContainerName = options.Value.ContainerName,
            BlobName = path,
            Resource = "b",
            ExpiresOn = DateTimeOffset.UtcNow.Add(expiry ?? TimeSpan.FromHours(1))
        };
        sasBuilder.SetPermissions(BlobSasPermissions.Read);

        return blob.GenerateSasUri(sasBuilder).ToString();
    }
}

Local File System Implementation (Development)

namespace {Company}.{Domain}.Infrastructure.Storage;

public sealed class LocalFileStorage(
    IOptions<StorageOptions> options) : IFileStorage
{
    private string BasePath => options.Value.LocalBasePath
        ?? Path.Combine(Path.GetTempPath(), "file-storage");

    public async Task<string> UploadAsync(string path, Stream content,
        string contentType, CancellationToken ct)
    {
        var fullPath = Path.Combine(BasePath, path);
        Directory.CreateDirectory(Path.GetDirectoryName(fullPath)!);

        await using var fileStream = File.Create(fullPath);
        await content.CopyToAsync(fileStream, ct);
        return fullPath;
    }

    public Task<Stream> DownloadAsync(string path, CancellationToken ct)
    {
        var fullPath = Path.Combine(BasePath, path);
        return Task.FromResult<Stream>(File.OpenRead(fullPath));
    }

    public Task DeleteAsync(string path, CancellationToken ct)
    {
        var fullPath = Path.Combine(BasePath, path);
        if (File.Exists(fullPath)) File.Delete(fullPath);
        return Task.CompletedTask;
    }

    public Task<bool> ExistsAsync(string path, CancellationToken ct)
        => Task.FromResult(File.Exists(Path.Combine(BasePath, path)));

    public string GetPublicUrl(string path, TimeSpan? expiry = null)
        => Path.Combine(BasePath, path);
}

Registration

if (builder.Environment.IsDevelopment())
    services.AddSingleton<IFileStorage, LocalFileStorage>();
else
{
    services.AddSingleton(new BlobServiceClient(connectionString));
    services.AddSingleton<IFileStorage, AzureBlobFileStorage>();
}

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Direct BlobClient in handlers | Use IFileStorage abstraction | | No file size validation | Enforce limits before upload | | Permanent public URLs | Use SAS tokens with expiry | | No content type validation | Whitelist allowed content types |

Detect Existing Patterns

# Find file storage interface
grep -r "IFileStorage\|IBlobStorage" --include="*.cs" src/

# Find Azure Blob usage
grep -r "BlobServiceClient\|BlobClient" --include="*.cs" src/

# Find storage configuration
grep -r "StorageOptions\|BlobStorage" --include="*.json" src/

Adding to Existing Project

1. Check for existing IFileStorage interface
2. Use the configured provider based on environment
3. Follow path conventions for organized storage
4. Validate file size and content type before upload
5. Use SAS tokens for time-limited access URLs