OssClient is the C# client for Object Storage Service (OSS). You can use it to manage OSS resources such as buckets and objects.
Create an OssClient
You can create an OssClient instance using one of the following methods.
V4 signature (Recommended)
The V4 signature algorithm is more secure. To initialize the client with a V4 signature, specify the Endpoint and the general-purpose Alibaba Cloud Region ID. The Region ID identifies the region of the request. For example, cn-hangzhou. You must also declare SignVersion.V4. V4 signatures are supported in OSS .NET SDK 2.14.0 and later.
The following example shows how to create an OssClient instance with a V4 signature and an OSS domain name. You can adapt this example for other scenarios, such as using a custom domain name or Security Token Service (STS).
using Aliyun.OSS;
using Aliyun.OSS.Common;
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Specify the Region ID for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region ID to cn-hangzhou.
const string region = "cn-hangzhou";
// Create a ClientConfiguration instance and modify the default parameters as needed.
var conf = new ClientConfiguration();
// Set the signature version to V4.
conf.SignatureVersion = SignatureVersion.V4;
// Create an OssClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);V1 signature (Not recommended)
From March 1, 2025, the V1 signature algorithm of OSS is no longer available to new customers with new UIDs. From September 1, 2025, OSS no longer updates and maintains the V1 signature algorithm, and the V1 signature algorithm is no longer available for new buckets. Upgrade V1 signatures to V4 signatures at the earliest opportunity to prevent impact on your business.
Use an OSS endpoint to create an OssClient instance
The following code shows how to create an OssClient instance using an OSS domain name.
using Aliyun.OSS;
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Create an OssClient instance.
var ossClient = new OssClient(endpoint, accessKeyId, accessKeySecret); Use a custom domain name to create an OSSClient instance
The following code shows how to create an OssClient instance using a custom domain name.
When you use a custom domain name, the ossClient.listBuckets method is not supported.
using Aliyun.OSS;
using Aliyun.OSS.Common;
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Specify the custom domain name.
const string endpoint = "yourDomain";
// Create a ClientConfiguration instance and modify the default parameters as needed.
var conf = new ClientConfiguration();
// Enable CNAME. CNAME is the procedure to attach a custom domain name to a bucket.
conf.IsCname = true;
// Create an OssClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf); Create an OssClient with STS
The following code shows how to create an OssClient instance using Security Token Service (STS).
using Aliyun.OSS;
// Before you run this sample code, make sure that you have used the temporary AccessKey pair obtained from STS to set the YOUR_ACCESS_KEY_ID and YOUR_ACCESS_KEY_SECRET environment variables.
var accessKeyId = Environment.GetEnvironmentVariable("YOUR_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("YOUR_ACCESS_KEY_SECRET");
// The security token obtained from STS.
const string securityToken = "yourSecurityToken";
// Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Create an OssClient instance.
var ossClient = new OssClient(endpoint, accessKeyId, accessKeySecret, securityToken);Configure the OssClient
ClientConfiguration is the configuration class for OssClient. You can use this class to configure parameters such as the proxy, connection timeout, and maximum connections. The following parameters can be configured:
Parameter | Description | Default value |
ConnectionLimit | The maximum number of concurrent connections. | 512 |
MaxErrorRetry | The maximum number of retries for a failed request. | 3 |
ConnectionTimeout | The connection timeout period, in milliseconds. | -1 (no timeout) |
EnableMD5Check | Specifies whether to enable MD5 validation for data uploads or downloads.
Important MD5 validation causes some performance overhead. | false |
IsCname | Specifies whether the Endpoint supports CNAME. CNAME is used to attach a custom domain name to a bucket. | false |
ProgressUpdateInterval | The update interval for the progress bar chart, in bytes. | 8096 |
ProxyHost | The proxy server. For example, | None |
ProxyPort | The proxy port. For example, | None |
ProxyUserName | The username for the proxy service. This parameter is optional. | None |
ProxyPassword | The password for the proxy service. This parameter is optional. | None |
The following code shows how to configure the OssClient.
using Aliyun.OSS;
using Aliyun.OSS.Common;
var conf = new ClientConfiguration();
// Set the maximum number of concurrent connections.
ClientConfiguration.ConnectionLimit = 512;
// Set the maximum number of retries for a failed request.
conf.MaxErrorRetry = 3;
// Set the connection timeout period.
conf.ConnectionTimeout = 300;
// Enable MD5 validation.
conf.EnableMD5Check = true;
// Set the proxy server.
conf.ProxyHost = "example.aliyundoc.com";
// Set the proxy port.
conf.ProxyPort = 3128;
// Set the username for the proxy.
conf.ProxyUserName = "user";
// Set the password for the proxy.
conf.ProxyPassword = "password";
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);