阿里云 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 包管理器控制台，执行以下命令：

bash 复制代码

Install-Package Aliyun.OSS.SDK.NetCore

2. 配置阿里云 OSS 客户端

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

csharp 复制代码

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 客户端对象

csharp 复制代码

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

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

2. 上传文件到 OSS

csharp 复制代码

 /// <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. 下载文件

csharp 复制代码

/// <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. 删除文件

csharp 复制代码

/// <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. 列举文件

csharp 复制代码

/// <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. 获取文件的元数据

csharp 复制代码

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 来获取更多错误信息：

csharp 复制代码

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：

csharp 复制代码

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 关键字来执行非阻塞操作：

csharp 复制代码

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# 实战技巧、代码示例 & 技术干货

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

1. 安装阿里云 OSS C# SDK

2. 配置阿里云 OSS 客户端

3. 常用操作及参数详解

1. 创建 OSS 客户端对象

2. 上传文件到 OSS

3. 下载文件

4. 删除文件

5. 列举文件

6. 获取文件的元数据

4. 详细参数解析

PutObject 方法参数详解：

ListObjectsRequest 参数详解：

5. 错误处理

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

7. 异步操作

8. 小结

`PutObject` 方法参数详解：

`ListObjectsRequest` 参数详解：