OssClient serves as the OSS .NET client to manage OSS resources such as buckets and objects.

Create an OssClient instance

To create an OssClient instance, you must specify yourEndpoint. For more information about endpoints, see Regions and endpoints and Map custom domain names.

  • Create the OssClient instance by using an OSS endpoint

    The following code provides an example on how to create an OssClient instance based on an OSS endpoint:

    using Aliyun.OSS;
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
    const string accessKeyId = "yourAccessKeyId";
    const string accessKeySecret = "yourAccessKeySecret";
    // 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 yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    
    // Create a new OssClient instance. 
    var ossClient = new OssClient(endpoint, accessKeyId, accessKeySecret);                    
  • Create an OssClient by using a custom domain name

    The following code provides an example on how to create an OssClient instance by using a custom domain name:

    using Aliyun.OSS;
    using Aliyun.OSS.Common;
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
    const string accessKeyId = "yourAccessKeyId";
    const string accessKeySecret = "yourAccessKeySecret";
    // 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 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);                    
    Important ossClient.listBuckets is unavailable when a CNAME is used.

Configure an OssClient instance

ClientConfiguration is a configuration class of OssClient. You can use ClientConfiguration to configure parameters such as host proxies, connection timeouts, and the maximum number of connections. You can configure the following parameters.

Parameter Description Default value
ConnectionLimit The maximum number of HTTP connections that can be enabled. 512
MaxErrorRetry The maximum number of retry attempts in the case of a request error. 3
ConnectionTimeout The timeout period for connections. Unit: millisecond. -1, which indicates that connections do not time out.
IsCname Specifies whether 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. false
ProgressUpdateInterval The update interval of the progress bar. Unit: bytes. 8096

The following 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 retry attempts in the case of a request error. 
conf.MaxErrorRetry = 3;
// Specify the timeout period of the connections. 
conf.ConnectionTimeout = 300;

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

    The following code provides an example on how to enable MD5 verification:

    using Aliyun.OSS;
    using Aliyun.OSS.Common;
    
    var conf = new ClientConfiguration();
    // Enable MD5 verification. By default, MD5 verification is disabled. If this parameter is set to true, MD5 verification is automatically performed on the uploaded and downloaded data. 
    conf.EnalbeMD5Check = true;
    
    var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);                    
    Important The system performance may degrade if MD5 verification is enabled.
  • Proxy network

    The following table describes the parameters that you can configure when you use proxy networks.

    Parameter Description Default value
    ProxyHost The address of the proxy server. Example: example.aliyundoc.com. None
    ProxyPort The port of the proxy server. Example: 3128 or 8080. 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 code provides an example on how to configure proxy networks that do not require an account and a password:

    using Aliyun.OSS;
    using Aliyun.OSS.Common;
    
    var conf = new ClientConfiguration();
    // Specify the proxy server. 
    conf.ProxyHost = "example.aliyundoc.com";
    // Specify the port of the proxy server. 
    conf.ProxyPort = 3128;
    
    var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);                    

    The following code provides an example on how to configure proxy networks that require an account and a password:

    using Aliyun.OSS;
    using Aliyun.OSS.Common;
    
    var conf = new ClientConfiguration();
    // Specify the proxy server. 
    conf.ProxyHost = "example.aliyundoc.com";
    // Specify the port of the proxy server. 
    conf.ProxyPort = 3128;
    // Specify the account 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);