Last updated: 2021-08-10 16:14:49

    Overview

    • Welcome to Tencent Cloud Software Development Kit (SDK) 3.0, a companion tool for the TencentCloud API 3.0 platform. SDK 3.0 is unified and features the same SDK usage, API call methods, error codes, and returned packet formats for different programming languages.
    • This document describes how to use, debug, and connect to TencentCloud APIs with the SDK for .NET 3.0 as an example.
    • This version currently supports various Tencent Cloud products such as CVM, VPC, and CBS and will support more products in the future.

    Dependent Environment

    • .NET Framework 4.5+ or .NET Core 2.1.
    • Get the security credential, which consists of SecretId and SecretKey. SecretId is used to identify the API requester, while SecretKey is a key used for signature string encryption and authentication by the server. You can get them on the API Key Management page as shown below:
      Note:

      Your security credential represents your account identity and granted permissions, which is equivalent to your login password. Do not disclose it to others.

    • Get the calling address (endpoint), which is generally in the format of *.tencentcloudapi.com and varies by product. For example, the endpoint of CVM is cvm.tencentcloudapi.com. For specific endpoints, please see the API documentation of the corresponding product .

    Installing SDK

    Method 1. Install through NuGet (recommended)

    Install on the command line (the version here is only an example. Please choose the latest version):

       dotnet add package TencentCloudSDK --version 3.0.0
       # For other information, please go to www.nuget.org/packages/TencentCloudSDK
    
    Note:

    The commands should be executed in the home directory of the project.

    Add a package through Visual Studio:
    For example, to create a HelloWorld project, run:

    dotnet new console -o HelloWorld
    # Enter the home directory of the HelloWorld project
    dotnet run
    # The output is: Hello World!
    dotnet add package TencentCloudSDK --version 3.0.0
    # Download SDK dependencies for the project
    
    Note:

    • If you want to install the package of a certain product such as CVM, just add the dependency TencentCloudSDK.Cvm.

    Method 2. Install through source code

    Go to the GitHub code hosting page to download the latest code, decompress and install it in your working directory, and then open it with Visual Studio 2017 for compiling.

    Using SDK

    Each API has a corresponding request structure and a response structure. For example, the DescribeInstances API for querying the CVM instance list has a request structure DescribeInstancesRequest and a response structure DescribeInstancesResponse.

    The following uses the CVM instance list querying API as an example to describe the basic usage of the SDK.

    using System;
    using System.Threading.Tasks;
    using TencentCloud.Common;
    using TencentCloud.Cvm.V20170312;
    using TencentCloud.Cvm.V20170312.Models;
    namespace TencentCloudExamples
    {
        class DescribeInstances
        {
            static void Main(string[] args)
            {
                try
                {
                    Credential cred = new Credential {"SecretId", "SecretKey"};
                    CvmClient client = new CvmClient(cred, "ap-guangzhou");
                    DescribeInstancesRequest req = new DescribeInstancesRequest();
                    DescribeInstancesResponse resp = client.DescribeInstancesSync(req);
                    Console.WriteLine(AbstractModel.ToJsonString(resp));
                }
                catch (Exception e)
               {
                    Console.WriteLine(e.ToString());
                }
            }
        }
    }
    

    More samples

    For more samples, please see the TencentCloudExamples directory in the GitHub repository.

    Sync and async calls

    The new version of the SDK provides both async and sync APIs. The sync APIs uniformly have the Sync suffix after the async APIs as demonstrated in the code above.

    Note:

    In the sample, as it is a console application, you can call the async APIs synchronously, i.e., ConfigureAwait(false).GetAwaiter().GetResult(). When developing ASP applications or Windows Forms applications, you cannot call the async APIs synchronously in the response method of UI controls; otherwise, the UI will stop responding.
    The solution is to change the response method of the UI controls to async and pay attention to the sync context. In addition, as async call immediately returns control to the user, it is prone to cause the user to click multiple times or perform unexpected operations. Such problems should be avoided in the program. For the source code, please refer to the WindowsFormsDemo project.

    Relevant Configuration

    Proxy

    If you use the SDK to call an API in a proxy environment, you need to set the system environment variable https_proxy (as shown in the sample code); otherwise, it may not be called normally, and a connection timeout exception will be thrown.

    FAQs

    The FluentClient on which the SDK depends is on v3.2, but this package is currently available on v4.0, which is incompatible with lower versions. Upgrading this package to v4.0 in NuGet will cause problems such as inability to call or call failure.