Bot Framework Composer 自定义动作开发指南：实现乘法计算功能

概述

在Bot Framework Composer中，动作(Action)是对话流程的核心组成部分。虽然Composer提供了丰富的内置动作，但开发者经常需要创建自定义动作来实现特定业务逻辑。本文将详细介绍如何在C#中开发一个名为MultiplyDialog的自定义乘法计算动作，并将其集成到Composer项目中。

技术准备

在开始之前，请确保具备以下条件：

1. 了解Composer中动作的基本概念
2. 已使用Composer创建过基础机器人项目
3. 安装了Bot Framework CLI工具（4.10或更高版本）

项目结构解析

本示例项目包含两个主要部分：

1. Composer主项目：一个标准的Dotnet项目，需要添加对自定义动作项目的依赖
2. 自定义动作项目：包含实现乘法计算功能的所有组件

自定义动作实现详解

1. 创建动作类

核心动作类MultiplyDialog继承自Dialog基类，主要实现BeginDialogAsync方法。该方法接收两个数字参数，计算它们的乘积并返回结果。

public class MultiplyDialog : Dialog
{
    public override async Task<DialogTurnResult> BeginDialogAsync(DialogContext dc, object options = null, CancellationToken cancellationToken = default)
    {
        // 获取输入参数
        var arg1 = (double)Options["arg1"];
        var arg2 = (double)Options["arg2"];
        
        // 计算乘积
        var result = arg1 * arg2;
        
        // 设置输出结果
        dc.State.SetValue("dialog.result", result);
        
        return await dc.EndDialogAsync(result, cancellationToken);
    }
}

2. 定义动作Schema

Schema文件MultiplyDialog.schema定义了动作的元数据，包括：

• 动作名称和描述
• 输入参数定义
• 输出结果定义

{
    "$schema": "https://schemas.botframework.com/schemas/component/v1.0/component.schema",
    "$role": "implements(Microsoft.IDialog)",
    "title": "Multiply two numbers",
    "description": "Multiplies two numbers and returns the result",
    "type": "object",
    "properties": {
        "arg1": {
            "type": "number",
            "title": "First number"
        },
        "arg2": {
            "type": "number",
            "title": "Second number"
        },
        "result": {
            "type": "string",
            "title": "Result property",
            "description": "Property to store the result in"
        }
    },
    "required": ["arg1", "arg2", "result"]
}

3. 实现BotComponent

MultiplyDialogBotComponent类负责将自定义动作注册到DI容器中：

public class MultiplyDialogBotComponent : BotComponent
{
    public override void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        // 注册自定义动作
        services.AddSingleton<DeclarativeType>(sp => 
            new DeclarativeType<MultiplyDialog>(MultiplyDialog.Kind));
    }
}

项目集成步骤

1. 添加项目引用：在主项目中添加对自定义动作项目的引用
2. 配置运行时设置：修改appsettings.json文件，将自定义组件添加到运行时配置中
3. 更新Schema文件：运行提供的脚本更新sdk.schema文件，使Composer能识别新动作

"runtimeSettings": {
    "components": [
        {
            "name": "CustomAction.MultiplyDialog"
        }
    ]
}

在Composer中使用自定义动作

完成上述步骤后，在Composer中：

1. 打开任意触发器
2. 点击"+"添加新动作
3. 在"Custom Actions"分类下找到"Multiply"动作
4. 配置输入参数和结果存储位置
5. 添加"Send a response"动作显示计算结果

测试与验证

1. 在Composer中重启机器人
2. 使用测试面板发送消息触发包含自定义动作的流程
3. 验证机器人是否正确返回乘法计算结果

最佳实践建议

1. 错误处理：在实际应用中，应添加参数验证和异常处理
2. 日志记录：建议添加适当的日志记录以方便调试
3. 单元测试：为自定义动作编写单元测试确保功能正确性
4. 文档注释：为代码添加详细的XML注释，方便其他开发者理解

扩展思考

本示例展示了基本的自定义动作开发流程，开发者可以在此基础上实现更复杂的业务逻辑，如：

• 数据库操作
• 外部API调用
• 复杂业务计算
• 多步骤交互流程

通过合理设计，可以将企业核心业务能力封装为Composer可用的自定义动作，显著提升对话机器人的开发效率。

总结

本文详细介绍了在Bot Framework Composer中开发和使用自定义动作的完整流程。掌握这一技术后，开发者可以突破Composer内置功能的限制，创建出功能更加强大、业务针对性更强的对话机器人解决方案。