首先来了解阿里云物联网平台。该平台支持多种通信协议，而 CZGL.AliIoTClient 客户端库基于 MQTT 协议实现，底层通讯库采用 M2MQTT。数据传输方式主要有两种：透传与Alink JSON。这两种方式在属性读写、事件上报、服务调用这四个 Topic 上存在差异，但在连接、普通 Topic 以及响应等环节基本一致。建议优先选用 Alink JSON 方式上传和下发数据。
| 传输形式 | 本质 | 说明 |
|---|---|---|
| Alink json | json | 需按照阿里云物联网文档配置 json |
| 透传 | 二进制 | 使用属性、事件和服务时，数据为二进制，有具体的传输位要求 |
CZGL.AliIoTClient 同时兼容 Alink JSON 与透传两种格式。SDK 内置了两个客户端类：
| 类 | 说明 |
|---|---|
| AliIoTClientJson | 以 Alink json 为传输形式的客户端 |
| AliIoTClientBinary | 以二进制为传输形式的客户端 |
这两个类在大部分功能上相同，区别仅体现在属性、事件、服务方面的数据传输格式。因此本文主要以 AliIoTClientJson 为例进行讲解。
2） 连接到阿里云IOT
2.1） 创建客户端
创建客户端实例时，需要传入一个 DeviceOptions 对象。在此之前，需先在阿里云物联网控制台复制设备的密钥等信息，并将其填入 DeviceOptions 中。示例如下：
AliIoTClientJson client = new AliIoTClientJson(new DeviceOptions{
ProductKey = "a1xrkGSkb5R",
DeviceName = "mire",
DeviceSecret = "CqGMkOBDiKJfrOWp1evLZC2O6fsMtEXw",
RegionId = "cn-shanghai"
});2.2） 设置要订阅的 Topic
连接客户端之前，需要先配置要订阅的普通 Topic，并决定是否接收属性设置命令、服务调用及响应等 Topic。
普通 Topic 可以通过以下方式设置：
string[] topics = new string[] { ... , ... , ...};需要填写 Topic 的完整 URI（可在控制台查看），例如 "/a1xrkGSkb5R/dockertest/user/update/error"。若想简化操作，也可使用：
string[] topics = new string[] { client.CombineHeadTopic("get") };只需输入 Topic 中 /user/ 后面的内容，AliIoTClientJson.CombineHeadTopic() 会自动补全完整地址。例如订阅 /a1xrkGSkb5R/dockertest/user/update/error，只需写：
string[] topics = new string[] { client.CombineHeadTopic("update/error") };除普通 Topic 外，还有设备上传数据、接收服务器响应、服务器设置设备属性、调用设备服务等场景，这些内容将在后续章节详细说明。
3） 设置默认事件
收到消息时，希望程序执行特定操作？将对应方法绑定到委托事件上，当条件满足时便会触发。这里先使用 CZGL.AliIoTClient 预置的默认委托方法，后续章节再介绍自定义方式。
client.UseDefaultEventHandler();4） 客户端连接
配置完成后，即可连接阿里云物联网。CZGL.AliIoTClient 提供了三个连接相关方法：
| 方法 | 说明 |
|---|---|
| AliIoTClientJson.ConnectIoT(string[], byte[], ushort) | 连接到阿里云物联网服务器 |
| AliIoTClientJson.ConnectIoTAsync(string[], byte[], ushort) | 异步连接到阿里云物联网服务器 |
| AliIoTClientJson.ConnectIoTClose() | 关闭、释放客户端 |
5） 示例
首先在阿里云物联网控制台创建一个产品，并在该产品下新建一个设备（其他功能无需添加），记录新设备的密钥等信息。然后在 Visual Studio 中新建一个 .NET Core 控制台应用，通过 NuGet 添加 CZGL.AliIoTClient 包。控制台代码如下：
// 创建客户端
client = new AliIoTClientJson(new DeviceOptions{
ProductKey = "a1xrkGSkb5R",
DeviceName = "mire",
DeviceSecret = "CqGMkOBDiKJfrOWp1evLZC2O6fsMtEXw",
RegionId = "cn-shanghai"
});
// 设置要订阅的Topic、运行接收内容的Topic
string[] topics = new string[] { client.CombineHeadTopic("get") };
// 使用默认事件
client.UseDefaultEventHandler();
// 连接服务器
client.ConnectIoT(topics, null, 60);
Console.ReadKey();运行后，打开阿里云物联网控制台，刷新设备列表，即可看到设备已在线。
6） 下发数据
新建的产品会包含几个默认 Topic，此处先用默认 Topic 演示。保持控制台程序运行，打开阿里云物联网控制台，找到对应设备的 .../user/get Topic（例如 /a1xrkGSkb5R/dockertest/user/get），点击“发布消息”，输入内容后发送。由于使用了默认事件方法，控制台不仅会打印消息内容，还会输出该 Topic 消息的一些属性信息。
7） 上传数据
设备 Topic 列表中有一个 .../user/update（例如 /a1xrkGSkb5R/dockertest/user/update），客户端可通过此 Topic 上传数据。上传普通 Topic 的方式有以下几种：
- 上传 byte 数组
public int CommonToServer(string topicName, byte[] content)
以 byte[] 形式上传数据，需要注意进制问题。参数 topicName 为 Topic 完整名称（可使用CombineHeadTopic()获取），content 为消息内容。返回消息 ID。 - 上传普通字符串
public int CommonToServer(string topicName, string content)
直接上传字符串，返回消息 ID。 - 指定编码上传
public int CommonToServer(string topicName, string content, [System.Text.Encoding encoding = null])
可指定字符串编码格式。阿里云物联网默认使用 UTF-8，CZGL.AliIoTClient也默认采用 UTF-8，通常无需修改，否则中文字符可能出现乱码。 - Base64 编码上传
public int CommonToServerBase64(string topicName, string content)
先将字符串进行 Base64 编码再上传。
public int CommonToServerBase64(string topicName, string content, [System.Text.Encoding encoding = null])
可指定编码，然后 Base64 编码后上传。
8） 创建Topic
在阿里云物联网控制台，打开某个产品，可以新建一个或多个 Topic，并设置该 Topic 的“订阅/发布”权限。随后修改程序验证上传和下发数据是否正常——这就是完整的流程。
