PageCard/WeiXinMPSDK

微信公众平台SDK Senparc.Weixin for C#，支持.NET Framework及.NET Core。已支持微信公众号、小程序、小游戏、企业号、企业微信、开放平台、微信支付、JSSDK、微信周边等全平台。 WeChat SDK for C#.

Senparc.Weixin —— 微信 .NET SDK

[English Version]

使用 Senparc.Weixin，您可以方便快速地开发微信全平台的应用（包括微信公众号、小程序、企业号、开放平台、微信支付，等等）。

目前 Senparc.Weixin 已经支持几乎所有微信平台模块和接口，并同时支持 .NET 3.5 / 4.0 / 4.5 / .NET Core 2.0 / .NET Core 2.1 多种框架。

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

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

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

公告

为更好地带动和帮助广大开发者向 .net core 转型，本项目的 .net core Sample 正在完善中（演示功能将和 .net 4.5 的 Sample 同步），尽请关注，欢迎交流！

下文索引

• 各模块类库
• 资源
• 📖 Senparc 官方图书教程
• 💻 Senparc 官方视频教程
• 贡献代码
• 如何使用.net core开发
• 关注测试账号（SenparcRobot）
• 项目文件夹说明（src文件夹下）
• Demo 文件夹说明（Samples文件夹下）
• Senparc.Weixin.MP.Sample中的关键代码说明
  • /Controllers/WeixinController.cs
• 使用Nuget安装到项目中
  • 如何处理微信公众号请求？
  • 如何处理微信小程序（小游戏）请求？
  • 如何增强 ASP.NET MVC 项目的功能？
  • 如何处理微信企业号请求？
  • 如何处理企业微信请求？
  • 如何处理微信开放平台请求？
  • 如何使用分布式缓存？
• 如何开发小程序
• 各分支说明
• 感谢贡献者
• 捐助
• License

本库为包含了 .NET 3.5/4.0/4.5/.NET Core 2.0/2.1 多个版本的源代码（核心逻辑完全一致）：

• 使用 Visual Studio 2017 打开 Demo（支持所有版本）：Senparc.Weixin.MP.Sample.vs2017.sln
• 使用其他版本 Visual Studio 打开 Demo（仅支持 .NET 4.5）：Senparc.Weixin.MP.Sample.sln
• 使用 Visual Studio 2010 SP1 打开 Demo（仅支持 .NET 4.5）：Senparc.Weixin.MP.Sample.vs2010sp1.sln

各模块类库

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

.NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.0

• 已经支持所有微信6 API，包括自定义菜单/个性化菜单、模板信息接口、素材上传接口、群发接口、多客服接口、支付接口、微小店接口、卡券接口等等。
• 已经支持用户会话上下文（解决服务器无法使用Session处理用户信息的问题）。
• 已经全面支持微信公众号、企业号、开放平台的最新API。
• 已经支持分布式缓存及缓存策略扩展。

目前官方的API都已完美集成，除非有特殊说明，所有升级都会尽量确保向下兼容，所以已经发布的版本请放心使用或直接升级（覆盖）最新的DLLs，建议使用 Nuget 进行更新。

资源

1. 官网地址：http://weixin.senparc.com/
2. Demo 地址：http://sdk.weixin.senparc.com/
3. 微信开发系列教程：http://www.cnblogs.com/szw/p/weixin-course-index.html
4. 微信技术交流社区：http://weixin.senparc.com/QA
5. 自定义菜单在线编辑工具：http://sdk.weixin.senparc.com/Menu
6. 在线消息测试工具：http://sdk.weixin.senparc.com/SimulateTool
7. 缓存测试工具：http://sdk.weixin.senparc.com/Cache/Test
8. chm帮助文档下载：http://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群：

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

• 业务联系QQ：498977166

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

资金捐助：进入

Senparc 官方图书教程

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

Senparc 官方视频教程

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

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

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

关注测试账号（SenparcRobot）：

如何使用.NET Core开发

当前分支包含了 .NET Framework 3.5 / 4.0 / 4.5 / 4.6.1 及 .NET Core 1.1 / 2.0 的全版本代码。
其中 .NET Framework 4.5 的 Demo 位于 /src/Senparc.Weixin.MP.Sample 目录下，
.NET Core 2.0 的 Demo 位于 /src/Senparc.Weixin.MP.Sample.vs2017 目录下。
注意：以上两个 Demo 所引用的 Senparc.Weixin SDK 库源代码是完全一致的，只是在编译运行的时候会根据条件自动选择输出版本。

以下所有介绍以 .NET Framework 版本为例。

贡献代码

如果需要使用或修改此项目的源代码，建议先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 分支）

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

文件夹	说明
Senparc.WebSocket	WebSocket 模块
Senparc.Weixin.Cache	Senparc.Weixin.Cache.Memcached.dll 、 Senparc.Weixin.Cache.Redis.dll 等分布式缓存扩展方案
Senparc.Weixin.MP.BuildOutPut	所有最新版本DLL发布文件夹
Senparc.Weixin.MP.MvcExtension	Senparc.Weixin.MP.MvcExtension.dll源码，为 MVC 项目提供的扩展包
Senparc.Weixin.MP	Senparc.Weixin.MP.dll 微信公众账号SDK源代码
Senparc.Weixin.Open	Senparc.Weixin.Open.dll 第三方开放平台SDK源代码
Senparc.Weixin.QY	Senparc.Weixin.QY.dll 微信企业号SDK源代码
Senparc.Weixin.Work	Senparc.Weixin.Work.dll 企业微信SDK源代码
Senparc.Weixin.WxOpen	Senparc.Weixin.WxOpen.dll 微信小程序SDK源代码，包括小游戏
Senparc.Weixin	所有Senparc.Weixin.[x].dll 基础类库源代码

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

文件夹	说明
Senparc.Weixin.MP.Sample	可以直接发布使用的Demo（.NET Framework 4.5 + ASP.NET MVC）
Senparc.Weixin.MP.Sample.WebForms	可以直接发布使用的Demo（.NET Framework 4.5 + + ASP.NET WebForms）
Senparc.Weixin.MP.Sample.vs2017	可以直接发布使用的Demo（.NET Core 2.0 + MVC）

Senparc.Weixin.MP.Sample中的关键代码说明

注：这是MVC项目，WebForms项目见对应Demo中的Weixin.aspx。

/Controllers/WeixinController.cs

下面的Token需要和微信公众平台后台设置的Token同步，如果经常更换建议写入Web.config等配置文件（实际使用过程中两列建议使用数字+英文大小写改写Token，Token一旦被破解，微信请求将很容易被伪造！）：

public readonly string Token = "weixin";

下面这个Action（Get）用于接收并返回微信后台Url的验证结果，无需改动。地址如：http://domain/Weixin或http://domain/Weixin/Index

/// <summary>
/// 微信后台验证地址（使用Get），微信后台的“接口配置信息”的Url填写如：http://weixin.senparc.com/weixin
/// </summary>
[HttpGet]
[ActionName("Index")]
public ActionResult Get(PostModel postModel, string echostr)
{
    if (CheckSignature.Check(postModel.Signature, postModel.Timestamp, postModel.Nonce, Token))
    {
        return Content(echostr); //返回随机字符串则表示验证通过
    }
    else
    {
        return Content("failed:" + postModel.Signature + "," 
            + MP.CheckSignature.GetSignature(postModel.Timestamp, postModel.Nonce, Token) + "。" +
            "如果你在浏览器中看到这句话，说明此地址可以被作为微信公众账号后台的Url，请注意保持Token一致。");
    }
}

上述方法中的PostModel是一个包括了了Signature、Timestamp、Nonce（由微信服务器通过请求时的Url参数传入），以及AppId、Token、EncodingAESKey等一系列内部敏感的信息（需要自行传入）的实体类，同时也会在后面用到。

下面这个Action（Post）用于接收来自微信服务器的Post请求（通常由用户发起），这里的if必不可少，之前的Get只提供微信后台保存Url时的验证，每次Post必须重新验证，否则很容易伪造请求。

/// <summary>
/// 用户发送消息后，微信平台自动Post一个请求到这里，并等待响应XML
/// </summary>
[HttpPost]
[ActionName("Index")]
public ActionResult Post(PostModel postModel)
{
    if (!CheckSignature.Check(postModel.Signature, postModel.Timestamp, postModel.Nonce, Token))
    {
        return Content("参数错误！");
    }
    ...
}

如何处理微信公众账号请求？

Senparc.Weixin.MP提供了2中处理请求的方式，传统方法及使用MessageHandler处理方法（推荐）。上面两个方法在wiki中已经有比较详细的说明，这里简单举例MessageHandler的处理方法。

MessageHandler的处理流程非常简单：

[HttpPost]
[ActionName("Index")]
public ActionResult Post(PostModel postModel)
{
    if (!CheckSignature.Check(postModel.Signature, postModel.Timestamp, postModel.Nonce, Token))
    {
        return Content("参数错误！");
    }

    postModel.Token = Token;
    postModel.EncodingAESKey = EncodingAESKey;//根据自己后台的设置保持一致
    postModel.AppId = AppId;//根据自己后台的设置保持一致

    var messageHandler = new CustomMessageHandler(Request.InputStream, postModel);//接收消息（第一步）

    messageHandler.Execute();//执行微信处理过程（第二步）

    return new FixWeixinBugWeixinResult(messageHandler);//返回（第三步）
}

整个消息除了postModel的赋值以外，接收（第一步）、处理（第二步）、返回（第三步）分别只需要一行代码。

上述代码中的CustomMessageHandler是一个自定义的类，继承自Senparc.Weixin.MP.MessageHandler.cs。MessageHandler是一个抽象类，包含了执行各种不同请求类型的抽象方法（如文字，语音，位置、图片等等），我们只需要在自己创建的CustomMessageHandler中逐个实现这些方法就可以了。刚建好的CustomMessageHandler.cs如下：

using System;
using System.IO;
using Senparc.Weixin.MP.MessageHandlers;
using Senparc.Weixin.MP.Entities;

namespace Senparc.Weixin.MP.Sample.CustomerMessageHandler
{
    public class CustomMessageHandler : MessageHandler<MessageContext>
    {
        public public CustomMessageHandler(Stream inputStream, PostModel postModel, int maxRecordCount = 0)
            : base(inputStream, postModel, maxRecordCount)
        {

        }

        public override IResponseMessageBase DefaultResponseMessage(IRequestMessageBase requestMessage)
        {
            //ResponseMessageText也可以是News等其他类型
            var responseMessage = CreateResponseMessage<ResponseMessageText>();
            responseMessage.Content = "这条消息来自DefaultResponseMessage。";
            return responseMessage;
        }

        public override IResponseMessageBase OnTextRequest(RequestMessageText requestMessage)
        {
            //...
        }

        public override IResponseMessageBase OnVoiceRequest(RequestMessageVoice requestMessage)
        {
            //...
        }

        //更多没有重写的OnXX方法，将默认返回DefaultResponseMessage中的结果。
        ....
    }
}

其中OnTextRequest、OnVoiceRequest等分别对应了接收文字、语音等不同的请求类型。

比如我们需要对文字类型请求做出回应，只需要完善OnTextRequest方法：

      public override IResponseMessageBase OnTextRequest(RequestMessageText requestMessage)
      {
          //TODO:这里的逻辑可以交给Service处理具体信息，参考OnLocationRequest方法或/Service/LocationSercice.cs
          var responseMessage = CreateResponseMessage<ResponseMessageText>();
          responseMessage.Content = string.Format("您刚才发送了文字信息：{0}", requestMessage.Content);
          return responseMessage;
      }

这样CustomMessageHandler在执行messageHandler.Execute()的时候，如果发现请求信息的类型是文本，会自动调用以上代码，并返回代码中的responseMessage作为返回信息。responseMessage可以是IResponseMessageBase接口下的任何类型（包括文字、新闻、多媒体等格式）。

从v0.4.0开始，MessageHandler增加了对用户会话上下文的支持，用于解决服务器上无法使用Session管理用户会话的缺陷。详见：用户上下文WeixinContext和MessageContext

使用Nuget安装到项目中

如何处理微信公众号请求？

• Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.MP

• 命令：

PM> Install-Package Senparc.Weixin.MP

如何处理微信小程序（小游戏）请求？

Senparc.Weixin.WxOpen 对微信小程序的消息、API 进行了封装，保持了公众号处理请求一致的开发过程。小程序模块同时支持小游戏。

• Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.WxOpen

• 命令：

PM> Install-Package Senparc.Weixin.WxOpen

如何增强 ASP.NET MVC 项目的功能？

Senparc.Weixin.MP.MVC 针对 ASP.NET MVC 项目做了更多的优化，包括便捷的浏览器环境判断、官方 bug 修复等。

• Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.MP.MVC

• 命令：

PM> Install-Package Senparc.Weixin.MP.MVC

如何处理微信企业号请求？

Senparc.Weixin.QY.dll对企业号相关功能进行了封装，操作过程和微信公众账号SDK（Senparc.Weixin.MP）保持了一致。

• Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.QY

• 命令：

PM> Install-Package Senparc.Weixin.QY

说明：QY目前已经随官方微信企业号同步停止更新，目前已经无缝移植到Work（企业微信）中。

如何处理企业微信请求？

Senparc.Weixin.Work.dll对企业微信相关功能进行了封装，操作过程和微信公众账号SDK（Senparc.Weixin.MP）以及企业号库（Senparc.Weixin.QY）保持了一致。

• Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.Work

• 命令：

PM> Install-Package Senparc.Weixin.Work

如何处理微信开放平台请求？

Senparc.Weixin.Open.dll对目前所有的开放平台API进行了封装，消息处理过程和微信公众账号SDK（Senparc.Weixin.MP）保持了一致，其他一些特殊的消息流程请先阅读官方的文档，然后对照Senparc.Weixin.MP.Sample中有关Open的Demo进行开发。

• Nuget 地址为https://www.nuget.org/packages/Senparc.Weixin.Open

• 命令：

PM> Install-Package Senparc.Weixin.Open

如何使用分布式缓存？

Senparc.Weixin SDK 提供了完善的缓存策略接口，默认使用本机缓存实现，同时也提供了 Redis 和 Memcached 两个扩展方案，您也可以根据相同的规则添加自己的缓存策略。

• Redis 缓存扩展包 Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.Cache.Redis
• 命令：

PM> Install-Package Senparc.Weixin.Senparc.Weixin.Cache.Redis

• Memcached 缓存扩展包 Nuget 地址：https://www.nuget.org/packages/Senparc.Weixin.Cache.Memcached
• 命令：

PM> Install-Package Senparc.Weixin.Senparc.Weixin.Cache.Memcached

如何开发小程序

小程序的后端架构和公众号保持了高度一致， 只需要使用Nuget安装Senparc.Weixin.WxOpen库即可开始使用小程序。 Senparc.Weixin.WxOpen目前包含了所有小程序需要用到的消息处理、AccessToken管理、模板消息、二维码生成等全套功能。

各分支说明

分支	说明
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 团队内部测试，可忽略。

感谢贡献者

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

捐助

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

资金捐助：

License

Apache License Version 2.0

Copyright 2018 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