Senparc.Weixin —— WeChat .NET SDK

[中文]

With Senparc.Weixin, you can easily and quickly develop applications for the Wechat platform, including Wechat Official Accounts, Mini Programs, Mini Games, Enterprise Accounts, Open Platforms, Wechat Pay, JS-SDK, Wechat Hardware/Bluetooth, and more. The demo of this project is also suitable for beginners to learn .NET programming.

Currently, Senparc.Weixin supports almost all Wechat platform modules and interfaces, and supports multiple frameworks such as .NET 3.5 / 4.0 / 4.5 / .NET Standard 2.x / .NET Core 2.x / .NET Core 3.x / .NET 6.0 / .NET 7.0 / .NET 8.0. It is compatible with all environments including MVC, Razor, WebApi, Console (command line), desktop applications (.exe), Blazor, MAUI, and background services, and is completely decoupled from external frameworks.

Senparc.Weixin SDK is currently the most widely used Wechat .NET SDK and one of the most popular .NET open source projects in China.

Since its inception in 2013, we have been continuously updating the project and sharing the complete source code and design ideas without reservation, hoping that more people can benefit from it, understand and spread the spirit of open source, and help the open source cause in China! We are grateful to all the friends who have helped us along the way!

If you like this project and want us to continue improving it, please give us a ★Star :)

🔔 Announcement

At the 2024 Microsoft MVP Global Summit, I had the privilege of interviewing Scott Hanselman and discussed a range of topics related to AI. We will continue our conversation on April 13, 2024, during the "Senparc 3.14 Technology Open Day" event, where we will delve deeper into the impact of AI and Agents on the future of the software industry and open-source software. Everyone is welcome to follow along! Watch the video
⚡ Sample now supports .NET 8.0 (backward compatible), click here to view!

🔒 Wechat Pay V3 module (V1.0) is now online! Nuget

🎠 Fully support automatic segmentation and sending of long text messages, more: 《Auto Reply Long Text Messages to Adapt to AIGC Applications》

🌟 Start: Separate documentation for each module + Sample code examples

Note:

1. The above module examples include both documentation and runnable code templates (just need to configure Wechat parameters without modifying any code).
2. The configuration, registration, and interface calling methods in the examples are consistent. Once you learn how to develop one module, you can apply the same knowledge to other modules. The Hello World example below uses Official Account as an example, but it can be extended to other modules as well.
3. More complete development documentation is provided in the /docs directory for advanced development, click here to view.

🚀 Hello World: Start your Wechat development journey with 3 lines of code!

Note:

1. The following source code is located in the /Samples/MP/ folder, using Wechat Official Account as an example. Once you learn how to develop for Official Account, you can apply the same knowledge to other modules (Mini Program, Enterprise Wechat, Wechat Pay, etc.).
2. To view other module or integration examples, you can check the independent samples in the /Samples/ folder or the integration samples in the /Samples/All/ folder (for advanced users).

Startup code (just 2 lines of code):

1. Add configuration above builder.Build() in Program.cs:

builder.Services.AddSenparcWeixinServices(builder.Configuration);  

Corresponds to ConfigureServices() method in Startup.cs.

2. Enable configuration below builder.Build() in Program.cs:

var registerService = app.UseSenparcWeixin(app.Environment, null, null, register => { },  
    (register, weixinSetting) =>  
{  
    // Register Official Account information (can be executed multiple times to register multiple Official Accounts)  
    register.RegisterMpAccount(weixinSetting, "Senparc Network Assistant Official Account");  
});  

Corresponds to Configure() method in Startup.cs.

Call advanced interfaces (just 1 line of code):

You can call interfaces (using Customer Service interface as an example) at any position in the program:

await CustomApi.SendTextAsync("AppId", "OpenId", "Hello World!");  

Tips:

1. Senparc.Weixin SDK automatically manages the AccessToken throughout its life cycle, so during development, you only need to provide the AppId without worrying about AccessToken expiration, etc.
2. Registration information such as AppId can be automatically obtained from Senparc.Weixin.Config.SenparcWeixinSetting, and the relevant parameters are configured in appsettings.json.
3. The above method also supports synchronous calls: Senparc.Weixin.MP.AdvancedAPIs.CustomApi.SendText().
4. All interface namespaces are defined according to the official API path rules, and the parameter naming is kept as consistent as possible with the documentation (especially the return parameters), making it easier for developers to quickly locate and test, and reduce the likelihood of bugs.

With the above code, you can call interfaces for all Wechat modules! Continue reading for more skills.

How to use the messaging capability of Official Accounts?

Official Accounts provide a messaging window by default, which can send different types of messages and interact with programs using text, images, voice, etc.

The following example also applies to the messaging of Enterprise Wechat and Mini Program Customer Service, just two steps!

Step 1: Create a custom MessageHandler to control message processing logic:

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>  
    /// Custom MessageHandler  
    /// Inherits from MessageHandler and overrides the corresponding request handling methods  
    /// </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>  
        /// Default message for all unhandled types  
        /// </summary>  
        /// <returns></returns>  
        public override IResponseMessageBase DefaultResponseMessage(IRequestMessageBase requestMessage)  
        {  
            //ResponseMessageText can also be News or other types  
            var responseMessage = this.CreateResponseMessage<ResponseMessageText>();  
            responseMessage.Content = $"You sent a message, but the program did not specify a processing procedure";  
            return responseMessage;  
        }  
  
        public override Task<IResponseMessageBase> OnImageRequestAsync(RequestMessageImage requestMessage)  
        {  
            //Handle image requests...  
        }  
  
        public override Task<IResponseMessageBase> OnLocationRequestAsync(RequestMessageLocation requestMessage)  
        {  
            //Handle location requests...  
        }  
    }  
}  

Step 2: Request the CustomMessageHandler:

We provide two ways to request the CustomMessageHandler: Middleware (recommended) and Controller (or WebApi). You can choose either one. Taking Middleware as an example, after enabling the configuration in Program.cs, add the following code to register the MessageHandler:

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

At this point, you can use https://YourDomain/WeixinAsync to configure in the Wechat Official Account backend [Settings and Development]>[Basic Configuration]>Server Address (URL), and the corresponding Token is set in appsettings.json (also applicable to Enterprise Wechat and Mini Program, please refer to the corresponding Sample).

In addition, you can also use the Controller (or WebApi) method to have more precise control over the entire message processing process (or use it in .NET Framework), click here to view.

Now you have mastered the basic skills required to develop for Wechat platforms. Keep reading for more resources:

📇 More Indexes

• 🏹 Libraries for each module
• 💾 Source code project folder description (under src folder)
• 🖥️ Samples folder description (under Samples folder)
• 🎨 Resources
• 📖 Senparc Official Book Tutorial
• 🖥️ Senparc Official Video Tutorial
• 🧪 Follow the test account (SenparcRobot)
• ✋ Contribute to the code
• 👩‍🏫 How to develop using .NET Core
• ↕️ Install via Nuget
• 🏬 How to deploy
• 🍴 Description of important branches
• 🍟 Thanks to contributors
• 💰 Donate
• ⭐ Star Count
• 📎 License

This repository contains the source code for multiple versions including .NET Framework/.NET Standard 2.0+/.NET Core 3.1/.NET 6/.NET 7/.NET 8:

• Use Visual Studio 2022 to open the demo (supports all versions): .NET 8.0 - Senparc.Weixin.Sample.Net7.sln (includes recommended source code references)
• Use Visual Studio 2019 or higher to open the .NET Framework demo: Senparc.Weixin.MP.Sample.Net45.sln (does not include source code, only references the libraries)
• Use Visual Studio 2019 or higher to open the command line Console demo (.NET Core): Senparc.Weixin.MP.Sample.Consoles.vs2019.sln

Legend

.NET Framework 4.6.2+	.NET Standard 2.0 / 2.1	.NET 8.0, backward compatible with .NET 5.0-7.0

Tip:

1. Starting from May 1, 2019, .NET Framework 3.5 and 4.0 will no longer receive updates. The last stable version of .NET Framework 3.5 + 4.0 can be found here.
   
2. Starting from April 3, 2022, .NET Framework 4.5 has been upgraded to 4.6.2. The last stable version of .NET Framework 4.5 can be found here.
   
3. If you are still using .NET Framework, it is recommended to upgrade your application to .NET Framework 4.8+ by January 12, 2027, as official support for .NET Framework 4.6.2 will end by then (source).

Feature Support

• Most of the WeChat 8.x APIs are supported, including WeChat Pay, custom menu/personalized menu, template message interface, material upload interface, mass message interface, customer service interface, payment interface, WeChat store interface, card interface, invoice interface, etc.
• Support for WeChat Official Accounts, Mini Programs, Enterprise Accounts, Open Platforms, WeChat Pay, and other modules.
• Support for user session context (solving the problem of using Session to process user information on the server).
• Full support for the latest APIs of WeChat Official Accounts, Mini Programs, Enterprise Accounts (WeChat Work), WeChat Pay V2/V3, and Open Platforms.
• Support for distributed caching and caching strategy extension (default support: local cache, Redis, Memcached, can be freely extended), no need to worry about the type of cache used during development, can be freely switched in the configuration file or during runtime.

1. The official APIs are perfectly integrated, and all upgrades will try to ensure backward compatibility unless otherwise specified. So you can safely use or directly upgrade (overwrite) the latest DLLs. It is recommended to use NuGet for updates.
   
2. You can also modify and compile the code yourself. Open the Senparc.Weixin.Sample.Net6.sln or Senparc.Weixin.Sample.Net8.sln solution to see all the source code. When the compilation mode is Release, a local NuGet package will be automatically generated (default generated in the /src/BuildOutPut/ folder).

💾 Explanation of Source Code Project Folders (under the src folder)

Enter Folder

🖥️ Explanation of Samples Folder (under the Samples folder)

The usage of all modules in the Senparc.Weixin SDK is highly consistent, including the configuration process, AccessToken management, message processing, service messages, API calls, etc. You only need to refer to the usage of any module (it is recommended to start with Official Accounts or Mini Programs), and you can apply the same principles to other modules.

From the following samples, you can learn about the configuration and usage of each independent module. Just open the .sln solution file in the corresponding folder to view the source code and run it to see the documentation. The All folder contains more comprehensive and advanced feature demonstrations.

Enter Samples Folder

🎨 Resources

1. Official website: https://weixin.senparc.com/
2. Online demo (for .NET 8.0, backward compatible with .NET 6.0, 7.0, and .NET Core): https://sdk.weixin.senparc.com/
3. WeChat development tutorials: https://www.cnblogs.com/szw/p/weixin-course-index.html
4. WeChat technical community: https://weixin.senparc.com/QA
5. Custom menu online editor: https://sdk.weixin.senparc.com/Menu
6. Online message testing tool: https://sdk.weixin.senparc.com/SimulateTool
7. Cache testing tool: https://sdk.weixin.senparc.com/Cache/Test
8. chm help document download: https://sdk.weixin.senparc.com/Document
9. Source code and latest updates: https://github.com/JeffreySu/WeiXinMPSDK
10. WeChat development resource collection: https://github.com/JeffreySu/WeixinResource
11. Auxiliary system for reading "In-depth Analysis of WeChat Development": https://book.weixin.senparc.com
12. Purchase "In-depth Analysis of WeChat Development": https://item.jd.com/12220004.html
13. "Rapid Development of WeChat Official Accounts and Mini Programs" video tutorial: https://github.com/JeffreySu/WechatVideoCourse

• Technical communication QQ groups:

Group 1 (Official Accounts): 300313885

Group 14 (Video Course Students): 588231256

Group 10 (Distributed Cache): 246860933

Group 12 (Mini Programs): 108830388

Group 16 (Open Platform): 860626938

The following groups are full:

Group 2: 293958349 (Full), Group 3: 342319110 (Full)

Group 4: 372212092 (Full), Group 5: 377815480 (Full), Group 6: 425898825 (Full)

Group 7: 482942254 (Full), Group 8: 106230270 (Full), Group 9: 539061281 (Full)

Group 11: 553198593 (Full), Group 13: 183424136 (Open Platform, Full), Group 15: 289181996 (Full)

• Business contact QQ: 498977166

If this project is helpful to you, we welcome any form of donation or participation in code updates and feedback. Thank you!

Donation: Enter

📖 Senparc Official Book Tutorial

The Wechat development book, titled "In-Depth Analysis of Wechat Development: Efficient Development Secrets for Official Accounts and Mini Programs," completed by Jeffrey Su and the Senparc team after 2 years of effort, has been published. The book comes with an auxiliary reading system: BookHelper.

Welcome to purchase the genuine book: 【Buy Genuine】

The code snapshot of the book's publication version is in the branch BookVersion1.

💻 Senparc Official Video Tutorial

In order to help everyone understand Wechat development details more intuitively and learn Wechat development and various tricks in .NET development process, we have established the "Senparc Classroom" group and launched Wechat development video courses, which cover the following two parts:

1. Wechat development basic skills
   
2. Case study of official accounts and mini programs
   

The total course duration is 60 lessons, with additional episodes.

Currently, the videos are available on NetEase Cloud Classroom, with well-produced content and abundant materials. The course has been selected as an "A" level course. 【Watch Videos】, 【View Course Code and Slides】.

🧪 Follow the test account to experience the functions (SenparcRobot):

Senparc Network Assistant Official Account	Senparc Network Assistant Mini Program	BookHelper

✋ Contribute Code

If you need to use or modify the source code of this project, it is recommended to Fork first. You are also welcome to submit a Pull Request for the general version you modified.

1. Fork
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the remote git repository (git push origin my-new-feature)
5. Go to the my-new-feature branch of your git remote repository on the github website and submit a Pull Request
   (Submit to the Developer branch instead of the master branch directly)

👩‍🏫 How to develop with .NET Core

The current branch includes the full version of .NET Framework 4.6.2+ and .NET 6.0/7.0/8.0 code (snapshot of versions that are no longer updated can be found in release).

The Demo for .NET Framework is located in the /src/Samples/All/net45-mvc directory, and

【Recommended】The Demo for .NET 8.0 (compatible with .NET 5.0, 6.0, 7.0, and .NET Core 3.1 and lower versions) is located in the /Samples/All/net8-mvc directory.


Note:

1. In the above Samples, the net8-mvc Sample directly references the source code of each module, and can generate a Senaprc.Weixin SDK library compatible with different versions after being compiled with Release.
   
2. You can also use the Demo for .NET 6.0 (compatible with .NET 5.0 and .NET Core 3.1 and lower versions) located in the /Samples/All/net6-mvc directory if you want.

↕️ Install via Nuget to the project

The Nuget installation methods for each module: Installing the SDK into the project using Nuget

🏬 Deployment guide

1) Deploy to Azure App Service

App Service is a Web service launched by Microsoft Azure, which has good support for .NET. The deployment steps are detailed in: Deploy the Wechat site to Azure.

2) Deploy to any server via FTP

Install an FTP service (FileZilla Server is recommended) on the Web server, and directly upload the compiled code from the local machine (the corresponding code in the Samples is Senparc.Weixin.Sample.Net7, Senparc.Weixin.Sample.Net6, or Senparc.Weixin.Sample.NetCore3). After compilation, you can use it directly without modifying the code. If you use Azure App Service or other cloud services, FTP is usually enabled as well.

🍴 Important Branches

🍟 Thanks To Contributors

Thanks to the developers who contributed to this project. You have not only improved this project, but also made a contribution to the Chinese open source community. Thank you! The list can be found here.

💰 Donations

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

Donate:

⭐ Star Quantity Statistics

📎 License

Apache License Version 2.0

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