All Products
Search
Document Center

Object Storage Service:Initialization

Last Updated:Oct 30, 2023

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

Note

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.

Important

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.

  • true

  • false

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: example.aliyundoc.com.

None

ProxyPort

The proxy port. 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 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);