基于 .NET 8.0 的 Senparc.Weixin 全平台综合示例:net8-mvc Sample 项目结构与部署指南
基于 .NET 8.0 的 Senparc.Weixin 全平台综合示例:net8-mvc Sample 项目结构与部署指南
Senparc.Weixin.Sample.Net8 是 WeiXinMPSDK 仓库中面向 .NET 8.0 的 MVC 综合示例项目,将公众号、小程序、企业微信、微信支付(V2/V3)、开放平台等 Senparc.Weixin SDK 全部模块集成于一个 Web 应用。阅读本文后,你将掌握该示例的编译环境要求、目录与配置结构、核心启动注册流程,以及公众号消息处理的两种接入方式,可直接据此部署测试或在真实项目中对照参考。
一、项目定位:SDK 各模块的"综合演练场"
Samples/All/net8-mvc/ 目录下的 Senparc.Weixin.Sample.Net8 承担着双重角色:
- 可部署的综合示例:它提供了 .NET 8.0 的 Mvc 项目示例,可以直接进行部署测试。开箱即可运行基础功能,高级功能测试则需要修改配置文件(如修改 appId、Token、Secret 等真实微信账号信息)。
- SDK 调试与多目标编译载体:该 Sample 可用于调试 Senparc.Weixin SDK 本身,支持 .NET 4.6.2+、.NET Standard 2.1+、.NET 8.0 的不同版本库编译,并且在 Release 编译条件下可以生成 NuGet 包。
正因为它是"所有模块集成在一起"的综合示例,业务逻辑复杂度明显高于单模块示例。仓库作者在 Samples/All/net8-mvc/readme.md 中特别说明:如果只需要查看单个模块的示例代码(公众号、小程序、开放平台、微信支付等),可以直接查看 Samples/ 目录下的其他对应文件夹——例如 Samples/MP、Samples/WxOpen、Samples/TenPayV3、Samples/Work 等独立示例项目。
不过无需担心阅读障碍:示例中已经将各个模块使用注释、文件夹等方式进行了区分,代码结构清晰。对于需要同时接入多个微信产品线的综合场景,本示例是非常合适的实际项目参考模板。
二、编译环境要求与多目标框架说明
原文档对开发环境给出了明确要求,这是编译本项目的第一道门槛:
- Visual Studio:需要升级到 VS 2022(或将来更新版本)。
- .NET 8.0 SDK:必须安装(官方下载地址)。
条件编译提示:由于
src/目录下的 SDK 源码中采用了条件编译(Conditional Compilation),默认情况下开发环境需要同时安装 .NET Framework 4.6.2 和 .NET 8.0 才能编译成功。这是因为同一套源码需要针对 .NET Framework 与 .NET Core/.NET 8.0 两个平台输出不同版本的库。
从 Senparc.Weixin.Sample.net8.csproj 可以看到该示例项目的目标框架为 net8.0,并通过 ProjectReference 引用了 Senparc.Weixin.Net8Sample.CommonService.csproj(公共业务服务层,位于 Samples/All/Senparc.Weixin.Sample.CommonService),同时以 Shared 方式导入 Senparc.Weixin.Sample.Shared.projitems 共享视图与静态资源。项目还引用了 Microsoft.Extensions.Configuration.Json、Senparc.AI.Kernel、Senparc.CO2NET.WebApi、Senparc.NeuChar.App/AspNet 等关键 NuGet 包,体现了完整的依赖栈。
注意:原文档中"采用 .NET 7.0 作为默认 Web 运行框架"的说法属于历史版本说明(当前示例已升级为 .NET 8.0 目标框架),实际以 csproj 中的
net8.0为准。
三、项目目录结构导读:按微信模块划分的 Controller
从源码结构看,示例将 Controller 按微信产品线清晰分目录组织(见 Controllers):
| 目录 | 对应模块 | 代表性文件 |
|---|---|---|
Controllers/Weixin/MP/ |
公众号 | WeixinController.cs、MenuController、OAuth2Controller、JSSDK、订阅消息、WebSocket 等 |
Controllers/Weixin/Open/ |
开放平台 | OpenController、OpenOAuthController |
Controllers/Weixin/TenPay/ |
微信支付 | TenPayController(V2)、TenPayV3Controller、TenPayApiV3Controller |
Controllers/Weixin/ThirdPartyAuth/ |
第三方平台授权 | ThirdPartyAuthController |
Controllers/Weixin/Work/ |
企业微信 | WorkController |
Controllers/Weixin/WxOpen/ |
小程序 | WxOpenController |
Controllers/Tools/ |
辅助工具 | CacheController、QrCodeController、AiDocController、SimulateToolController 等 |
此外,Controllers/ 下还有 BaseController.cs(所有 Controller 的基类,统一输出当前缓存策略类型到视图)与 CaseCollectionController.cs、HomeController.cs。公共的业务处理逻辑(消息处理器、模板消息、事件服务等)则统一放在 Samples/All/Senparc.Weixin.Sample.CommonService 中,被各版本示例共享。
四、核心配置文件:appsettings.json 参数全解
示例的微信账号与系统配置全部集中在 appsettings.json 中,由三个顶层节点组成,key 会被 SDK 自动识别,切勿修改 key 名称,未使用的参数可以直接删除整条配置。
1. SenparcSetting(CO2NET 全局配置)
"SenparcSetting": {
"IsDebug": true,
"DefaultCacheNamespace": "DefaultCache",
"Cache_Redis_Configuration": "#{Cache_Redis_Configuration}#",
"Cache_Memcached_Configuration": "#{Cache_Memcached_Configuration}#",
"SenparcUnionAgentKey": "#{SenparcUnionAgentKey}#"
}
IsDebug:调试模式开关,开启后会在App_Data/WeixinTraceLog/目录下记录全部 API 请求日志,正式发布建议关闭。Cache_Redis_Configuration:Redis 连接字符串。默认值#{Cache_Redis_Configuration}#是 Azure DevOps 占位符格式,未修改时不启用 Redis。启用示例:localhost:6379(无密码)或localhost:6379,password=senparc,connectTimeout=1000,connectRetry=2,syncTimeout=10000,defaultDatabase=3。Cache_Memcached_Configuration:Memcached 连接字符串,规则同上,默认占位符时不启用。
2. SenparcWeixinSetting(微信账号配置)
"SenparcWeixinSetting": {
"IsDebug": true,
"Token": "#{Token}#",
"EncodingAESKey": "#{EncodingAESKey}#",
"WeixinAppId": "#{WeixinAppId}#",
"WeixinAppSecret": "#{WeixinAppSecret}#",
"WxOpenAppId": "#{WxOpenAppId}#",
"WxOpenAppSecret": "#{WxOpenAppSecret}#",
"WxOpenToken": "#{WxOpenToken}#",
"WxOpenEncodingAESKey": "#{WxOpenEncodingAESKey}#",
"WeixinCorpId": "#{WeixinCorpId}#",
"WeixinCorpAgentId": "#{WeixinCorpAgentId}#",
"WeixinCorpSecret": "#{WeixinCorpSecret}#",
"WeixinCorpToken": "#{WeixinCorpToken}#",
"WeixinCorpEncodingAESKey": "#{WeixinCorpEncodingAESKey}#",
"TenPayV3_MchId": "#{TenPayV3_MchId}#",
"TenPayV3_Key": "#{TenPayV3_Key}#",
"TenPayV3_CertPath": "#{TenPayV3_CertPath}#",
"TenPayV3_CertSecret": "#{TenPayV3_CertSecret}#",
"TenPayV3_PrivateKey": "#{TenPayV3_PrivateKey}#",
"TenPayV3_SerialNumber": "#{TenPayV3_SerialNumber}#",
"TenPayV3_ApiV3Key": "#{TenPayV3_APIv3Key}#",
"EncryptionType": "#{EncryptionType}#",
"Component_Appid": "#{Component_Appid}#",
"Component_Secret": "#{Component_Secret}#",
"Component_Token": "#{Component_Token}#",
"Component_EncodingAESKey": "#{Component_EncodingAESKey}#"
}
关键参数说明:
- 公众号:
Token、EncodingAESKey、WeixinAppId、WeixinAppSecret对应公众平台后台的接口配置信息,Token 必须与后台完全一致(区分大小写)。 - 小程序:
WxOpenAppId/WxOpenAppSecret/WxOpenToken/WxOpenEncodingAESKey。 - 企业微信:
WeixinCorpId、WeixinCorpAgentId(应用 AgentId)、WeixinCorpSecret、WeixinCorpToken、WeixinCorpEncodingAESKey。 - 微信支付 V3:
TenPayV3_MchId(商户号)、TenPayV3_Key、TenPayV3_CertPath(证书路径,支持物理路径如D:\cert\apiclient_cert.p12或受保护目录下的相对路径如~/App_Data/cert/...)、TenPayV3_CertSecret(证书密码)、TenPayV3_PrivateKey(私钥明文或 pem 文件路径)、TenPayV3_SerialNumber(证书序列号)、TenPayV3_ApiV3Key(APIv3 密钥)、TenPayV3_TenpayNotify(支付回调地址)。EncryptionType必填,为 RSA 或 SM(SM2),需根据商户平台申请证书时的类型选择,大部分情况为 RSA。 - 开放平台:
Component_Appid、Component_Secret、Component_Token、Component_EncodingAESKey。
3. 多账号注册:Items 节点
Items 节点下可以添加任意多个、任意模块、任意组合的账号,每个条目的字段格式与上一级节点对应,key 不能重复。配置文件内置了"第二个公众号""第三个公众号""第二个小程序""企业微信审批"等多个示例组。例如:
"Items": {
"第二个小程序": {
"WxOpenAppId": "#{WxOpenAppId2}#",
"WxOpenAppSecret": "#{WxOpenAppSecret2}#",
"WxOpenToken": "#{WxOpenToken2}#",
"WxOpenEncodingAESKey": "#{WxOpenEncodingAESKey2}#"
}
}
4. SenparcAiSetting(可选 AI 能力)
示例还集成了 Senparc.AI,支持 AzureOpenAI、OpenAI、NeuChar 等多种平台,通过 AiPlatform 枚举选择(如 "AiPlatform": "AzureOpenAI"),并可在 Items 下注册额外的模型组合(如 AzureDalle3 图像生成配置)。
配置值中的
#{...}#为 Azure DevOps 部署占位符。如果你有明文信息,请删除占位符符号,直接写入完整字符串,例如"Token": "MyFullToken"。
五、启动与注册流程:Program.cs 与 Startup.cs
1. 入口:Program.cs
Program.cs 使用标准的 Generic Host 创建 Web 主机,关键在于通过 UseServiceProviderFactory(new SenparcServiceProviderFactory()) 注入 Senparc 自定义的依赖注入工厂,这是 SDK 注册的基础:
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
}).UseServiceProviderFactory(new SenparcServiceProviderFactory());
2. 服务注册:ConfigureServices
Startup.cs 的 ConfigureServices() 完成了核心注册:
services.AddSession():使用 Session(必须在配置 Mvc 之前)。AddControllersWithViews().AddNewtonsoftJson():MVC 视图 + NewtonsoftJson 序列化支持。services.AddMemoryCache():本地缓存(内存缓存必加)。services.AddSignalR():WebSocket 实时通信。services.AddSenparcWeixin(Configuration, Env):Senparc.Weixin 注册(必须),随后通过.AddSenparcWebSocket<CustomNetCoreWebSocketMessageHandler>()注册 WebSocket,.AddSenparcAI(Configuration)注册 AI 能力(可选)。- 部署在 IIS 时需启用
services.Configure<IISServerOptions>(options => options.AllowSynchronousIO = true);部署在 Linux 时对应配置KestrelServerOptions(源码中已给出注释示例)。
3. 管道配置:Configure
Configure() 中展示了完整的中间件编排顺序,其注册顺序具有强参考价值:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance); // 启用 GB2312(按需)
app.UseEnableRequestRewind();
app.UseSession();
app.UseSenparcGlobal(env, senparcSetting.Value, globalRegister => { /* 缓存、日志、APM 配置 */ })
.UseSenparcWeixin(senparcWeixinSetting.Value, (weixinRegister, weixinSetting) => { /* 微信账号注册 */ });
app.UseAuthorization();
app.UseEndpoints(endpoints => { ... });
其中 UseSenparcGlobal() 内的 globalRegister 回调负责:
- 全局缓存配置:
ChangeDefaultCacheNamespace()设置缓存命名空间(多网站共用同一分布式缓存时的隔离手段);按需注册 CsRedis(UseKeyValueRedisNow()键值对策略,推荐)或 Memcached(UseMemcachedNow())。 - TraceLog 注册:
RegisterTraceLog(ConfigTraceLog),其中ConfigTraceLog()演示了SenparcTrace.SendCustomLog、SenparcTrace.OnLogFunc、WeixinTrace.OnWeixinExceptionFunc(异常时发送模板消息给管理员)等日志回调。
UseSenparcWeixin() 内的 weixinRegister 回调则负责微信账号注册,建议按以下顺序执行,尤其须将缓存放在第一位:
- 微信缓存:
UseSenparcWeixinCacheCsRedis()(与 StackExchange.Redis 两选一)、UseSenparcWeixinCacheMemcached()。注意:使用非本地缓存却不注册,会收到"当前扩展缓存策略没有进行注册"的异常。 - 公众号/小程序:
RegisterMpAccount(...)、RegisterWxOpenAccount(senparcWeixinSetting.Value, "【盛派网络小助手】小程序"),并演示了使用Items["第二个小程序"]注册第二个账号。 - 企业微信:
RegisterWorkAccount(senparcWeixinSetting.Value, "【盛派网络】企业微信")、RegisterWorkAccount(senparcWeixinSetting.Value["企业微信审批"], ...)。 - 微信支付:
RegisterTenpayOld(...)(V2)、RegisterTenpayV3(...)、RegisterTenpayApiV3(...)(最新的 APIv3)。 - 开放平台:
RegisterOpenComponent(...),并给出三个委托实现——getComponentVerifyTicketFunc(从App_Data/OpenTicket读取 component_verify_ticket)、getAuthorizerRefreshTokenFunc(从App_Data/AuthorizerInfo读取授权方 refresh_token)、authorizerTokenRefreshedFunc(token 刷新后回写本地文件)。源码注释明确提示:本地文件存储仅方便演示,分布式系统请使用其他存储方式。
六、公众号消息接入的两种方式
方式一:MessageHandler 中间件(推荐)
Startup.cs 中使用 app.UseMessageHandlerForMp("/WeixinAsync", ...) 直接挂载公众号消息处理器,无需单独创建 Controller。其 options 演示了完整配置项:
app.UseMessageHandlerForMp("/WeixinAsync", CustomMessageHandler.GenerateMessageHandler, options =>
{
options.AccountSettingFunc = context => senparcWeixinSetting.Value; // [必须] 动态指定账号配置
options.DefaultMessageHandlerAsyncEvent = DefaultMessageHandlerAsyncEvent.SelfSynicMethod; // [可选] 未重写异步方法时调用同步方法
options.EnableRequestLog = true; // [可选] 请求日志,默认为 true
options.EnbleResponseLog = true; // [可选] 回复日志,默认为 true
options.AggregateExceptionCatch = ex => { /* 异常处理 */ return false; };
options.TextResponseLimitOptions = new TextResponseLimitOptions(2048, senparcWeixinSetting.Value.WeixinAppId); // 超长文本自动走客服接口分批次回复
});
中间件同样支持小程序与企业微信:UseMessageHandlerForWxOpen("/WxOpenAsync", ...) 与 UseMessageHandlerForWork("/WorkAsync", ...)。中间件还支持多账号:通过 URL 参数(如 /Weixin?id=1),在 AccountSettingFunc 中从 context.Request 读取参数并返回对应的 SenparcWeixinSetting。
方式二:传统 Controller(精细控制)
WeixinController.cs 展示了有特殊自定义需求时的消息处理方案,可高度控制处理过程的每个细节。其 Get(微信后台验证)方法核心逻辑为:
[HttpGet]
[ActionName("Index")]
public ActionResult Get(PostModel postModel, string echostr)
{
if (CheckSignature.Check(postModel.Signature, postModel.Timestamp, postModel.Nonce, Token))
{
return Content(echostr); // 返回随机字符串则表示验证通过
}
...
}
Controller 从 Config.SenparcWeixinSetting.MpSetting 读取 Token、EncodingAESKey、WeixinAppId(与公众平台后台保持一致,区分大小写),Post 方法则通过 messageHandler.ExecuteAsync() 处理用户消息(SDK 已全面转向异步方法驱动,不再推荐同步方法)。
七、其他运行框架的对应 Demo
如果你的运行环境并非 .NET 8.0,仓库在同一目录族下提供了其他版本的示例:
- .NET 10.0 Demo(推荐):net10-mvc/Senparc.Weixin.Sample.Net10,与当前 .NET 8 示例结构基本一致,面向最新 .NET 版本。
- .NET Framework 4.5 Demo:net45-mvc/Senparc.Weixin.MP.Sample。注意:.NET Framework 4.5 版示例已于 2019 年 9 月 1 日起停止小版本更新,但大版本更新仍保持同步,且 .NET 4.5 所有库的更新不受影响。
此外,Samples/MP 目录下还提供了仅包含公众号模块的精简示例(Senparc.Weixin.Sample.MP 与 Senparc.Weixin.Sample.MP.Simple),适合作为最小可运行模板快速上手。
八、部署与调试建议
- 首次运行:确保本机安装了 .NET 8.0 SDK(建议配合 VS 2022+),克隆仓库后直接打开解决方案编译。若因条件编译报错,请检查是否已安装 .NET Framework 4.6.2 开发包。
- 接入真实账号:将
appsettings.json中对应模块的#{...}#占位符替换为真实参数(Token、AppId、AppSecret 等),并在微信公众平台/小程序后台将服务器 URL 指向本示例对应路由(如/WeixinAsync或/Weixin)。 - 分布式缓存:生产环境建议配置
Cache_Redis_Configuration启用 Redis,并通过ChangeDefaultCacheNamespace设置命名空间;本地联调可直接使用默认内存缓存。 - 日志与异常:开发阶段保持
IsDebug = true以记录完整 API 请求日志;正式发布前关闭 Debug,并利用WeixinTrace.OnWeixinExceptionFunc接入异常告警(如模板消息通知管理员)。 - 学习路径:先对照 Samples/All/net8-mvc/readme.md 理解项目全貌,再按模块逐个阅读
Controllers/Weixin/下的分模块代码,配合 Samples/All/Senparc.Weixin.Sample.CommonService 中的消息处理器(CustomMessageHandler 等)与 src 目录下的 SDK 源码理解底层实现。
本示例覆盖了 SDK 从服务注册、账号配置、消息路由到缓存、日志、支付的完整接入链路,是学习 Senparc.Weixin 在 .NET 8.0 下综合集成的首选参考,也是将公众号、小程序、企业微信、微信支付与开放平台组合进同一系统的落地范本。