阿里云 OSS C# SDK 使用实践与参数详解

阿里云 OSS（Object Storage Service）提供了一种高效、可靠、安全的存储解决方案，可以用来存储和管理数据文件。阿里云 OSS 的 C# SDK 是一组面向 .NET 开发人员的 API，用于在 C# 中与 OSS 进行交互。

---

1. 安装阿里云 OSS C# SDK

首先，你需要在项目中引入阿里云 OSS 的 SDK。可以通过 NuGet 来安装阿里云的 OSS 客户端 SDK。

在 Visual Studio 中打开 NuGet 包管理器控制台，执行以下命令：

Install-Package Aliyun.OSS.SDK.NetCore

---

2. 配置阿里云 OSS 客户端

要使用 OSS 服务，你需要配置 AccessKeyId、AccessKeySecret 和 Endpoint，这三个参数是连接到 OSS 服务的必备信息。

using Aliyun.OSS;
using System;

class OSSExample
{
    private static string accessKeyId = "你的AccessKeyId";
    private static string accessKeySecret = "你的AccessKeySecret";
    private static string endpoint = "http://oss-cn-hangzhou.aliyuncs.com"; // 区域Endpoint，根据实际情况修改
    private static string bucketName = "你的bucket名称";

    static void Main(string[] args)
    {
        var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
        Console.WriteLine("客户端初始化成功！");
    }
}

---

3. 常用操作及参数详解

1. 创建 OSS 客户端对象

OssClient client = new OssClient(endpoint, accessKeyId, accessKeySecret);

• endpoint：阿里云 OSS 的域名，可以在阿里云控制台获取。
• accessKeyId 和 accessKeySecret：是你在阿里云控制台创建的密钥，用于身份验证。

2. 上传文件到 OSS

 /// <summary>
 /// 上传本地文件到阿里云OSS
 /// </summary>
 /// <param name="localFilePath">本地文件完整路径</param>
 /// <param name="ossObjectName">OSS中存储的文件路径+名称（如：hnt/20221227171528.jpg）</param>
 /// <exception cref="ArgumentNullException">参数为空时抛出</exception>
 /// <exception cref="FileNotFoundException">本地文件不存在时抛出</exception>
 public void UploadFileToOss(string localFilePath, string ossObjectName)
 {
     // 入参合法性校验
     if (string.IsNullOrWhiteSpace(localFilePath))
         throw new ArgumentNullException(nameof(localFilePath), "本地文件路径不能为空");
     if (string.IsNullOrWhiteSpace(ossObjectName))
         throw new ArgumentNullException(nameof(ossObjectName), "OSS对象名称不能为空");
     if (!File.Exists(localFilePath))
         throw new FileNotFoundException("本地文件不存在", localFilePath);

     try
     {
         // 创建客户端并执行上传
         var client = CreateOssClient();
         client.PutObject(bucketName, ossObjectName, localFilePath);
         Console.WriteLine($"文件上传成功！OSS路径：{ossObjectName}");
     }
     catch (OssException ex)
     {
         // 捕获OSS专属异常（含错误码），便于定位问题
         Console.WriteLine($"OSS上传异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
         throw; // 抛出异常让上层处理
     }
     catch (Exception ex)
     {
         Console.WriteLine($"文件上传失败：{ex.Message}");
         throw;
     }
 }

• bucketName：目标存储空间名称。
• objectName：文件在 OSS 中的对象名称。
• localFile：本地文件路径。

3. 下载文件

/// <summary>
/// 从阿里云OSS下载文件到本地
/// </summary>
/// <param name="ossObjectName">OSS中的文件路径+名称</param>
/// <param name="localSavePath">本地保存的完整路径</param>
/// <exception cref="ArgumentNullException">参数为空时抛出</exception>
public void DownloadFileFromOss(string ossObjectName, string localSavePath)
{
    // 入参合法性校验
    if (string.IsNullOrWhiteSpace(ossObjectName))
        throw new ArgumentNullException(nameof(ossObjectName), "OSS对象名称不能为空");
    if (string.IsNullOrWhiteSpace(localSavePath))
        throw new ArgumentNullException(nameof(localSavePath), "本地保存路径不能为空");

    try
    {
        var client = CreateOssClient();
        // 自动创建下载目录（避免目录不存在导致失败）
        string saveDirectory = Path.GetDirectoryName(localSavePath);
        if (!string.IsNullOrEmpty(saveDirectory) && !Directory.Exists(saveDirectory))
        {
            Directory.CreateDirectory(saveDirectory);
        }

        // 构建下载请求并写入本地文件流
        var getRequest = new GetObjectRequest(bucketName, ossObjectName);
        using (var localFileStream = File.OpenWrite(localSavePath))
        {
            client.GetObject(getRequest, localFileStream);
        }

        Console.WriteLine($"文件下载成功！本地路径：{localSavePath}");
    }
    catch (OssException ex)
    {
        Console.WriteLine($"OSS下载异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
        throw;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"文件下载失败：{ex.Message}");
        throw;
    }
}

• 通过指定 OSS 中的对象名来下载文件。

4. 删除文件

/// <summary>
/// 删除阿里云OSS中的指定文件
/// </summary>
/// <param name="ossObjectName">OSS中的文件路径+名称</param>
/// <exception cref="ArgumentNullException">参数为空时抛出</exception>
public void DeleteFileFromOss(string ossObjectName)
{
    if (string.IsNullOrWhiteSpace(ossObjectName))
        throw new ArgumentNullException(nameof(ossObjectName), "OSS对象名称不能为空");

    try
    {
        var client = CreateOssClient();
        client.DeleteObject(bucketName, ossObjectName);
        Console.WriteLine($"文件删除成功！OSS路径：{ossObjectName}");
    }
    catch (OssException ex)
    {
        Console.WriteLine($"OSS删除异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
        throw;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"文件删除失败：{ex.Message}");
        throw;
    }
}

5. 列举文件

/// <summary>
/// 获取OSS指定前缀（目录）下的文件列表
/// </summary>
/// <param name="prefix">文件前缀/目录名（如：hnt/，空则查询整个Bucket）</param>
/// <param name="isRecursive">是否递归查询子目录（true=递归，false=仅当前目录）</param>
/// <param name="maxKeys">返回的最大文件数量（默认1000，最大不超过1000）</param>
/// <returns>文件名称列表（完整OSS路径）</returns>
/// <exception cref="ArgumentOutOfRangeException">maxKeys≤0或>1000时抛出</exception>
public List<string> ListFilesInOss(string prefix = "", bool isRecursive = false, int maxKeys = 1000)
{
    // 入参校验：maxKeys需在1-1000之间（OSS接口限制）
    if (maxKeys <= 0 || maxKeys > 1000)
        throw new ArgumentOutOfRangeException(nameof(maxKeys), "最大返回数量需在1-1000之间");

    try
    {
        var client = CreateOssClient();
        var listRequest = new ListObjectsRequest(bucketName)
        {
            Prefix = prefix ?? "",          // 前缀（目录），为空则查全部
            Delimiter = isRecursive ? null : "/", // 非递归时用/分隔目录，仅返回当前层级
            MaxKeys = maxKeys               // 最大返回数量
        };

        // 执行列表查询
        var listResult = client.ListObjects(listRequest);
        var fileList = new List<string>();

        // 遍历结果，收集文件名称（排除目录占位符）
        foreach (var objectSummary in listResult.ObjectSummaries)
        {
            // 过滤掉目录本身（以/结尾的是目录，不是文件）
            if (!objectSummary.Key.EndsWith("/"))
            {
                fileList.Add(objectSummary.Key);
            }
        }

        Console.WriteLine($"获取文件列表成功！前缀：{prefix}，数量：{fileList.Count}");
        return fileList;
    }
    catch (OssException ex)
    {
        Console.WriteLine($"OSS获取列表异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
        throw;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"获取文件列表失败：{ex.Message}");
        throw;
    }
}

• Prefix：按前缀过滤对象。
• MaxKeys：最大返回的对象数量。

6. 获取文件的元数据

ObjectMetadata metadata = client.GetObjectMetadata(bucketName, "your-object-name.txt");
Console.WriteLine("文件大小: " + metadata.ContentLength);
Console.WriteLine("文件类型: " + metadata.ContentType);

---

4. 详细参数解析

PutObject 方法参数详解：

• bucketName：存储空间名称，必须在阿里云 OSS 中创建并设置权限。
• objectName：上传的对象名，可以理解为文件的路径。
• file：本地文件路径，或者是流数据。

ListObjectsRequest 参数详解：

• Prefix：过滤条件，列出以特定前缀命名的文件。
• MaxKeys：每次返回的文件数量，最大为1000。
• Delimiter：分隔符，用于将文件按目录分层返回。

---

5. 错误处理

在操作 OSS 时，可能会遇到各种错误，可以通过捕获 OssException 来获取更多错误信息：

try
{
    client.PutObject(bucketName, objectName, localFile);
}
catch (OssException ex)
{
    Console.WriteLine("发生错误: " + ex.Message);
}
catch (Exception ex)
{
    Console.WriteLine("未知错误: " + ex.Message);
}

---

6. 生成签名 URL（预签名 URL）

如果你想要生成一个可以在一定时间内访问 OSS 对象的 URL，可以使用以下代码来生成预签名 URL：

DateTime expiration = DateTime.Now.AddMinutes(10);  // 10分钟有效期
string url = client.GeneratePresignedUrl(bucketName, "your-object-name.txt", expiration);
Console.WriteLine("预签名 URL: " + url);

---

7. 异步操作

C# SDK 也支持异步操作，你可以使用 async 和 await 关键字来执行非阻塞操作：

public async Task UploadFileAsync()
{
    string objectName = "your-object-name.txt";
    string localFile = @"C:\path\to\your\file.txt";
    await client.PutObjectAsync(bucketName, objectName, localFile);
    Console.WriteLine("文件上传成功！");
}

---

8. 小结

通过 C# SDK 使用阿里云 OSS 时，你只需关心几个核心的操作，如：上传文件、下载文件、列举文件和删除文件等。以上是一些常用的操作方法和参数解析，你可以根据自己的实际需求灵活应用。

---

👋 关注我！持续分享 C# 实战技巧、代码示例 & 技术干货