SDK 中心 .Net 产品文档

SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第1 共9页 SDK 中心 .NET 产品文档 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第2 共9页 【版权声明】 ©2013-2023 腾讯云版权所有 本文档（含所有文字、数据、图片等内容）完整的著作权归腾讯云计算（北京）有限责任公司单独所有，未经腾讯 云事先明确书面许可，任何主体不得以任何形式复制、修改、使用、抄袭、传播本文档全部或部分内容。前述行为 构成对腾讯云著作权的侵犯，腾讯云将依法采取措施追究法律责任。 【商标声明】 及其它腾讯云服务相关的商标均为腾讯云计算（北京）有限责任公司及其关联公司所有。本文档涉及的第三方主体 的商标，依法由权利人所有。未经腾讯云及有关权利人书面许可，任何主体不得以任何方式对前述商标进行使用、 复制、修改、传播、抄录等行为，否则将构成对腾讯云及有关权利人商标权的侵犯，腾讯云将依法采取措施追究法 律责任。 【服务声明】 本文档意在向您介绍腾讯云全部或部分产品、服务的当时的相关概况，部分产品、服务的内容可能不时有所调整。 您所购买的腾讯云产品、服务的种类、服务标准等应由您与腾讯云之间的商业合同约定，除非双方另有约定，否 则，腾讯云对本文档内容不做任何明示或默示的承诺或保证。 【联系我们】 我们致力于为您提供个性化的售前购买咨询服务，及相应的技术售后服务，任何问题请联系 4009100100。 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第3 共9页 简介 欢迎使用腾讯云开发者工具套件（SDK）3.0，SDK 3.0 是云 API 3.0 平台的配套工具。SDK 3.0 实现了统 一化，各个语言版本的 SDK 具备使用方法相同、接口调用方式相同、错误码和返回包格式相同等优点。 本文以 .NET SDK 3.0 为例，介绍如何使用、调试并接入腾讯云产品 API。 目前已支持云服务器 CVM、私有网络 VPC 、云硬盘 CBS 等 腾讯云产品，后续会支持其他云产品接入。 依赖环境 .NET Framework 4.5+ 或者 .NET Core 2.1。 获取安全凭证。安全凭证包含 SecretId 及 SecretKey 两部分。SecretId 用于标识 API 调用者的身份， SecretKey 用于加密签名字符串和服务器端验证签名字符串的密钥。前往 API 密钥管理 页面，即可进行获 取，如下图所示： .NET 最近更新时间：2021-03-10 11:03:41 注意： 您的安全凭证代表您的账号身份和所拥有的权限，等同于您的登录密码，切勿泄露他人。 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第4 共9页 获取调用地址。调用地址（endpoint）一般形式为*.tencentcloudapi.com，产品的调用地址有一定区别，例 如，云服务器的调用地址为cvm.tencentcloudapi.com。具体调用地址可参考对应产品的 API 文档。 安装 SDK 方式一、通过 nuget 安装（推荐） 通过命令行安装（这里的版本仅作为示例，实际请选择最新版本）： dotnet add package TencentCloudSDK --version 3.0.0 # 其他信息请前往 www.nuget.org/packages/TencentCloudSDK 获取 通过 Visual Studio 添加包： 例如，创建一个 HelloWorld 项目： dotnet new console -o HelloWorld # 进入到 HelloWorld 项目主目录 dotnet run # 输出为：Hello World! dotnet add package TencentCloudSDK --version 3.0.0 # 为项目下载 SDK 依赖 方式二、通过源码安装 前往 Github 代码托管地址 下载最新代码，解压后安装到你的工作目录下，使用 Visual Studio 2017 打开编 译。 使用 SDK 注意： 命令需要在项目的主目录下执行。 说明： 如果想单独安装某个产品，例如云服务器 CVM，则添加依赖 TencentCloudSDK.Cvm 即可。 更多 SDK 支持的云产品，请参见 云产品名列表。 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第5 共9页 每个接口都有一个对应的 Request 结构和一个 Response 结构。例如，云服务器的查询实例列表接口 DescribeInstances 有对应的请求结构体 DescribeInstancesRequest 和返回结构体 DescribeInstancesResponse。 下面以云服务器查询实例列表接口为例，介绍 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()); } } } } using System; using System.Threading.Tasks; using TencentCloud.Common; SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第6 共9页 using TencentCloud.Common.Profile; using TencentCloud.Cvm.V20170312; using TencentCloud.Cvm.V20170312.Models; namespace TencentCloudExamples { class DescribeInstances { static void Main(string[] args) { try { // 必要步骤： // 实例化一个认证对象，入参需要传入腾讯云账户密钥对 secretId、secretKey。 // 这里采用的是从环境变量读取的方式，需要在环境变量中先设置这两个值。 // 您也可以直接在代码中写死密钥对，但是小心不要将代码复制、上传或者分享给他人， // 以免泄露密钥对危及您的财产安全。 Credential cred = new Credential { SecretId = Environment.GetEnvironmentVariable("TENCENTCLOUD_SECRET_ID"), SecretKey = Environment.GetEnvironmentVariable("TENCENTCLOUD_SECRET_KEY") }; // 实例化一个 client 选项，可选的，没有特殊需求可以跳过 ClientProfile clientProfile = new ClientProfile(); // 指定签名算法（默认为 HmacSHA256） clientProfile.SignMethod = ClientProfile.SIGN_SHA1; // 非必要步骤 // 实例化一个客户端配置对象，可以指定超时时间等配置 HttpProfile httpProfile = new HttpProfile(); // SDK 默认使用 POST 方法。 // 如果您一定要使用 GET 方法，可以在这里设置。GET 方法无法处理一些较大的请求。 httpProfile.ReqMethod = "POST"; // SDK 有默认的超时时间，非必要请不要进行调整。 // 如有需要请在代码中查阅以获取最新的默认值。 httpProfile.Timeout = 10; // 请求连接超时时间，单位为秒（默认60秒） // SDK 会自动指定域名。通常是不需要特地指定域名的，但是如果您访问的是金融区的服务， // 则必须手动指定域名，例如云服务器的上海金融区域名：cvm.ap-shanghai-fsi.tencentcloudapi.co m httpProfile.Endpoint = ("cvm.tencentcloudapi.com"); // 代理服务器，当您的环境下有代理服务器时设定 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第7 共9页 httpProfile.WebProxy = Environment.GetEnvironmentVariable("HTTPS_PROXY"); clientProfile.HttpProfile = httpProfile; // 实例化要请求产品（以 cvm 为例）的 client 对象 // 第二个参数是地域信息，可以直接填写字符串 ap-guangzhou，或者引用预设的常量，clientProfile 是可选的 CvmClient client = new CvmClient(cred, "ap-guangzhou", clientProfile); // 实例化一个请求对象，根据调用的接口和实际情况，可以进一步设置请求参数 // 您可以直接查询 SDK 源码确定 DescribeInstancesRequest 有哪些属性可以设置， // 属性可能是基本类型，也可能引用了另一个数据结构。 // 推荐使用 IDE 进行开发，可以方便的跳转查阅各个接口和数据结构的文档说明。 DescribeInstancesRequest req = new DescribeInstancesRequest(); // 基本类型的设置。 // 此接口允许设置返回的实例数量。此处指定为只返回一个。 // SDK 采用的是指针风格指定参数，即使对于基本类型您也需要用指针来对参数赋值。 // SDK 提供对基本类型的指针引用封装函数 req.Limit = 1; // 数组类型的设置。 // 此接口允许指定实例 ID 进行过滤，但是由于和接下来要演示的 Filter 参数冲突，先注释掉。 // req.InstanceIds = new string[] { "ins-r8hr2upy" }; // 复杂对象的设置。 // 在这个接口中，Filters 是数组，数组的元素是复杂对象 Filter，Filter 的成员 Values 是 string 数组。 // 填充请求参数,这里 request 对象的成员变量即对应接口的入参 // 您可以通过官网接口文档或跳转到 request 对象的定义处查看请求参数的定义 Filter respFilter = new Filter(); // 创建 Filter 对象, 以 zone 的维度来查询 cvm 实例 respFilter.Name = "zone"; respFilter.Values = new string[] { "ap-guangzhou-1", "ap-guangzhou-2" }; req.Filters = new Filter[] { respFilter }; // Filters 是成员为 Filter 对象的列表 //// 这里还支持以标准 json 格式的 string 来赋值请求参数的方式。下面的代码跟上面的参数赋值是等效 的 //string strParams = "{\"Filters\":[{\"Name\":\"zone\",\"Values\":[\"ap-guangzhou-1\",\"ap-gua ngzhou-2\"]}]}"; //req = DescribeInstancesRequest.FromJsonString(strParams); // 通过 client 对象调用 DescribeInstances 方法发起请求。注意请求方法名与请求对象是对应的 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第8 共9页 更多示例 更多示例请参见 github TencentCloudExamples 目录。 同步调用与异步调用 新版本 SDK 中同时提供了异步接口和同步接口，同步接口统一在异步接口之后添加了 Sync 后缀，在上述代码中已 有样例。 // 返回的 resp 是一个 DescribeInstancesResponse 类的实例，与请求对象对应 DescribeInstancesResponse resp = client.DescribeInstancesSync(req); // 使用同步接口调用结果 // DescribeInstancesResponse resp = client.DescribeInstancesSync(req); // 输出 json 格式的字符串回包 Console.WriteLine(AbstractModel.ToJsonString(resp)); // 也可以取出单个值。 // 您可以通过官网接口文档或跳转到 response 对象的定义处查看返回字段的定义 Console.WriteLine(resp.TotalCount); } catch (Exception e) { Console.WriteLine(e.ToString()); } Console.Read(); } } } 注意： 在示例中由于是控制台应用程序，因此可以使用同步方式调用异步接口，即 ConfigureAwait(false).GetAwaiter().GetResult() 。在开发 ASP 应用程序，或者 Windows Forms 应用程序时，UI 控件的响应方法中，不能使用同步方式调用异步接口，否则会造成界面停止响应。 解决办法：将 UI 控件的响应方法改为异步，同时要注意同步上下文。另外，由于异步调用立即返回控制权 给用户，很容易造成用户多次点击，或者用户进行了一些不期望的操作，程序中应注意此类问题。源码可以 参考项目中的 WindowsFormsDemo 项目。 SDK 中心 版权所有：腾讯云计算（北京）有限责任公司 第9 共9页 源码可以参考：腾讯云社区专栏文章 相关配置 代理 若在代理的环境下使用 SDK 进行接口调用，则需设置系统环境变量 https_proxy （已在示例代码中体现），否则 可能出现无法正常调用、抛出连接超时异常的现象。 常见问题 SDK 依赖的 FluentClient 使用的是3.2版本，但这个包目前发布了4.0版本且不兼容低版本，在 nuget 中升级此 包到4.0版本会导致无法调用或调用失败等问题。