.NET快速入门

更新时间:2025-04-24 03:50:21

本文为您提供使用OSS .NET SDK 进行常见存储操作的快速入门。您将学习如何安装SDK、配置访问凭证,以及执行基本操作,包括创建存储空间(Bucket)、上传、下载、列举和删除文件(Object)等。

注意事项

关于OSS支持的RegionEndpoint的对应关系,请参见OSS地域和访问域名

配置凭证

请确认您已注册阿里云账号,并完成实名认证。

  1. 创建有OSS管理权限的RAM用户AccessKey

    使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

    在资源编排ROS控制台的创建资源栈页面的安全确认下,勾选确认,然后单击创建

    1.png

    创建完成后,在输出中,复制创建的AccessKey。

    image

  2. 使用RAM用户AccessKey配置环境变量。

    Linux
    macOS
    Windows
    1. 在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
      1. 执行以下命令使变更生效。

        source ~/.bashrc
      2. 执行以下命令检查环境变量是否生效。

        echo $OSS_ACCESS_KEY_ID
        echo $OSS_ACCESS_KEY_SECRET
    1. 在终端中执行以下命令,查看默认Shell类型。

      echo $SHELL
      1. 根据默认Shell类型进行操作。

        Zsh
        Bash
        1. 执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
          echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
        2. 执行以下命令使变更生效。

          source ~/.zshrc
        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
          echo $OSS_ACCESS_KEY_SECRET
        1. 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

          echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
          echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile
        2. 执行以下命令使变更生效。

          source ~/.bash_profile
        3. 执行以下命令检查环境变量是否生效。

          echo $OSS_ACCESS_KEY_ID
          echo $OSS_ACCESS_KEY_SECRET
    CMD
    PowerShell
    1. CMD中运行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"
      1. 运行以下命令,检查环境变量是否生效。

        echo %OSS_ACCESS_KEY_ID%
        echo %OSS_ACCESS_KEY_SECRET%
    1. PowerShell中运行以下命令。

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)
      1. 运行以下命令,检查环境变量是否生效。

        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
        [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

  3. 参考上述方式修改系统环境变量后,请重启或刷新您的编译运行环境,包括IDE、命令行界面、其他桌面应用程序及后台服务,以确保最新的系统环境变量成功加载。

安装SDK

Windows 环境安装
Unix/Mac 环境安装
NuGet 方式安装
DLL 引用方式安装
项目引入方式安装
  1. 如果您的Visual Studio没有安装NuGet,请先安装NuGet

  2. Visual Studio中新建或者打开已有的项目,选择工具 > NuGet程序包管理器 > 管理解决方案的NuGet程序包

  3. 搜索aliyun.oss.sdk,在结果中找到Aliyun.OSS.SDK(适用于.NET Framework)或Aliyun.OSS.SDK.NetCore(适用于.Net Core),选择最新版本,单击安装

  1. 下载并解压.NET SDK开发包。

  2. Release模式下编译aliyun-oss-sdk项目,生成DLL库。

  3. 打开Visual Studio解决方案资源管理器,选择您的项目,右击项目名称 ,选择 引用 > 添加引用 ,在弹出的对话框中选择浏览

  4. 找到DLL库生成的bin目录,选择Aliyun.OSS.dll文件,单击确定

如果是下载了SDK包或者从GitHub上下载了源码,并通过源码安装,操作步骤如下:

  1. Visual Studio中,右击选择解决方案,在弹出的菜单中单击添加现有项目

  2. 在弹出的对话框中选择aliyun-oss-sdk.csproj文件,单击打开

  3. 右击项目名称,选择引用 > 添加引用,在弹出的对话框中选择项目选项卡,选中aliyun-oss-sdk项目,单击确定

通过NuGet方式安装的步骤如下:

  1. Xamarin中新建或者打开已有的项目,选择工具Add NuGet Packages

  2. 搜索到Aliyun.OSS.SDKAliyun.OSS.SDK.NetCore,选择最新版本,单击Add Package添加到项目应用中。

快速使用

以下示例程序演示了如何创建存储空间(Bucket)、上传、下载、列举和删除文件(Object)等。

创建存储空间

using Aliyun.OSS;
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// yourBucketName填写Bucket名称。
var bucketName = "yourBucketName";

// 创建OSSClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // 创建存储空间。
    var bucket = client.CreateBucket(bucketName);
    Console.WriteLine("Create bucket succeeded, {0} ", bucket.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Create bucket failed, {0}", ex.Message);
}

上传文件

using Aliyun.OSS;

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称,例如examplebucket。
var bucketName = "examplebucket";
// 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。
var objectName = "exampledir/exampleobject.txt";
// 填写本地文件完整路径,例如D:\\localpath\\examplefile.txt。如果未指定本地路径,则默认从示例程序所属项目对应本地路径中上传文件。
var localFilename = "D:\\localpath\\examplefile.txt";
// 创建OSSClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // 上传文件。
    var result = client.PutObject(bucketName, objectName, localFilename);
    Console.WriteLine("Put object succeeded, ETag: {0} ", result.ETag);
}
catch (Exception ex)
{
    Console.WriteLine("Put object failed, {0}", ex.Message);
}

下载文件

using Aliyun.OSS;
using Aliyun.OSS.Common;

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称,例如examplebucket。
var bucketName = "examplebucket";
// 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。
var objectName = "exampledir/exampleobject.txt";
// 下载Object到本地文件examplefile.txt,并保存到指定的本地路径中(D:\\localpath)。如果指定的本地文件存在会覆盖,不存在则新建。
// 如果未指定本地路径,则下载后的文件默认保存到示例程序所属项目对应本地路径中。
var downloadFilename = "D:\\localpath\\examplefile.txt";
// 创建OSSClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{   
    // 下载文件。
    var result = client.GetObject(bucketName, objectName);
    using (var requestStream = result.Content)
    {
        using (var fs = File.Open(downloadFilename, FileMode.OpenOrCreate))
        {
            int length = 4 * 1024;
            var buf = new byte[length];
            do
            {
                length = requestStream.Read(buf, 0, length);
                fs.Write(buf, 0, length);
            } while (length != 0);
        }
    }
    Console.WriteLine("Get object succeeded");
}
catch (OssException ex)
{
    Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
        ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
catch (Exception ex)
{
    Console.WriteLine("Failed with error info: {0}", ex.Message);
}

列举文件

using Aliyun.OSS;
using Aliyun.OSS.Common;
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称,例如examplebucket。
var bucketName = "examplebucket";
// 创建OSSClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    var objects = new List<string>();
    ObjectListing result = null;
    string nextMarker = string.Empty;
    do
    {
        var listObjectsRequest = new ListObjectsRequest(bucketName)
        {
            Marker = nextMarker,
        };
        // 列举文件。
        result = client.ListObjects(listObjectsRequest);
        foreach (var summary in result.ObjectSummaries)
        {
            Console.WriteLine(summary.Key);
            objects.Add(summary.Key);
        }
        nextMarker = result.NextMarker;
    } while (result.IsTruncated);
    Console.WriteLine("List objects of bucket:{0} succeeded ", bucketName);
}
catch (OssException ex)
{
    Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
        ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
catch (Exception ex)
{
    Console.WriteLine("Failed with error info: {0}", ex.Message);
}

删除文件

using Aliyun.OSS;
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称,例如examplebucket。
var bucketName = "examplebucket";
// 填写Object完整路径,完整路径中不能包含Bucket名称,例如exampledir/exampleobject.txt。
var objectName = "exampledir/exampleobject.txt";
// 创建OSSClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // 删除文件。
    client.DeleteObject(bucketName, objectName);
    Console.WriteLine("Delete object succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("Delete object failed, {0}", ex.Message);
}

运行示例

  1. 在您的测试工程目录下创建main.cs文件,根据需要将示例代码拷贝至main.cs文件中。

  2. 请替换以下命令里的"yourRegion"、"yourBucketName"、"yourObjectName"为您的实际配置,其中yourRegion填写bucket所在地域,例如华东1(杭州)填写为cn-hangzhou。

    dotnet script main.cs -- <yourRegion> <yourBucketName> <yourObjectName>

常见问题

当使用SDK时遇到报错AccessDenied该如何进行排查?

当您遇到AccessDenied错误时通常是因为没有相应的访问权限。以下是解决此问题的步骤:

  1. 确认AccessKey IDAccessKey Secret:请确保您使用了正确的AccessKey IDAccessKey Secret。详情请参见创建AccessKey

  2. 检查RAM用户权限:确认RAM用户是否拥有BucketObject相关操作权限。具体步骤,请参见RAM用户授权

  3. 检查Bucket Policy:如果错误信息中提到“Access denied by bucket policy”,则表明是受到Bucket Policy的策略拒绝了。详情请参考Bucket Policy

  4. 更多错误类型的查询,请您参阅EC错误码,例如关于访问控制方面的常见报错,可参见03-ACCESS_CONTROL

相关文档

  • 关于OSS .NET SDK 的更多信息,请参见官方文档

  • 本页导读 (1)
  • 注意事项
  • 配置凭证
  • 安装SDK
  • 快速使用
  • 创建存储空间
  • 上传文件
  • 下载文件
  • 列举文件
  • 删除文件
  • 运行示例
  • 常见问题
  • 当使用SDK时遇到报错AccessDenied该如何进行排查?
  • 相关文档
AI助理

点击开启售前

在线咨询服务

你好,我是AI助理

可以解答问题、推荐解决方案等