An OSSClient serves as the Object Storage Service (OSS) client for .NET to manage OSS resources such as buckets and objects.
Create an OSSClient instance
You can use one of the following methods to create an OSSClient instance:
(Recommended) Use the V4 signature algorithm
We recommend that you use the V4 signature algorithm which provides better security. If you use the V4 signature algorithm, include the region parameter. The region parameter must be an Alibaba Cloud Region ID. Example: cn-Hangzhou. You must also declare SignVersion.V4. OSS SDK for .NET 2.14.0 and later support the V4 signature algorithm.
The following sample code provides an example on how to create an OSSClient instance by using an OSS endpoint and the V4 signature algorithm. To create an OSSClient instance by using a custom domain name or access credentials obtained from Security Token Service (STS), modify the following sample code based on your actual scenario.
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 configured.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret=Environment.GetEnvironmentVariable ("OSS_ACCESS_KEY_SECRET");
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located 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 in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
const string region = "cn-hangzhou";
// Create a ClientConfiguration instance and modify the default parameters based on your requirements.
var conf = new ClientConfiguration();
// Specify the V4 signature.
conf.SignatureVersion = SignatureVersion.V4;
// Create an OSSClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
c.SetRegion(region);(Not recommended) Use the V1 signature algorithm
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 sample code provides an example on how to create an OSSClient instance by using an OSS endpoint:
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 configured.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located 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 sample code provides an example on how to create an OSSClient instance by using a custom domain name.
ossClient.listBuckets is unavailable if a custom domain name is used.
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 configured.
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 based on your requirements.
var conf = new ClientConfiguration();
// Specify that a CNAME can be used as an endpoint to create the OssClient instance. A CNAME record specifies the mapping relationship between a custom domain name and a bucket.
conf.IsCname = true;
// Create an OSSClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf); Use access credentials obtained from STS to create an OSSClient instance
The following sample code provides an example on how to create an OSSClient instance by using access credentials obtained from STS:
using Aliyun.OSS;
// Before you run the sample code, make sure that the YOUR_ACCESS_KEY_ID and YOUR_ACCESS_KEY_SECRET environment variables are configured by using the temporary access credentials that you obtained from STS.
var accessKeyId = Environment.GetEnvironmentVariable("YOUR_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("YOUR_ACCESS_KEY_ID");
// Specify the security token obtained from STS.
const string securityToken = "yourSecurityToken";
// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located 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 an OSSClient instance
ClientConfiguration is a configuration class of an OSSClient instance. You can use ClientConfiguration to configure parameters, such as the proxy, the connection timeout period, and the maximum number of connections. The following table describes the parameters.
Parameter | Description | Default value |
ConnectionLimit | The maximum number of concurrent connections. | 512 |
MaxErrorRetry | The maximum number of retries when a request error occurs. | 3 |
ConnectionTimeout | The timeout period for connections. Unit: milliseconds. | -1 (indicates that the connection never times out) |
EnalbeMD5Check | Specifies whether to enable MD5 verification when you upload or download objects.
Important The system performance may be compromised if MD5 verification is enabled. | false |
IsCname | Specifies whether a CNAME can be used as an endpoint to create the OSSClient instance. CNAME is used to bind a custom domain name to a bucket. | false |
ProgressUpdateInterval | The update interval of the progress bar. Unit: bytes. | 8096 |
ProxyHost | The proxy server. Example: | None |
ProxyPort | The proxy port. Example: | None |
ProxyUserName | The username used to access the proxy network. This parameter is optional. | None |
ProxyPassword | The password used to access the proxy network. This parameter is optional. | None |
The following sample code provides an example on how to configure an OSSClient instance:
using Aliyun.OSS;
using Aliyun.OSS.Common;
var conf = new ClientConfiguration();
// Specify the maximum number of concurrent connections.
ClientConfiguration.ConnectionLimit = 512;
// Specify the maximum number of retries in case of a request error.
conf.MaxErrorRetry = 3;
// Specify the timeout period of the connections.
conf.ConnectionTimeout = 300;
// Enable MD5 verification.
conf.EnalbeMD5Check = true;
// Specify the proxy server.
conf.ProxyHost = "example.aliyundoc.com";
// Specify the port of the proxy server.
conf.ProxyPort = 3128;
// Specify the username used to access the proxy network.
conf.ProxyUserName = "user";
// Specify the password used to access the proxy network.
conf.ProxyPassword = "password";
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);