阿里雲物聯網 .NET Core 客戶端 | CZGL.AliIoTClient：1. 連接阿里雲物聯網

1） 阿里雲物聯網

阿里雲物聯網支持多種通訊協議，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

設置要訂閱的普通 Topic：

string[] topics = new string[] { ... , ... , ...  };

要求填寫 Topic 完整的長度的 URI ，可到控制檯中查看。例如 "/a1xrkGSkb5R/dockertest/user/update/error"

如果你不想這麼麻煩，可以使用

string[] topics = new string[] { client.CombineHeadTopic("get") };

只需輸入 Topic 的 /user/ 後面的內容即可，AliIoTClientJson.CombineHeadTopic() 會爲你生成完整的 Topic 地址。
例如需要訂閱 "/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 做示範。

運行上面已經編寫好的控制檯程序，不要關閉。

打開阿里雲物聯網控制檯，打開相應的設備，在設備的 Topic列表 裏面找到 .../user/get 這個 Topic，
例如： /a1xrkGSkb5R/dockertest/user/get

點擊 發佈消息 ，然後輸入要發送的內容，最後查看控制檯是否收到下發的消息。
由於使用了 CZGL.AliIoTClient 中，默認的事件方法，因此除了消息內容，也會輸出這條 Topic 消息的一些屬性信息。

---

7） 上傳數據

設備的 Topic 列表，有個 .../user/update ，例如 /a1xrkGSkb5R/dockertest/user/update 。
這個 Topic 允許客戶端上傳數據，下面將說明客戶端如何上傳數據到阿里雲物聯網服務器。

上傳普通 Topic 的方法：

I. 上傳 byte

public int CommonToServer(string topicName, byte[] content)

摘要:
此種方式以 byte[] 形式上傳數據，注意 byte[] 的進制

參數:
topicName: Topic 的完整名稱，可使用 CombineHeadTopic() 方法獲取
content: 消息內容

返回結果: 消息 ID

II. 普通字符串

public int CommonToServer(string topicName, string content)

摘要:
普通方式推送 Topic 到服務器，直接上傳字符串

返回結果: 消息 ID

III. 其它上傳方法

還要其它幾個方法，放到一起說明。

public int CommonToServer(string topicName, string content, 
                          [System.Text.Encoding encoding = null])

說明：上傳數據到指定 Topic ，指定字符串的編碼格式。阿里雲物聯網默認使用 UTF8。

  CZGL.AliIoTClient 也默認使用 UTF8 作爲數據的編碼，可以自定義上傳字符串的編碼。
  一般不需要改，不然中文字符串會亂碼。

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 具有 訂閱/發佈 權限。
然後修改程序試試是否正常上傳、下發數據。