如何初始化.NET - Object Storage Service

OssClient是OSS服務的.NET用戶端，用於管理儲存空間（Bucket）和檔案（Object）等OSS資源。

建立OssClient

您可以通過以下多種方式建立OssClient。

V4簽名（推薦）

推薦使用更安全的V4簽名演算法。使用V4簽名初始化時，除指定Endpoint以外，您還需要指定阿里雲通用Region ID作為發起請求地區的標識，樣本值為cn-hangzhou。同時聲明SignVersion.V4。OSS .NET SDK 2.14.0及以上版本支援V4簽名。

以使用OSS網域名稱建立OSSClient時使用V4簽名為例，其他通過自訂網域名、STS等建立OSSClient的情境可參考以下樣本執行相應修改。

using Aliyun.OSS;
using Aliyun.OSS.Common;
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數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所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

// 填寫Bucket所在地區對應的Region。以華東1（杭州）為例，Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";

// 建立ClientConfiguration執行個體，按照您的需要修改預設參數。
var conf = new ClientConfiguration();

// 設定v4簽名。
conf.SignatureVersion = SignatureVersion.V4;

// 建立OssClient執行個體。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);

V1簽名（不推薦）

重要

阿里雲Object Storage Service自2025年03月01日起不再對新使用者（即新UID ）開放使用V1簽名，並將於2025年09月01日起停止更新與維護且不再對新增Bucket開放使用V1簽名。請儘快切換到V4簽名，避免影響服務。更多資訊，請參見公告連結。

使用OSS網域名稱建立OssClient

以下代碼用於使用OSS網域名稱建立OssClient。

using Aliyun.OSS;
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數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所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
  
// 構造OssClient執行個體。
var ossClient = new OssClient(endpoint, accessKeyId, accessKeySecret);

使用自訂網域名建立OssClient

以下代碼用於使用自訂網域名建立OssClient。

重要

使用自訂網域名時，不支援使用ossClient.listBuckets方法。

using Aliyun.OSS;
using Aliyun.OSS.Common;
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填寫自訂網域名。
const string endpoint = "yourDomain";

// 建立ClientConfiguration執行個體，按照您的需要修改預設參數。
var conf = new ClientConfiguration();

// 開啟CNAME開關。CNAME是指將自訂網域名綁定到儲存空間的過程。
conf.IsCname = true;

// 建立OssClient執行個體。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);

使用STS建立OssClient

以下代碼用於使用STS建立一個OssClient。

using Aliyun.OSS;
// 運行本程式碼範例之前，請確保已使用STS服務擷取的臨時存取金鑰設定環境變數YOUR_ACCESS_KEY_ID和YOUR_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("YOUR_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("YOUR_ACCESS_KEY_ID");
// 從STS服務擷取的安全性權杖（SecurityToken）。
const string  securityToken = "yourSecurityToken";
// 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

// 構造OssClient執行個體。
var ossClient = new OssClient(endpoint, accessKeyId, accessKeySecret, securityToken);

配置OssClient

ClientConfiguration是OSSClient的配置類，您可通過此類來配置代理、連線逾時、最大串連數等參數。可設定的參數如下：

參數	描述	預設值
ConnectionLimit	最大並發串連數。	512
MaxErrorRetry	請求失敗後最大的重試次數。	3
ConnectionTimeout	設定連線逾時時間，單位為毫秒。	-1（不逾時）
EnalbeMD5Check	上傳或下載資料時是否開啟MD5校正。 true：開啟MD5校正。 false：關閉MD5校正。重要使用MD5校正時會有一定的效能開銷。	false
IsCname	Endpoint是否支援CNAME。CNAME用於將自訂網域名綁定到儲存空間。	false
ProgressUpdateInterval	進度條更新間隔，單位為位元組。	8096
ProxyHost	Proxy 伺服器，例如`example.aliyundoc.com`。	無
ProxyPort	代理連接埠，例如`3128` 或 `8080`。	無
ProxyUserName	代理服務帳號，選擇性參數。	無
ProxyPassword	代理服務密碼，選擇性參數。	無

以下代碼用於配置OssClient。

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

var conf = new ClientConfiguration();
// 設定最大並發串連數。
ClientConfiguration.ConnectionLimit = 512;
// 佈建要求失敗後最大的重試次數。
conf.MaxErrorRetry = 3;
// 設定連線逾時時間。
conf.ConnectionTimeout = 300;
// 開啟MD5校正。
conf.EnalbeMD5Check = true;
// 設定Proxy 伺服器。
conf.ProxyHost = "example.aliyundoc.com";
// 設定代理連接埠。
conf.ProxyPort = 3128;
// 設定代理網路的訪問帳號。
conf.ProxyUserName = "user";
// 設定代理網路的訪問密碼。
conf.ProxyPassword = "password";

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