# 环信 IM Windows SDK 快速入门

    本文介绍如何快速集成环信 IM Windows SDK 实现发送和接收单聊文本消息。

    # 技术原理

    下图展示在客户端发送和接收单聊文本消息的工作流程。

    img

    如上图所示,发送和接收单聊消息的步骤如下:

    1. 客户端向你的应用服务器请求 Token,你的应用服务器返回 Token。
    2. 客户端 A 和客户端 B 使用获得的 Token 登录环信即时通讯系统。
    3. 客户端 A 发送消息到环信即时通讯服务器。
    4. 环信即时通讯服务器将消息发送到客户端 B,客户端 B 接收消息。

    # 前提条件

    开始前,请确保你的开发环境满足以下条件:

    • Windows SDK 0.1.0 或以上;
    • Visual Studio IDE 2019 或以上;
    • .Net Framework 4.5.2 或以上;
    • 目前 Windows SDK 仅支持 64 位运行模式;
    • 有效的环信即时通讯 IM 开发者账号和 App Key,见 环信即时通讯云控制台 (opens new window)

    # 项目设置

    实现发送和接收单聊文本消息之前,参考以下步骤设置你的项目。

    # 1. 下载并设置 Windows Demo 项目

    参考以下步骤:

    1. 克隆 chat_windows_demo (opens new window) 至本地;
    2. 在 Windows 浏览器中跳转到第一步克隆仓库的本地目录下;
    3. 双击打开 windows-example.sln 打开 Visual Studio 开发工具;
    4. 在 Visual Studio 上部的下拉菜单中,选择解决方案配置为: Debug;解决方案平台为: x64;

    # 2. 集成环信即时通讯 SDK

    你可以参考以下步骤集成 SDK:

    1. 下载:点击 Windows SDK (opens new window) 进行下载,下载的 NuGet 包一般存放在 C:\Users\XXX\Downloads (XXX 为本机用户名);
    2. 将下载的 NuGet 包拷贝到自己的工作目录,比如 D:\workspace\WinSDK 下,以下说明以此目录举例;
    3. 在 Visual Studio 开发环境里,右键点击 windows-example 项目,选择 管理 NuGet 程序包 (N)...
    4. 在弹出的 NuGet:windows-example tab 页面里,点击右上角的小齿轮会弹出 NuGet 程序包源的设置窗体,点击窗体右上角的 + 按钮,在 包源 的文本框内会出现 Package source 这一栏,点击选中,并修改文本框下的 名称。例如 名称 可以设置为 Local Package source 则设置为第 2 步中的目录, D:\workspace\WinSDK,点击确定;
    5. NuGet:windows-example tab 页面,在右上角的 “程序包源” 处点击下拉菜单,选中刚刚配置的包源名称 Local Package source
    6. NuGet:windows-example tab 页面上部,选中 浏览,在下面搜索框的右边,勾选 包括预发行版,此时下面的区域会出现 agora_chat_sdk (如果没有出现,点击搜索框右侧的刷新按),选中这一栏,右边会出现一个向下的小箭头,点击进行安装,或者点击右侧栏最右边的 安装 按钮;
    7. 在弹出的 预览更改 窗体中,点击确定按钮;
    8. 到此 Windows SDK 的 NuGet 包集成完毕。

    # 实现发送和接收单聊消息

    本节介绍如何使用即时通讯 SDK 在你的 Windows .Net 项目中实现发送和接收单聊消息。

    # 1. 打开代码文件开始编辑

    在 Visual Studio 的 windows-example 项目下,点击 MainWindow.xaml 左边的小三角,然后双击 MainWindow.xaml.cs 文件开始编辑。

    注意

    如果 Visual Studio 提示 JsonConvert 未定义(即下面有红色波浪线),这是由于当前的项目里没有导入 Newtonsoft.Json 包造成的,可以通过重新安装 Newtonsoft.Json 来骤修复这个问题,以下是具体步骤:

    • 右键点击 windows-example 项目,然后选择 管理 NuGet 程序包
    • NuGet:windows-example tab 页面下,选择 已安装,点击 Newtonsoft.Json 这一栏,然后点击这一栏右边的小红叉,或者点击最右边分隔栏里的 “ 卸载 ” 按钮,将 Newtonsoft.Json 卸载掉;
    • NuGet:windows-example tab 页面下,选择 浏览,在搜索框里输入 Newtonsoft,然后在下面出现的搜索结果中,选中 Newtonsoft.Json,点击这一栏右边的下载小图标,进行重新安装即可。

    # 2. 添加命名空间

    MainWindow.xaml.cs 头部添加以下命名空间:

    using ChatSDK;
    using ChatSDK.MessageBody;
    

    # 3. 初始化 SDK

    InitSDK 函数中添加以下代码完成 SDK 初始化:

    var options = new Options(appKey: APPKEY);
    options.UsingHttpsOnly = true;
    SDKClient.Instance.InitWithOptions(options);
    

    提示

    代码中目前的 App Key 为 easemob-demo#easeim, 为演示用,如果是正式环境,需要使用你申请的 App Key。

    # 4.创建账号

    SignUp_Click 函数尾部添加以下代码,用于创建 AppServer 上的登录账户,示例代码如下:

    bool result = await RegisterToAppServer(UserIdTextBox.Text, PasswordTextBox.Text);
    if (result)
    {
        AddLogToLogText("sign up succeed");
    }
    else
    {
        AddLogToLogText("sign up failed");
    }
    

    注意

    该注册模式为在客户端注册,主要用于测试,简单方便,但不推荐在正式环境中使用;正式环境中应使用服务器端调用 Restful API 注册,具体见:注册单个用户 (opens new window)

    # 5. 登录账号

    SignIn_Click 函数尾部添加以下代码,用于使用账号登录即时通讯系统,示例代码如下:

    string token = await LoginToAppServer(UserIdTextBox.Text, PasswordTextBox.Text);
    if (token != null)
    {
       SDKClient.Instance.LoginWithAgoraToken(UserIdTextBox.Text, token, handle: new CallBack(
            onSuccess: () =>
            {
                AddLogToLogText("sign in sdk succeed");
            },
            onError: (code, desc) =>
            {
                AddLogToLogText($"sign in sdk failed, code: {code}, desc: {desc}");
            }
        ));
    }
    else
    {
        AddLogToLogText($"fetch token error");
    }
    

    提示

    此处登录账户包含两个操作:1. 调用 LoginToAppServer 获取 Agora token;2. 调用 LoginWithAgoraToken 使用用户名和 Agora token 进行环信服务器登录。

    # 6. 登出账号

    SignOut_Click 函数尾部添加以下代码,用于登出即时通讯系统,示例代码如下:

    SDKClient.Instance.Logout(true, handle: new CallBack(
        onSuccess: () =>
        {
            AddLogToLogText("sign out sdk succeed");
        },
        onError: (code, desc) =>
        {
            AddLogToLogText($"sign out sdk failed, code: {code}, desc: {desc}");
        }
    ));
    

    # 7.发送一条文本消息

    SendBtn_Click 函数尾部添加以下代码,可以用于创建一条文本消息,然后发送该消息:

    Message msg = Message.CreateTextSendMessage(SingleChatIdTextBox.Text, MessageContentTextBox.Text);
        SDKClient.Instance.ChatManager.SendMessage(ref msg, new CallBack(
        onSuccess: () =>
        {
            Dip.Invoke(() =>
            {
                AddLogToLogText($"send message succeed, receiver: {SingleChatIdTextBox.Text},  message: {MessageContentTextBox.Text}");
            });
        },
        onError: (code, desc) =>
        {
            AddLogToLogText($"send message failed, code: {code}, desc: {desc}");
        }
    ));
    

    提示

    发送一条文本消息示例代码中的,在成功回调函数中,为了使用界面元素,例如:SingleChatIdTextBox.Text;MessageContentTextBox.Text,需要使用 System.Windows.Threading.Dispatcher(参见代码中的 Dip 变量)的 Invoke 进行操作。

    # 8.接收消息

    接收消息需要对象继承 IChatManagerDelegate 并实现相关的回调函数,同时将对象加入到监听列表中。

    示例代码如下:

    在类声明的头部继承 IChatManagerDelegate 对象。

    public partial class MainWindow : Window, IChatManagerDelegate
    
    

    MainWindow 类内部添加以下回调函数。

    提示

    由于这里只测试消息接收回调,所以其他回调暂时无需实现,保留空函数即可。

    public void OnMessagesReceived(List<Message> messages)
    {
        foreach (Message msg in messages)
        {
            if (msg.Body.Type == MessageBodyType.TXT)
            {
                TextBody txtBody = msg.Body as TextBody;
                AddLogToLogText($"received text message: {txtBody.Text}, from: {msg.From}");
            }
            else if (msg.Body.Type == MessageBodyType.IMAGE)
            {
                _ = msg.Body as ImageBody;
                AddLogToLogText($"received image message, from: {msg.From}");
            }
            else if (msg.Body.Type == MessageBodyType.VIDEO)
            {
                _ = msg.Body as VideoBody;
                AddLogToLogText($"received video message, from: {msg.From}");
            }
            else if (msg.Body.Type == MessageBodyType.VOICE)
            {
                _ = msg.Body as VoiceBody;
                AddLogToLogText($"received voice message, from: {msg.From}");
            }
            else if (msg.Body.Type == MessageBodyType.LOCATION)
            {
                _ = msg.Body as LocationBody;
                AddLogToLogText($"received location message, from: {msg.From}");
            }
            else if (msg.Body.Type == MessageBodyType.FILE)
            {
                _ = msg.Body as FileBody;
                AddLogToLogText($"received file message, from: {msg.From}");
            }
        }
    }
    
    public void OnCmdMessagesReceived(List<Message> messages)
    {
    
    }
    
    public void OnMessagesRead(List<Message> messages)
    {
    
    }
    
    public void OnMessagesDelivered(List<Message> messages)
    {
    
    }
    
    public void OnMessagesRecalled(List<Message> messages)
    {
    
    }
    
    public void OnReadAckForGroupMessageUpdated()
    {
    
    }
    
    public void OnGroupMessageRead(List<GroupReadAck> list)
    {
    
    }
    
    public void OnConversationsUpdate()
    {
    
    }
    
    public void OnConversationRead(string from, string to)
    {
    
    }
    
    

    AddChatDelegate 函数中添加以下代码,以将 TestCode 对象实例加入到监听列表中

    SDKClient.Instance.ChatManager.AddChatManagerDelegate(this);
    

    # 9.测试修改后的项目

    在 Visual Studio 窗体上部,点击 启动 按钮。

    1. 注册用户:在 user id 文本框中输入用户名,在 password 文本框中输入密码,点击 Sign up 进行用户注册。注册的结果会在下方的方形区域进行显示。这里可以创建两个用户,例如 quickstart_senderquickstart_receiver,一个用来发送消息,一个用来接收消息。
    2. 用户登录:在 user id 文本框中输入用户名,例如输入 quickstart_sender,在 password 文本框中输入密码,点击 Sign in 进行登录。登录结果会在下方的方形区域进行显示。
    3. 发送消息:在 single chat id 文本框中输入消息接收方,例如输入 quickstart_receiver,在 message content 文本框中输入想要发送的文本内容,如 how are you.,点击 Send 进行消息发送,消息发送结果会在下方的方形区域进行显示。
    4. 用户退出登录:直接点击 Sign out 会让当前用户退出登录,退出结果会在下方的方形区域进行显示。
    5. 接收消息:在 user id 文本框中输入接收消息的用户名,例如 quickstart_receiver, 在 password 文本框输入密码,点击 Sign in 进行登录。登录成功后,下方的方形区域将会显示接收到的消息,例如第 3 步发送的 how are you.

    # 参考信息

    除文中用到的 用户 ID + 声网 token 登录方式(Demo 中使用)外,我们也支持 用户 ID + 密码 以及 用户 ID + 环信 token 的登录方式,具体可参考 API reference。

    更新时间:2022-09-16 11:03:39