Skip to content

Latest commit

 

History

History
675 lines (508 loc) · 36.1 KB

readme.en.md

File metadata and controls

675 lines (508 loc) · 36.1 KB
Raw

Senparc.Weixin SDK

Senparc.Weixin —— Wechat .NET SDK

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

[中文]

Wechat is the most famous IM APP in China which has more than 1 billion active users and more than ten million Official Accounts.

By using Senparc.Weixin SDK, you can develop all wechat platform applications, including Official Account, Mini Programm, Mini Game, Enterprise Account, Open Platform, Wechat Pay, JS-SDK, Wechat IoT/Bluetooth, etc.

Now, Senparc.Weixin has been supported almost all of the API for Wechat's all modules. It supports mutipule .Net targets .NET 3.5 / 4.0 / 4.5 / .NET Standard 2.0 / .NET Core 2.2 / .NET Core 3.0.

Senparc.Weixin SDK is the most widly used .NET Wechat SDK. Also it is one of the most popular .NET open source project in China.

For more than seven years, we have been keeping the project constantly updated, share the complete source code and design ideas without reservation. Hopefully more people will benefit from it, understand and disseminate the spirit of open source. Grateful to the friends who helped us along the way!

If you like and hope us to continue to optimize this project, please give us a Star:)

Notice

🍦 file.api.weixin.qq.com Domain name officially disabled(2020.0.15), please update to the latest version!
🏆 《2019-2020 Outstanding Contributors of Senparc Developer Community Shortlist》 has been published. Please check and register the information before 30/6/2020 10:24 AM 😄
🥇 .NET Core 3.1 Senparc.Weixin SDK source code and Demo has been released!

Index

The library contains the source code (the Core logic is exactly the same) that includes .Net 3.5/4.0/4.5/.NET Standard 2.0/.NET Core 2.2.

SDK Modules

# Module Libraries DLL Nuget & Support .NET Versions
1 Base Library Senparc.Weixin.dll Senparc.Weixin .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
2 Official Account /
JSSDK
ect.		 Senparc.Weixin.MP.dll MP .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
3 Tencent Pay(TenPay) Senparc.Weixin.TenPay.dll TenPay .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.0
4 ASP.NET MVC Extension
.NET Framework +
Core		 Senparc.Weixin.MP.MVC.dll         MP.MVC .NET 3.5 .NET 4.0 .NET 4.5  .NET Core 2.x
5 Corporate Account Senparc.Weixin.QY.dll QY .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
6 Corporate Wechat Senparc.Weixin.Work.dll Work .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
7 Open Platform Senparc.Weixin.Open.dll Open .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
8 Redis Distributed Cache Senparc.Weixin.Cache.
Redis.dll		 Cache.Redis .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
9 Memcached
Distributed Cache		 Senparc.Weixin.Cache.
Memcached.dll		 Cache.Memcached .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
10 Mini Program
(s.p. Mini Game)
(indep. proj.)  		 Senparc.Weixin.WxOpen.dll       WxOpen  .NET 3.5    .NET 4.0 .NET 4.5 .NET Core 2.x
11 WebSocket
(indep. proj.)  		 Senparc.WebSocket.dll Senparc.WebSocket .NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x

Legend

.NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.x
.NET 3.5 .NET 4.0 .NET 4.5 .NET Core 2.0 + 2.1

Tip: .NET 3.5 .NET 4.0 last stable release click here, since May 1, 2019 to stop updating.

Functional Support

  • Supported all Wechat 7.x APIs, includes customize menu / personalized menu, template message, material APIs, group message, multi-customer service, TenPay, MerChant, cards APIs, ect.
  • Supported Wechat Official Account, MiniProgram, MiniProgram-Game, Enterpaise Account, Open Platform modules.
  • Supported user dialogue context, to solve application service can not use Session to handle users' dialogues.
  • Fully supported latest APIs for Wechat Official Account, Corporate Account(Corporate Wechat), Open Platform.
  • Supported Distributed Cache Strategy with high scalability.

All updates will ensure downward compatibility unless otherwise specified. So you can cover new DLLs directly or use Nuget to manage packages(highly recommend).

Personalize your WeChat project Sample

  1. Web version：view course。

WeChatSampleBuilder

  1. Desktop App: Login https://weixin.senparc.com/User to download WeChatSampleBuilder tool, and view description。

WeChatSampleBuilder

Notice: using the WeChatSampleBuilder tool simply makes it easier for you to test and learn the Sample code, not to generate a complete production environment project. If you need to build a production environment project, refer to the full Demo or other tutorials. It is recommended to use an existing system framework, such as SenparcCoreFramework.

resources

  1. Senparc.Weixin SDK Official Site: https://weixin.senparc.com/
  2. Online Demo Site：https://sdk.weixin.senparc.com/
  3. Blog tutorial: https://www.cnblogs.com/szw/archive/2013/05/14/weixin-course-index.html
  4. WeChat technology exchange community: https://weixin.senparc.com/QA
  5. Online editing tool for Customize menu: https://sdk.weixin.senparc.com/Menu
  6. Online test tool for Messages: https://sdk.weixin.senparc.com/SimulateTool
  7. Online test tool for Cache：https://sdk.weixin.senparc.com/Cache/Test
  8. chm documentation download：https://sdk.weixin.senparc.com/Document
  9. Source code and the latest updates : https://github.com/JeffreySu/WeiXinMPSDK
  10. WeChat development resources: https://github.com/JeffreySu/WeixinResource
  11. Depth Analysis of WeChat Development reading system：https://book.weixin.senparc.com
  12. Buy Depth Analysis of WeChat Development：https://item.jd.com/12220004.html
  13. Video Course：https://github.com/JeffreySu/WechatVideoCourse
  • Technical communication QQ group:

14th Group(Video Course Student Group)：588231256
15th Group(Official Account): 289181996
10th Group(Distributed Cache): 246860933
12th Group(Mini Program): 108830388
16h Group(Open Platform): 860626938
the following groups are full:
1st group：300313885(full)，2nd group：293958349(full)，3rd group：342319110(full)
4th group：372212092(full)，5th group: 377815480(full)，6th group：425898825(full)
7th group：482942254(full)，8th group：106230270(full)，9th group：539061281(full)
11th group：553198593(full)，13th group: 183424136(full)

  • Business contact QQ：498977166

If this project is useful to you, we welcome any form of donations from all parties, including participation in project code updates or feedback. Thank you!

donate: Enter

Senparc official tutorials

By Jeffrey Su and Senparc team took 2 years to complete the development of WeChat book have been published, the book's full name is: Depth Analysis of WeChat Development: the efficient development of the Official Account and Mini Program, the auxiliary reading system has been on the line: BookHelper。
Welcome to buy genuine books:【Buy】
The branch of code snapshot for the book published version BookVersion1。

Follow Demo Official Account(SenparcRobot)：

Senparc Helper Official Account Senparc Helper Mini-Program BookHelper

Develop with .net Core

Current branch including .NET Framework 4.5 / 4.6.1 及 .NET Core 2.0 / 2.1 full version codes.
.NET Framework 4.5 Demo under /src/Senparc.Weixin.MP.Sample directory,
.NET Core 2.0 Demo under /src/Senparc.Weixin.MP.Sample.vs2017 directory.
Attention: the source code of the Senparc.Weixin SDK library referenced by the above two Demo is exactly the same, it will automatically select the output version according to the conditions when compiling and running.

All of the following introduction use the example of the .NET Framework 4.5.

Contribute Code

If you need to use or modify the program source code, recommended to Fork. We also welcome you to modify the generic version of Pull Request.

  1. Fork
  2. Create your own branch (git checkout -b my-new-feature)
  3. Submit your changes (git commit -am'Added some feature')
  4. Submit modify records to a remote warehouse (git push origin git my-new-feature)
  5. And then go to the my-new-feature branch of the git on GitHub site, launch Pull Request (Please refer to Developer branch, not directly submitted to the master branch)

Project folder description (under src folder)

Folder Description
Senparc.WebSocket WebSocket Module
Senparc.Weixin.Cache Senparc.Weixin.Cache.Memcached.dll 、 Senparc.Weixin.Cache.Redis.dll Distributed Cache extension solutions
Senparc.Weixin.MP.BuildOutPut DLLs output folder
Senparc.Weixin.MP.MvcExtension Senparc.Weixin.MP.MvcExtension.dll source code, extension for ASP.NET MVC
Senparc.Weixin.MP Senparc.Weixin.MP, Official Account SDK source code
Senparc.Weixin.Open Senparc.Weixin.Open.dll, 3rd Open Platform SDK source code
Senparc.Weixin.QY Senparc.Weixin.QY.dll, Corporate Account SDK source code
Senparc.Weixin.Work Senparc.Weixin.Work.dll Corporate Wechat SDk source code
Senparc.Weixin.WxOpen Senparc.Weixin.WxOpen.dll Mini Program SDK source code. Include Mini Game.
Senparc.Weixin all Senparc.Weixin.[x].dll base library source code

Demo folder description (under Samples folder)

Folder Description SDK Library Reference
Senparc.Weixin.MP.Sample Demo, can be released directly(.NET Framework 4.5 + ASP.NET MVC) Nuget Packages
Senparc.Weixin.MP.Sample.WebForms Demo, can be released directly(.NET Framework 4.5 + ASP.NET WebForms) Nuget Packages
Senparc.Weixin.MP.Sample.vs2019 Demo, can be released directly(.NET Core 2.0 + MVC) Source Code
Senparc.Weixin.MP.Sample.Consoles.vs2019 Console Demo（.NET Core） Source Code

Senparc.Weixin.MP.Sample Key Code

Note: This is MVC projct, you can learn corresponding file in WebForm project.

/Controllers/WeixinController.cs

The following Token needs to be synchronized with the Token synchronization in the background Settings of the WeChat Official Account Site(https://mp.weixin.qq.com). You can set the Token string in database or config file like Web.cofing. It's strongly recommend to use complex string, because the request is easy to forge while the Token is cracked.

public readonly string Token = "weixin";

The following Action (Get) is used to receive and return the validation results of the WeChat background Url without any changes. Address such as http://domain/Weixin or http://domain/Weixin/Index

/// <summary>
/// WeChat background validation Url (Get request), such as 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) + "。" +
            "If you see this message in browser, that means this url address can be used in Wechat Official Account background setting for validation Url. Please note that the Token is consistent.");
    }
}

In above methods, PostModel is an entity including Signature, Timestamp, Nonce (by WeChat server via the incoming request Url parameter), AppId and Token, EncodingAESKey and a series of internal sensitive information (need to pass it in) entity class. PostModel also used in the rear.

The following Action (Post) used to receive Post request from WeChat server (usually initiated by the user), if necessary, here before you Get only provide WeChat background save Url validation, every Post must revalidate, otherwise it's easy to forge the request.

/// <summary>
/// After the user sends the message, the WeChat platform automatically posts a request to this place and waits for the response XML
/// </summary>
[HttpPost]
[ActionName("Index")]
public ActionResult Post(PostModel postModel)
{
    if (!CheckSignature.Check(postModel.Signature, postModel.Timestamp, postModel.Nonce, Token))
    {
        return Content("Parameter error!");
    }
    ...
}

How to handle WeChat Official Account request?

Senparc.Weixin.MP provides two ways to process requests, traditional methos and MessageHandler (recommended).

The above two methods have been described in more detail in the wiki, which is a simple example of the MessageHandler method.

The MessageHandler process is very simple:

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

    postModel.Token = Token;
    postModel.EncodingAESKey = EncodingAESKey;//Be consistent with your Settings in the background
    postModel.AppId = AppId;//Be consistent with your Settings in the background


    var messageHandler = new CustomMessageHandler(Request.InputStream, postModel);//Receive messages (first step)

    messageHandler.Execute();//Processing (step 2)

    return new FixWeixinBugWeixinResult(messageHandler);//Return (step 3)
}

In addition to the postModel assignment, the receipt (step 1), processing (step 2), and return (step 3) will only need one line of code.

CustomMessageHandler in the code above is a custom class that inherits from Senparc.Weixin.MP.MessageHandler.cs. MessageHandler is an abstract class that contains the request perform a variety of different types of abstract methods (such as text, voice, location, pictures, etc.), we only need to create your own CustomMessageHandler in each of these methods is implemented.The newly built CustomMessageHandler.cs is as follows:

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 can also be other types like News
            var responseMessage = CreateResponseMessage<ResponseMessageText>();
            responseMessage.Content = "This message is from DefaultResponseMessage。";
            return responseMessage;
        }

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

        public override IResponseMessageBase OnVoiceRequest(RequestMessageVoice requestMessage)
        {
            //...
        }
        
        //More OnXX methods that are not overridden will return the result in DefaultResponseMessage by default.
        ....
    }
}

OnTextRequest and OnVoiceRequest correspond to different request types, such as receiving text and voice.

For example, we need to respond to text type requests, just perfect the OnTextRequest method:

      public override IResponseMessageBase OnTextRequest(RequestMessageText requestMessage)
      {
          //TODO: the logic can be dealt with to the Service details, reference OnLocationRequest method or /Service/LocationSercice.cs
          var responseMessage = CreateResponseMessage<ResponseMessageText>();
          responseMessage.Content = string.Format("You just sent the message：{0}", requestMessage.Content);
          return responseMessage;
      }

In this way, when the CustomMessageHandler executes the Messagehandler.execute(), it will automatically call the above code and return the ResponseMessage in the code to return the information if it finds that the type of the request information is Text. ResponseMessage can be any type under the IResponseMessageBase interface (including text, news, multimedia, etc.).

Starting with v0.4.0, the MessageHandler adds support for user Session context, which can be used to resolve defects on the server that can't use Session to manage user sessions. Details：User context WeixinContext and MessageContext

Use Nuget to install the project

How to handle WeChat Official Account?

PM> Install-Package Senparc.Weixin.MP

How to handle WeChat Mini Program (include Mini Game)?

Senparc.Weixin.WxOpen encapsulates the message and API of WeChat mini programs, keeping the development process of the Official Account request consistent. This module also support Mini Game.

PM> Install-Package Senparc.Weixin.WxOpen

How to enhance the functionality of ASP.NET MVC Project?

Senparc.Weixin.MP.MVC has done more optimization for ASP.NET MVC project, including convenient browser environment judgment, official bug fix, etc.

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

How to handle WeChat Corporate Account?

Senparc.Weixin.QY.dll for Corporate Account encapsulation were conducted for the relevant functions, operation process remain the same with WeChat Official Account SDK (Senparc.Weixin.MP) .

PM> Install-Package Senparc.Weixin.QY

Note: QY has been stopped updating with the WeChat Corporate Account and has been seamlessly ported to Work (Corporate WeChat).

How to handle Corporate Wechat?

Senparc.Weixin.Work.dll for Corporate Wechat encapsulation were conducted for the relevant functions, operation process remain the same with WeChat Official Account SDK (Senparc.Weixin.MP) and WeChat Corporate Account (Senparc.Weixin.QY.dll).

PM> Install-Package Senparc.Weixin.Work

How to handle Wechat Open Platform?

Senparc.Weixin.Open.dll is encapsulatied all Open Platform APIs , message operation process remain the same with WeChat Official Account SDK (Senparc.Weixin.MP), some other special message process please read the official document, then compares Demo in the Senparc.Weixin.MP.Sample project.

PM> Install-Package Senparc.Weixin.Open

How to use distributed cache?

Senparc. Weixin SDK provides the perfect caching policy interface, use the default native cache implementation, it also provides a Redis and Memcached expansion plans, you can also add your own caching strategies according to the same rules.

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

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

How to develop Mini Program?

The back-end architecture of the mini program is highly consistent with the Official Account, Only use the Nuget installationSenparc.Weixin.WxOpen to start your Mini Program develop.

Senparc.Weixin.WxOpen currently contains all the information processing, AccessToken management, template message, QR code generation, etc.

Welcome developers to Pull Request for modules that are not completed or need to be added.

Branch Description

 Branch       Description        
master   Officially published main branch, usually this branch is stable, can be used in production environment.
Developer 1, development branch, the branch for the Beta version, usually we submit the new version to this branch first, the stable version will push to the master branch. If you want to sneak peek in new function, you can use this branch.
2, this branch is compatible with the.net 4.5 /.net core /.net core 2.0 version, and it is recommended that Pull Request to this branch, not master

| BookVersion1 | this branch is code snapshot for book Depth Analysis of WeChat Development . | DotNET-Core_MySQL | this branch shows the integration with Pomelo.EntityFrameworkCore.MySql in .NET Core environment. | NET4.0     | Support for .Net 4.0 only, this branch has stopped updating in 2017. The latest code of .Net 4.0 is updated with the master/Developer branch

| NET3.5     | Support for.Net 3.5 only, which stopped updating in 2015. The latest code is updated with the master/Developer branch | Developer-Senparc.SDK | This branch is used only for the Senparc team internal test, you can ignore this one.

Thanks for Contributors

Thanks to the developers who have contributed to this project, you have not only perfected this project, but also made a contribution to Open Source Enterprise. Thank you! Click Here to see the list.

Donate

If this project is useful to you, we welcome any form of contributions, including participation in project code updates or feedback.Thank you!

Donate:

donate

Stargazers over time

Stargazers over time

License

Apache License Version 2.0

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