用 C# 接入微信全平台与支付（WeiXinMPSDK）

微信各平台的接口分散在公众号、小程序、企业微信、微信支付、开放平台这几套体系里，签名验签、AccessToken 获取与刷新、消息加解密、回调地址校验都要单独处理。用 .NET 做后端时，这些重复工作如果从零手写，光是 Token 过期和多实例并发刷新就够消耗一轮排期。

Senparc.Weixin 是用 C# 写的微信全平台 SDK，输入 AppId 等账号配置，输出公众号、小程序、企业微信、微信支付等模块的接口封装与消息处理中间件，供 .NET 开发者接入微信生态。

仓库主语言 C# 占比 96.4%，采用 Apache-2.0 许可，2013 年 1 月立项，最近一次提交在 2026 年 9 月，当前 Star 8903、Fork 4339、开放 Issue 219。框架覆盖面从 .NET Framework 3.5 一直到 .NET 10.0，兼容 MVC、Razor、WebApi、控制台程序、Blazor、MAUI 和后台服务，与外部框架解耦。源码托管在 JeffreySu/WeiXinMPSDK。

五分钟先跑通

环境只需要一个能跑的 .NET 工程，SDK 通过 NuGet 分发。README 说明可以按平台分别引用模块包，也可以直接引用 Senparc.Weixin.All 一次性带上全部模块，自动引用所有子模块。本次摘录没有包含逐字的安装命令原文，只给出了包名与引用关系。

以公众号为例，启动代码分两步，都写在 Program.cs 里。第一步加在 builder.Build() 上方：

builder.Services.AddSenparcWeixinServices(builder.Configuration);

第二步加在 builder.Build() 下方，注册账号信息：

var registerService = app.UseSenparcWeixin(app.Environment, null, null, register => { },
    (register, weixinSetting) =>
{
    // 注册公众号信息（可以执行多次，注册多个公众号）
    register.RegisterMpAccount(weixinSetting, "【盛派网络小助手】公众号");
});

如果用的是旧格式 Startup.cs，这两段分别对应 ConfigureServices() 和 Configure()。AppId、AppSecret、Token 这些参数写在 appsettings.json 里，运行时可以从 Senparc.Weixin.Config.SenparcWeixinSetting 取到。

高级接口在程序任意位置调用一句即可，以客服消息为例：

await CustomApi.SendTextAsync("AppId", "OpenId", "Hello World!");

要让公众号接收用户消息，还得写一个自定义 MessageHandler，继承 MessageHandler<DefaultMpMessageContext>，重写 OnImageRequestAsync、OnLocationRequestAsync 这类方法处理对应类型，DefaultResponseMessage 处理兜底消息。然后在 Program.cs 里把请求路径接上：

app.UseMessageHandlerForMp("/WeixinAsync",
    (stream, postModel, maxRecordCount, serviceProvider)
        => new CustomMessageHandler(stream, postModel, maxRecordCount, false, serviceProvider),
    options => options.AccountSettingFunc = context => Senparc.Weixin.Config.SenparcWeixinSetting);

跑通之后你会得到什么

把上面的中间件跑起来，公众号后台【设置与开发】>【基本配置】里的服务器地址(URL) 填上 https://你的域名/WeixinAsync，Token 与 appsettings.json 保持一致，微信就会把用户消息推给你的程序，程序按 MessageHandler 里的逻辑返回响应。

接口调用的结果就是返回对象本身，SDK 不生成中间文件，也没有报告目录。所有接口命名空间参照微信官方 API 路径规则定义，参数命名尽量与官方文档一致，方便在源码里定位。

再往下的扩展方向有三个：register 可以执行多次给不同平台注册多个账号；改用 Controller 或 WebApi 方式承载 MessageHandler，可以对消息处理步骤做更细的控制，也适用于 .NET Framework；把公众号对话能力接到 AI 服务上，仓库里的 Samples with AI 目录有聊天机器人集成示例。

主要功能

• 全平台模块覆盖：公众号、小程序、小游戏、企业微信/企业号、开放平台、微信支付、JSSDK、微信硬件与蓝牙。各模块解耦后独立发包，也可以引用 Senparc.Weixin.All 一次引全，学会一个模块的用法即可类推其他模块。
• AccessToken 自动托管：SDK 将 AccessToken 的全生命周期纳入托管，调用时只提供 AppId，不用自己处理过期与刷新。
• 消息处理管道：以 MessageHandler 作基类，重写各类型请求方法完成分发。接入方式有中间件与 Controller/WebApi 两种，前者更省代码，后者控制粒度更细。
• 消息加解密控制：构造 MessageHandler 时有 onlyAllowEncryptMessage 参数，可以要求只接收加密消息，对应公众号后台的消息加解密模式。
• 微信支付 V3 模块：作为独立的 Senparc.Weixin.TenPayV3 模块与 NuGet 包发布；仓库里把 V2 模块标注为不推荐。
• 长文本自动分片：仓库公告说明已支持长文本自动分片发送，面向 GenAI 场景下回复超长内容。
• 缓存与分布式部署：项目 Topics 包含 redis、memcached、distributed-cache，AccessToken 与消息上下文可以交给外部缓存托管，多实例部署时不必每个实例各自持有。
• AI 集成示例：Samples with AI 目录提供 AI 聊天机器人与微信集成的可运行示例。

常用参数与配置

• SenparcWeixinSetting：appsettings.json 中集中存放 AppId、AppSecret、Token 等账号信息的配置节。
• autoRegisterAllPlatforms: true：UseSenparcWeixin 的最后一个参数，设为 true 后系统自动注册所有配置好的账号，不需要在回调里逐个注册，需要引用 Senparc.Weixin.All 包。
• RegisterMpAccount(weixinSetting, "名称")：手动注册一个公众号账号，可调用多次注册多个账号。
• onlyAllowEncryptMessage：MessageHandler 构造参数之一，控制是否只接受加密消息。
• maxRecordCount：MessageHandler 构造参数之一，控制消息上下文的记录条数。
• IsDebug：README 与用户反馈里都出现过，用于控制调试信息输出。
• AccountSettingFunc：UseMessageHandlerForMp 的 options 里指定账号配置来源，示例中直接返回 SenparcWeixinSetting。
• UseMessageHandlerForMp 的第一个参数：中间件路径，示例是 "/WeixinAsync"，需要与公众号后台填写的服务器地址后缀一致。

结果在哪里看

公众号的验证结果和消息回流情况在后台【设置与开发】>【基本配置】里看，服务器地址填对并通过校验后，用户发的消息会打到你的中间件路径上。接口调用的结果以返回对象形式直接出现在程序里，没有落盘产物。

运行时输出的调试信息由 IsDebug 控制，仓库也提供了按模块拆分的在线文档与可运行示例：文档在 sdk.weixin.senparc.com/Docs/ 下按公众号、小程序、企业微信、微信支付 V3、微信支付 V2 分栏，在线示例是 sdk.weixin.senparc.com，项目主页是 weixin.senparc.com。docs 目录里另有更完整的开发说明文档。

实际使用中的坑

• HttpClient 的用法（已解决，66 条评论）：有用户在 Linux 下做压测后反馈，SDK 早期在 .NET Core 下每次都 new HttpClient()，正确做法应使用一个全局静态对象。这条已修复。
• Redis 超时（已解决，45 条评论）：报错形如 Timeout performing EXISTS Senparc:DefaultCache:Container:Senparc.Weixin.Work.Containers.AccessTokenContainer...，集中在默认缓存容器的 AccessToken 相关键上。
• StackExchange.Redis 版本差异（已解决，33 条评论）：有用户测试后反馈，StackExchange.Redis 1.2.6 在 Linux 下并发稍高时依然会报 Timeout，建议换成其他 Redis 库。
• IsDebug 设为 false 仍有输出（已解决，32 条评论）：只调用 SnsApi.JsCode2Json 的情况下，配置文件中把 IsDebug 设为 false 后仍然持续打印大量信息。
• 企业付款到零钱的证书问题（已解决，32 条评论）：调用 TenPayV3 相关接口做企业付款时，一直提示证书错误，需要重新下载对应证书。

选型参考

下面两个项目与 WeiXinMPSDK 处在不同层，重合点只在缓存这一层：WeiXinMPSDK 自己需要外部缓存来托管 AccessToken 与消息上下文，这两个库管的是缓存本身。

如果团队不做微信开发，只需要一层缓存抽象或一套分布式缓存集群，WeiXinMPSDK 解决不了这个问题，直接用 EasyCaching 更省事。反过来，WeiXinMPSDK 对缓存的抽象是服务于 AccessToken 与上下文托管的，可替换的缓存实现不如专门的缓存库丰富，把缓存选型完全交给它并不合适。

什么情况下别用它

技术栈不是 .NET 的团队，直接用对应语言的微信 SDK 更合适，这个项目只有 C# 实现。

只打算调用两三个微信接口、不准备长期维护的项目，自己写 HTTP 请求和签名逻辑反而更轻，引入整套 SDK 会增加依赖体积和升级负担。

需要把微信、钉钉、飞书等多个平台的接入统一到一层抽象里的场景，这个项目只解决微信一侧，统一层仍需自己设计。

团队不愿意接受以中文站点为主的文档与问答社区，也要考虑清楚，仓库虽然提供了 readme.en.md，但分模块文档与问答社区的主体是中文。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.5 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。