Bitzsoft.Integrations.FileStorage.Azure 1.0.0-alpha.1

Bitzsoft.Integrations.FileStorage.Azure

Azure Blob Storage 文件存储实现。

功能特性

• 完整实现 IFileStore 接口：覆盖存储桶管理、文件读写、删除、预签名 URL 等核心操作
• SAS 令牌预签名 URL：通过 Azure SharedKey 生成 Blob SAS 下载 / 上传地址，无需暴露存储账户密钥给客户端
• 配置提供器模式：通过 IAzureBlobConfigProvider 抽象配置获取，支持静态配置或动态配置中心
• 自动创建存储桶：保存文件时若目标容器不存在将自动创建

注意事项

• CopyFileAsync 和 MoveFileAsync 当前抛出 NotImplementedException，后续版本将实现
• 预签名上传 URL 生成需要配置 AccountKey（SharedKey 凭证）

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.FileStorage.Azure

PackageReference

<PackageReference Include="Bitzsoft.Integrations.FileStorage.Azure" Version="1.0.0" />

配置

appsettings.json

{
  "AzureBlob": {
    "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=your-account-key;EndpointSuffix=core.windows.net",
    "AccountKey": "your-account-key",
    "DefaultBucketName": "my-app-container",
    "UploadUrlExpiration": 3600,
    "DownloadUrlExpiration": 3600
  }
}

注册服务

基础注册

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 注册文件名 / 存储桶名称处理器工厂
services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 注册 Azure Blob 配置
services.AddSingleton<IAzureBlobConfigProvider, AzureBlobConfigProvider>();

// 注册文件存储服务
services.AddSingleton<IAzureBlobFileStore, AzureFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAzureBlobFileStore>());

从 IConfiguration 绑定配置

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();

services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 从配置节绑定 AzureOptions
services.AddSingleton<IAzureBlobConfigProvider>(sp =>
{
    var options = configuration.GetSection("AzureBlob").Get<AzureOptions>();
    return new AzureBlobConfigProvider(options);
});

services.AddSingleton<IAzureBlobFileStore, AzureFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAzureBlobFileStore>());

使用 IOptions 模式

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

services.AddSingleton<IFileNameProcessorFactory, DefaultFileNameProcessorFactory>();
services.AddSingleton<IBucketNameProcessorFactory, DefaultBucketNameProcessorFactory>();

// 配置选项
services.Configure<AzureOptions>(
    configuration.GetSection("AzureBlob"));

// AzureBlobConfigProvider 内部通过 IOptions<AzureOptions> 获取配置
services.AddSingleton<IAzureBlobConfigProvider, AzureBlobConfigProvider>();
services.AddSingleton<IAzureBlobFileStore, AzureFileStore>();
services.AddSingleton<IFileStore>(sp => sp.GetRequiredService<IAzureBlobFileStore>());

使用示例

保存文件并生成 SAS 下载链接

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;

public class DocumentService
{
    private readonly IFileStore _fileStore;

    public DocumentService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<string> UploadAndGetDownloadUrlAsync(
        Stream documentStream, string documentName)
    {
        // 保存文件到默认容器
        var result = await _fileStore.SaveFileAsync(
            documentStream, documentName);

        // 生成带 SAS 令牌的下载链接
        var downloadUrl = await _fileStore.GenerateDownloadUrlAsync(
            result.FilePath);

        return downloadUrl;
    }
}

指定容器保存文件

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;

public class AvatarService
{
    private readonly IFileStore _fileStore;

    public AvatarService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> SaveAvatarAsync(
        Stream imageStream, string userId, string fileExtension)
    {
        var args = new SaveFileArgs($"avatars/{userId}.{fileExtension}", imageStream)
        {
            BucketName = "user-uploads",
            ContentType = $"image/{fileExtension}"
        };

        return await _fileStore.SaveFileAsync(args);
    }
}

生成客户端直传 URL

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;

public class UploadPreparationService
{
    private readonly IFileStore _fileStore;

    public UploadPreparationService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    /// <summary>
    /// 生成 SAS 直传 URL，供前端通过 PUT 请求直接上传到 Azure Blob
    /// </summary>
    public async Task<DirectUploadParam> PrepareDirectUploadAsync(
        string blobName, string containerName)
    {
        var args = new GenerateUploadUrlArgs(blobName)
        {
            BucketName = containerName
        };

        // 返回的 DirectUploadParam.Url 包含完整的 SAS 查询参数
        // 前端使用 PUT 请求直接上传
        var uploadParam = await _fileStore.GenerateUploadUrlAsync(args);
        return uploadParam;
    }
}

存储桶（容器）管理

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;

public class ContainerManager
{
    private readonly IFileStore _fileStore;

    public ContainerManager(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task EnsureContainerExistsAsync(string containerName)
    {
        var exists = await _fileStore.BucketExistsAsync(containerName);
        if (!exists)
        {
            await _fileStore.CreateBucketAsync(containerName);
        }
    }

    public async Task RemoveContainerAsync(string containerName)
    {
        var exists = await _fileStore.BucketExistsAsync(containerName);
        if (exists)
        {
            await _fileStore.DeleteBucketAsync(containerName);
        }
    }
}

从远程 URL 下载文件到 Azure Blob

using Bitzsoft.Integrations.FileStorage;
using Bitzsoft.Integrations.FileStorage.Azure;

public class ExternalFileSyncService
{
    private readonly IFileStore _fileStore;

    public ExternalFileSyncService(IFileStore fileStore)
    {
        _fileStore = fileStore;
    }

    public async Task<FileResult> ImportFromUrlAsync(
        string sourceUrl, string saveAs, string containerName)
    {
        var args = new SaveFileByUrlArgs(saveAs, sourceUrl)
        {
            BucketName = containerName
        };

        return await _fileStore.SaveFileByUrlAsync(args);
    }
}

核心类型一览

依赖

• Bitzsoft.Integrations.FileStorage -- 基础抽象层
• Azure.Storage.Blobs -- Azure Blob Storage 官方 SDK
• Microsoft.Extensions.Options -- 选项模式支持

相关包

• Bitzsoft.Integrations.FileStorage -- 多云文件存储抽象层
• Bitzsoft.Integrations.FileStorage.Aliyun -- 阿里云 OSS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aws -- AWS S3 文件存储实现