简介：这是一份面向C#开发者的企业级消息集成实战源码，聚焦钉钉开放平台API调用，适用于需在内部系统中快速接入钉钉通知、用户身份识别等能力的中高级开发人员。资源完整实现access_token获取（基于AgentId、AppKey、AppSecret）、通过手机号查询userid（依赖通讯录权限开通）等核心流程，代码结构清晰，具备即插即用特性。压缩包共11个文件，含3个关键C#源码文件（含Program.cs主入口与业务逻辑）、2个DLL依赖（TopSdk.dll与Newtonsoft.Json.dll）、2个缓存文件、1个XML配置说明及1个sln/csproj工程文件，整体907KB，轻量易部署。已有1749人学习下载，读者可直接复用项目结构、理解钉钉OAuth2授权链路、掌握SDK集成要点，并参考obj/bin/.vs等标准VS构建目录组织方式，快速适配自有业务系统。
1. C#钉钉消息推送（源码）：不是调个API就完事，而是把Webhook签名、加解密、重试熔断全跑通的生产级落地包
你是不是也试过：照着钉钉开放文档写了个HttpClient.PostAsync()，发条文本消息成功了，就以为“搞定了”？结果一上测试环境，遇到企业自建SSO登录态校验失败、敏感词被拦截不报错、网络抖动时消息重复发送、或者更玄学的——消息发出去了，但钉钉机器人后台日志里压根没记录请求？这根本不是“能用”，是“侥幸能用”。这份C#钉钉消息推送源码，是我从某高校实验室一个跨平台告警系统里完整剥离出来的实战包，它不只封装了基础HTTP调用，而是把钉钉消息链路中真正卡住人的三座大山全拆解了：Webhook签名生成与时间戳防重放、AES加解密（适配自定义机器人安全设置）、以及带指数退避+本地去重ID的可靠投递机制。它面向的是需要嵌入到Windows服务、ASP.NET Core后台任务、或WinForms运维工具里的开发者——不是写Demo的，是真要扛住每小时万级告警、且不能丢一条的。如果你正被“消息发不出去”“发出去收不到”“收到但内容乱码”反复折磨，这份源码就是你该立刻拉下来跑通的第一份可信基线。
2. 钉钉消息推送的核心难点：为什么官方SDK不够用，而手写HTTP又容易翻车？
钉钉开放平台对消息推送的安全要求远高于普通Webhook，尤其在启用“加签”或“加密”模式后，官方提供的.NET SDK（如DingTalk.Api）存在明显断层：它只覆盖了基础免签场景，对加签验证逻辑封装不透明，对AES加密/解密流程缺乏可调试入口，更没有内置消息幂等性保障。而纯手写HTTP请求，又极易在几个关键点踩坑：时间戳精度偏差导致签名失效、AES CBC模式IV处理错误引发解密失败、HTTP状态码未分级处理造成静默丢弃。这份源码的设计哲学很直接——把钉钉文档里藏在“注意事项”小字里的规则，变成可单步调试的C#代码。它不追求大而全的API覆盖，而是死磕最常被调用的三类消息：文本（Text）、Markdown（Markdown）、ActionCard（动作卡片），并确保每一种在加签+加密双启用模式下100%通过钉钉服务端校验。下面我们就从最底层的签名生成开始，一层层拆解它是怎么把黑匣子变成白盒的。
2.1 Webhook加签机制：时间戳、密钥、签名三要素缺一不可
钉钉加签模式要求每次请求必须携带timestamp和sign两个Query参数，其中sign是通过对timestamp + "\n" + 密钥进行HMAC-SHA256哈希后Base64编码得到。注意，这里的“密钥”是钉钉机器人后台配置的加签密钥（一串32位字符串），不是AppKey或AppSecret。很多开发者第一次失败，就是因为把AppSecret当成了加签密钥。源码中DingTalkSignatureGenerator类封装了这一逻辑：
public static string GenerateSign(string timestamp, string secret) { var data = $"{timestamp}\n{secret}"; using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)); var hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(data)); return Convert.ToBase64String(hashBytes); }关键参数说明：
timestamp必须是毫秒级时间戳（DateTimeOffset.Now.ToUnixTimeMilliseconds().ToString()），误差超过1小时即失效；secret必须严格匹配钉钉后台机器人设置页的“加签密钥”，复制时注意前后空格；data字符串拼接必须是timestamp + "\n" + secret，换行符\n是硬性要求，少一个字符签名就无效。
这个方法看似简单，但实际部署时，服务器时钟不同步是高频问题。我一般会在初始化时强制校准一次NTP时间，或在日志里打上DateTimeOffset.UtcNow和DateTimeOffset.Now的差值，避免因本地时钟漂移导致签名批量失效。
2.2 AES加密消息体：CBC模式+PKCS7填充+固定IV的硬核组合
当钉钉机器人开启“加密”选项后，所有发送的消息体（msg字段）必须先AES加密，再Base64编码，最后作为encrypt字段提交。源码采用AES-128-CBC模式，密钥为钉钉后台提供的32位AES密钥（注意：此密钥与加签密钥完全不同），IV固定为16字节全0（new byte[16]）。AesMessageEncryptor类实现如下：
public static string EncryptMessage(string plainText, string aesKey) { using var aes = Aes.Create(); aes.Key = Encoding.UTF8.GetBytes(aesKey); aes.IV = new byte[16]; // 钉钉要求IV固定为16字节0 aes.Mode = CipherMode.CBC; aes.Padding = PaddingMode.PKCS7; using var encryptor = aes.CreateEncryptor(); var plainBytes = Encoding.UTF8.GetBytes(plainText); var encryptedBytes = encryptor.TransformFinalBlock(plainBytes, 0, plainBytes.Length); return Convert.ToBase64String(encryptedBytes); }关键参数说明：
aesKey是钉钉后台“加密密钥”字段的32位字符串，需用Encoding.UTF8.GetBytes()转为字节数组；IV必须是16字节全0数组，不能用随机IV，否则钉钉服务端无法解密；PaddingMode.PKCS7是钉钉强制要求的填充方式，用PKCS5或None会导致解密失败；- 加密前
plainText必须是标准JSON字符串（如{"msgtype":"text","text":{"content":"test"}}），不能含BOM头。
这里有个血泪经验：某次上线后发现所有加密消息都显示“解密失败”，排查三天才发现是开发机UTF-8编码带BOM头，导致JSON字符串开头多了3个不可见字节，AES加密后整个密文错位。从此我养成了习惯——所有消息体JSON序列化前，强制用new UTF8Encoding(encoderShouldEmitUTF8Identifier: false)。
2.3 消息结构组装：Text/Markdown/ActionCard三类消息的字段差异与必填项
钉钉消息体JSON结构差异极大，稍填错字段名或层级就会返回400 Bad Request且无具体错误提示。源码通过强类型Model（DingTalkTextMessage、DingTalkMarkdownMessage、DingTalkActionCardMessage）约束字段，并在序列化前做合法性校验。以最常用的ActionCard为例，其核心字段包括：
| 字段名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
msgtype | string | 是 | 固定为"actionCard" |
actionCard.title | string | 是 | 卡片标题，支持最多100字符 |
actionCard.text | string | 是 | 卡片正文，必须是Markdown格式，且首行不能为空行 |
actionCard.btnOrientation | string | 否 | "0"（横向）或"1"（纵向），默认"0" |
actionCard.hideAvatar | string | 否 | "0"（显示头像）或"1"（隐藏），默认"0" |
actionCard.btns | array | 是 | 按钮列表，每个按钮含title和actionURL |
var actionCard = new DingTalkActionCardMessage { MsgType = "actionCard", ActionCard = new ActionCard { Title = "【告警】数据库连接池耗尽", Text = "### 连接池使用率：98%\n> 当前活跃连接：198/200\n> 最近1分钟慢查询：12次\n\n[查看详情](https://monitor.example.com/db)", BtnOrientation = "0", HideAvatar = "0", Btns = new List<ActionCardButton> { new ActionCardButton { Title = "立即扩容", ActionURL = "https://ops.example.com/resize?pool=db" }, new ActionCardButton { Title = "查看日志", ActionURL = "https://log.example.com/search?q=db_pool" } } } }; string jsonPayload = JsonSerializer.Serialize(actionCard, new JsonSerializerOptions { WriteIndented = false });注意：
ActionCard.Text字段中的Markdown语法有严格限制——不支持表格、不支持HTML标签、链接必须用[text](url)格式，且url必须是HTTPS协议。曾有同事在text里写了<a href="http://...">，结果整条消息被钉钉静默过滤。
3. 可靠投递机制：为什么加了重试还不够？本地消息ID去重才是关键
单纯HTTP重试解决不了钉钉消息的“超时即未知”问题：当网络超时、DNS解析失败或钉钉服务端响应延迟时，客户端无法判断消息是“已接收未处理”还是“根本没收到”。如果盲目重试，可能造成消息重复。这份源码的可靠投递模块（ReliableDingTalkSender）采用“客户端幂等ID + 服务端状态轮询”双保险策略。它在每次发送前生成唯一messageId（基于Guid.NewGuid().ToString("N")），并将其作为msgId字段写入消息体，同时将messageId与发送时间戳存入本地内存缓存（ConcurrentDictionary<string, DateTime>）。若发送失败或超时，模块不会立即重试，而是先检查该messageId是否已在缓存中存在且距今不足5分钟——若是，则跳过重试，避免短时内重复提交。
3.1 指数退避重试策略：从100ms到1.6秒的渐进式等待
重试不是简单for(int i=0; i<3; i++)，而是采用标准指数退避（Exponential Backoff）算法，避免雪崩式重试冲击钉钉服务端。RetryPolicy类定义如下：
public class RetryPolicy { private readonly int _maxRetries = 3; private readonly TimeSpan _baseDelay = TimeSpan.FromMilliseconds(100); public async Task<T> ExecuteAsync<T>(Func<Task<T>> operation, CancellationToken cancellationToken = default) { for (int attempt = 0; attempt <= _maxRetries; attempt++) { try { return await operation().ConfigureAwait(false); } catch (HttpRequestException ex) when (attempt < _maxRetries && IsTransientError(ex)) { var delay = _baseDelay * (long)Math.Pow(2, attempt); // 100ms, 200ms, 400ms, 800ms await Task.Delay(delay, cancellationToken).ConfigureAwait(false); continue; } } throw new InvalidOperationException("Max retry attempts exceeded"); } private bool IsTransientError(HttpRequestException ex) => ex.StatusCode == HttpStatusCode.RequestTimeout || ex.StatusCode == HttpStatusCode.ServiceUnavailable || ex.StatusCode == HttpStatusCode.GatewayTimeout; }参数说明：
_maxRetries = 3：最多重试3次（含首次），总尝试次数为4次；_baseDelay = 100ms：首次重试等待100毫秒，后续按2^n倍增（第2次200ms，第3次400ms，第4次800ms）；IsTransientError仅对408、503、504等瞬时错误重试，对400、401、403等客户端错误直接抛出，避免掩盖配置错误。
3.2 本地消息ID缓存：ConcurrentDictionary实现毫秒级去重
messageId去重不是靠数据库，而是用ConcurrentDictionary<string, DateTime>实现无锁内存缓存。ReliableDingTalkSender在发送前执行：
private readonly ConcurrentDictionary<string, DateTime> _sentMessageIds = new(); public async Task<bool> SendAsync(DingTalkMessageBase message, string webhookUrl, string secret = null, string aesKey = null) { var messageId = Guid.NewGuid().ToString("N"); var now = DateTime.UtcNow; // 先检查是否已在5分钟内发送过同ID消息 if (_sentMessageIds.TryGetValue(messageId, out var sentTime) && (now - sentTime) < TimeSpan.FromMinutes(5)) { Log.Warning($"Message with ID {messageId} skipped due to recent send within 5 minutes"); return false; // 跳过重试 } // 写入缓存，标记为已发送 _sentMessageIds.AddOrUpdate(messageId, now, (id, oldTime) => now); // 构建带msgId的消息体 message.MsgId = messageId; var payload = BuildPayload(message, secret, aesKey); // 执行带重试的HTTP发送 var response = await _retryPolicy.ExecuteAsync(() => PostToWebhook(payload, webhookUrl)); // 发送成功后，清理过期ID（此处简化，实际用定时器清理） CleanupExpiredIds(now); return response.IsSuccessStatusCode; }关键设计点：
AddOrUpdate保证多线程并发写入安全，无需额外锁；- 缓存有效期设为5分钟，覆盖钉钉Webhook的典型超时窗口（通常30~60秒）；
CleanupExpiredIds方法应由后台定时器（如PeriodicTimer）每分钟执行一次，遍历并移除sentTime < now - 5min的条目，防止内存泄漏。
3.3 避坑：加签、加密、重试三大模块的常见问题与排查
现象 → 原因 → 解决，这是我在三个不同项目里踩过的坑，按发生频率排序：
现象：加签模式下，
401 Unauthorized错误，但timestamp和secret确认无误。
原因：服务器系统时钟与NTP时间偏差超过1小时，导致钉钉服务端拒绝签名。
解决：在服务启动时执行w32tm /resync（Windows）或sudo ntpdate -s time.windows.com（Linux），并在日志中记录DateTimeOffset.UtcNow与DateTimeOffset.Now的差值，差值>30秒即告警。现象：启用AES加密后，钉钉返回
{"errcode":310000,"errmsg":"decrypt fail"}。
原因：IV未设为16字节全0，或aesKey长度不是16/24/32字节（钉钉要求32字节，即32个ASCII字符）。
解决：打印aes.Key.Length和aes.IV.Length到日志，确保二者均为16；用Encoding.UTF8.GetByteCount(aesKey)验证密钥字节数。现象：ActionCard消息发送成功（HTTP 200），但钉钉群内无任何显示，后台机器人日志也无记录。
原因：actionCard.text字段中Markdown语法错误，如首行为空、含非法HTML、链接非HTTPS。
解决：将text内容粘贴到 钉钉Markdown预览工具 中验证；或临时改用纯文本消息测试通道是否通畅。现象：重试后消息重复发送，群内出现两条一模一样的告警。
原因：messageId生成逻辑被放在重试循环内，每次重试都生成新ID。
解决：messageId必须在SendAsync方法入口处一次性生成，并作为参数传入重试委托，确保四次尝试用同一个ID。现象：
ConcurrentDictionary内存持续增长，服务运行一周后OOM。
原因：未实现CleanupExpiredIds的定时清理，过期ID永久驻留内存。
解决：添加PeriodicTimer，每60秒触发一次清理，代码示例：_cleanupTimer = new PeriodicTimer(TimeSpan.FromMinutes(1)); while (await _cleanupTimer.WaitForNextTickAsync()) CleanupExpiredIds(DateTime.UtcNow);。
4. 源码结构与依赖说明：如何在你的项目中零改造接入
这份源码不是黑盒DLL，而是一个可直接编译、调试、修改的完整C#类库项目（.csproj格式），目标框架为.NET 6.0（兼容.NET Core 3.1+及.NET 5+）。它刻意规避了任何第三方HTTP客户端抽象（如Refit、RestSharp），全部基于System.Net.Http原生API实现，确保最小依赖和最高可控性。整个项目结构极简，只有5个核心文件，全部位于DingTalk.Core命名空间下：
| 文件名 | 功能 | 关键类/方法 |
|---|---|---|
DingTalkSignatureGenerator.cs | Webhook加签逻辑 | GenerateSign(string timestamp, string secret) |
AesMessageEncryptor.cs | AES加密/解密逻辑 | EncryptMessage(string plainText, string aesKey) |
DingTalkMessageModels.cs | 强类型消息Model | DingTalkTextMessage,DingTalkMarkdownMessage,DingTalkActionCardMessage |
ReliableDingTalkSender.cs | 可靠投递主类 | SendAsync(DingTalkMessageBase message, ...) |
RetryPolicy.cs | 重试策略封装 | ExecuteAsync<T>(Func<Task<T>> operation) |
依赖说明：
- 仅依赖
System.Text.Json（.NET 6+内置，无需NuGet）；- 若需在
.NET Core 3.1中使用，需手动安装System.Text.JsonNuGet包（版本4.7.2+）；- 无其他第三方NuGet依赖，杜绝了因依赖冲突导致的
AssemblyLoadException。
接入步骤极其简单，三步完成：
4.1 步骤一：添加源码文件到你的项目
将上述5个.cs文件直接拖入你的ASP.NET Core Web API、Windows Service或Console App项目中。无需修改命名空间，源码已声明namespace DingTalk.Core;。若你的项目命名空间不同，只需在调用处using DingTalk.Core;即可。
4.2 步骤二：初始化并发送第一条消息
以ASP.NET Core为例，在Program.cs中注册服务：
// 注册为Singleton，全局复用HttpClient实例 builder.Services.AddSingleton<ReliableDingTalkSender>();在Controller中注入并使用：
[ApiController] [Route("api/[controller]")] public class NotifyController : ControllerBase { private readonly ReliableDingTalkSender _sender; public NotifyController(ReliableDingTalkSender sender) => _sender = sender; [HttpPost("alert")] public async Task<IActionResult> SendAlert([FromBody] AlertRequest request) { var message = new DingTalkTextMessage { MsgType = "text", Text = new TextContent { Content = $"【告警】{request.ServiceName}：{request.Message}" } }; // webhookUrl从配置读取，secret和aesKey按需传入（若未启用加签/加密则传null） var success = await _sender.SendAsync( message, Configuration["DingTalk:WebhookUrl"], Configuration["DingTalk:Secret"], Configuration["DingTalk:AesKey"]); return success ? Ok("Sent") : StatusCode(500, "Send failed"); } }4.3 步骤三：配置钉钉机器人并获取必要参数
登录钉钉管理后台 → 工作台 → 机器人管理 → 创建自定义机器人 → 选择“加签”和/或“加密” → 复制以下三个参数到你的appsettings.json：
{ "DingTalk": { "WebhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=xxx", "Secret": "SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 加签密钥 "AesKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // AES加密密钥，32位 } }重要提醒：
WebhookUrl中的access_token是公开的，但Secret和AesKey是高危密钥，严禁硬编码在源码或提交到Git。务必通过环境变量、Azure Key Vault或.NET Secret Manager管理。
5. 生产环境验证技巧：如何用三行命令确认你的推送链路100%健康？
在测试环境跑通不等于生产环境可用。我给自己定了一条铁律：每次发布新版本前，必须用真实钉钉群做端到端健康检查，且检查项必须覆盖加签、加密、重试三个维度。下面这套验证方法，是我从某公司SRE团队抄来的，实测有效，5分钟内可完成。
5.1 验证加签有效性：curl命令直击签名核心
不用启动你的应用，直接用curl模拟加签请求，验证timestamp和sign计算是否正确。假设你的webhookUrl为https://oapi.dingtalk.com/robot/send?access_token=abc，secret为SEC123：
# 1. 获取当前毫秒时间戳 TIMESTAMP=$(date +%s%3N) # 2. 生成sign（注意：secret必须原样传入，不能urlencode） SIGN=$(echo -n "$TIMESTAMP\nSEC123" | openssl dgst -sha256 -hmac "SEC123" | awk '{print $2}' | base64) # 3. 发送测试请求（发送纯文本） curl -X POST "$WEBHOOK_URL×tamp=$TIMESTAMP&sign=$SIGN" \ -H 'Content-Type: application/json' \ -d '{"msgtype": "text", "text": {"content": "【健康检查】加签验证成功"}}'验证点：
- 若返回
{"errcode":0,"errmsg":"ok"}，说明加签逻辑100%正确；- 若返回
401，重点检查TIMESTAMP是否为毫秒级（%s%3N）、SIGN生成时是否用了-n参数避免换行、secret是否复制完整（含SEC前缀）。
5.2 验证AES加密正确性：在线工具交叉比对
加签验证通过后，下一步验证AES加密。取一段标准JSON（如{"msgtype":"text","text":{"content":"test"}}），用源码中的AesMessageEncryptor.EncryptMessage()加密，得到Base64密文。然后，用钉钉官方提供的 AES加密测试工具 输入同一段JSON和你的32位AesKey，对比输出的密文是否完全一致。注意：在线工具的IV默认为16字节0，必须勾选“IV为0”选项。
5.3 验证可靠投递：制造网络故障，观察重试与去重行为
这是最关键的一步。我用iptables（Linux）或Windows Firewall（Windows）临时阻断钉钉域名，制造网络故障：
# Linux下临时屏蔽钉钉域名（执行后所有钉钉请求超时） sudo iptables -A OUTPUT -d oapi.dingtalk.com -j DROP # 然后在你的应用中连续调用SendAsync 5次 # 观察日志：应看到3次重试日志（100ms, 200ms, 400ms），第4次仍失败后抛出异常 # 同时检查_consentMessageIds_缓存：5个messageId应全部写入，且无重复 # 恢复网络 sudo iptables -D OUTPUT -d oapi.dingtalk.com -j DROP预期日志特征：
- 第一次发送：
INFO Sending message with ID: a1b2c3...- 超时后：
WARN Attempt 1 failed, retrying in 100ms...- 第二次：
INFO Sending message with ID: a1b2c3...（ID相同！）- 成功后：
INFO Message a1b2c3... sent successfully- 缓存中：
_sentMessageIds.Count == 1（证明去重生效）
从那以后我每次上线新告警功能，都强制走一遍这三步验证——哪怕只是改了一个标点符号。因为钉钉消息不是“发出去就行”，而是“发出去、被钉钉接收、被用户看到、且只看到一次”。这份源码的价值，不在于它有多炫技，而在于它把每一个可能让消息消失的缝隙，都用可验证的代码堵死了。希望帮到你。
本文还有配套的精品资源，点击获取
