简介本资源是面向C#开发者与微信生态应用工程师的开源SDK实践项目提供完整的微信全平台公众号、小程序、小游戏、企业微信、开放平台及微信支付等集成解决方案。项目采用标准C#语言开发结构清晰、注释规范代码可读性高适合中高级开发者快速上手二次开发或学习微信各平台API对接逻辑。压缩包共含3065个文件主体为1784个.cs业务逻辑文件与250个.cshtml前端视图文件分别承担核心SDK封装与轻量级管理界面功能整体包体大小为54.78MB。目前已有270人下载学习资源附带完整目录层级与模块化设计说明涵盖消息加解密、OAuth2授权、JS-SDK签名、支付回调处理等关键实现细节便于读者深入理解微信多平台统一接入架构与工程化落地方式。1. 这不是又一个微信 SDK 封装库C# 开发者真正需要的 WeiXinMPSDK 是什么很多 C# 团队在接入微信生态时第一反应是“找一个能调通公众号接口的 NuGet 包”结果往往陷入三重困境调用公众号菜单 API 成功了但发现小程序登录态无法复用拿到用户 openid 后想发模板消息却卡在模板 ID 校验失败更常见的是——本地调试一切正常部署到 IIS 后HttpContext.Current为空、日志不写入、签名验证始终失败。这些问题的根源不是代码写错了而是缺失一个统一抽象层它必须同时承载公众号、小程序、企业微信、开放平台四类主体的身份上下文支持多租户配置隔离且能与 ASP.NET Core 的依赖注入、中间件、日志系统原生融合。WeiXinMPSDK 正是为解决这一结构性矛盾而生——它不提供“一键生成菜单”的 GUI 工具也不打包微信 JS-SDK 的前端 JS 文件而是用 C# 的强类型、泛型约束和策略模式把微信各平台共性协议如签名生成、AES 解密、XML/JSON 自动序列化抽成可替换组件把差异逻辑如小程序 session_key 解密方式、企业微信 corp_id 绑定规则封装进独立实现类。适合正在用 C# 构建 SaaS 系统、需要为不同客户分配独立微信应用、且要求日志可追溯、异常可熔断、配置可热更新的中大型项目团队。2. 从零初始化 WeiXinMPSDK注册服务、加载配置与多平台实例管理WeiXinMPSDK 的核心设计哲学是“配置即契约”——所有平台能力都通过IWeixinService接口暴露而具体实现由WeixinOptions配置驱动。这意味着你无需为公众号、小程序分别 new 出不同类只需在Startup.cs或Program.cs中完成一次注册后续按需解析即可。2.1 在 ASP.NET Core 6 中注册 SDK 服务// Program.cs (Minimal Hosting Model) var builder WebApplication.CreateBuilder(args); // 注册 WeiXinMPSDK 服务关键必须在 AddControllers 之前 builder.Services.AddWeixinServices(options { // 全局基础配置所有平台共用的 HTTP 超时、重试策略、日志前缀 options.HttpClientOptions.Timeout TimeSpan.FromSeconds(15); options.HttpClientOptions.MaxRetryCount 3; // 多平台配置源支持从 IConfiguration、数据库或 Consul 动态加载 options.ConfigProvider new ConfigurationWeixinConfigProvider(builder.Configuration); }); // 同时注册控制器和 Razor Pages确保中间件顺序正确 builder.Services.AddControllersWithViews(); builder.Services.AddRazorPages(); var app builder.Build();提示AddWeixinServices必须在AddControllersWithViews()之前调用。因为 SDK 内部依赖IOptionsMonitorWeixinOptions实现配置热更新若注册顺序颠倒会导致IWeixinService解析时获取到空配置。2.2 配置文件定义用 JSON 结构表达平台拓扑关系WeiXinMPSDK 要求配置必须体现“平台类型 → 应用标识 → 密钥凭证”的三级嵌套。以下appsettings.json片段展示了典型 SaaS 场景{ Weixin: { Platforms: [ { Type: OfficialAccount, // 公众号 AppId: wx1234567890abcdef, AppSecret: a1b2c3d4e5f678901234567890abcdef, Token: mytoken123, EncodingAESKey: abcdefghijklmnopqrstuvwxyz0123456789012 }, { Type: MiniProgram, // 小程序 AppId: wxa0987654321fedcb, AppSecret: z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4, Token: miniprogram_token, EncodingAESKey: 0123456789012345678901234567890123456789012 }, { Type: WorkWechat, // 企业微信 CorpId: ww1234567890abcdef, CorpSecret: s3c4r5e6t7k8e9y0a1b2c3d4e5f6g7h8, AgentId: 100001, Token: workwechat_token, EncodingAESKey: key_for_workwechat_32_chars_long } ] } }注意EncodingAESKey必须为 43 位 Base64 字符含这是微信服务器强制要求。WeiXinMPSDK 在启动时会校验该字段长度若不合法将抛出WeixinConfigurationException并阻止应用启动避免线上签名失败。2.3 按需解析平台服务用泛型工厂获取强类型实例SDK 提供IWeixinServiceFactory接口允许你在 Controller 或 Service 中根据运行时参数如 URL 路径中的platformmp动态获取对应平台服务[ApiController] [Route(api/[controller])] public class WeixinController : ControllerBase { private readonly IWeixinServiceFactory _factory; public WeixinController(IWeixinServiceFactory factory) { _factory factory; } [HttpPost(callback/{platform})] public async TaskIActionResult HandleCallback( string platform, [FromBody] JObject requestBody) { // 根据路径参数解析平台类型 var platformType platform.ToLower() switch { mp WeixinPlatformType.OfficialAccount, mini WeixinPlatformType.MiniProgram, ww WeixinPlatformType.WorkWechat, _ throw new ArgumentException($Unsupported platform: {platform}) }; // 获取对应平台的服务实例自动绑定配置、日志、HTTP 客户端 var service _factory.Create(platformType); try { // 所有平台均实现 IWeixinService但方法签名不同 if (service is IOfficialAccountService oaService) { var result await oaService.VerifySignatureAsync(requestBody); return Ok(new { Valid result }); } else if (service is IMiniProgramService miniService) { var userInfo await miniService.DecodeUserInfoAsync( code: Request.Query[code], encryptedData: requestBody[encryptedData]?.ToString(), iv: requestBody[iv]?.ToString()); return Ok(userInfo); } } catch (WeixinApiException ex) { // SDK 统一异常包含微信原始错误码errcode、消息errmsg及请求ID _logger.LogError(ex, Weixin API call failed. RequestId: {RequestId}, ex.RequestId); return BadRequest(new { ex.ErrCode, ex.ErrMsg }); } return BadRequest(Unsupported operation for this platform); } }逻辑说明IWeixinServiceFactory.Create()方法内部会根据platformType查找匹配的WeixinOptions.Platforms配置项并注入对应平台的HttpClient、ILogger和IOptionsMonitorWeixinOptions。整个过程对开发者透明无需手动 new 实例或管理生命周期。3. 实战用 WeiXinMPSDK 实现公众号消息自动回复与事件分发公众号开发最易踩坑的环节是消息加解密与事件路由。WeiXinMPSDK 将 XML 解析、AES 解密、事件类型识别、消息体反序列化全部封装进WeixinMessageHandler基类开发者只需继承并重写抽象方法即可。3.1 创建自定义消息处理器继承基类并实现业务逻辑public class CustomMessageHandler : WeixinMessageHandler { private readonly ILoggerCustomMessageHandler _logger; public CustomMessageHandler( IServiceProvider serviceProvider, ILoggerCustomMessageHandler logger) : base(serviceProvider) { _logger logger; } // 重写文本消息处理逻辑 protected override async TaskIResponseMessageBase OnTextRequestAsync(RequestMessageText requestMessage) { _logger.LogInformation(Received text: {Content}, requestMessage.Content); // 示例关键词触发不同响应 if (requestMessage.Content.Contains(帮助)) { return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content 欢迎使用客服系统\n1. 输入【订单】查询最新订单\n2. 输入【人工】转接客服 }; } else if (requestMessage.Content.StartsWith(订单)) { var orderId requestMessage.Content.Substring(2).Trim(); var orderService ServiceProvider.GetRequiredServiceIOrderService(); var order await orderService.GetByNumberAsync(orderId); return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content order null ? $未找到订单 {orderId} : $订单 {order.Number} 状态{order.Status} }; } return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content 暂不支持该指令请输入【帮助】查看菜单 }; } // 重写关注事件处理 protected override async TaskIResponseMessageBase OnEventSubscribeRequestAsync(RequestMessageEvent_Subscribe requestMessage) { _logger.LogInformation(New subscriber: {OpenId}, requestMessage.FromUserName); // 自动发送欢迎图文消息 return new ResponseMessageNews { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Articles new ListArticle { new Article { Title 欢迎关注我们的服务号, Description 点击了解如何使用我们的订单查询、会员积分等功能, PicUrl https://example.com/welcome.jpg, Url https://example.com/guide } } }; } // 重写扫码事件带参数二维码 protected override async TaskIResponseMessageBase OnEventQrScanRequestAsync(RequestMessageEvent_QrScan requestMessage) { _logger.LogInformation(QrScan event: {Ticket}, SceneId: {SceneId}, requestMessage.Ticket, requestMessage.EventKey); // EventKey 格式为 qrscene_12345提取 scene_id var sceneId requestMessage.EventKey.Replace(qrscene_, ); var userService ServiceProvider.GetRequiredServiceIUserService(); await userService.BindUserAsync(requestMessage.FromUserName, sceneId); return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content 您已成功绑定推荐人 }; } }参数说明RequestMessageText、RequestMessageEvent_Subscribe等类型均由 SDK 提供已预定义 XML 属性映射如[XmlRoot(xml)]、[XmlElement(ToUserName)]无需手动解析。ServiceProvider可用于解析业务服务如IOrderService实现依赖注入解耦。3.2 在 Startup 中注册处理器并挂载中间件// Program.cs builder.Services.AddTransientCustomMessageHandler(); var app builder.Build(); // 挂载微信消息处理中间件必须在 UseRouting 之后、UseEndpoints 之前 app.UseWeixinMessageHandlerCustomMessageHandler(/weixin/callback); // 注意此路径必须与公众号后台配置的服务器地址完全一致含 /weixin/callback app.UseRouting(); app.UseEndpoints(endpoints { endpoints.MapControllers(); });关键点UseWeixinMessageHandlerT是 SDK 提供的专用中间件它会自动验证signature、timestamp、nonce参数有效性对加密消息启用消息加密时执行 AES 解密将原始 XML 请求反序列化为对应RequestMessageXXX类型调用OnTextRequestAsync等重写方法将返回的IResponseMessageBase序列化为 XML 并加密如启用后返回。3.3 配置公众号后台确保服务器地址与 Token 严格匹配在微信公众平台后台mp.weixin.qq.com的「开发」→「基本配置」中必须填写字段值说明服务器地址URLhttps://yourdomain.com/weixin/callback必须是 HTTPS且与UseWeixinMessageHandler路径一致Tokenmytoken123必须与appsettings.json中对应平台的Token字段完全相同区分大小写EncodingAESKeyabcdefghijklmnopqrstuvwxyz0123456789012必须与配置中EncodingAESKey完全一致排错技巧若验证失败检查 IIS 或 Nginx 是否截断了?echostrxxx查询参数某些反向代理默认过滤未知参数。可在中间件中添加日志输出原始HttpContext.Request.QueryString进行确认。4. 进阶跨平台用户体系打通与敏感操作审计日志当系统同时接入公众号、小程序、企业微信时用户身份分散在三个独立的openid/unionid体系中。WeiXinMPSDK 提供IUserLinker接口支持基于手机号、邮箱或自定义唯一 ID 建立跨平台关联并强制记录所有敏感操作日志。4.1 实现跨平台用户关联统一用户中心对接public class UnifiedUserLinker : IUserLinker { private readonly IUserRepository _userRepository; private readonly ILoggerUnifiedUserLinker _logger; public UnifiedUserLinker(IUserRepository userRepository, ILoggerUnifiedUserLinker logger) { _userRepository userRepository; _logger logger; } // 小程序登录成功后调用此方法绑定用户 public async Task LinkMiniProgramUserAsync(string openId, string unionId, string phoneNumber) { var user await _userRepository.FindByPhoneAsync(phoneNumber); if (user null) { user new User { Phone phoneNumber, CreatedAt DateTime.UtcNow }; await _userRepository.CreateAsync(user); } // 关联小程序 OpenID 到用户 await _userRepository.LinkOpenIdAsync(user.Id, WeixinPlatformType.MiniProgram, openId); // 若存在 UnionID同步关联公众号和企业微信同一主体下 UnionID 相同 if (!string.IsNullOrEmpty(unionId)) { await _userRepository.LinkUnionIdAsync(user.Id, unionId); _logger.LogInformation(UnionId linked for user {UserId}: {UnionId}, user.Id, unionId); } } // 公众号网页授权后调用此方法绑定 public async Task LinkOfficialAccountUserAsync(string openId, string unionId, string email) { var user await _userRepository.FindByEmailAsync(email); if (user null) { user new User { Email email, CreatedAt DateTime.UtcNow }; await _userRepository.CreateAsync(user); } await _userRepository.LinkOpenIdAsync(user.Id, WeixinPlatformType.OfficialAccount, openId); } } // 在 Program.cs 中注册 builder.Services.AddSingletonIUserLinker, UnifiedUserLinker();逻辑说明IUserLinker是 SDK 定义的扩展点当IMiniProgramService.LoginAsync()或IOfficialAccountService.GetUserInfoAsync()成功返回用户信息后SDK 会自动调用LinkXXXUserAsync方法。开发者只需实现数据持久化逻辑无需修改业务代码。4.2 敏感操作审计自动记录 API 调用与响应详情WeiXinMPSDK 内置IAuditLogger接口对所有调用微信 API 的操作如发送模板消息、创建二维码、获取用户列表进行结构化日志记录包含请求参数、响应结果、耗时、IP 地址等字段public class DatabaseAuditLogger : IAuditLogger { private readonly IAuditLogRepository _logRepository; private readonly IHttpContextAccessor _httpContextAccessor; public DatabaseAuditLogger( IAuditLogRepository logRepository, IHttpContextAccessor httpContextAccessor) { _logRepository logRepository; _httpContextAccessor httpContextAccessor; } public async Task LogAsync(AuditLogEntry entry) { var log new AuditLog { Platform entry.Platform.ToString(), ApiName entry.ApiName, RequestParameters JsonConvert.SerializeObject(entry.RequestParameters), ResponseResult JsonConvert.SerializeObject(entry.ResponseResult), DurationMs entry.DurationMs, StatusCode entry.StatusCode, ClientIp _httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString() ?? unknown, Timestamp DateTime.UtcNow, RequestId entry.RequestId }; await _logRepository.InsertAsync(log); } } // 注册审计日志器必须在 AddWeixinServices 之后 builder.Services.AddSingletonIAuditLogger, DatabaseAuditLogger(); builder.Services.AddHttpContextAccessor(); // 用于获取客户端 IP审计日志字段说明ApiName: 如template.send、qrcode.create便于按接口类型聚合分析RequestParameters: JSON 序列化的请求参数已脱敏手机号、邮箱等敏感字段ResponseResult: 微信原始响应 JSON含errcode、errmsg等DurationMs: 从请求发出到收到响应的毫秒数用于性能监控StatusCode: HTTP 状态码200/401/429 等非微信业务错误码。4.3 配置审计日志开关与采样率平衡性能与可观测性审计日志默认记录所有 API 调用但在高并发场景下可能影响性能。SDK 支持按平台、API 名称、错误状态设置采样策略// Program.cs 中配置审计策略 builder.Services.AddWeixinServices(options { // 仅对错误响应errcode ! 0和模板消息类 API 进行全量记录 options.AuditOptions.SamplingRules new[] { new AuditSamplingRule { Platform WeixinPlatformType.OfficialAccount, ApiNamePattern template.*, // 正则匹配 SampleRate 1.0 // 100% 采样 }, new AuditSamplingRule { Platform WeixinPlatformType.MiniProgram, ApiNamePattern .*, Condition entry entry.StatusCode ! 200 || entry.ResponseResult?.Contains(\errcode\:0) false, SampleRate 0.1 // 错误响应 10% 采样 } }; });提示ApiNamePattern使用 .NET 正则语法Condition是 FuncAuditLogEntry, bool 委托可用于复杂判断如排除测试环境调用、过滤特定 errcode。采样率SampleRate为 0.01.0 的 double 值0.1 表示 10% 概率记录。本文还有配套的精品资源点击获取
C#微信多平台SDK：统一抽象层设计与ASP.NET Core集成
简介本资源是面向C#开发者与微信生态应用工程师的开源SDK实践项目提供完整的微信全平台公众号、小程序、小游戏、企业微信、开放平台及微信支付等集成解决方案。项目采用标准C#语言开发结构清晰、注释规范代码可读性高适合中高级开发者快速上手二次开发或学习微信各平台API对接逻辑。压缩包共含3065个文件主体为1784个.cs业务逻辑文件与250个.cshtml前端视图文件分别承担核心SDK封装与轻量级管理界面功能整体包体大小为54.78MB。目前已有270人下载学习资源附带完整目录层级与模块化设计说明涵盖消息加解密、OAuth2授权、JS-SDK签名、支付回调处理等关键实现细节便于读者深入理解微信多平台统一接入架构与工程化落地方式。1. 这不是又一个微信 SDK 封装库C# 开发者真正需要的 WeiXinMPSDK 是什么很多 C# 团队在接入微信生态时第一反应是“找一个能调通公众号接口的 NuGet 包”结果往往陷入三重困境调用公众号菜单 API 成功了但发现小程序登录态无法复用拿到用户 openid 后想发模板消息却卡在模板 ID 校验失败更常见的是——本地调试一切正常部署到 IIS 后HttpContext.Current为空、日志不写入、签名验证始终失败。这些问题的根源不是代码写错了而是缺失一个统一抽象层它必须同时承载公众号、小程序、企业微信、开放平台四类主体的身份上下文支持多租户配置隔离且能与 ASP.NET Core 的依赖注入、中间件、日志系统原生融合。WeiXinMPSDK 正是为解决这一结构性矛盾而生——它不提供“一键生成菜单”的 GUI 工具也不打包微信 JS-SDK 的前端 JS 文件而是用 C# 的强类型、泛型约束和策略模式把微信各平台共性协议如签名生成、AES 解密、XML/JSON 自动序列化抽成可替换组件把差异逻辑如小程序 session_key 解密方式、企业微信 corp_id 绑定规则封装进独立实现类。适合正在用 C# 构建 SaaS 系统、需要为不同客户分配独立微信应用、且要求日志可追溯、异常可熔断、配置可热更新的中大型项目团队。2. 从零初始化 WeiXinMPSDK注册服务、加载配置与多平台实例管理WeiXinMPSDK 的核心设计哲学是“配置即契约”——所有平台能力都通过IWeixinService接口暴露而具体实现由WeixinOptions配置驱动。这意味着你无需为公众号、小程序分别 new 出不同类只需在Startup.cs或Program.cs中完成一次注册后续按需解析即可。2.1 在 ASP.NET Core 6 中注册 SDK 服务// Program.cs (Minimal Hosting Model) var builder WebApplication.CreateBuilder(args); // 注册 WeiXinMPSDK 服务关键必须在 AddControllers 之前 builder.Services.AddWeixinServices(options { // 全局基础配置所有平台共用的 HTTP 超时、重试策略、日志前缀 options.HttpClientOptions.Timeout TimeSpan.FromSeconds(15); options.HttpClientOptions.MaxRetryCount 3; // 多平台配置源支持从 IConfiguration、数据库或 Consul 动态加载 options.ConfigProvider new ConfigurationWeixinConfigProvider(builder.Configuration); }); // 同时注册控制器和 Razor Pages确保中间件顺序正确 builder.Services.AddControllersWithViews(); builder.Services.AddRazorPages(); var app builder.Build();提示AddWeixinServices必须在AddControllersWithViews()之前调用。因为 SDK 内部依赖IOptionsMonitorWeixinOptions实现配置热更新若注册顺序颠倒会导致IWeixinService解析时获取到空配置。2.2 配置文件定义用 JSON 结构表达平台拓扑关系WeiXinMPSDK 要求配置必须体现“平台类型 → 应用标识 → 密钥凭证”的三级嵌套。以下appsettings.json片段展示了典型 SaaS 场景{ Weixin: { Platforms: [ { Type: OfficialAccount, // 公众号 AppId: wx1234567890abcdef, AppSecret: a1b2c3d4e5f678901234567890abcdef, Token: mytoken123, EncodingAESKey: abcdefghijklmnopqrstuvwxyz0123456789012 }, { Type: MiniProgram, // 小程序 AppId: wxa0987654321fedcb, AppSecret: z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4, Token: miniprogram_token, EncodingAESKey: 0123456789012345678901234567890123456789012 }, { Type: WorkWechat, // 企业微信 CorpId: ww1234567890abcdef, CorpSecret: s3c4r5e6t7k8e9y0a1b2c3d4e5f6g7h8, AgentId: 100001, Token: workwechat_token, EncodingAESKey: key_for_workwechat_32_chars_long } ] } }注意EncodingAESKey必须为 43 位 Base64 字符含这是微信服务器强制要求。WeiXinMPSDK 在启动时会校验该字段长度若不合法将抛出WeixinConfigurationException并阻止应用启动避免线上签名失败。2.3 按需解析平台服务用泛型工厂获取强类型实例SDK 提供IWeixinServiceFactory接口允许你在 Controller 或 Service 中根据运行时参数如 URL 路径中的platformmp动态获取对应平台服务[ApiController] [Route(api/[controller])] public class WeixinController : ControllerBase { private readonly IWeixinServiceFactory _factory; public WeixinController(IWeixinServiceFactory factory) { _factory factory; } [HttpPost(callback/{platform})] public async TaskIActionResult HandleCallback( string platform, [FromBody] JObject requestBody) { // 根据路径参数解析平台类型 var platformType platform.ToLower() switch { mp WeixinPlatformType.OfficialAccount, mini WeixinPlatformType.MiniProgram, ww WeixinPlatformType.WorkWechat, _ throw new ArgumentException($Unsupported platform: {platform}) }; // 获取对应平台的服务实例自动绑定配置、日志、HTTP 客户端 var service _factory.Create(platformType); try { // 所有平台均实现 IWeixinService但方法签名不同 if (service is IOfficialAccountService oaService) { var result await oaService.VerifySignatureAsync(requestBody); return Ok(new { Valid result }); } else if (service is IMiniProgramService miniService) { var userInfo await miniService.DecodeUserInfoAsync( code: Request.Query[code], encryptedData: requestBody[encryptedData]?.ToString(), iv: requestBody[iv]?.ToString()); return Ok(userInfo); } } catch (WeixinApiException ex) { // SDK 统一异常包含微信原始错误码errcode、消息errmsg及请求ID _logger.LogError(ex, Weixin API call failed. RequestId: {RequestId}, ex.RequestId); return BadRequest(new { ex.ErrCode, ex.ErrMsg }); } return BadRequest(Unsupported operation for this platform); } }逻辑说明IWeixinServiceFactory.Create()方法内部会根据platformType查找匹配的WeixinOptions.Platforms配置项并注入对应平台的HttpClient、ILogger和IOptionsMonitorWeixinOptions。整个过程对开发者透明无需手动 new 实例或管理生命周期。3. 实战用 WeiXinMPSDK 实现公众号消息自动回复与事件分发公众号开发最易踩坑的环节是消息加解密与事件路由。WeiXinMPSDK 将 XML 解析、AES 解密、事件类型识别、消息体反序列化全部封装进WeixinMessageHandler基类开发者只需继承并重写抽象方法即可。3.1 创建自定义消息处理器继承基类并实现业务逻辑public class CustomMessageHandler : WeixinMessageHandler { private readonly ILoggerCustomMessageHandler _logger; public CustomMessageHandler( IServiceProvider serviceProvider, ILoggerCustomMessageHandler logger) : base(serviceProvider) { _logger logger; } // 重写文本消息处理逻辑 protected override async TaskIResponseMessageBase OnTextRequestAsync(RequestMessageText requestMessage) { _logger.LogInformation(Received text: {Content}, requestMessage.Content); // 示例关键词触发不同响应 if (requestMessage.Content.Contains(帮助)) { return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content 欢迎使用客服系统\n1. 输入【订单】查询最新订单\n2. 输入【人工】转接客服 }; } else if (requestMessage.Content.StartsWith(订单)) { var orderId requestMessage.Content.Substring(2).Trim(); var orderService ServiceProvider.GetRequiredServiceIOrderService(); var order await orderService.GetByNumberAsync(orderId); return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content order null ? $未找到订单 {orderId} : $订单 {order.Number} 状态{order.Status} }; } return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content 暂不支持该指令请输入【帮助】查看菜单 }; } // 重写关注事件处理 protected override async TaskIResponseMessageBase OnEventSubscribeRequestAsync(RequestMessageEvent_Subscribe requestMessage) { _logger.LogInformation(New subscriber: {OpenId}, requestMessage.FromUserName); // 自动发送欢迎图文消息 return new ResponseMessageNews { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Articles new ListArticle { new Article { Title 欢迎关注我们的服务号, Description 点击了解如何使用我们的订单查询、会员积分等功能, PicUrl https://example.com/welcome.jpg, Url https://example.com/guide } } }; } // 重写扫码事件带参数二维码 protected override async TaskIResponseMessageBase OnEventQrScanRequestAsync(RequestMessageEvent_QrScan requestMessage) { _logger.LogInformation(QrScan event: {Ticket}, SceneId: {SceneId}, requestMessage.Ticket, requestMessage.EventKey); // EventKey 格式为 qrscene_12345提取 scene_id var sceneId requestMessage.EventKey.Replace(qrscene_, ); var userService ServiceProvider.GetRequiredServiceIUserService(); await userService.BindUserAsync(requestMessage.FromUserName, sceneId); return new ResponseMessageText { ToUserName requestMessage.FromUserName, FromUserName requestMessage.ToUserName, CreateTime DateTime.Now.ToUniversalTime().Seconds, Content 您已成功绑定推荐人 }; } }参数说明RequestMessageText、RequestMessageEvent_Subscribe等类型均由 SDK 提供已预定义 XML 属性映射如[XmlRoot(xml)]、[XmlElement(ToUserName)]无需手动解析。ServiceProvider可用于解析业务服务如IOrderService实现依赖注入解耦。3.2 在 Startup 中注册处理器并挂载中间件// Program.cs builder.Services.AddTransientCustomMessageHandler(); var app builder.Build(); // 挂载微信消息处理中间件必须在 UseRouting 之后、UseEndpoints 之前 app.UseWeixinMessageHandlerCustomMessageHandler(/weixin/callback); // 注意此路径必须与公众号后台配置的服务器地址完全一致含 /weixin/callback app.UseRouting(); app.UseEndpoints(endpoints { endpoints.MapControllers(); });关键点UseWeixinMessageHandlerT是 SDK 提供的专用中间件它会自动验证signature、timestamp、nonce参数有效性对加密消息启用消息加密时执行 AES 解密将原始 XML 请求反序列化为对应RequestMessageXXX类型调用OnTextRequestAsync等重写方法将返回的IResponseMessageBase序列化为 XML 并加密如启用后返回。3.3 配置公众号后台确保服务器地址与 Token 严格匹配在微信公众平台后台mp.weixin.qq.com的「开发」→「基本配置」中必须填写字段值说明服务器地址URLhttps://yourdomain.com/weixin/callback必须是 HTTPS且与UseWeixinMessageHandler路径一致Tokenmytoken123必须与appsettings.json中对应平台的Token字段完全相同区分大小写EncodingAESKeyabcdefghijklmnopqrstuvwxyz0123456789012必须与配置中EncodingAESKey完全一致排错技巧若验证失败检查 IIS 或 Nginx 是否截断了?echostrxxx查询参数某些反向代理默认过滤未知参数。可在中间件中添加日志输出原始HttpContext.Request.QueryString进行确认。4. 进阶跨平台用户体系打通与敏感操作审计日志当系统同时接入公众号、小程序、企业微信时用户身份分散在三个独立的openid/unionid体系中。WeiXinMPSDK 提供IUserLinker接口支持基于手机号、邮箱或自定义唯一 ID 建立跨平台关联并强制记录所有敏感操作日志。4.1 实现跨平台用户关联统一用户中心对接public class UnifiedUserLinker : IUserLinker { private readonly IUserRepository _userRepository; private readonly ILoggerUnifiedUserLinker _logger; public UnifiedUserLinker(IUserRepository userRepository, ILoggerUnifiedUserLinker logger) { _userRepository userRepository; _logger logger; } // 小程序登录成功后调用此方法绑定用户 public async Task LinkMiniProgramUserAsync(string openId, string unionId, string phoneNumber) { var user await _userRepository.FindByPhoneAsync(phoneNumber); if (user null) { user new User { Phone phoneNumber, CreatedAt DateTime.UtcNow }; await _userRepository.CreateAsync(user); } // 关联小程序 OpenID 到用户 await _userRepository.LinkOpenIdAsync(user.Id, WeixinPlatformType.MiniProgram, openId); // 若存在 UnionID同步关联公众号和企业微信同一主体下 UnionID 相同 if (!string.IsNullOrEmpty(unionId)) { await _userRepository.LinkUnionIdAsync(user.Id, unionId); _logger.LogInformation(UnionId linked for user {UserId}: {UnionId}, user.Id, unionId); } } // 公众号网页授权后调用此方法绑定 public async Task LinkOfficialAccountUserAsync(string openId, string unionId, string email) { var user await _userRepository.FindByEmailAsync(email); if (user null) { user new User { Email email, CreatedAt DateTime.UtcNow }; await _userRepository.CreateAsync(user); } await _userRepository.LinkOpenIdAsync(user.Id, WeixinPlatformType.OfficialAccount, openId); } } // 在 Program.cs 中注册 builder.Services.AddSingletonIUserLinker, UnifiedUserLinker();逻辑说明IUserLinker是 SDK 定义的扩展点当IMiniProgramService.LoginAsync()或IOfficialAccountService.GetUserInfoAsync()成功返回用户信息后SDK 会自动调用LinkXXXUserAsync方法。开发者只需实现数据持久化逻辑无需修改业务代码。4.2 敏感操作审计自动记录 API 调用与响应详情WeiXinMPSDK 内置IAuditLogger接口对所有调用微信 API 的操作如发送模板消息、创建二维码、获取用户列表进行结构化日志记录包含请求参数、响应结果、耗时、IP 地址等字段public class DatabaseAuditLogger : IAuditLogger { private readonly IAuditLogRepository _logRepository; private readonly IHttpContextAccessor _httpContextAccessor; public DatabaseAuditLogger( IAuditLogRepository logRepository, IHttpContextAccessor httpContextAccessor) { _logRepository logRepository; _httpContextAccessor httpContextAccessor; } public async Task LogAsync(AuditLogEntry entry) { var log new AuditLog { Platform entry.Platform.ToString(), ApiName entry.ApiName, RequestParameters JsonConvert.SerializeObject(entry.RequestParameters), ResponseResult JsonConvert.SerializeObject(entry.ResponseResult), DurationMs entry.DurationMs, StatusCode entry.StatusCode, ClientIp _httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString() ?? unknown, Timestamp DateTime.UtcNow, RequestId entry.RequestId }; await _logRepository.InsertAsync(log); } } // 注册审计日志器必须在 AddWeixinServices 之后 builder.Services.AddSingletonIAuditLogger, DatabaseAuditLogger(); builder.Services.AddHttpContextAccessor(); // 用于获取客户端 IP审计日志字段说明ApiName: 如template.send、qrcode.create便于按接口类型聚合分析RequestParameters: JSON 序列化的请求参数已脱敏手机号、邮箱等敏感字段ResponseResult: 微信原始响应 JSON含errcode、errmsg等DurationMs: 从请求发出到收到响应的毫秒数用于性能监控StatusCode: HTTP 状态码200/401/429 等非微信业务错误码。4.3 配置审计日志开关与采样率平衡性能与可观测性审计日志默认记录所有 API 调用但在高并发场景下可能影响性能。SDK 支持按平台、API 名称、错误状态设置采样策略// Program.cs 中配置审计策略 builder.Services.AddWeixinServices(options { // 仅对错误响应errcode ! 0和模板消息类 API 进行全量记录 options.AuditOptions.SamplingRules new[] { new AuditSamplingRule { Platform WeixinPlatformType.OfficialAccount, ApiNamePattern template.*, // 正则匹配 SampleRate 1.0 // 100% 采样 }, new AuditSamplingRule { Platform WeixinPlatformType.MiniProgram, ApiNamePattern .*, Condition entry entry.StatusCode ! 200 || entry.ResponseResult?.Contains(\errcode\:0) false, SampleRate 0.1 // 错误响应 10% 采样 } }; });提示ApiNamePattern使用 .NET 正则语法Condition是 FuncAuditLogEntry, bool 委托可用于复杂判断如排除测试环境调用、过滤特定 errcode。采样率SampleRate为 0.01.0 的 double 值0.1 表示 10% 概率记录。本文还有配套的精品资源点击获取
