Wsq.WeCom.AppChat 1.0.0

Wsq.WeCom.AppChat

Wsq.WeCom.AppChat 是一个轻量级的 .NET Standard 2.0 类库，用于封装 企业微信 (WeCom) 的 应用群聊 (AppChat) API。

该库旨在简化企业微信自建应用的消息推送流程，支持自动管理 AccessToken、创建群聊以及发送文本、Markdown 和图片消息。

📋 功能特性

• 多平台兼容：基于 .NET Standard 2.0 开发，兼容 .NET Framework 4.6.1+、.NET Core 2.0+、.NET 5/6/7/8+。
• Token 自动管理：内置 AccessToken 缓存与自动刷新机制，无需手动处理 Token 过期。
• 群聊管理：支持通过 API 创建应用群聊，获取 chatid。
• 消息推送：
  • 支持纯文本 (Text)
  • 支持 Markdown (支持颜色高亮)
  • 支持图片 (Image) - 自动处理素材上传

📦 依赖环境

• System.Text.Json (>= 4.7.2)

🚀 快速开始

1. 初始化配置

在使用任何功能前，需要配置企业的 CorpId 和自建应用的 Secret。

using Wsq.WeCom.AppChat;

// 1. 配置企业微信信息
var config = new WeComConfig(
    corpId: "wwxxxxxxxxxxxxxxxx",      // 你的企业ID
    corpSecret: "xxxxxxxxxxxxxxxxxxxx" // 你的应用Secret
);

// 2. 创建客户端实例 (建议在程序中作为单例使用)
var client = new WeComAppChatClient(config);

2. 创建群聊 (获取 ChatId)

如果还没有群，可以使用此方法创建一个新群。 注意：userList 必须包含至少 2 个人的 UserID（企业通讯录中的账号），且 ownerUserId 必须在 userList 中。

try 
{
    string chatId = await client.CreateGroupAsync(
        groupName: "交易预警群",
        ownerUserId: "ZhangSan", 
        userList: new[] { "ZhangSan", "LiSi", "WangWu" }
    );
    
    Console.WriteLine($"群创建成功，ChatID: {chatId}");
    // 请保存这个 ChatID，后续发消息都需要用到它
}
catch (Exception ex)
{
    Console.WriteLine($"创建失败: {ex.Message}");
}

3. 发送消息

发送文本消息

string targetChatId = "CHATID_xxxxxxxxxx"; // 填入上面获取到的 ChatID

await client.SendTextAsync(targetChatId, "交易系统已启动，正在监控数据...");

发送 Markdown 消息 (推荐)

Markdown 支持简单的样式和颜色，非常适合发送报警或交易信号。 支持的颜色：

• <font color="info">绿色</font>
• <font color="warning">橙红色</font>
• <font color="comment">灰色</font>

string mdContent = @"### 🚀 交易信号触发
> 标的：**BTC/USDT**
> 方向：<font color=""info"">做多 (Long)</font>
> 现价：$68,000
> 涨幅：<font color=""warning"">+5.2%</font>";

await client.SendMarkdownAsync(targetChatId, mdContent);

发送图片消息

该方法会自动读取本地文件 → 上传到企业微信临时素材 → 获取 MediaId → 发送群消息。

string imagePath = @"C:\Data\kline_chart.png";

if (System.IO.File.Exists(imagePath))
{
    await client.SendImageAsync(targetChatId, imagePath);
}

⚠️ 注意事项与限制

1. ChatID 说明：

   • 本库使用的是 appchat/send 接口，只能向“由应用创建的群”发送消息。
   • 不能向你手机上手动拉的普通群发送消息。必须使用 CreateGroupAsync 创建群，或者使用官方后台获取的 chatid。

2. 图片限制：

   • 格式支持 JPG, PNG。
   • 文件大小不能超过 2MB。
   • 如果要发送大图，请先在代码中进行压缩处理。

3. API 频率：

   • 企业微信对 API 调用频率有限制，请避免短时间内发送大量消息（如死循环发送），否则应用可能会被暂时封禁接口权限。

4. UserID：

   • 代码中用到的用户名（如 "ZhangSan"）指的是企业通讯录中的 账号 (UserID)，不是中文姓名。

🛠️ 异常处理

库中所有方法在 API 调用失败（如 Token 无效、参数错误、无权限）时，都会抛出 Exception。异常信息中包含企业微信返回的 errcode 和 errmsg。

建议在外层使用 try-catch 包裹：

try
{
    await client.SendTextAsync(chatId, "Hello");
}
catch (Exception ex)
{
    // 例如：WeCom API Error (40096): userid not found
    Console.WriteLine($"发送失败: {ex.Message}");
}