Easy.OSS.Net 1.0.10

简介

Easy.OSS.Net 是一个基于 .NET 平台的对象存储服务（OSS）操作库，封装了主流云存储服务（目前只支持阿里云OSS、腾讯云COS）提供的API。开发者通过调用api实现对象存储的上传、下载、管理等操作。 Easy.OSS.Net支持 .NET Standard 2.1、 .NET 6、.NET 7、.NET 8、.NET 9 和 .NET 10 平台。

快速开始

1. 注册服务

// 注册oss服务，可以同时注册阿里云、腾讯云的服务、目前只支持这两种云存储服务；
// 使用时解析服务IOSSProvider，默认拿到的是第一个注册的服务；
// 如果需要指定某个服务，可以使用FromKeyedServices特性，传入注册时的key值来解析对应的服务实例，或通过IOSSProviderBuilder.Build(name)方法来获取对应的服务实例。
//builder.Services.AddOSSService(); // 默认找配置文件OSSProvider配置接点的
builder.Services.AddOSSService("Aliyun", "OSSProvider:Aliyun"); // 阿里云的
builder.Services.AddOSSService("TCloud", "OSSProvider:TCloud"); // 腾讯云的
builder.Services.AddOSSService("Aliyun", options=>{
    // 通过委托配置
}); 

2. 配置文件

在 appsettings.json 中添加对应的配置节： 方式1：如果同时使用多个提供者，可以配置为如下格式：

"OSSProvider": {
    "Aliyun": {
      "Endpoint": "https://oss-cn-guangzhou.aliyuncs.com", // 阿里云必填。支持自定义域名，格式如：https://cdn.customdomain.com
      "Region": "cn-guangzhou",
      "AccessKey": "Your AccessKey",
      "AccessKeySecret": "Your AccessKeySecret",
      "EnableCache": true, // 生成预签名uri是否启用缓存
      "ExpireSeconds": 1*24*3600 // 预签名uri过期时间，默认1天
      "EnableMd5":false, // 上传对象时是否计算并设置Content-MD5头，默认false

    },
    "TCloud": {
      "AppId": "1328436615",
      "Endpoint":null, // 腾讯云默认域名可不填写。如果使用自定义域名，则填写自定义域名，格式如：https://cdn.customdomain.com
      "Region": "ap-guangzhou",
      "AccessKey": "Your AccessKey",
      "AccessKeySecret": "Your AccessKeySecret",
      "EnableCache": true, // 生成预签名uri是否启用缓存
      "ExpireSeconds": 1*24*3600 // 预签名uri过期时间，默认1天
      "EnableMd5":false, // 上传对象时是否计算并设置Content-MD5头，默认false
    }

  }

方式2：如果只使用单一提供者，也可以直接配置为如下格式：

"OSSProvider": {
    "Provider": "Aliyun", // 提供者
    "Endpoint": "https://oss-cn-guangzhou.aliyuncs.com",
     "Region": "cn-guangzhou",
     "AccessKey": "Your AccessKey",
     "AccessKeySecret": "Your AccessKeySecret",
     "EnableCache": true, // 生成预签名uri是否启用缓存
     "ExpireSeconds": 1*24*3600 // 预签名uri过期时间，默认1天
     "EnableMd5":false, // 上传对象时是否计算并设置Content-MD5头，默认false
  }

注意：OSSProvider配置节不提供是否启用https的配置项，库内强制开启https。

3. 使用服务

下面只列出部分常用的API示例：

// 创建oss存储空间
app.MapPost("/bucket", async (string bucketName, [FromService] IOSSProvider ossService) =>
{
    var result = await ossService.CreateBucketAsync(bucketName);
    if (!result)
    {
        return Results.BadRequest("Failed to create bucket.");
    }
    return Results.Ok(result);
})
    .WithDescription("创建存储空间")
    .WithName("创建存储空间");

app.MapGet("/bucketacl", async (string bucketName, [FromKeyedServices("TCloud")] IOSSProvider ossService) =>
{
    var acl = await ossService.GetBucketAclAsync(bucketName);

    return Results.Ok(acl);
})
    .WithDescription("获取存储空间访问权限")
    .WithName("获取存储空间访问权限");

// 列出所有存储空间
app.MapGet("/buckets", async ([FromKeyedServices("TCloud")] IOSSProvider ossService) =>
{
    var buckets = await ossService.ListBucketsAsync();
    return Results.Ok(buckets);
})
    .WithDescription("列出所有存储空间")
    .WithName("列出所有存储空间");

// 上传文件
app.MapPost("/upload", [RequestSizeLimit(5L * 1024 * 1024 * 1024)] async (IFormFile file, HttpContext context, [FromKeyedServices("TCloud")] IOSSProvider ossService) =>
{
    if (file is null || file.Length == 0)
    {
        return Results.BadRequest("No file uploaded.");
    }
    using var stream = file.OpenReadStream();
    var result = await ossService.PutObjectAsync("easy-ossnet-test", file.FileName, stream);
    if (!result)
    {
        return Results.BadRequest("File upload failed.");
    }
    return Results.Ok("File uploaded successfully.");
})
    .WithDescription("上传对象到存储空间")
    .WithName("上传对象到存储空间").DisableAntiforgery();

// 下载文件,通过包含流的回调写入响应，此方式是流式传输的。
app.MapGet("/object", async (HttpContext context, string bucketName, string objectName, [FromKeyedServices("Aliyun")] IOSSProvider provider) =>
{
    // 对文件名进行 URL 编码，处理中文字符
    var encodedFileName = Uri.EscapeDataString(objectName);

    await provider.GetObjectAsync(bucketName, objectName, async (stream, token) =>
    {
        context.Response.ContentType = "application/octet-stream";
        context.Response.Headers.ContentDisposition = $"attachment; filename*=UTF-8''{encodedFileName}";

        await stream.CopyToAsync(context.Response.Body, token);
    },
    (StreamProgressEventArgs args) =>
    {
        Console.WriteLine("Progress: {0}/{1}", args.TransferredBytes, args.TotalBytes);
    });
})
.WithDescription("下载对象")
.WithName("下载对象");

// 下载文件，通过返回的流再包装为文件流返回，此方式内部流是内存流，会将文件全部读入内存，适用于小文件下载。
app.MapGet("/objectStream", async (string bucketName, string objectName, [FromKeyedServices("TCloud")] IOSSProvider provider) =>
{
    var stream = await provider.GetObjectStreamAsync(bucketName, objectName,(StreamProgressEventArgs args) =>
    {
        Console.WriteLine("Progress: {0}/{1}", args.TransferredBytes, args.TotalBytes);
    });

    if (stream == null) return Results.NotFound("Object not found.");
    return Results.File(stream, "application/octet-stream", objectName);
})
    .WithDescription("通过文件流下载")
    .WithName("通过文件流下载");

app.MapGet("/objects", async (string bucketName, [FromKeyedServices("Aliyun")] IOSSProvider provider) =>
{
    var objects = await provider.ListObjectsAsync(bucketName, prefix: null);
    return Results.Ok(objects);
})
    .WithDescription("列出存储空间所有对象")
    .WithName("列出存储空间所有对象");


app.MapGet("acl", async (string bucketName, string objectName, [FromKeyedServices("TCloud")] IOSSProvider provider) =>
{
    var acl = await provider.GetObjectAclAsync(bucketName, objectName);
    if (acl == null) return Results.NotFound("Object not found.");
    return Results.Ok(acl);
})
    .WithDescription("获取对象访问权限")
    .WithName("获取对象访问权限");

app.MapPut("acl", async ([FromBody] ObjectAclInput input, [FromKeyedServices("TCloud")] IOSSProvider provider) =>
{
    var result = await provider.SetObjectAclAsync(input.BucketName, input.ObjectName, input.ControlEnum);
    if (!result) return Results.BadRequest("Failed to set ACL.");
    return Results.Ok("ACL set successfully.");
})
    .WithDescription("设置对象访问权限")
    .WithName("设置对象访问权限");

app.MapGet("metadata", async (string bucketName, string objectName, [FromKeyedServices("Aliyun")] IOSSProvider provider) =>
{
    var metadata = await provider.GetObjectMetaAsync(bucketName, objectName);
    if (metadata == null) return Results.NotFound("Object not found.");
    return Results.Ok(metadata);
})
    .WithDescription("获取对象元数据")
    .WithName("获取对象元数据");

app.MapPut("metadata", async ([FromBody] BucketInput input, [FromKeyedServices("Aliyun")] IOSSProvider provider) =>
{
    var metadata = await provider.GetObjectMetaAsync(input.BucketName, input.ObjectName);
    if (metadata == null) return Results.NotFound("Object not found.");
    metadata.CacheControl = "no-cache";
    metadata.UserMetaData.Add("t1", "测试值1");
    var result = await provider.ModifyObjectMetaAsync(input.BucketName, input.ObjectName, metadata);
    if (!result) return Results.BadRequest("Failed to update metadata.");
    return Results.Ok("Metadata updated successfully.");
})
    .WithDescription("设置对象元数据")
    .WithName("设置对象元数据");

app.MapGet("/objectGetUri", async (string bucketName, string objectName, [FromKeyedServices("Aliyun")] IOSSProvider provider) =>
{
    // 生成一个预签名下载url(强制下载)，有效期3600秒
    var uri = await provider.GeneratePreSignedGetObjectUriAsync(bucketName, objectName, PreSignedGetUriBehavior.ForceDownload,3600);
    return Results.Ok(uri);

})
    .WithDescription("生成一个预签名下载url")
    .WithName("预签名下载url");