Getting Started

Last updated: 2021-11-10 12:44:59

    Resources

    • Download the XML .NET SDK source code here.
    • Download XML .NET SDK here.
    • For the SDK APIs and their parameters, please see SDK API.
    • Find the complete code here.
    • For the SDK changelog, please see Changelog.
    • For SDK FAQs, please see .NET (C#) SDK FAQs.
    Note:

    If you encounter errors such as non-existent functions or methods when using the SDK, please update the SDK to the latest version and try again.

    Step 1. Integrate the SDK

    Environment requirements

    The .NET SDK is developed based on .NET Standard 2.0.

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

    Installing the SDK

    You can install the SDK using NuGet by adding the following to the csproj file in your project:

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

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

    dotnet add package Tencent.QCloud.Cos.Sdk
    

    If you develop for the target framework .Net Framework 4.0 or below, please download Releases and use COSXML-Compatible.dll.

    In your Visual Studio project, click Project > Add Reference > Browse > COSXML-Compatible.dll to add the .NET(C#) SDK.

    Note:

    About the backward compatibility of the .NET SDK, please see Backward Compatibility.

    Step 2. Initialize COS Services

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

    Note:

    For the definition of terms such as SecretId, SecretKey, and Bucket, please see COS Glossary.

    Namespaces commonly used in this SDK include:

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

    Before making any COS requests, always instantiate the following 3 objects: CosXmlConfig, QCloudCredentialProvider, and CosXmlServer.

    • CosXmlConfig provides an API to configure the SDK.
    • QCloudCredentialProvider provides an API to set the key information.
    • CosXmlServer provides APIs for COS operations.
    Note:

    The initialization sample below uses a temporary key. For more information about how to generate and use a temporary key, please see Generating and Using Temporary Keys.

    1. Initialize a COS service

    // 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()
    .IsHttps(true)  // Set HTTPS as default request method.
    .SetRegion(region)  // Set the default bucket region.
    .SetDebugLog(true)  // Display logs.
    .Build();  // Create a CosXmlConfig object.
    

    2. Provide access credentials

    The SDK supports three types of access credentials: permanent keys, updated temporary keys, and unchanging temporary keys.

    Type 1: permanent key

    string secretId = "SECRET_ID"; //“SecretId of your TencentCloud API key”;
    string secretKey = "SECRET_KEY"; //“SecretKey of your TencentCloud API key”;
    long durationSecond = 600;          // Validity period of each request signature in seconds
    QCloudCredentialProvider cosCredentialProvider = new DefaultQCloudCredentialProvider(
    secretId, secretKey, durationSecond);
    

    Type 2: updated temporary key

    Since temporary keys are short term, you can obtain new ones using the following method:

    public class CustomQCloudCredentialProvider : DefaultSessionQCloudCredentialProvider
    {
     // Even if you do not already have a current temporary key, you can still use this method.
    public CustomQCloudCredentialProvider(): base(null, null, 0L, null) {
      ;
    }
     public override void Refresh()
    {
      //... First, request a temporary key from Tencent Cloud.
      string tmpSecretId = "SECRET_ID"; // “SecretId of the temporary key”;
      string tmpSecretKey = "SECRET_KEY"; // “SecretKey of the temporary key”;
      string tmpToken = "COS_TOKEN"; // “Token of the temporary key”;
      long tmpStartTime = 1546860702;// Start time in seconds of the temporary key’s validity period
      long tmpExpireTime = 1546862502;// End time in seconds of the temporary key’s validity period
      // Call the API to update the key
      SetQCloudCredential(tmpSecretId, tmpSecretKey, 
        String.Format("{0};{1}", tmpStartTime, tmpExpiredTime), tmpToken);
    }
    }
    QCloudCredentialProvider cosCredentialProvider = new CustomQCloudCredentialProvider();
    

    Type 3: unchanging temporary key (not recommended)

    Note:

    This method is not recommended as a request may fail if the temporary key has expired at the time of request.

    string tmpSecretId = "SECRET_ID"; // “SecretId of the temporary key”;
    string tmpSecretKey = "SECRET_KEY"; // “SecretKey of the temporary key”;
    string tmpToken = "COS_TOKEN"; // “Token of the temporary key”;
    long tmpExpireTime = 1546862502;// End time in seconds of the temporary key’s validity period
    QCloudCredentialProvider cosCredentialProvider = new DefaultSessionQCloudCredentialProvider(
    tmpSecretId, tmpSecretKey, tmpExpireTime, tmpToken);
    

    3. Initialize CosXmlServer

    Use CosXmlConfig and QCloudCredentialProvider to initialize the CosXmlServer service class. We recommend you use the service class as a singleton in your project.

    CosXml cosXml = new CosXmlServer(config, cosCredentialProvider);
    

    Step 3. Access COS

    Creating a bucket

    try
    {
     String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
     PutBucketRequest request = new PutBucketRequest(bucket);
     // 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 the bucket list

    try
    {
     GetServiceRequest request = new GetServiceRequest();
     // Execute the request.
     GetServiceResult result = cosXml.GetService(request);
     // Get the 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

    // Initialize TransferConfig.
    TransferConfig transferConfig = new TransferConfig();
    // Initialize TransferManager.
    TransferManager transferManager = new TransferManager(cosXml, transferConfig);
    String bucket = "examplebucket-1250000000"; // Bucket, formatted as `BucketName-APPID`
    String cosPath = "exampleobject"; // Location identifier of the object in the bucket, i.e., the object key
    String srcPath = @"temp-source-file";// Absolute path to the local file
    // Upload an object.
    COSXMLUploadTask uploadTask = new COSXMLUploadTask(bucket, cosPath);
    uploadTask.SetSrcPath(srcPath);
    uploadTask.progressCallback = delegate (long completed, long total)
    {
       Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
    };
    try{
     COSXML.Transfer.COSXMLUploadTask.UploadTaskResult result = await 
       transferManager.UploadAsync(uploadTask);
     Console.WriteLine(result.GetResultInfo());
     string eTag = result.eTag;
    } catch (Exception e) {
       Console.WriteLine("CosException: " + e);
    }
    

    Querying objects

    try
    {
    String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
    GetBucketRequest request = new GetBucketRequest(bucket);
    // Execute the request.
    GetBucketResult result = cosXml.GetBucket(request);
    // Bucket information
    ListBucket info = result.listBucket;
    if (info.isTruncated) {
      // The data is truncated, and the next marker of the data is recorded.
      this.nextMarker = info.nextMarker;
    }
    }
    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

    // Initialize TransferConfig.
    TransferConfig transferConfig = new TransferConfig();
    // Initialize TransferManager.
    TransferManager transferManager = new TransferManager(cosXml, transferConfig);
    String bucket = "examplebucket-1250000000"; // Bucket, formatted as `BucketName-APPID`
    String cosPath = "exampleobject"; // Location identifier of the object in the bucket, i.e., the object key
    string localDir = System.IO.Path.GetTempPath();// Local file directory
    string localFileName = "my-local-temp-file"; // Specify the name of the file to be saved locally
    // Download an object.
    COSXMLDownloadTask downloadTask = new COSXMLDownloadTask(bucket, cosPath, 
    localDir, localFileName);
    downloadTask.progressCallback = delegate (long completed, long total)
    {
      Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
    };
    try{
    COSXML.Transfer.COSXMLDownloadTask.DownloadTaskResult result = await 
      transferManager.DownloadAsync(downloadTask);
    Console.WriteLine(result.GetResultInfo());
    string eTag = result.eTag;
    } catch (Exception e) {
      Console.WriteLine("CosException: " + e);
    }
    

    Deleting an object

    try
    {
    string bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
    string key = "exampleobject"; // Object key
    DeleteObjectRequest request = new DeleteObjectRequest(bucket, key);
    // 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());
    }