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
To create an OSSClient instance, you must specify an endpoint. For more information about endpoints, see Regions and endpoints.
You can use one of the following methods to create an OSSClient instance:
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. Modify parameters as required.
var conf = new ClientConfiguration();
// Specify that a CNAME record can be used. 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 STS to create an OSSClient instance
The following sample code provides an example on how to create an OSSClient instance by using Security Token Service (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 OSSClient
ClientConfiguration is a configuration class of OSSClient. You can use ClientConfiguration to configure parameters such as the host proxy, the connection timeout, and the maximum number of connections. The following table describes the parameters that you can configure when you configure an OSSClient instance.
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 (no timeout) |
EnalbeMD5Check | Specifies whether to enable MD5 verification when you upload or download objects.
Important The system performance may be affected 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 account used to log on to the proxy server. This parameter is optional. | None |
ProxyPassword | The password used to log on to the proxy server. 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 to the instance.
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);