Qishao.DingTalkStream.Robot 2026.8.7

Qishao.DingTalkStream.Robot

Qishao.DingTalkStream.Robot 是 Qishao.DingTalkStream.Core 的机器人消息扩展库，提供机器人回调订阅、机器人消息解析、会话 Webhook 主动发送，以及机器人回调快速回复数据构造能力。

安装

dotnet add package Qishao.DingTalkStream.Robot

目标框架

• net8.0
• netstandard2.1

当前项目引用 Qishao.DingTalkStream.Core。netstandard2.1 额外引用 System.Text.Json。

引用方式

当前仓库内使用项目引用：

<ProjectReference Include="..\Qishao.DingTalkStream.Robot\Qishao.DingTalkStream.Robot.csproj" />

Qishao.DingTalkStream.Robot 会同时带入 Qishao.DingTalkStream.Core。

快速开始

注册机器人消息回调订阅和消息处理器：

using Qishao.DingTalkStream.Core;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddDingtalkStream(options =>
        {
            options.ClientId = context.Configuration["ClientId"];
            options.ClientSecret = context.Configuration["ClientSecret"];
            options.AutoReplySystemMessage = true;
        })
        .RegisterIMRobotMessageCallback()
        .AddMessageHandler<RobotMessageHandler>()
        .AddHostServices();
    })
    .Build();

await host.RunAsync();

处理机器人文本消息，并通过会话 Webhook 主动回复：

using Qishao.DingTalkStream.Core;
using Qishao.DingTalkStream.Robot;

public sealed class RobotMessageHandler : IDingTalkStreamMessageHandler
{
    public async Task HandleMessage(MessageEventHanderArgs e)
    {
        if (!e.Headers.IsRobotTopic())
        {
            return;
        }

        var robotMessage = e.GetRobotMessageData();
        if (robotMessage.MsgType != "text")
        {
            return;
        }

        var text = robotMessage.GetTextContent();
        await DingtalkRobotWebhookUtilites.SendTextMessage(
            robotMessage.SessionWebhook,
            $"收到：{text.Content}");
    }
}

机器人订阅

RegisterIMRobotMessageCallback() 注册固定订阅：

判断推送是否为机器人消息：

if (e.Headers.IsRobotTopic())
{
    var robotMessage = e.GetRobotMessageData();
}

消息模型

GetRobotMessageData() 将 DingTalkStreamDataPackage.Data 解析为 ReceivedRobotMessage。

常用属性：

接收内容解析

按 MsgType 调用对应扩展方法。类型不匹配时会抛出 ArgumentException。

两种回复方式

1. 使用会话 Webhook 主动发送

DingtalkRobotWebhookUtilites 通过 SessionWebhook 发送消息，方法返回 bool，只表示 HTTP 响应是否成功。

支持构造和发送：

示例：

await DingtalkRobotWebhookUtilites.SendMarkdownMessage(
    robotMessage.SessionWebhook,
    "处理结果",
    "### 已收到机器人消息");

2. 使用 Stream 回调立即回复

DingtalkStreamRobotUtilities 构造机器人回调响应数据，再交给 DingTalkStreamUtilities.CreateReplyMessage 包装完整响应。

var data = await DingtalkStreamRobotUtilities.CreateReply_Text_MessageDataOfRobot("收到消息");
var reply = await DingTalkStreamUtilities.CreateReplyMessage(e.Headers.MessageId, data);
await e.Reply(reply);

支持构造：

• CreateReply_Text_MessageDataOfRobot
• CreateReply_Markdown_MessageDataOfRobot
• CreateReply_Image_MessageDataOfRobot
• CreateReply_Link_MessageDataOfRobot
• CreateReply_ActionCard_MessageDataOfRobot
• CreateReply_ActionCard2_MessageDataOfRobot
• CreateReply_Audio_MessageDataOfRobot
• CreateReply_File_MessageDataOfRobot
• CreateReply_Video_MessageDataOfRobot

注意点

• DingtalkRobotWebhookUtilites、DingtalkStreamDataHeadersExtentions 是当前公开 API，拼写保持兼容。
• SessionWebhook 来自钉钉推送数据，并带有 SessionWebhookExpiredTime，发送前要考虑过期时间。
• IsRobotTopic() 只判断 headers.topic 是否等于 /v1.0/im/bot/messages/get。
• GetRobotMessageData() 会解析 Data JSON。若推送数据结构异常，会直接抛出 JSON 或字段访问异常。
• BtnOrientation 当前枚举值注释和名称存在历史不一致，使用前以实际序列化结果为准。

构建验证

dotnet build .\Qishao.DingTalkStream.Robot\Qishao.DingTalkStream.Robot.csproj --no-restore