ECS .NET V2.0 SDK call example-Elastic Compute Service(ECS)-阿里云帮助中心

This topic uses the DescribeInstances API operation as an example to describe how to install and use the .NET V2.0 SDK to query the details of one or more Elastic Compute Service (ECS) instances.

Prerequisites

The AccessKey of an Alibaba Cloud account provides full access to your resources, which poses a high security risk if the AccessKey is leaked. We recommend that you create a Resource Access Management (RAM) user and grant the RAM user only the required permissions. Then, use the AccessKey of the RAM user to call API operations. For more information, see Create an AccessKey.
You have granted the RAM user permissions to manage ECS resources. The example code in this topic shows a query operation. In this example, the AliyunECSReadonlyAccess system policy is used. You can grant custom permissions as needed.
1. Use custom policies.
  For more information about how to create custom policies, see Create a custom policy and Authorization information.
  ECS provides custom policy examples based on best practices. You can use these examples to quickly create custom policies that meet your business needs. For more information, see Custom policies.
2. Use system policies.
  For information about all system policies that ECS supports and their permission descriptions, see System policies for ECS.
Configure the AccessKey using environment variables. For more information, see Configure environment variables on Linux, macOS, and Windows systems.

Install the SDK

For more information about how to install the .NET V2.0 SDK, see SDK Center. You can use one of the following methods to install the ECS SDK:

.NET CLI

dotnet add package AlibabaCloud.SDK.Ecs20140526 --version 4.3.1

Package Manager

Install-Package AlibabaCloud.SDK.Ecs20140526 -Version 4.3.1

PackageReference

<PackageReference Include="AlibabaCloud.SDK.Ecs20140526" Version="4.3.1" />

Paket CLI

paket add AlibabaCloud.SDK.Ecs20140526 --version 4.3.1

F# Interactive

#r "nuget: AlibabaCloud.SDK.Ecs20140526, 4.3.1"

Use the SDK

1. Initialize the client

The Alibaba Cloud SDK supports multiple types of access credentials to initialize a client, such as an AccessKey and a Security Token Service (STS) token. For more information, see Manage access credentials. This example shows how to initialize a client using an AccessKey.

namespace ecs
{
    public class Sample
    {
        static void Main(string[] args)
        {
            var ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config
            {
                // Obtain the AccessKey ID from an environment variable.
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Obtain the AccessKey secret from an environment variable.
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                Endpoint = "ecs.cn-hangzhou.aliyuncs.com"
            };
            var escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
        }
    }
}

2. Create a request object for the API operation

Before you create the request object, see the API documentation for the operation to obtain parameter information.

Note

The naming convention for request objects is {APIName}Request. For example, the request object for the DescribeInstances operation is DescribeInstancesRequest.

// Create a request object.
var describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeInstancesRequest
{
    RegionId = "cn-hangzhou"
};

3. Send the request

When you use a client to call an OpenAPI operation, you can set runtime parameters, such as timeout and agent configurations. For more information, see Advanced configurations.

Note

The naming convention for API response objects is {APIName}Response. For example, the response object for the DescribeInstances operation is DescribeInstancesResponse.

// Create a runtime configuration object.
var runtimeOptions = new RuntimeOptions();
// Send the request.  
var describeInstancesResponse = escClient.DescribeInstancesWithOptions(describeInstancesRequest, runtimeOptions);

4. Handle exceptions

The .NET SDK classifies exceptions in detail. The main exceptions are:

TeaUnretryableException: This exception is mainly caused by network issues. It is usually thrown after the maximum number of retries is reached. You can use exception.getLastRequest to query the request information from when the error occurred.
TeaException: This exception indicates business errors that occur during SDK requests.

Take appropriate measures to handle exceptions, such as propagating exceptions, recording logs, and attempting recovery, to ensure system robustness and stability.

5. Complete example

using AlibabaCloud.TeaUtil.Models;
using Tea;

namespace ecs
{
    public class Sample
    {
        static void Main(string[] args)
        {
            var ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config
            {
                // Obtain the AccessKey ID from an environment variable.
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Obtain the AccessKey secret from an environment variable.
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                Endpoint = "ecs.cn-hangzhou.aliyuncs.com"
            };

            var escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            
            // Create a request object.
            var describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeInstancesRequest
            {
                RegionId = "cn-hangzhou"
            };
            // Create a runtime configuration object.
            var runtimeOptions = new RuntimeOptions();
            try
            {
                // Send the request.  
                var describeInstancesResponse =
                    escClient.DescribeInstancesWithOptions(describeInstancesRequest, runtimeOptions);
                Console.WriteLine(describeInstancesResponse.ToMap());
            }
            catch (TeaUnretryableException error)
            {
                // This is for printing and demonstration purposes only. Handle exceptions with care. Do not ignore exceptions in your projects.
                Console.WriteLine(error);
            }
            catch (TeaException error)
            {
                // This is for printing and demonstration purposes only. Handle exceptions with care. Do not ignore exceptions in your projects.
                // Error message
                Console.WriteLine(error.Message);
            }
            catch (Exception error)
            {
                // This is for printing and demonstration purposes only. Handle exceptions with care. Do not ignore exceptions in your projects.
                Console.WriteLine(error);
            } 
        }
    }
}

Scenario-based examples

More information

In addition to the preceding methods, you can also use generalized calls to call ECS OpenAPI operations. For more information, see Generalized calls.

For more information about the V1.0 SDK, see V1.0 .NET SDK.