Getting Started

Last updated: 2020-04-16 11:39:12

    Download and installation

    Relevant Resources

    Environmental Requirements

    COS XML .NET SDK is developed based on .NET Standard 2.0.

    • Windows: Install .NET Core 2.0 or above or .NET Framework 4.6.1 or above.
    • Linux/Mac: Install .NET Core 2.0 or above.

    Installing SDKs

    We provide a way to integrate Nuget, which can add to the csproj file of your project:

    <PackageReference Include="Tencent.QCloud.Cos.Sdk" Version="5.4.*" />

    If .NET CLI is used, run the following command for installation:

    dotnet add package Tencent.QCloud.Cos.Sdk

    You can also manually download the SDK here.

    Getting Started

    The section below describes how to perform basic operations with COS .NET SDK, such as initializing a client, creating a bucket, querying the bucket list, uploading an object, querying the object list, downloading an object, and deleting an object.

    • For definitions of SecretID, SecretKey, Bucket and other terms, see COS Glossary.

    Namespaces commonly used in SDKs include:

    using COSXML;
    using COSXML.Auth;
    using COSXML.Model.Object;
    using COSXML.Model.Bucket;
    using COSXML.CosException;

    Initialization

    Before executing any COS requests, instantiate 3 objects: CosXmlConfig, QCloudCredentialProvider, and CosXmlServer.

    • CosXmlConfig provides an API to configure SDK.
    • QCloudCredentialProvider provides an API to set the key information.
    • CosXmlServer provides APIs to perform operations on COS API services.

    For more information on how to generate and use the temporary keys used in the initialization samples below, see Generating and Using Temporary Keys.

    // Initialize CosXmlConfig 
    string appid = "1250000000";// Set the APPID of your Tencent Cloud account
    string region = "COS_REGION"; // Set the default bucket region
    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid(appid)  // Set the APPID of your Tencent Cloud account
      .SetRegion(region)  // Set the default bucket region
      .SetDebugLog(true)  // Show the log
      .Build();  // Create a CosXmlConfig object
    
    // Initialize QCloudCredentialProvider. COS SDK supports 3 different methods, using permanent key, temporary key, and a custom method.
    QCloudCredentialProvider cosCredentialProvider = null;
    
    // Method 1: Permanent Key
    String secretId = "COS_SECRETID"; // "TencentCloud API key SecretId";
    String secretKey = "COS_SECRETKEY"; // "Enter the SecretKey of your TencentCloud API key";
    long durationSecond = 600;          // Validity period of the request signature in seconds
    cosCredentialProvider = new DefaultQCloudCredentialProvider(secretId, secretKey, durationSecond);
    
    // Method 2: Temporary Key
    String tmpSecretId = "COS_SECRETID"; // "Temporary key SecretId";
    String tmpSecretKey = "COS_SECRETKEY"; // "Temporary key SecretKey";
    string tmpToken = "COS_TOKEN"; //"Temporary key token";
    long tmpExpireTime = 1546862502;// End of the validity period of the temporary key
    cosCredentialProvider = new DefaultSessionQCloudCredentialProvider(tmpSecretId, tmpSecretKey, 
      tmpExpireTime, tmpToken);
    
    // Initialize CosXmlServer
    CosXmlServer cosXml = new CosXmlServer(config, cosCredentialProvider);
    // Method 3: The key is provided via a custom method. You need to inherit QCloudCredentialProvider and override the GetQCloudCredentials() method.
    public class MyQCloudCredentialProvider : QCloudCredentialProvider
    {
      public override QCloudCredentials GetQCloudCredentials()
      {
        String secretId = "COS_SECRETID"; // Permanent key SecretId
        String secretKey ="COS_SECRETKEY"; // Permanent key SecretKey
        // Validity period of the key, accurate to the second. E.g., 1546862502;1546863102
        string keyTime = "SECRET_STARTTIME;SECRET_ENDTIME"; 
        return new QCloudCredentials(secretId, secretKey, keyTime);
      }
    
      public override void Refresh()
      {
        // Overrides the key. Callback is performed automatically when the key expires.
      }
    }

    Creating a Bucket

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid("1250000000") // Set the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Set the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // TencentCloud API key SecretId
    String secretKey = "COS_SECRETKEY"; // TencentCloud API key SecretKey
    long durationSecond = 600;          //Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
      PutBucketRequest request = new PutBucketRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      PutBucketResult result = cosXml.PutBucket(request);
      // Request successful
      Console.WriteLine(result.GetResultInfo());
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Querying Bucket List

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid("1250000000") // Set the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Set the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // TencentCloud API key SecretId
    String secretKey = "COS_SECRETKEY"; // TencentCloud API key SecretKey
    long durationSecond = 600;          //Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      GetServiceRequest request = new GetServiceRequest();
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      GetServiceResult result = cosXml.GetService(request);
      // Get a list of all buckets
      List<ListAllMyBuckets.Bucket> allBuckets = result.listAllMyBuckets.buckets;
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Uploading an Object

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid("1250000000") // Set the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Set the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // TencentCloud API key SecretId
    String secretKey = "COS_SECRETKEY"; // TencentCloud API key SecretKey
    long durationSecond = 600;          //Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Bucket, format: BucketName-APPID
      string key = "exampleobject"; // The location of the object in the bucket, i.e. ObjectKey.
      string srcPath = @"temp-source-file";// Absolute path to the local file
      if (!File.Exists(srcPath)) {
        // If a target file do not exist, create a temporary file for testing
        File.WriteAllBytes(srcPath, new byte[1024]);
      }
    
      PutObjectRequest request = new PutObjectRequest(bucket, key, srcPath);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Set progress callback
      request.SetCosProgressCallback(delegate (long completed, long total)
      {
        Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
      });
      // Execute the request
      PutObjectResult result = cosXml.PutObject(request);
      // Object etag
      string eTag = result.eTag;
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Querying Object List

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid("1250000000") // Set the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Set the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // TencentCloud API key SecretId
    String secretKey = "COS_SECRETKEY"; // TencentCloud API key SecretKey
    long durationSecond = 600;          //Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
      GetBucketRequest request = new GetBucketRequest(bucket);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Get the object in a/
      request.SetPrefix("a/");
      // Execute the request
      GetBucketResult result = cosXml.GetBucket(request);
      // bucket information
      ListBucket info = result.listBucket;
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Downloading an Object

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid("1250000000") // Set the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Set the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // TencentCloud API key SecretId
    String secretKey = "COS_SECRETKEY"; // TencentCloud API key SecretKey
    long durationSecond = 600;          //Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Bucket, format: BucketName-APPID
      string key = "exampleobject"; // The location of the object in the bucket, i.e. ObjectKey.
      string localDir = System.IO.Path.GetTempPath();// Local file directory
      string localFileName = "my-local-temp-file"; // Specify the file name of the file to be saved locally
      GetObjectRequest request = new GetObjectRequest(bucket, key, localDir, localFileName);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Set progress callback
      request.SetCosProgressCallback(delegate (long completed, long total)
      {
        Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
      });
      // Execute the request
      GetObjectResult result = cosXml.GetObject(request);
      // Request successful
      Console.WriteLine(result.GetResultInfo());
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }
    
    // Download the returned bytes data
    try
    {
      String bucket = "examplebucket-1250000000"; // Bucket, format: BucketName-APPID
      string key = "exampleobject"; // The location of the object in the bucket, i.e. ObjectKey.
    
      GetObjectBytesRequest request = new GetObjectBytesRequest(bucket, key);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Set progress callback
      request.SetCosProgressCallback(delegate (long completed, long total)
      {
        Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
      });
      // Execute the request
      GetObjectBytesResult result = cosXml.GetObject(request);
      // Get content
      byte[] content = result.content;
      // Request successful
      Console.WriteLine(result.GetResultInfo());
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Delete an object

    CosXmlConfig config = new CosXmlConfig.Builder()
      .SetConnectionTimeoutMs(60000)  // Set the connection timeout period in milliseconds, which is 45,000 ms by default
      .SetReadWriteTimeoutMs(40000)  // Set the read/write timeout period in milliseconds, which is 45,000 ms by default
      .IsHttps(true)  // Set HTTPS as default request method
      .SetAppid("1250000000") // Set the APPID of your Tencent Cloud account
      .SetRegion("COS_REGION") // Set the default bucket region
      .Build();
    
    String secretId = "COS_SECRETID"; // TencentCloud API key SecretId
    String secretKey = "COS_SECRETKEY"; // TencentCloud API key SecretKey
    long durationSecond = 600;          //Validity period of the request signature in seconds
    QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
      secretKey, durationSecond);
    
    CosXml cosXml = new CosXmlServer(config, qCloudCredentialProvider);
    
    try
    {
      String bucket = "examplebucket-1250000000"; // Bucket, format: BucketName-APPID
      string key = "exampleobject"; // The location of the object in the bucket, i.e. ObjectKey.
      DeleteObjectRequest request = new DeleteObjectRequest(bucket, key);
      // Set the validity period of the signature
      request.SetSign(TimeUtils.GetCurrentTime(TimeUnit.SECONDS), 600);
      // Execute the request
      DeleteObjectResult result = cosXml.DeleteObject(request);
      // Request successful
      Console.WriteLine(result.GetResultInfo());
    }
    catch (COSXML.CosException.CosClientException clientEx)
    {
      // Request failed
      Console.WriteLine("CosClientException: " + clientEx);
    }
    catch (COSXML.CosException.CosServerException serverEx)
    {
      // Request failed
      Console.WriteLine("CosServerException: " + serverEx.GetInfo());
    }

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help