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

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
  }
}

注册服务

使用 DI 扩展方法（推荐）

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

var services = new ServiceCollection();

// 一行注册 Azure Blob 文件存储服务（内部自动注册处理器工厂、配置提供器、第三方请求日志基础设施）
services.AddBitzsoftAzureBlobFileStorage(options =>
{
    options.ConnectionString = "DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=your-account-key;EndpointSuffix=core.windows.net";
    options.AccountKey = "your-account-key";
    options.DefaultBucketName = "my-app-container";
});

手动注册

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>());

第三方请求日志

⚠️ 机制说明：本连接器基于 Azure.Storage.Blobs SDK，HTTP 管道封装在 SDK 内部，无法用 DelegatingHandler 拦截（与 HttpClient 直连实现不同）。因此请求日志改由 IRequestLogRecorder 回调钩子实现——在对象存储操作包装层记录每次 API 调用，汇入与 HttpClient 拦截同一个日志管道（IRequestLogStore），由宿主统一持久化。

记录内容（每个对象存储操作产生一条）：

局限（诚实声明）：

• SDK 不暴露原始 HTTP 状态码与响应头，故无法像 HttpClient 拦截那样记录真实 HTTP StatusCode/RequestHeaders，StatusCode 仅为尽力而为（成功记 200、异常时留空）。
• 仅本连接器已实现的对象存储操作会被记录；SDK 的其他能力（如生命周期、跨域、权限策略等）本连接器未实现，不在记录范围。

// ① 默认：启用回调但不持久化（日志丢弃）
services.AddBitzsoftAzureBlobFileStorage(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，对象存储操作自动落库
//    AddBitzsoftAzureBlobFileStorage 内部已注入 IRequestLogRecorder，宿主无需再额外挂载 handler
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 0;               // 下载响应可能很长，0=不截断完整保留
    opts.SensitiveFields.Add("mySecret"); // 额外脱敏字段
});
services.AddBitzsoftAzureBlobFileStorage(options => { /* ... */ });

自定义 IRequestLogStore 实现（SqlSugar / Dapper / MongoDB）详见 Bitzsoft.Integrations.RequestLogging。

使用示例

保存文件并生成 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.Compatibility -- 基础工具库
• Bitzsoft.Integrations.FileStorage -- 多云文件存储抽象层
• Azure.Storage.Blobs -- Azure Blob Storage 官方 SDK
• Microsoft.Extensions.Options -- 选项模式支持

相关包

• Bitzsoft.Integrations.FileStorage -- 多云文件存储抽象层
• Bitzsoft.Integrations.FileStorage.Minio -- MinIO 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aliyun -- 阿里云 OSS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Aws -- AWS S3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Tencent -- 腾讯云 COS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Huawei -- 华为云 OBS 文件存储实现
• Bitzsoft.Integrations.FileStorage.Kingsoft -- 金山云 KS3 文件存储实现
• Bitzsoft.Integrations.FileStorage.Qiniu -- 七牛云 Kodo 文件存储实现
• Bitzsoft.Integrations.FileStorage.Upyun -- 又拍云文件存储实现
• Bitzsoft.Integrations.FileStorage.Nas -- NAS / 本地文件系统存储实现
• Bitzsoft.Integrations.FileStorage.All -- 全部云存储实现聚合包