Skip to content

Latest commit

 

History

History
699 lines (547 loc) · 42 KB

readme.md

File metadata and controls

699 lines (547 loc) · 42 KB
Raw

Senparc.Weixin —— 微信 .NET SDK

Build status NuGet GitHub commit activity the past week, 4 weeks, year license

[English Version]

使用 Senparc.Weixin，您可以方便快速地开发微信全平台的应用（包括微信公众号、小程序、小游戏、企业号、开放平台、微信支付、JS-SDK、微信硬件/蓝牙，等等）。本项目的 Demo 同样适合初学者进行 .NET 编程学习。

目前 Senparc.Weixin 已经支持几乎所有微信平台模块和接口，并同时支持 .NET 3.5 / 4.0 / 4.5 / .NET Standard 2.x / .NET Core 2.x / .NET Core 3.x / .NET 6.0 多种框架，同时兼容所有 MVC、Razor、WebApi、Console（命令行）、桌面应用（.exe）、Blazor、MAUI、后台服务等环境，和外部框架完全解耦。

Senparc.Weixin SDK 是目前使用率最高的微信 .NET SDK，也是国内最受欢迎的 .NET 开源项目之一。

自 2013 年起立项 9 年多来，我们一直保持着项目的持续更新，并将完整的源代码以及设计思想毫无保留地分享给大家，希望有更多的人可以从中受益，理解并传播开源的精神，一同助力中国开源事业！感恩一路上给我们提供帮助的朋友们！

如果你喜欢并希望我们继续优化这个项目，请给我们一个 ★Star ：)

公告

🔒 微信支付 V3 模块已上线！
⚡ Sample 已支持 .NET 6.0，点击这里查看！

Hello World ：用 3 句代码开启你的微信开发之旅！

说明：
下述源码位于 /Samples/MP/ 文件夹，以微信公众号为例。学会公众号就可以举一反三使用其他模块，基本用法一致（小程序、企业微信、微信支付等）。
如需查看其他模块或集成示例，可以查看位于 /Samples/ 文件夹下的其他独立 Sample，或 /Samples/All/ 文件夹下的集成 Sample（进阶）。

启动代码（只需 2 句代码）：

在 Program.cs 的 builder.Build() 上方添加配置：

builder.Services.AddSenparcWeixinServices(builder.Configuration);

对应于 Startup.cs 的 ConfigureServices() 方法内。

在 Program.cs 的 builder.Build() 下方启用配置：

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

对应于 Startup.cs 的 Configure() 方法内。

调用高级接口（只需 1 句代码）：

可在程序任意位置调用接口（以客服接口为例）：

await Senparc.Weixin.MP.AdvancedAPIs.CustomApi.SendTextAsync("AppId", "OpenId", "Hello World!");

提示：

  1. Senparc.Weixin SDK 将全生命周期自动托管 AccessToken，因此开发过程只需提供 AppId，无需操心 AccessToken 过期等问题。
  2. AppId 等注册信息可从 Senparc.Weixin.Config.SenparcWeixinSetting 中自动获取，相关参数在 appsettings.json 中配置。
  3. 以上方法也支持同步方法：Senparc.Weixin.MP.AdvancedAPIs.CustomApi.SendText() 。
  4. 所有接口命名空间均参照官方 API 路径规则定义，且参数命名方式尽量与文档保持一致（特别是返回参数），以方便开发者在源码中快速查找定位、提升测试效率、降低 bug 发生的可能性。

至此，您已经可以举一反三调用所有微信模块的接口啦！更多技能请继续往下看。

如何使用公众号消息对话能力？

公众号默认提供了对话窗口，可以发送文字、图片、语音等不同类型的信息和程序互动。

以下示例同样适用于企业微信和小程序客服消息的对话，只需两步！

第一步：创建自定义 MessageHandler 负责控制消息处理逻辑：

CustomMessageHandler.cs 
using Senparc.NeuChar.Entities;
using Senparc.Weixin.MP.Entities;
using Senparc.Weixin.MP.Entities.Request;
using Senparc.Weixin.MP.MessageContexts;
using Senparc.Weixin.MP.MessageHandlers;

namespace Senparc.Weixin.Sample.MP
{
    /// <summary>
    /// 自定义MessageHandler
    /// 把MessageHandler作为基类，重写对应请求的处理方法
    /// </summary>
    public partial class CustomMessageHandler : MessageHandler<DefaultMpMessageContext>
    {
        public CustomMessageHandler(Stream inputStream, PostModel postModel, int maxRecordCount = 0,
            bool onlyAllowEncryptMessage = false, IServiceProvider serviceProvider = null)
            : base(inputStream, postModel, maxRecordCount, onlyAllowEncryptMessage, null, serviceProvider)
        {
        }

        /// <summary>
        /// 所有未处理类型的默认消息
        /// </summary>
        /// <returns></returns>
        public override IResponseMessageBase DefaultResponseMessage(IRequestMessageBase requestMessage)
        {
            //ResponseMessageText也可以是News等其他类型
            var responseMessage = this.CreateResponseMessage<ResponseMessageText>();
            responseMessage.Content = $"你发送了一条消息，但程序没有指定处理过程";
            return responseMessage;
        }

        public override Task<IResponseMessageBase> OnImageRequestAsync(RequestMessageImage requestMessage)
        {
            //处理图片请求...
        }

        public override Task<IResponseMessageBase> OnLocationRequestAsync(RequestMessageLocation requestMessage)
        {
            //处理地理位置请求...
        }
    }
}

第二步：请求 CustomMessageHandler：

有 中间件（推荐）和 Controller（或WebApi） 两种方式请求 CustomMessageHandler。以中间件为例，在 Program.cs 中启用配置后添加代码，注册 MessageHandler：

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

此时，您已经可以使用 https://YourDomain/WeixinAsync 在微信公众号后台【设置与开发】>【基本配置】> 服务器地址(URL) 中进行配置，对应 Token 在 appsettings.json 中设置（同样适用于企业微信和小程序，请参考对应 Sample）。

此外，您还可以使用 Controller（或 WebApi） 方式可以对整个消息处理步骤进行更加细致的控制（或在 .NET Framework 中使用），点击这里查看。

更多介绍索引

本库包含了 .NET Framework/.NET Standard 2.0/.NET Core/.NET 6 多个版本的源代码（核心逻辑完全一致）：

各模块类库

# 模块功能 DLL Nuget 支持 .NET 版本
1 基础库 Senparc.Weixin.dll Senparc.Weixin
Senparc.Weixin		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
2 微信公众号 /
JSSDK / 摇周边
等等		 Senparc.Weixin.MP.dll MP
MP		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
3 微信小程序
（支持小游戏）
（独立项目）		 Senparc.Weixin.WxOpen.dll WxOpen
WxOpen		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
4 微信支付 Senparc.Weixin.TenPay.dll TenPay
TenPay		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
5 微信支付 V3 Senparc.Weixin.TenPayV3.dll TenPayV3
TenPay		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
6 ASP.NET MVC 扩展
 Senparc.Weixin.MP.MVC.dll         MP.MVC
Mvc		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
7 微信企业号 Senparc.Weixin.QY.dll QY
QY		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
9 企业微信 Senparc.Weixin.Work.dll Work
Work		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
9 微信开放平台 Senparc.Weixin.Open.dll Open
Open		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
10 Redis 分布式缓存 Senparc.Weixin.Cache.
Redis.dll		 Cache.Redis
Redis		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
11 Memcached
分布式缓存		 Senparc.Weixin.Cache.
Memcached.dll		 Cache.Memcached
MC		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0
12 WebSocket
（独立项目）  		 Senparc.WebSocket.dll Senparc.WebSocket
WebSocket		 .NET 4.5 .NET Standard 2.0/2.1 .NET Core .NET 5.0 / 6.0

图例

.NET 4.6 .NET Standard 2.x .NET Core .NET 5.0 / 6.0
.NET Framework 4.6.2 .NET Standard 2.0 / 2.1 .NET Core 2.x / 3.x .NET 5.0 / .NET 6.0

提示：

  1. 自 2019 年 5 月 1 日起，.NET Framework 3.5 及 4.0 停止更新，最后一个 .NET Framework 3.5 + 4.0 稳定版点击这里。
  2. 自 2022 年 4 月 3 日起，.NET Framework 4.5 升级为 4.6.2，最后一个 .NET Framework 4.5 的稳定版点击这里。

功能支持

  • 已经支持大部分微信 8.x API，包括微信支付、自定义菜单/个性化菜单、模板信息接口、素材上传接口、群发接口、多客服接口、支付接口、微小店接口、卡券接口、发票接口等等。
  • 已支持微信公众号、小程序、企业号、开放平台、微信支付等各个模块。
  • 已经支持用户会话上下文（解决服务器无法使用 Session 处理用户信息的问题）。
  • 已经全面支持微信公众号、小程序、企业号（企业微信）、微信支付V2/V3、开放平台的最新 API。
  • 已经支持分布式缓存及缓存策略扩展（默认支持：本地缓存、Redis、Memcached，可自由扩展），开发过程无需关心所使用缓存的类型，可在配置文件或运行过程中自由切换。

1.目前官方的 API 都已完美集成，除非有特殊说明，所有升级都会尽量确保向下兼容，所以已经发布的版本请放心使用或直接升级（覆盖）最新的 dll，建议使用 Nuget 进行更新。
2. 您也可以自行修改并编译代码，打开 Senparc.Weixin.Sample.Net6.sln 解决方案即可看到所有源码。当编译模式为 Release 时，将自动生成本地 Nuget 包（默认生成到 /src/BuildOutPut/ 文件夹下）。

源码项目文件夹说明（src文件夹下）

展开
文件夹 说明
Senparc.WebSocket WebSocket 模块
Senparc.Weixin.Cache Senparc.Weixin.Cache.Memcached.dll 、 Senparc.Weixin.Cache.Redis.dll 等分布式缓存扩展方案
Senparc.Weixin.AspNet Senparc.Weixin.AspNet.dll 专为 Web 提供支撑的类库
Senparc.Weixin.MP.MvcExtension Senparc.Weixin.MP.MvcExtension.dll源码，为 MVC 项目提供的扩展包
Senparc.Weixin.MP Senparc.Weixin.MP.dll 微信公众账号SDK源代码
Senparc.Weixin.MP.Middleware Senparc.Weixin.MP.Middleware.dll 微信公众账号消息中间件源代码
Senparc.Weixin.Open Senparc.Weixin.Open.dll 第三方开放平台SDK源代码
Senparc.Weixin.TenPay Senparc.Weixin.TenPay.dll & Senparc.Weixin.TenPayV3.dll 包含微信支付 V2 和 V3 的源代码
Senparc.Weixin.Work Senparc.Weixin.Work.dll 企业微信SDK源代码
Senparc.Weixin.Work.Middleware Senparc.Weixin.Work.Middleware.dll 企业微信消息中间件源代码
Senparc.Weixin.WxOpen Senparc.Weixin.WxOpen.dll 微信小程序SDK源代码，包括小游戏
Senparc.Weixin.WxOpen.Middleware Senparc.Weixin.WxOpen.Middleware.dll 微信小程序消息中间件源代码，包括小游戏
Senparc.Weixin 所有Senparc.Weixin.[x].dll 基础类库源代码

进入文件夹

Samples 文件夹说明（Samples文件夹下）

Senparc.Weixin SDK 所有的模块的用法都保持了高度的一致，包括配置过程、AccessToken 管理、消息处理、服务消息、接口调用，等等。您只需参考任意一个模块的用法（推荐从公众号或小程序开始），就可以举一反三使用其他模块。

从以下 Sample 中您可以了解到每个独立模块的配置和使用方式，直接打开对应文件夹下的 .sln 解决方案即可查看对应源码，运行即可看到说明文档。其中 All 文件夹中包含了更多综合和进阶功能的演示。

文件夹 说明 SDK 引用方式
MP 公众号 Nuget 包
TenPayV2 微信支付 V1 和 V2 Nuget 包
TenPayV3 微信支付 V3（TenPay APIv3） Nuget 包
Work 企业微信 Nuget 包
WxOpen 微信小程序 Nuget 包
Shared 所有 Sample 都需要用到的共享文件
All 包含微信公众号、小程序、微信支付、企业微信等所有功能的混合场景演示，
推荐用于集成多个平台的项目，或许要进行深度开发的场景参考（进阶）
┣ All/console 命令行 Console Demo（.NET Core） Nuget 包
┣ All/net45-mvc 可以直接发布使用的Demo（.NET Framework 4.5 + ASP.NET MVC） Nuget 包
┗ All/net6-mvc 可以直接发布使用的 Demo（.NET 6.0），兼容 .NET 5.0 和 .NET Core 源码

进入文件夹

资源

  1. 官网地址：https://weixin.senparc.com/
  2. 在线 Demo 地址：https://sdk.weixin.senparc.com/
  3. 微信开发系列教程：https://www.cnblogs.com/szw/p/weixin-course-index.html
  4. 微信技术交流社区：https://weixin.senparc.com/QA
  5. 自定义菜单在线编辑工具：https://sdk.weixin.senparc.com/Menu
  6. 在线消息测试工具：https://sdk.weixin.senparc.com/SimulateTool
  7. 缓存测试工具：https://sdk.weixin.senparc.com/Cache/Test
  8. chm帮助文档下载：https://sdk.weixin.senparc.com/Document
  9. 源代码及最新更新：https://github.com/JeffreySu/WeiXinMPSDK
  10. 微信开发资源集合：https://github.com/JeffreySu/WeixinResource
  11. 《微信开发深度解析》阅读辅助系统：https://book.weixin.senparc.com
  12. 购买《微信开发深度解析》：https://item.jd.com/12220004.html
  13. 《微信公众号 + 小程序快速开发》视频教程：https://github.com/JeffreySu/WechatVideoCourse
  • 技术交流QQ群：

5群（公众号）：377815480
14群（视频课程学员群）：588231256
10群（分布式缓存群）：246860933
12群（微信小程序）：108830388
16群（开放平台）：860626938
以下群已满：
1群：300313885（已满），2群：293958349（已满），3群：342319110（已满）
4群：372212092（已满），6群：425898825（已满）
7群：482942254（已满），8群：106230270（已满），9群：539061281（已满）
11群：553198593（已满），13群：183424136（开放平台，已满），15群：289181996（已满）

  • 业务联系QQ：498977166

如果这个项目对您有用，我们欢迎各方任何形式的捐助，也包括参与到项目代码更新或意见反馈中来。谢谢！

资金捐助：进入

Senparc 官方图书教程

由 Jeffrey Su 和盛派团队耗时 2 年完成的微信开发图书已经出版，书名：《微信开发深度解析：公众号、小程序高效开发秘籍》，全书配套辅助阅读系统已经上线： BookHelper。
欢迎购买正版图书：【购买正版】
图书出版时的代码版本快照见分支 BookVersion1。

Senparc 官方视频教程

为了帮助大家更直观地了解微信开发细节，同时结合《微信开发深度解析》图书进行学习，我们成立“盛派课堂”小组，开设了微信开发视频课程，帮助大家从多个维度学习微信开发以及 .NET 开发过程中的诸多技巧。
视频包含两大部分：

  1. 微信开发基础技能
  2. 公众号及小程序案例实战

共计 60 课时，配有番外篇。
目前视频已经在网易云课堂上线，课程制作精良、内容充实，被选为“A”级课程，【观看视频】，【查看课程代码及课件】。

关注测试账号体验功能（SenparcRobot）：

盛派网络小助手公众号 盛派网络小助手小程序 BookHelper

贡献代码

如果需要使用或修改此项目的源代码，建议先Fork。也欢迎将您修改的通用版本Pull Request过来。

  1. Fork
  2. 创建您的特性分支 (git checkout -b my-new-feature)
  3. 提交您的改动 (git commit -am 'Added some feature')
  4. 将您的修改记录提交到远程 git 仓库 (git push origin my-new-feature)
  5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request （请提交到 Developer 分支，不要直接提交到 master 分支）

如何使用 .NET Core 开发

当前分支包含了 .NET Framework 3.5 / 4.0 / 4.5 / 4.6.2 及 .NET Core 2.0 + 2.1 / .NET 5.0 + 6.0 的全版本代码（已经不更新的版本请查看 release 快照）。
其中 .NET Framework 的 Demo 位于 /src/Samples/All/net45-mvc 目录下，
【推荐】.NET 6.0（向下兼容 .NET 5.0 及 .NET Core 3.1 等更低版本） 的 Demo 位于 /Samples/All/net6-mvc 目录下。

注意：以上 Sample 中，net6-mvc 中的 Sample 直接引用了每个模块的源码，使用 Release 编译后可生成兼容不同版本的 Senaprc.Weixin SDK 库。

使用Nuget安装到项目中

各个模块的 Nuget 安装方式：《使用 Nuget 将 SDK 安装到项目中》

如何部署

1) 部署到 Azure App Service

App Service 是 Microsoft Azure 推出的 Web 服务，对 .NET 有很好的支持。部署步骤详见：《将微信站点部署到 Azure 中》。

2) 部署到任意服务器的 FTP

在 Web 服务器上安装 FTP 服务（推荐 FileZilla Server），直接使用 FTP 直接上传本地已经编译好的代码（本项项目 Samples 中对应的是 Senparc.Weixin.Sample.Net6 或 Senparc.Weixin.Sample.NetCore3，编译后即可直接使用，无需修改代码）。如果使用 Azure App Service 或其他云服务，通常 FTP 也都是开通的。

各重要分支说明

 分支       说明        
master   正式发布的主分支，通常这个分支比较稳定，可以用于生产环境。
Developer 1、开发分支，此分支通常为 Beta 版本，新版本都会先在此分支中进行开发，最后推送稳定版到 master 分支，如果想对新功能先睹为快，可以使用此分支。
2、此分支同时兼容 .NET 4.5 / .NET Core / .NET Core 2.0 版本，建议 Pull Request 的代码都到这个分支下，而不是 master
BookVersion1 此分支为《微信开发深度解析：微信公众号、小程序高效开发秘籍》图书出版时对应代码快照。
DotNET-Core_MySQL 此分支为 .NET Core 环境下的 Pomelo.EntityFrameworkCore.MySql 框架集成演示分支。
NET4.0     仅支持 .NET 4.0 的分支，此分支已于2017年停止更新。.NET 4.0 最新代码随 master / Developer 分支同步更新
NET3.5     仅支持 .NET 3.5 的分支，此分支已于2015年停止更新。.NET 3.5 最新代码随 master / Developer 分支同步更新
Developer-Senparc.SDK 此分支仅用于 Senparc 团队内部测试，可忽略。

感谢贡献者

感谢为此项目做出贡献的开发者，你们不光完善了这个项目，也为中国开源事业出了一份力，感谢你们！名单点击这里查看。

捐助

如果这个项目对您有用，我们欢迎各方任何形式的捐助，也包括参与到项目代码更新或意见反馈中来。谢谢！

资金捐助：

donate

Star 数量统计

starcharts stargazers over time

License

Apache License Version 2.0

Copyright 2022 Jeffrey Su & Suzhou Senparc Network Technology Co.,Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file 
except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the 
License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
either express or implied. See the License for the specific language governing permissions 
and limitations under the License.

Detail: https://github.com/JeffreySu/WeiXinMPSDK/blob/master/license.md