简介：本资源是一份面向C#开发者的企业微信消息推送功能实现方案，聚焦于微信企业号主动发送文本、图片、语音、视频及图文消息的核心场景，适用于需构建内部通知系统或客户触达服务的中高级.NET开发人员。压缩包共40个文件，含22个核心C#源码文件（如QYWeixinHelper.cs、WeChatMsgSend.cs、MsgType.cs等）、3个工程配置文件（.csproj）、1个解决方案文件（.sln）及配套配置（App.config）、资源文件（.resx）和编译输出目录结构，整体仅35KB，轻量易集成。已有875人学习下载，代码组织清晰，按Common、Model、IMC三层划分，封装了企业号认证、媒体上传、消息构建与发送全流程逻辑，并内置WeChatData、WeChatUrlData等数据模型与URL常量管理，便于快速理解接口调用规范与SDK集成方式。

1. 企业微信消息推送不是“发个HTTP请求”就完事：这个C#项目把认证、加密、重试、日志全打成一个可直接引用的类库

某公司内部系统要对接微信企业号做告警通知，开发同学第一反应是翻微信官方文档——结果卡在「获取access_token」环节整整两天：token有效期2小时、必须全局缓存、并发刷新时容易雪崩、过期后请求直接40001……最后发现，光是「正确拿到token」这一步，就涉及HTTP客户端复用、内存缓存策略、线程安全锁、失败降级逻辑四层嵌套。这个C# WChat项目就是为解决这类血泪问题而生：它不提供UI界面，不封装成exe安装包，而是以标准.NET Standard 2.0类库形式交付，核心功能就三件事——自动管理access_token生命周期、按微信规范组装并签名JSON消息体、内置指数退避重试+错误码分类处理。适合正在做OA/ERP/运维平台集成的企业级开发者，尤其当你已经写过3次以上重复的GetAccessToken()却还在修缓存bug时，它能让你省下至少16小时调试时间。

2. 项目结构与技术栈：从.csproj到WeChatConfig，看清它为什么能跑在.NET Core和.NET Framework双环境

2.1 目录结构：5个核心文件撑起整个消息推送能力

项目解压后共12个文件，但真正参与运行逻辑的只有以下5个（其余为NuGet配置、示例程序、README）：

WChat.Core/ ├── WChat.Core.csproj # .NET Standard 2.0 类库工程，TargetFramework netstandard2.0 ├── Config/ │ └── WeChatConfig.cs # 全局配置类，含CorpId/Secret/AgentId/AesKey/Token等字段 ├── Models/ │ ├── MessageRequest.cs # 消息请求基类（文本/图片/卡片等继承它） │ └── ResponseResult.cs # 统一响应结构，含errcode/errmsg/invaliduser等字段 ├── Services/ │ ├── IWeChatService.cs # 主服务接口，定义SendText/SendNews等方法 │ └── WeChatService.cs # 默认实现，含token缓存、HTTP调用、加解密逻辑 └── Utils/ ├── CryptoHelper.cs # AES-256-CBC加解密（企业号消息体加密必需） └── HttpHelper.cs # 封装HttpClient，支持超时/重试/日志输出

提示：WeChatService.cs是唯一需要你重点关注的实现类，它把微信企业号API的「认证-构造-加密-发送-解析」整条链路串起来了，后续所有改造都围绕它展开。

2.2 技术选型：为什么坚持用.NET Standard 2.0而不是.NET 6+

项目未使用任何新语法糖（如record、top-level statements），所有代码兼容.NET Framework 4.6.1+ 和 .NET Core 2.1+。原因很实际：很多企业内部系统仍运行在Windows Server 2012 R2上，IIS托管的ASP.NET WebForms或MVC 5项目无法升级.NET Core。作者在WChat.Core.csproj中明确锁定：

<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.0</TargetFramework> <LangVersion>7.3</LangVersion> </PropertyGroup> <ItemGroup> <PackageReference Include="Newtonsoft.Json" Version="13.0.3" /> <PackageReference Include="Microsoft.Extensions.Caching.Memory" Version="6.0.1" /> </ItemGroup> </Project>

注意Microsoft.Extensions.Caching.Memory版本虽为6.0.1，但它在netstandard2.0下完全可用——这是.NET生态里少有的“高版本包向下兼容”案例。我一般会保留这个版本，因为它的MemoryCache支持PostEvictionCallbacks，能监听token过期事件并触发预刷新，比手写Timer轮询更可靠。

2.3 配置加载机制：WeChatConfig如何从appsettings.json自动绑定

项目默认不强制依赖DI容器，但提供了开箱即用的配置绑定方案。以ASP.NET Core为例，在Program.cs中：

// 注册配置类 builder.Services.Configure<WeChatConfig>(builder.Configuration.GetSection("WeChat")); // 注入服务（带缓存依赖） builder.Services.AddMemoryCache(); builder.Services.AddSingleton<IWeChatService, WeChatService>();

对应appsettings.json需包含：

{ "WeChat": { "CorpId": "wwxxxxxxxxxxxxxxxx", "Secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "AgentId": 1000001, "Token": "mytoken123", "EncodingAESKey": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG" } }

关键点在于：WeChatConfig类本身标记了[JsonObject]，且所有属性均为public set;，Newtonsoft.Json能自动完成反序列化。如果你用的是.NET Framework + web.config，只需改用ConfigurationManager.AppSettings["WeChat:CorpId"]手动赋值——项目没绑死配置源，这点很务实。

2.4 HTTP通信层设计：HttpHelper为何不用IHttpClientFactory而自己管连接池

HttpHelper.cs中创建HttpClient的方式是：

private static readonly HttpClient _httpClient = new HttpClient(new HttpClientHandler { MaxConnectionsPerServer = 100, AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate });

而非通过DI注入IHttpClientFactory。原因有二：

1. 轻量级定位：该项目目标是作为工具类库被引用，不希望强依赖ASP.NET Core的DI体系；
2. 连接复用刚需：微信API对QPS有限制（默认2000次/分钟），若每次new HttpClient会导致TIME_WAIT堆积，最终触发SocketException。

_httpClient设为static readonly确保整个AppDomain内单例，配合MaxConnectionsPerServer=100，实测在100并发推送场景下，TCP连接数稳定在80~90之间，无端口耗尽问题。如果你的项目已用IHttpClientFactory，只需在WeChatService构造函数中接收HttpClient实例并传给HttpHelper即可，无需改底层逻辑。

3. 核心模块拆解：WeChatService.SendText()从参数校验到返回结果的完整链路

3.1 token获取与缓存：GetAccessTokenAsync()如何避免并发击穿

WeChatService.SendText()第一行就是：

var accessToken = await GetAccessTokenAsync(cancellationToken).ConfigureAwait(false);

而GetAccessTokenAsync()的实现是典型「双重检查锁+内存缓存」模式：

private readonly IMemoryCache _cache; private readonly object _lockObj = new object(); public async Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default) { var cacheKey = "wechat:access_token"; if (_cache.TryGetValue(cacheKey, out string token)) return token; // 双重检查：防止多个线程同时进入锁 lock (_lockObj) { if (_cache.TryGetValue(cacheKey, out token)) return token; // 调用微信API获取新token var url = $"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={_config.CorpId}&corpsecret={_config.Secret}"; var response = await _httpHelper.GetAsync<AccessTokenResponse>(url, cancellationToken).ConfigureAwait(false); if (response.errcode != 0) throw new InvalidOperationException($"获取access_token失败：{response.errmsg}"); // 缓存2小时，提前30秒过期触发刷新（防临界失效） var options = new MemoryCacheEntryOptions() .SetAbsoluteExpiration(TimeSpan.FromMinutes(119.5)); _cache.Set(cacheKey, response.access_token, options); return response.access_token; } }

关键参数说明：

• TimeSpan.FromMinutes(119.5)：微信token有效期为7200秒（2小时），这里设为119.5分钟，留30秒缓冲；
• ConfigureAwait(false)：避免同步上下文捕获，提升异步性能；
• AccessTokenResponse是简单POCO类，仅含errcode/errmsg/access_token/expires_in四个字段；

注意：此实现未处理token刷新时的并发问题（即多个线程同时发现缓存失效，都去调API）。生产环境建议升级为SemaphoreSlim限流，或改用Lazy<Task<T>>模式——但本项目定位是「够用就好」，所以用lock足矣。

3.2 消息体构造与签名：SendText()如何生成符合企业号规范的JSON

SendText()方法接收string userIds,string content两个参数，内部调用：

var request = new TextMessageRequest { touser = userIds, msgtype = "text", agentid = _config.AgentId, text = new { content = content }, safe = 0 // 0-明文，1-加密（企业号要求必须为0） };

重点在TextMessageRequest继承自MessageRequest，而后者重写了ToJsonString()方法：

public virtual string ToJsonString() { var json = JsonConvert.SerializeObject(this, Formatting.None, new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore, ContractResolver = new CamelCasePropertyNamesContractResolver() }); // 企业号要求：所有字段名小驼峰，且不带空格/换行 return json.Replace(" ", "").Replace("\n", "").Replace("\r", ""); }

这个ToJsonString()被SendText()直接用于HTTP Body：

var url = $"https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={accessToken}"; await _httpHelper.PostAsync(url, request.ToJsonString(), cancellationToken).ConfigureAwait(false);

提示：CamelCasePropertyNamesContractResolver确保"touser"而非"toUser"，这是微信API的硬性要求。曾有同事因Newtonsoft.Json默认首字母大写，导致返回40013 invalid userid，查了3小时才发现是序列化问题。

3.3 加密模块：CryptoHelper.AesEncrypt()如何适配企业号的CBC模式

企业号消息体加密（非必选，但推荐开启）使用AES-256-CBC，PKCS7填充，IV向量固定为16字节\0。CryptoHelper.AesEncrypt()实现如下：

public static string AesEncrypt(string plaintext, string encodingAESKey) { var key = Convert.FromBase64String(encodingAESKey + "="); // 补齐Base64长度 var iv = new byte[16]; // 全0 IV using var aes = Aes.Create(); aes.Key = key; aes.IV = iv; 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); }

参数说明：

• encodingAESKey：配置中的43位字符串，需补=凑成合法Base64（微信文档没说，但实测不补会报错）；
• IV必须为16字节全0，不能随机生成，否则微信服务器无法解密；
• 输出为Base64字符串，直接拼入XML消息体的<Encrypt>节点；

注意：此加密仅用于「被动回复消息」场景（如用户发消息给应用，应用回消息）。主动推送（本项目主功能）无需加密，但CryptoHelper保留了该能力，方便后续扩展。

3.4 错误码统一处理：ResponseResult如何将errcode映射为可抛异常

微信API返回JSON中errcode为0表示成功，非0则需按码处理。WeChatService中所有HTTP调用后都执行：

if (result.errcode != 0) { var ex = result.errcode switch { 40014 => new InvalidAccessTokenException(result.errmsg), 40001 => new InvalidSecretException(result.errmsg), 40003 => new InvalidUserIdException(result.errmsg), 40004 => new InvalidAgentIdException(result.errmsg), _ => new WeChatApiException($"微信API错误[{result.errcode}]: {result.errmsg}") }; throw ex; }

这种switch式异常映射，比泛泛的throw new Exception()有用得多——业务层可精准catch InvalidUserIdException做用户ID格式校验，或catch InvalidAccessTokenException触发token强制刷新。我一般会在全局异常过滤器中捕获这些自定义异常，记录到ELK并返回前端友好提示。

4. 运行与调试：从零启动一个控制台示例，验证消息是否真能发出去

4.1 创建测试项目：3步接入WChat.Core类库

新建一个.NET 6.0控制台项目（dotnet new console -n WChatTest），然后执行：

# 添加项目引用（假设WChat.Core已解压到../WChat.Core） dotnet add reference ../WChat.Core/WChat.Core.csproj # 安装Newtonsoft.Json（若未自动引入） dotnet add package Newtonsoft.Json --version 13.0.3

在Program.cs中编写测试代码：

using WChat.Core.Config; using WChat.Core.Services; var config = new WeChatConfig { CorpId = "wwxxxxxxxxxxxxxxxx", Secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", AgentId = 1000001, Token = "mytoken123", EncodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG" }; var service = new WeChatService(config); try { var result = await service.SendText("USERID1|USERID2", "【测试】这是一条来自WChat.Core的推送", CancellationToken.None); Console.WriteLine($"发送成功：{result.errcode}"); } catch (Exception ex) { Console.WriteLine($"发送失败：{ex.Message}"); }

提示：USERID1必须是企业微信通讯录中真实存在的成员UserID（不是手机号或邮箱），否则返回40003 invalid user。可在企业微信管理后台「通讯录」中导出CSV查看。

4.2 启动调试：如何快速定位HTTP请求失败原因

当SendText()抛出异常时，不要急着改代码，先看三处日志：

1. 控制台输出：HttpHelper默认启用Console.WriteLine打印请求URL和响应状态码；
2. Fiddler抓包：启动Fiddler，设置Tools > Options > HTTPS > Decrypt HTTPS traffic，运行程序，观察qyapi.weixin.qq.com域名下的请求；
3. 微信API返回体：在WeChatService.cs的PostAsync调用后加断点，查看responseContent变量值，典型错误如：

注意：微信API对IP有白名单限制。若你在本地开发机测试，需在企业微信管理后台「应用管理 > 应用 > IP白名单」中添加开发机公网IP（非127.0.0.1）。内网测试可临时关闭白名单（不推荐生产环境）。

4.3 模拟高并发：用Parallel.ForEach验证token缓存是否生效

为验证GetAccessTokenAsync()的缓存效果，写一段压力测试：

var tasks = Enumerable.Range(0, 100) .Select(_ => Task.Run(async () => { var token = await service.GetAccessTokenAsync(); Console.Write("."); // 每获取一次打印一个点 return token; })) .ToArray(); await Task.WhenAll(tasks); Console.WriteLine($"\n100次token获取耗时：{sw.ElapsedMilliseconds}ms");

实测结果：首次运行耗时约800ms（网络延迟+API响应），后续99次均在0.2ms内返回——证明内存缓存生效。若耗时全部在700ms左右，则说明缓存未命中，大概率是_cache未正确注入或cacheKey拼写错误。

4.4 日志增强：如何把每次推送记录到本地文件

项目未内置日志框架，但预留了HttpHelper的扩展点。在HttpHelper.cs中找到LogRequest方法：

private void LogRequest(string url, string body) { // 默认只输出到Console，可在此处扩展 Console.WriteLine($"[REQ] {DateTime.Now:HH:mm:ss} {url} {body?.Substring(0, Math.Min(50, body.Length))}..."); }

改为写入文件：

private void LogRequest(string url, string body) { var logLine = $"[{DateTime.Now:yyyy-MM-dd HH:mm:ss}] {url} {body}\n"; File.AppendAllText("./wechat_push.log", logLine); }

这样每次SendText()都会在项目根目录生成wechat_push.log，内容形如：
[2023-10-05 14:22:31] https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=xxx {"touser":"USERID1","msgtype":"text","agentid":1000001,"text":{"content":"测试"}}

提示：生产环境建议用Serilog或NLog替代File.AppendAllText，避免高并发下文件锁冲突。但此项目定位轻量，文件日志已足够排障。

5. 常见问题排查：5个真实踩坑记录，覆盖90%新手报错场景

5.1 现象：SendText()始终返回40014 invalid credential

原因：WeChatConfig.Secret字符串末尾有不可见字符（如Windows换行\r\n或编辑器自动添加的BOM头）
解决：用Notepad++打开配置文件，编码→转为UTF-8无BOM格式；或在C#中用Secret.Trim()再赋值

5.2 现象：发送成功但企业微信手机端收不到消息

原因：WeChatConfig.AgentId填的是「应用ID」而非「应用序号」。企业微信后台「应用管理」列表中，AgentId是纯数字（如1000001），不是UUID格式的ID
解决：登录企业微信管理后台→应用管理→点击目标应用→地址栏URL中agentid=1000001部分即为正确值

5.3 现象：并发调用SendText()时偶发ObjectDisposedException: Cannot access a disposed object

原因：HttpClient被多次dispose（常见于在using块中创建HttpClient实例）
解决：确认HttpHelper中_httpClient为static readonly，且所有调用方未自行new HttpClient。检查是否有其他类库也创建了同名静态HttpClient

5.4 现象：中文消息体显示为乱码（如"?????"）

原因：HttpHelper.PostAsync()未设置Content-Type: application/json; charset=utf-8
解决：在PostAsync方法中添加：

var content = new StringContent(json, Encoding.UTF8, "application/json"); content.Headers.ContentType.CharSet = "utf-8"; // 强制声明charset

5.5 现象：GetAccessTokenAsync()在.NET Framework项目中抛TypeLoadException

原因：Microsoft.Extensions.Caching.Memory6.0.1依赖System.Runtime.CompilerServices.Unsafe6.0.0，而.NET Framework 4.7.2默认不包含该程序集
解决：在项目中手动安装System.Runtime.CompilerServices.UnsafeNuGet包（版本6.0.0），或降级Microsoft.Extensions.Caching.Memory至3.1.32（兼容性更好）

6. 二次开发指南：如何扩展支持「模板消息」和「用户信息查询」两个高频需求

6.1 扩展模板消息：新增SendTemplateMessage()方法

企业微信模板消息需先在管理后台配置模板ID，再通过/cgi-bin/message/template/send接口发送。我们基于现有结构扩展：

1. 在Models/下新增TemplateMessageRequest.cs：

public class TemplateMessageRequest : MessageRequest { public string template_id { get; set; } public string touser { get; set; } public int agentid { get; set; } public Dictionary<string, TemplateDataItem> data { get; set; } public bool enable_duplicate_check { get; set; } = true; public int duplicate_check_interval { get; set; } = 600; // 10分钟 } public class TemplateDataItem { public string value { get; set; } public string color { get; set; } = "#173177"; }

2. 在IWeChatService.cs中添加方法声明：

Task<ResponseResult> SendTemplateMessage(TemplateMessageRequest request, CancellationToken cancellationToken = default);

3. 在WeChatService.cs中实现（复用现有token获取和HTTP调用）：

public async Task<ResponseResult> SendTemplateMessage(TemplateMessageRequest request, CancellationToken cancellationToken = default) { var accessToken = await GetAccessTokenAsync(cancellationToken).ConfigureAwait(false); var url = $"https://qyapi.weixin.qq.com/cgi-bin/message/template/send?access_token={accessToken}"; var json = request.ToJsonString(); return await _httpHelper.PostAsync<ResponseResult>(url, json, cancellationToken).ConfigureAwait(false); }

调用示例：

var templateReq = new TemplateMessageRequest { template_id = "TEMPLATE_ID_FROM_WECHAT_BACKEND", touser = "USERID1", agentid = 1000001, data = new Dictionary<string, TemplateDataItem> { ["first"] = new TemplateDataItem { value = "故障告警" }, ["keyword1"] = new TemplateDataItem { value = "数据库连接超时" }, ["remark"] = new TemplateDataItem { value = "请立即处理" } } }; await service.SendTemplateMessage(templateReq);

6.2 扩展用户信息查询：增加GetUserDetail()方法

企业微信提供/cgi-bin/user/get接口查询用户详情，常用于校验UserID合法性或获取手机号。在WeChatService.cs中添加：

public async Task<UserDetailResponse> GetUserDetail(string userId, CancellationToken cancellationToken = default) { var accessToken = await GetAccessTokenAsync(cancellationToken).ConfigureAwait(false); var url = $"https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token={accessToken}&userid={userId}"; return await _httpHelper.GetAsync<UserDetailResponse>(url, cancellationToken).ConfigureAwait(false); } // 对应响应模型 public class UserDetailResponse { public int errcode { get; set; } public string errmsg { get; set; } public string userid { get; set; } public string name { get; set; } public string mobile { get; set; } public string email { get; set; } public string department { get; set; } }

提示：GetUserDetail()可作为SendText()的前置校验。例如在发送前调用var user = await service.GetUserDetail("USERID1")，若user.errcode != 0则跳过发送并记录告警，避免无效推送消耗配额。

6.3 配置热更新：如何在不重启服务的情况下修改WeChatConfig

当前WeChatConfig是构造时传入的静态对象，若想支持配置热更新（如修改Secret后自动生效），需改造为IOptionsMonitor<WeChatConfig>模式。步骤如下：

1. 在WeChatService.cs构造函数中接收IOptionsMonitor<WeChatConfig>：

private readonly IOptionsMonitor<WeChatConfig> _configMonitor; public WeChatService(IOptionsMonitor<WeChatConfig> configMonitor) { _configMonitor = configMonitor; _config = configMonitor.CurrentValue; }

2. 在GetAccessTokenAsync()中动态获取最新配置：

private WeChatConfig CurrentConfig => _configMonitor.CurrentValue;

3. 在Program.cs中注册：

builder.Services.Configure<WeChatConfig>(builder.Configuration.GetSection("WeChat")); builder.Services.AddSingleton<IWeChatService, WeChatService>();

此时修改appsettings.json并保存，_configMonitor.OnChange会自动触发回调，下次SendText()将使用新配置。从那以后我每次上线新配置，都强制走一遍GetUserDetail()验证连通性，再批量推送——这招帮我在灰度发布时拦截了7次配置错误。希望帮到你

本文还有配套的精品资源，点击获取