基于 .NET 8.0 的 Senparc.Weixin 全平台综合示例:net8-mvc Sample 项目结构与部署指南

原创2026-09-24 13:35:211,412 阅读
文章标签:后端即时通讯API设计

基于 .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 承担着双重角色:

  1. 可部署的综合示例:它提供了 .NET 8.0 的 Mvc 项目示例,可以直接进行部署测试。开箱即可运行基础功能,高级功能测试则需要修改配置文件(如修改 appId、Token、Secret 等真实微信账号信息)。
  2. 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),适合作为最小可运行模板快速上手。

八、部署与调试建议

  1. 首次运行:确保本机安装了 .NET 8.0 SDK(建议配合 VS 2022+),克隆仓库后直接打开解决方案编译。若因条件编译报错,请检查是否已安装 .NET Framework 4.6.2 开发包。
  2. 接入真实账号:将 appsettings.json 中对应模块的 #{...}# 占位符替换为真实参数(Token、AppId、AppSecret 等),并在微信公众平台/小程序后台将服务器 URL 指向本示例对应路由(如 /WeixinAsync 或 /Weixin)。
  3. 分布式缓存:生产环境建议配置 Cache_Redis_Configuration 启用 Redis,并通过 ChangeDefaultCacheNamespace 设置命名空间;本地联调可直接使用默认内存缓存。
  4. 日志与异常:开发阶段保持 IsDebug = true 以记录完整 API 请求日志;正式发布前关闭 Debug,并利用 WeixinTrace.OnWeixinExceptionFunc 接入异常告警(如模板消息通知管理员)。
  5. 学习路径:先对照 Samples/All/net8-mvc/readme.md 理解项目全貌,再按模块逐个阅读 Controllers/Weixin/ 下的分模块代码,配合 Samples/All/Senparc.Weixin.Sample.CommonService 中的消息处理器(CustomMessageHandler 等)与 src 目录下的 SDK 源码理解底层实现。

本示例覆盖了 SDK 从服务注册、账号配置、消息路由到缓存、日志、支付的完整接入链路,是学习 Senparc.Weixin 在 .NET 8.0 下综合集成的首选参考,也是将公众号、小程序、企业微信、微信支付与开放平台组合进同一系统的落地范本。

登录后查看全文
WeiXinMPSDK