简介这份资源面向使用C#进行企业级应用开发的程序员聚焦微信企业号主动推送消息这一常见需求帮助开发者快速掌握通过API向员工或客户发送文本、图片、语音、视频及图文消息的完整实现思路。压缩包共40个文件约35KB以22个cs源码文件为核心辅以3个csproj工程文件、1个sln解决方案、2个resx资源文件及config配置等整体结构清晰便于直接导入Visual Studio研究。内容涵盖获取AppID与AppSecret、封装配置类、调用官方SDK构建各类消息对象、上传媒体获取MediaId、监听关注与菜单点击等事件以及处理SendMessage返回结果等关键环节代码示例与文档可帮助读者理解消息推送的完整链路。目前已有873人学习下载适合需要快速落地微信企业号消息推送功能的中级C#开发者参考借鉴。1. C# WChat 开发微信企业号主动推送从零跑通第一条消息企业微信刚出来那会儿很多团队还在用邮件和短信做告警延迟高、费用贵、还容易被忽略。后来大家发现把告警、审批、日报这些消息直接推到企业微信里打开率能到九成以上。这个标题里的 WChat就是一套用 C# 封装企业微信服务端接口的类库核心场景是让后端程序主动把消息推给指定的人或群而不是等用户来点。它适合做运维告警、生产日报、审批提醒、设备状态推送这类后台服务尤其适合已经用 C# 写上位机或管理系统的团队不用再单独搭一套消息中间件。接下来我按实际落地的顺序把注册应用、拿凭证、发消息、排错这几步拆开讲代码可以直接抄。2. 企业微信主动推送的接口模型与 WChat 封装思路2.1 主动推送和被动回复的本质区别企业微信的消息通道分两种一种是用户发消息给应用应用在 5 秒内回复这叫被动回复另一种是应用自己决定什么时候发、发给谁这叫主动推送。标题里的“主动推送消息”指的就是后者。被动回复依赖回调 URL 和加解密链路长、调试烦主动推送只需要一个 access_token 和一条 HTTPS 请求对后端服务更友好。主动推送的接口地址是固定的消息类型不同请求体结构不同但入口都是同一个https://qyapi.weixin.qq.com/cgi-bin/message/send?access_tokenxxx。WChat 这类封装库做的事就是把拼 JSON、发 HTTP、解析错误码这三步包起来让调用方只关心“发给谁、发什么”。这里有个容易混淆的点企业微信的“应用消息”和“群机器人消息”是两套接口。应用消息能发给企业成员支持文本、图片、图文、文件、模板卡片等群机器人只能发到群里支持文本、Markdown、图片、图文。标题里的“企业号”是老叫法现在统一叫企业微信但接口路径没变。选型时先确认你要发给个人还是群再决定用哪套。2.2 WChat 的封装层次与依赖选择WChat 不是官方库是社区里对企业微信 API 的 C# 封装。它的典型结构分三层底层是 HTTP 客户端负责发请求和收响应中间层是凭证管理负责拿 access_token 并缓存上层是消息构造器按消息类型拼 JSON。你自己写也不难但用封装库能省掉重复处理错误码和序列化的工作。依赖选择上我一般用HttpClient而不是WebClient因为HttpClient支持异步、连接池复用、超时控制更细。JSON 序列化用System.Text.Json或Newtonsoft.Json都行前者性能好后者兼容性强。如果项目里已经有 Newtonsoft就别再引第二个库。WChat 内部通常用 Newtonsoft因为企业微信返回的字段里有不少动态结构用JObject处理更灵活。access_token 的缓存是重点。企业微信规定 token 有效期 7200 秒但频繁获取会触发频率限制。常见做法是在内存里缓存过期前 5 分钟刷新。如果是多实例部署得用 Redis 或数据库做分布式缓存否则每个实例各拿各的容易把配额打满。2.3 最小可跑通的推送代码下面这段代码演示用 WChat 风格发一条文本消息给指定成员。先装包再写调用。包名以实际项目为准这里用常见的命名空间示意。using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; using Newtonsoft.Json; public class WeComPusher { private static readonly HttpClient _http new HttpClient(); private const string CorpId 你的企业ID; private const string CorpSecret 你的应用Secret; private const int AgentId 1000002; // 应用AgentId // 获取 access_token实际项目应加缓存 public static async Taskstring GetTokenAsync() { var url $https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid{CorpId}corpsecret{CorpSecret}; var resp await _http.GetStringAsync(url); dynamic obj JsonConvert.DeserializeObject(resp); if (obj.errcode ! 0) throw new Exception($获取token失败: {obj.errmsg}); return obj.access_token; } // 发送文本消息 public static async Task SendTextAsync(string toUser, string content) { var token await GetTokenAsync(); var url $https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token}; var body new { touser toUser, // 成员账号多个用|分隔 msgtype text, agentid AgentId, text new { content content }, safe 0 // 0表示可对外分享 }; var json JsonConvert.SerializeObject(body); var httpContent new StringContent(json, Encoding.UTF8, application/json); var resp await _http.PostAsync(url, httpContent); var result await resp.Content.ReadAsStringAsync(); dynamic obj JsonConvert.DeserializeObject(result); if (obj.errcode ! 0) throw new Exception($发送失败: {obj.errcode} - {obj.errmsg}); } }逻辑说明GetTokenAsync每次调用都重新拿 token只适合演示。生产环境要加静态变量缓存记录过期时间。SendTextAsync里touser是成员账号不是姓名多个账号用竖线分隔。agentid必须和 Secret 对应的应用一致填错会返回 60011 或 60020。safe字段控制消息是否可对外分享内部告警一般填 0。参数说明CorpId在企业微信管理后台“我的企业”里看CorpSecret在应用详情页里生成只显示一次丢了要重置AgentId也在应用详情页是数字。这三个值建议放配置文件或环境变量不要硬编码。3. 消息类型、接收者与频率控制的落地细节3.1 文本、Markdown、图文卡片的构造差异文本消息最简单但表达力有限。Markdown 消息支持标题、加粗、链接、代码块适合发日报和告警详情。图文卡片适合带跳转链接的通知比如审批待办。三种消息的 JSON 结构不同但都在同一个 send 接口里。Markdown 消息的msgtype是markdown内容放在markdown.content里。注意企业微信的 Markdown 不支持表格和图片只支持部分语法。图文消息的msgtype是newsarticles数组里每项有title、description、url、picurl。picurl必须是公网可访问的图片地址本地路径不行。// Markdown 消息示例 var mdBody new { touser zhangsan|lisi, msgtype markdown, agentid AgentId, markdown new { content **告警**服务器CPU超过90%\n 时间2024-01-01 10:00 } }; // 图文消息示例 var newsBody new { touser all, msgtype news, agentid AgentId, news new { articles new[] { new { title 生产日报, description 点击查看详情, url https://your-domain.com/report, picurl https://your-domain.com/cover.png } } } };参数上touser填all表示发给应用可见范围内的所有人慎用容易打扰。articles最多 8 条超出会报错。picurl建议用 640x320 的图太大加载慢。3.2 接收者标识UserID、部门、标签怎么选企业微信的接收者有三种成员账号UserID、部门 ID、标签 ID。touser填成员toparty填部门totag填标签。三者可以同时用但总人数不能超过应用可见范围。UserID 是管理员在通讯录里设置的不是手机号也不是邮箱。如果不知道 UserID可以在管理后台导出通讯录或者调user/list接口查。部门 ID 在通讯录里看根部门是 1。标签适合按项目组或值班组发消息比如“运维值班”标签。一个常见坑touser里填了中文姓名接口不报错但发不出去。必须用 UserID。另一个坑应用可见范围没包含目标成员接口返回 60011提示“无权限”。解决方法是去应用详情页把可见范围调大或者把成员加进范围。3.3 频率限制与重试策略企业微信对主动推送有频率限制每个应用每分钟最多发 600 次每天最多发 30000 次。超过会返回 45009提示“接口调用超过限制”。这个限制是按应用算的不是按成员。应对策略有三条第一合并消息把多条告警合成一条 Markdown 发第二加队列用Channel或BlockingCollection做缓冲控制发送速率第三失败重试但只对 45009 以外的错误重试45009 要等下一分钟。// 简单限流每秒最多发 5 条 private static readonly SemaphoreSlim _semaphore new SemaphoreSlim(5, 5); public static async Task SendWithLimitAsync(string toUser, string content) { await _semaphore.WaitAsync(); try { await SendTextAsync(toUser, content); } finally { // 延迟释放控制速率 _ Task.Delay(200).ContinueWith(_ _semaphore.Release()); } }这段代码用信号量控制并发实际项目可以用Polly做更精细的重试和熔断。注意Task.Delay里释放信号量的写法有点绕更清晰的做法是用RateLimiter或自己维护时间窗口。4. 主动推送的避坑与排查清单4.1 坑一access_token 频繁获取导致 45009现象程序跑一段时间后开始报 45009重启后又正常。原因每次发消息都调gettokentoken 接口本身也有频率限制而且多实例部署时每个实例都在拿。解决加内存缓存记录expires_in提前 300 秒刷新多实例用 Redis 存 token加分布式锁。4.2 坑二消息发出但成员收不到现象接口返回errcode: 0但目标成员说没收到。原因应用可见范围没包含该成员或者成员关闭了应用通知。解决检查应用详情页的可见范围让成员在“企业微信-我-设置-新消息通知”里确认没关。另外touser填错 UserID 时接口也可能返回 0但消息进了黑洞所以要先用user/get确认 UserID 存在。4.3 坑三Markdown 消息里的换行不生效现象发出去的 Markdown 挤成一行。原因JSON 序列化时\n被转义成\\n企业微信收到的是字面量。解决用JsonConvert.SerializeObject时默认会正确处理\n但如果手动拼字符串就会出问题。建议用匿名对象序列化不要手写 JSON 字符串。4.4 坑四图文消息的 picurl 不显示现象图文卡片能收到但封面图是空白。原因picurl用了内网地址或需要登录的地址。解决把图片放到公网可访问的静态服务器或者用企业微信的素材上传接口先传图拿media_id再用media_id构造图文。注意media_id有效期 3 天。4.5 坑五多线程并发发送时 token 被覆盖现象并发发送时偶尔报 40001提示 token 无效。原因多个线程同时刷新 token旧 token 被新 token 覆盖但请求还在用旧的。解决用LazyT或SemaphoreSlim保证同一时间只有一个线程刷新 token其他线程等刷新完再用新 token。5. 把推送做成可复用的后台服务封装、验证与监控5.1 封装成独立服务类把 token 管理、消息构造、发送、重试、日志这几块拆开做成一个WeComService类注册为单例。token 用MemoryCache存过期前刷新。发送方法统一返回SendResult包含errcode、errmsg、msgid。这样业务代码只调await _weCom.SendTextAsync(zhangsan, 内容)不用关心底层。public class WeComService { private readonly IMemoryCache _cache; private readonly HttpClient _http; private readonly WeComOptions _options; public WeComService(IMemoryCache cache, HttpClient http, WeComOptions options) { _cache cache; _http http; _options options; } private async Taskstring GetTokenAsync() { if (_cache.TryGetValue(wecom_token, out string token)) return token; var url $https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid{_options.CorpId}corpsecret{_options.Secret}; var resp await _http.GetStringAsync(url); var obj JsonConvert.DeserializeObjectdynamic(resp); if (obj.errcode ! 0) throw new Exception($token失败: {obj.errmsg}); token (string)obj.access_token; _cache.Set(wecom_token, token, TimeSpan.FromSeconds(7000)); return token; } public async TaskSendResult SendTextAsync(string toUser, string content) { var token await GetTokenAsync(); var url $https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token{token}; var body new { touser toUser, msgtype text, agentid _options.AgentId, text new { content } }; var json JsonConvert.SerializeObject(body); var resp await _http.PostAsync(url, new StringContent(json, Encoding.UTF8, application/json)); var result await resp.Content.ReadAsStringAsync(); return JsonConvert.DeserializeObjectSendResult(result); } }参数说明WeComOptions里放CorpId、Secret、AgentId从配置绑定。MemoryCache的过期时间设 7000 秒比 7200 少 200 秒留出刷新余量。SendResult类里至少包含errcode、errmsg、msgid。5.2 验证推送是否成功接口返回errcode: 0只代表企业微信接收了请求不代表成员一定看到。要确认送达可以调message/get接口查消息状态但那个接口需要msgid而且有延迟。更实用的做法是在消息里加一个“确认”链接成员点了之后回调你的服务这样能确认人真的看到了。另一个验证方法是看日志。每次发送记录msgid、touser、msgtype、errcode、耗时。如果errcode非 0把errmsg也记下来。日志用NLog或Serilog都行按天切分保留 30 天。5.3 监控与告警推送服务本身也要被监控。关键指标有三个发送成功率、平均耗时、token 刷新失败次数。成功率低于 95% 要告警耗时超过 2 秒要查网络token 刷新失败要检查 CorpId 和 Secret 是否被改。监控方式可以用 Prometheus 的Counter和Histogram也可以用简单的内存计数加定时上报。如果推送量不大直接在日志里打点用grep统计也行。5.4 一个我踩过的坑早期做告警推送时我把touser填成了成员的手机号接口返回 0但消息一直没到。查了半天才发现企业微信的touser只认 UserID手机号要先用user/get_userid_by_mobile换。后来我养成习惯任何接收者标识先用查询接口确认一遍再发消息。这个习惯帮我省了很多“消息发出去了但没人收到”的排查时间。希望帮到你。本文还有配套的精品资源点击获取
