# Magicodes.Wx.Sdk **Repository Path**: ultravin/Magicodes.Wx.Sdk ## Basic Information - **Project Name**: Magicodes.Wx.Sdk - **Description**: 最简洁最易于使用的微信Sdk，包括公众号Sdk、小程序Sdk、企业微信Sdk等，以及Abp VNext集成。 - **Primary Language**: C# - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 16 - **Created**: 2022-01-12 - **Last Updated**: 2022-01-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Magicodes.Wx.Sdk ## 概述 最简洁最易于使用的微信Sdk，包括公众号Sdk、小程序Sdk、企业微信Sdk等，以及Abp VNext集成。 - [GitHub地址：https://github.com/xin-lai/Magicodes.Wx.Sdk](https://github.com/xin-lai/Magicodes.Wx.Sdk) - [Gitee地址：https://gitee.com/xl_wenqiang/Magicodes.Wx.Sdk](https://gitee.com/xl_wenqiang/Magicodes.Wx.Sdk) | **名称** | **Nuget** | |----------|:-------------:| | **Magicodes.Wx.PublicAccount.Sdk** | **[![NuGet](https://buildstats.info/nuget/Magicodes.Wx.PublicAccount.Sdk)](https://www.nuget.org/packages/Magicodes.Wx.PublicAccount.Sdk)** | | **Magicodes.Wx.PublicAccount.Sdk.AspNet** | **[![NuGet](https://buildstats.info/nuget/Magicodes.Wx.PublicAccount.Sdk.AspNet)](https://www.nuget.org/packages/Magicodes.Wx.PublicAccount.Sdk.AspNet)** | | **Magicodes.Wx.PublicAccount.Sdk.Abp** | **[![NuGet](https://buildstats.info/nuget/Magicodes.Wx.PublicAccount.Sdk.Abp)](https://www.nuget.org/packages/Magicodes.Wx.PublicAccount.Sdk.Abp)** | ## 如何贡献？ [如何快速封装一个微信接口？](./docs/如何快速编写一个微信Api.md)（30秒编写一个微信Api，欢迎多多PR） 如何快速定义一个微信上传文件的接口？ ## RoadMap ### 公众号 - [x] 全局 - [x] 接口结果基类（`ApiResultBase`） - [x] 全局返回码（`ReturnCodes`） - [x] 是否成功返回（`IsSuccess`） - [x] 获取异常友好提示消息（`GetFriendlyMessage`） - [x] Access Token获取（`ITokenApi`） - [x] Token管理器（`ITokenManager`） - [x] Access Token API请求筛选器（`AccessTokenApiFilter`） - [x] IWxApiBase - [x] IWxApiWithAccessTokenFilter（启用`AccessTokenApiFilter`） - [x] 从配置文件获取公众号配置 ```json "Wx": { "PublicAccount": { "AppId": "", "AppSecret": "" } } ``` - [x] 函数注入（`WxFuncs`） - [x] GetWeChatOptions【获取公众号配置】 - [x] GetAccessTokenByAppId【根据AppId获取Access Token】 - [x] CacheAccessToken【缓存Access Token】 - [x] 异常（`WxSdkException`） - [x] Abp Vnext集成（`Magicodes.Wx.PublicAccount.Sdk.Abp`） - [x] WxPublicAccountSdkModule（默认已实现IDistributedCache） - [x] Magicodes.Wx.PublicAccount.Sdk.AspNet模块 - [x] 事件消息控制器（`WxEventController`） - [x] 服务器事件消息处理器（`IWxEventsHandler`） - [x] 公众号网页开发基类（`WxPublicAccountControllerBase`） - [x] 公众号授权筛选器（`WxPublicAccountOAuthFilter`） - [ ] 基础消息能力 - [x] 服务器事件消息 - [x] 服务器事件消息配置接入以及验证 - [x] 事件推送 - [x] 关注事件：`FromSubscribeEvent` - [x] 取消关注事件：`FromUnsubscribeEvent` - [x] 扫码事件：`FromScanEvent` - [x] 地理位置选择器事件：`FromLocationEvent` - [x] 点击事件：`FromClickEvent` - [x] 点击菜单链接跳转事件：`FromViewEvent` - [x] 模板消息推送完成事件：`FromTemplateSendJobFinishEvent` - [x] 点击菜单跳转小程序事件：`FromViewMiniprogramEvent` - [x] 基础消息 - [x] 文本消息：`FromTextMessage` - [x] 图片消息：`FromImageMessage` - [x] 语音消息：`FromVoiceMessage` - [x] 视频消息：`FromVideoMessage` - [x] 小视频消息：`FromShortVideoMessage` - [x] 地理位置消息：`FromLocationMessage` - [x] 链接消息：`FromLinkMessage` - [x] 被动消息回复 - [x] 回复文本消息：`ToTextMessage` - [x] 回复图片消息：`ToImageMessage` - [x] 回复语音消息：`ToVoiceMessage` - [x] 回复视频消息：`ToVideoMessage` - [x] 回复音乐消息：`ToMusicMessage` - [x] 回复图文消息：`ToNewsMessage` - [x] 回复空消息（不回复）：`ToNullMessage` - [ ] 群发接口 - [x] 上传图文消息内的图片获取URL【订阅号与服务号认证后均可用】（`IMediaApi`>>`UploadImageAsync`） - [x] 上传图文消息素材【订阅号与服务号认证后均可用】 - [x] 根据标签进行群发【订阅号与服务号认证后均可用】 - [x] 根据OpenID列表群发【订阅号不可用，服务号认证后可用】 - [x] 删除群发【订阅号与服务号认证后均可用】 - [ ] 预览接口【订阅号与服务号认证后均可用】 - [ ] 查询群发消息发送状态【订阅号与服务号认证后均可用】 - [ ] api调用次数进行清零 - [ ] 获取公众号当前使用的自动回复规则 - [ ] 公众号一次性订阅消息 - [x] 模板消息（`ITemplateApi`） - [x] [1 设置所属行业](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#0)（`SetIndustryAsync`） - [x] [2 获取设置的行业信息](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#1)（`GetIndustryAsync`） - [x] [3 获得模板ID](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#2)（`GetTemplateIdAsync`） - [x] [4 获取模板列表](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#3)（`GetAllPrivateTemplateAsync`） - [x] [5 删除模板](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#4)（`DelPrivateTemplateAsync`） - [x] [6 发送模板消息](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Template_Message_Interface.html#5)（`SendAsync`） - [ ] 自定义菜单（`IMenuApi`） - [x] 创建接口（`CreateAsync`） - [x] 查询接口（`GetAsync`） - [x] 删除接口（`DeleteAsync`） - [ ] 个性化菜单接口 - [ ] 获取自定义菜单配置 - [ ] 订阅通知 - [ ] 选用模板 - [ ] 删除模板 - [ ] 获取公众号类目 - [ ] 获取模板中的关键词 - [ ] 获取所属类目的公共模板 - [ ] 获取私有模板列表 - [ ] 发送订阅通知 - [ ] 客服消息 - [ ] 客服管理（`IKfAccountApi`） - [x] 获取客服基本信息（`GetKFListAsync`） - [x] 添加客服账号（`AddAsync`） - [x] 邀请绑定客服账号（`InviteWorkerAsync`） - [x] 设置客服信息（`UpdateAsync`） - [x] 上传客服头像（`UploadHeadimg`） - [x] 删除客服账号（`DelAsync`） - [x] 获取在线客服接待会话数（`GetOnlineKFListAsync`） - [x] 微信网页开发 - [x] 网页授权 - [x] 获取授权链接（`WxHelper >> GetAuthorizeUrl`） - [x] 通过code换取网页授权access_token（`IOauth2Api >> GetAccessTokenAsync`) - [x] 刷新access_token（`IOauth2Api >> RefreshTokenAsync`) - [x] 拉取用户信息（`ISnsApi >> GetUserInfoAsync`） - [x] 检验授权凭证（access_token）是否有效（`ISnsApi >> AuthAsync`） - [ ] 对话能力 - [ ] 顾问管理 - [ ] 添加顾问 - [ ] 获取顾问信息 - [ ] 修改顾问信息 - [ ] 删除顾问 - [ ] 获取服务号顾问列表 - [ ] 生产顾问二维码 - [ ] 扫顾问二维码后的事件推送 - [ ] 获取顾问聊天记录 - [ ] 设置快捷回复与关注自动回复 - [ ] 获取快捷回复与关注自动回复 - [ ] 设置离线自动回复与敏感词 - [ ] 获取离线自动回复与敏感词 - [ ] 新建顾问分组 - [ ] 获取顾问分组列表 - [ ] 获取顾问分组信息 - [ ] 分组内添加顾问 - [ ] 分组内删除顾问 - [ ] 获取顾问所在分组 - [ ] 删除顾问分组 - [ ] 客户管理 - [ ] 为顾问分配客户 - [ ] 为顾问移除客户 - [ ] 获取顾问的客户列表 - [ ] 为客户更好顾问 - [ ] 修改客户昵称 - [ ] 查询客户所属顾问 - [ ] 查询指定顾问和客户的关系 - [ ] 标签管理 - [ ] 新建标签类型 - [ ] 删除标签类型 - [ ] 为标签添加可选值 - [ ] 获取标签和可选值 - [ ] 为客户设置标签 - [ ] 查询客户标签 - [ ] 根据标签值刷选客户 - [ ] 删除客户标签 - [ ] 设置自定义客户信息 - [ ] 获取自定义客户信息 - [ ] 素材管理 - [ ] 添加小程序卡片素材 - [ ] 查询小程序卡片素材 - [ ] 删除 小程序卡片素材 - [ ] 添加图片素材 - [ ] 查询图片素材 - [ ] 删除图片素材 - [ ] 添加文字素材 - [ ] 查询文字素材 - [ ] 删除文字素材 - [ ] 群发任务管理 - [ ] 添加群发任务 - [ ] 获取群发任务列表 - [ ] 获取指定群发任务信息 - [ ] 修改群发任务 - [ ] 取消群发任务 - [ ] 素材管理（`IMediaApi`） - [x] 新增临时素材（`UploadAsync`） - [ ] 获取临时素材 - [ ] 新增永久素材 - [ ] 获取永久素材 - [ ] 删除永久素材 - [ ] 修改永久图文素材 - [ ] 获取素材总数 - [ ] 获取素材列表 - [ ] 图文消息留言管理 - [ ] 用户管理（`IUserApi`） - [x] 设置用户备注名（`UpdateRemarkAsync`） - [x] 获取用户基本信息（UnionID机制）（`InfoAsync`） - [x] 获取用户列表（`GetAsync`） - [ ] 黑名单管理 - [x] 用户标签管理（`ITagsApi`） - [x] 创建标签（`CreateAsync`） - [x] 获取公众号已创建的标签（`GetAsync`） - [x] 编辑标签（`UpdateAsync`） - [x] 删除标签（`DeleteAsync`） - [x] 获取标签下粉丝列表（`IUserApi`>>`GetUserByTagAsync`） - [x] 批量为用户打标签（`BatchTaggingAsync`） - [x] 批量为用户取消标签（`BatchUnTaggingAsync`） - [x] 获取用户身上的标签列表（`GetIdListAsync`） - [ ] 账号管理 - [ ] 生产带参数的二维码 - [ ] 长链接转短链接接口 - [ ] 短key托管 - [ ] 微信认证时间推送 - [ ] 数据统计 - [ ] 用户分析 - [ ] 图文分析 - [ ] 消息分析 - [ ] 广告分析 - [ ] 分广告位数据 - [ ] 返佣商品数据 - [ ] 结算收入数据 - [ ] 接口分析 - [ ] 微信卡券 - [ ] 微信卡券接口 - [ ] 更新日志 - [ ] 创建卡券 - [ ] 投放卡券 - [ ] 核销卡券 - [ ] 管理卡券 - [ ] 卡券事件推送 - [ ] 卡券-小程序打通 - [ ] 微信礼品卡 - [ ] 会员卡专区 - [ ] 玩法介绍 - [ ] 创建会员卡 - [ ] 管理会员卡 - [ ] 特殊票券 - [ ] 卡券错误码 - [ ] 第三方开发者模式 - [ ] 微信门店 - [ ] 微信门店接口 - [ ] 微信门店小程序接口 - [ ] 微信小店 - [ ] 智能接口 - [ ] 语义理解 - [ ] AI开放接口 - [ ] OCR识别 - [ ] 图像处理 - [ ] 一物一码 - [ ] 微信发票 - [ ] 微信非税缴费 ### 小程序 - [ ] 登录 - [ ] 用户信息 - [ ] ... ## 快速上手 本Sdk上手非常简单，参考教程如下所示。 ### 1）安装包 ```powershell Install-Package Magicodes.Wx.PublicAccount.Sdk.AspNet ``` 推荐使用此包，亦可使用`Magicodes.Wx.PublicAccount.Sdk`来进行更多的自定义配置。 ### 2）基础配置 - **配置文件配置** 公众号的参考配置如下所示，请在`appsettings.json`文件中进行配置： ```json "Wx": { "PublicAccount": { "AppId": "", "AppSecret": "" } ``` - **通过代码配置** 参考代码如下所示： ```csharp app.UseMagicodesWeChatSdk(setup => { setup.GetWeChatOptions = () => { //配置 return new WxPublicAccountOption() { AppId = "", AppSecret = "" }; }; }); ``` ### 3）配置Sdk 参考代码如下所示： ```csharp public void ConfigureServices(IServiceCollection services) { //添加公众号Sdk集成 services.AddMPublicAccountSdk() //使用内存缓存 .AddDistributedMemoryCache(); } public void Configure(IApplicationBuilder app) { //配置公众号Sdk app.UseMPublicAccountSdk() //使用分布式缓存缓存Access Token .UseWxDistributedCacheForAccessToken(); } ``` ### 4）调用Api 接下来就简单了，通过依赖注入的方式注入相关Api，比如构造函数注入： ```csharp public HomeController(IMenuApi menuApi) { _menuApi = menuApi; } ``` 然后就可以使用了，如下面代码： ```csharp var result = await _menuApi.CreateAsync(new CreateMenuInput() { Button = new List() { new ClickButton() { Name = "今日歌曲", Key = "V1001_TODAY_MUSIC" }, new SubMenuButton() { Name = "菜单", SubButtons = new List() { new ViewButton() { Name = "搜索", Url = "http://www.soso.com/" }, //需关联小程序后 //new MiniprogramButton() //{ // Name = "wxa", // Url = "http://mp.weixin.qq.com", // AppId = "wx286b93c14bbf93aa", // Pagepath = "pages/lunar/index" //}, new ClickButton() { Name = "赞一下我们", Key = "V1001_GOOD" } } } } }); result.EnsureSuccess(); ``` ## 微信服务器事件、消息处理和被动消息回复 如何处理微信服务器事件、消息，步骤如下所示： ### 1）配置Sdk nuget包的安装和公众号的配置我们这里跳过，直接秀出Sdk配置代码： ```csharp public void ConfigureServices(IServiceCollection services) { //注册IWxEventsHandler,如需处理自定义事件消息,请务必实现IWxEventsHandler services.AddSingleton(); services.AddMPublicAccountSdk() .AddDistributedMemoryCache() //添加服务器消息事件处理器 .AddServerMessageHandler(); } public void Configure(IApplicationBuilder app) { //配置公众号Sdk app.UseMPublicAccountSdk() //使用分布式缓存缓存Access Token .UseWxDistributedCacheForAccessToken(); } ``` ### 2）实现IWxEventsHandler 参考代码如下所示： ```csharp /// /// 公众号事件消息处理程序 /// public class TestWxEventsHandler : IWxEventsHandler { /// /// 执行 /// /// /// public async Task Execute(IFromMessage fromMessage) { if (fromMessage is FromTextMessage) { //返回多图文 var toMsg = new ToNewsMessage() { Articles = new List() { new ToNewsMessage.ArticleInfo() { Description = "最简洁最易于使用的微信Sdk，包括公众号Sdk、小程序Sdk、企业微信Sdk等，以及Abp VNext集成。", PicUrl = "https://www.xin-lai.com/imgs/xinlai-logo_9d2c29c2794e6a173738bf92b056ab69.png", Title="Magicodes.Wx.Sdk简介", Url = "http://xin-lai.com" } }, FromUserName = "Test", ToUserName = "Test" }; return await Task.FromResult(toMsg); } else if (fromMessage is FromSubscribeEvent) { //返回文本消息 return await Task.FromResult(new ToTextMessage() { Content = "欢迎关注!", }); } else if (fromMessage is FromTextMessage) { //返回文本 return await Task.FromResult(new ToTextMessage() { Content = "Test", }); } return await Task.FromResult(new ToNullMessage()); } } ``` 相关事件和消息以及消息回复的定义，如下所示： - 事件推送 - 关注事件：`FromSubscribeEvent` - 取消关注事件：`FromUnsubscribeEvent` - 扫码事件：`FromScanEvent` - 地理位置选择器事件：`FromLocationEvent` - 点击事件：`FromClickEvent` - 点击菜单链接跳转事件：`FromViewEvent` - 模板消息推送完成事件：`FromTemplateSendJobFinishEvent` - 点击菜单跳转小程序事件：`FromViewMiniprogramEvent` - 基础消息 - 文本消息：`FromTextMessage` - 图片消息：`FromImageMessage` - 语音消息：`FromVoiceMessage` - 视频消息：`FromVideoMessage` - 小视频消息：`FromShortVideoMessage` - 地理位置消息：`FromLocationMessage` - 链接消息：`FromLinkMessage` - 被动消息回复 - 回复文本消息：`ToTextMessage` - 回复图片消息：`ToImageMessage` - 回复语音消息：`ToVoiceMessage` - 回复视频消息：`ToVideoMessage` - 回复音乐消息：`ToMusicMessage` - 回复图文消息：`ToNewsMessage` - 回复空消息（不回复）：`ToNullMessage` ## MVC网页授权 在ASP.NET MVC，我们可以通过本SDK快速获得微信用户信息，参考代码如下所示： ```csharp //注意继承WxPublicAccountControllerBase public class HomeController : WxPublicAccountControllerBase { private readonly ILogger _logger; public HomeController(ILogger logger) { _logger = logger; } //设置了WxPublicAccountOAuthFilter的Action在缓存过期的情况下，将自动跳转到微信网页授权页面进行授权 //OAuthLevel设置为OpenIdAndUserInfo允许获取粉丝信息 [WxPublicAccountOAuthFilter(OAuthLevel = OAuthLevels.OpenIdAndUserInfo)] public async Task IndexAsync() { //调用父级控制器的获取粉丝信息方法，该方法从ISnsApi中获取粉丝详细信息 var userResult = await GetWeChatUserInfoAsync(); var model = new UserInfo() { Headimgurl = userResult.Headimgurl, NickName = userResult.NickName, Sex = userResult.Sex }; _logger.LogDebug($"NickName:{userResult.NickName}"); return View(model); } } ``` ## Abp VNext集成 Magicodes.Wx.PublicAccount.Sdk默认提供了Abp VNext模块，相关步骤如下所示： ### 1）安装Magicodes.Wx.PublicAccount.Sdk.Abp ```powershell Install-Package Magicodes.Wx.PublicAccount.Sdk.Abp ``` ### 2）添加模块依赖 ```csharp [DependsOn( typeof(WxPublicAccountSdkModule) )] ``` 如需处理服务器事件消息，还需注册IWxEventsHandler： ```csharp context.Services.AddSingleton(); ``` ## 联系我们 ### 订阅号 关注“**麦扣聊技术**”订阅号可以获得最新文章、教程、文档，并且加入微信生态群： ![](https://docs.xin-lai.com/medias/wechat.jpg "麦扣聊技术") ### QQ群 - **编程交流群<85318032>**（由于不经常在线，为了避免骚扰，设置了一定门槛） #### 文档官网&官方博客 - **文档官网：** - **博客：** #### 其他开源库 - **** - ****