Magicodes.Wx.Sdk

概述

最简洁最易于使用的微信Sdk，包括公众号Sdk、小程序Sdk、企业微信Sdk等，以及Abp VNext集成。

GitHub地址：https://github.com/xin-lai/Magicodes.Wx.Sdk
Gitee地址：https://gitee.com/xl_wenqiang/Magicodes.Wx.Sdk

名称	Nuget
Magicodes.Wx.PublicAccount.Sdk
Magicodes.Wx.PublicAccount.Sdk.AspNet
Magicodes.Wx.PublicAccount.Sdk.Abp

如何贡献？

如何快速封装一个微信接口？（30秒编写一个微信Api，欢迎多多PR）

如何快速定义一个微信上传文件的接口？

RoadMap

公众号

全局
- 接口结果基类（ApiResultBase）
  - 全局返回码（ReturnCodes）
  - 是否成功返回（IsSuccess）
  - 获取异常友好提示消息（GetFriendlyMessage）
- Access Token获取（ITokenApi）
- Token管理器（ITokenManager）
- Access Token API请求筛选器（AccessTokenApiFilter）
  - IWxApiBase
  - IWxApiWithAccessTokenFilter（启用AccessTokenApiFilter）
- 从配置文件获取公众号配置
```
  "Wx": {
    "PublicAccount": {
      "AppId": "",
      "AppSecret": ""
    }
  }
```
- 函数注入（WxFuncs）
  - GetWeChatOptions【获取公众号配置】
  - GetAccessTokenByAppId【根据AppId获取Access Token】
  - CacheAccessToken【缓存Access Token】
- 异常（WxSdkException）
- Abp Vnext集成（Magicodes.Wx.PublicAccount.Sdk.Abp）
  - WxPublicAccountSdkModule（默认已实现IDistributedCache）
- Magicodes.Wx.PublicAccount.Sdk.AspNet模块
  - 事件消息控制器（WxEventController）
  - 服务器事件消息处理器（IWxEventsHandler）
  - 公众号网页开发基类（WxPublicAccountControllerBase）
  - 公众号授权筛选器（WxPublicAccountOAuthFilter）
基础消息能力
- 服务器事件消息
  - 服务器事件消息配置接入以及验证
  - 事件推送
    - 关注事件：FromSubscribeEvent
    - 取消关注事件：FromUnsubscribeEvent
    - 扫码事件：FromScanEvent
    - 地理位置选择器事件：FromLocationEvent
    - 点击事件：FromClickEvent
    - 点击菜单链接跳转事件：FromViewEvent
    - 模板消息推送完成事件：FromTemplateSendJobFinishEvent
    - 点击菜单跳转小程序事件：FromViewMiniprogramEvent
  - 基础消息
    - 文本消息：FromTextMessage
    - 图片消息：FromImageMessage
    - 语音消息：FromVoiceMessage
    - 视频消息：FromVideoMessage
    - 小视频消息：FromShortVideoMessage
    - 地理位置消息：FromLocationMessage
    - 链接消息：FromLinkMessage
  - 被动消息回复
    - 回复文本消息：ToTextMessage
    - 回复图片消息：ToImageMessage
    - 回复语音消息：ToVoiceMessage
    - 回复视频消息：ToVideoMessage
    - 回复音乐消息：ToMusicMessage
    - 回复图文消息：ToNewsMessage
    - 回复空消息（不回复）：ToNullMessage
- 群发接口
  - 上传图文消息内的图片获取URL【订阅号与服务号认证后均可用】（IMediaApi>>UploadImageAsync）
  - 上传图文消息素材【订阅号与服务号认证后均可用】
  - 根据标签进行群发【订阅号与服务号认证后均可用】
  - 根据OpenID列表群发【订阅号不可用，服务号认证后可用】
  - 删除群发【订阅号与服务号认证后均可用】
  - 预览接口【订阅号与服务号认证后均可用】
  - 查询群发消息发送状态【订阅号与服务号认证后均可用】
- api调用次数进行清零
- 获取公众号当前使用的自动回复规则
- 公众号一次性订阅消息
- 模板消息（ITemplateApi）
  - 1 设置所属行业（SetIndustryAsync）
  - 2 获取设置的行业信息（GetIndustryAsync）
  - 3 获得模板ID（GetTemplateIdAsync）
  - 4 获取模板列表（GetAllPrivateTemplateAsync）
  - 5 删除模板（DelPrivateTemplateAsync）
  - 6 发送模板消息（SendAsync）
自定义菜单（IMenuApi）
- 创建接口（CreateAsync）
- 查询接口（GetAsync）
- 删除接口（DeleteAsync）
- 个性化菜单接口
  - 创建个性化菜单（AddConditionalAsync）
  - 删除个性化菜单（DelConditionalAsync）
  - 测试个性化菜单匹配结果（TryMatchAsync）
- 获取自定义菜单配置（GetAsync）
订阅通知（INewTmplApi）
- 选用模板（AddTemplateAsync）
- 删除模板（DeleteTemplateAsync）
- 获取公众号类目（GetCategoryAsync）
- 获取模板中的关键词（GetPubTemplateKeyWordsByIdAsync）
- 获取所属类目的公共模板（GetPubTemplateTitleListAsync）
- 获取私有模板列表（GetTemplateListAsync）
- 发送订阅通知（SendAsync）
客服消息
- 客服管理（IKfAccountApi）
  - 获取客服基本信息（GetKFListAsync）
  - 添加客服账号（AddAsync）
  - 邀请绑定客服账号（InviteWorkerAsync）
  - 设置客服信息（UpdateAsync）
  - 上传客服头像（UploadHeadimg）
  - 删除客服账号（DelAsync）
  - 获取在线客服接待会话数（GetOnlineKFListAsync）
微信网页开发
- 网页授权
  - 获取授权链接（WxHelper >> GetAuthorizeUrl）
  - 通过code换取网页授权access_token（IOauth2Api >> GetAccessTokenAsync)
  - 刷新access_token（IOauth2Api >> RefreshTokenAsync)
  - 拉取用户信息（ISnsApi >> GetUserInfoAsync）
  - 检验授权凭证（access_token）是否有效（ISnsApi >> AuthAsync）
对话能力
- 顾问管理（IGuideApi）
  - 添加顾问（AddGuideAcctAsync）
  - 获取顾问信息（GetGuideAcctAsync）
  - 修改顾问信息（UpdateGuideAcctAsync）
  - 删除顾问（DelGuideAcctAsync）
  - 获取服务号顾问列表（GetGuideAcctListAsync）
  - 生产顾问二维码（GuideCreateQrCodeAsync）
  - 扫顾问二维码后的事件推送
  - 获取顾问聊天记录（GetGuideBuyerChatRecordAsync）
  - 设置快捷回复与关注自动回复（SetGuideConfigAsync）
  - 获取快捷回复与关注自动回复（GetGuideConfigAsync）
  - 设置离线自动回复与敏感词（SetGuideAcctConfigAsync）
  - 获取离线自动回复与敏感词（GetGuideAcctConfigAsync）
  - 允许微信用户复制小程序页面路径（PushShowWxaPathMenuAsync）
  - 新建顾问分组（NewGuideGroupAsync）
  - 获取顾问分组列表（GetGuideGroupListAsync）
  - 获取顾问分组信息（GetGroupInfoAsync）
  - 分组内添加顾问（AddGuide2GuideGroupAsync）
  - 分组内删除顾问（DelGuide2GuideGroupAsync）
  - 获取顾问所在分组（GetGroupByGuideAsync）
  - 删除顾问分组（DelGuideGroupAsync）
- 客户管理
  - 为顾问分配客户（AddGuideBuyerRelationAsync）
  - 为顾问移除客户（DelGuideBuyerRelationAsync）
  - 获取顾问的客户列表（GetGuideBuyerRelationListAsync）
  - 为客户更好顾问（RebindGuideAcctForBuyerAsync）
  - 修改客户昵称（UpdateGuideBuyerRelationAsync）
  - 查询客户所属顾问（GetGuideBuyerRelationByBuyerAsync）
  - 查询指定顾问和客户的关系（GetGuideBuyerRelationAsync）
- 标签管理
  - 新建标签类型（NewGuideTagOptionAsync）
  - 删除标签类型（DelGuideTagOptionAsync）
  - 为标签添加可选值（AddGuideTagOptionAsync）
  - 获取标签和可选值（GetGuideTagOptionAsync）
  - 为客户设置标签（AddGuideBuyerTagAsync）
  - 查询客户标签（GetGuideBuyerTagAsync）
  - 根据标签值刷选客户（QueryGuideBuyerByTagAsync）
  - 删除客户标签（DelGuideBuyerTagAsync）
  - 设置自定义客户信息（AddGuideBuyerDisplayTagAsync）
  - 获取自定义客户信息（GetGuideBuyerDisplayTagAsync）
- 素材管理
  - 添加小程序卡片素材（SetGuideCardMaterialAsync）
  - 查询小程序卡片素材（GetGuideCardMaterialAsync）
  - 删除小程序卡片素材（DelGuideCardMaterialAsync）
  - 添加图片素材（SetGuideImageMaterialAsync）
  - 查询图片素材（GetGuideImageMaterialAsync）
  - 删除图片素材（DelGuideImageMaterialAsync）
  - 添加文字素材（SetGuideWordMaterialAsync）
  - 查询文字素材（GetGuideWordMaterialAsync）
  - 删除文字素材（DelGuideWordMaterialAsync）
- 群发任务管理
  - 添加群发任务（AddGuideMasssendJobAsync）
  - 获取群发任务列表（GetGuideMassendJobListAsync）
  - 获取指定群发任务信息（GetGuideMassendJobAsync）
  - 修改群发任务（UpdateGuideMasssendJobAsync）
  - 取消群发任务（CancelGuideMassendJobAsync）
素材管理（IMediaApi）
- 新增临时素材（UploadAsync）
- 获取临时素材
- 新增永久素材
- 获取永久素材
- 删除永久素材
- 修改永久图文素材
- 获取素材总数
- 获取素材列表
图文消息留言管理
用户管理（IUserApi）
- 设置用户备注名（UpdateRemarkAsync）
- 获取用户基本信息（UnionID机制）（InfoAsync）
- 获取用户列表（GetAsync）
- 黑名单管理（ITagsApi）
  - 获取公众号的黑名单列表（GetBlackListAsync）
  - 拉黑用户（BatchBlackListAsync）
  - 取消拉黑用户（BatchUnBlackListAsync）
用户标签管理（ITagsApi）
- 创建标签（CreateAsync）
- 获取公众号已创建的标签（GetAsync）
- 编辑标签（UpdateAsync）
- 删除标签（DeleteAsync）
- 获取标签下粉丝列表（IUserApi>>GetUserByTagAsync）
- 批量为用户打标签（BatchTaggingAsync）
- 批量为用户取消标签（BatchUnTaggingAsync）
- 获取用户身上的标签列表（GetIdListAsync）
账号管理
- 生产带参数的二维码
- 长链接转短链接接口
- 短key托管
- 微信认证时间推送
数据统计
- 用户分析
- 图文分析
- 消息分析
- 广告分析
  - 分广告位数据
  - 返佣商品数据
  - 结算收入数据
- 接口分析
微信卡券
- 微信卡券接口
- 更新日志
- 创建卡券
- 投放卡券
- 核销卡券
- 管理卡券
- 卡券事件推送
- 卡券-小程序打通
- 微信礼品卡
- 会员卡专区
  - 玩法介绍
  - 创建会员卡
  - 管理会员卡
- 特殊票券
- 卡券错误码
- 第三方开发者模式
微信门店
- 微信门店接口
- 微信门店小程序接口
微信小店
智能接口
- 语义理解
- AI开放接口
- OCR识别
- 图像处理
一物一码
微信发票
微信非税缴费

小程序

登录
用户信息
...

快速上手

本Sdk上手非常简单，参考教程如下所示。

1）安装包

Install-Package Magicodes.Wx.PublicAccount.Sdk.AspNet

推荐使用此包，亦可使用Magicodes.Wx.PublicAccount.Sdk来进行更多的自定义配置。

2）基础配置

配置文件配置

公众号的参考配置如下所示，请在appsettings.json文件中进行配置：

  "Wx": {
    "PublicAccount": {
      "AppId": "",
      "AppSecret": ""
    }

通过代码配置

参考代码如下所示：

        app.UseMagicodesWeChatSdk(setup =>
        {
            setup.GetWeChatOptions = () =>
            {
                //配置
                return new WxPublicAccountOption()
                {
                    AppId = "",
                    AppSecret = ""
                };
            };
        });

3）配置Sdk

参考代码如下所示：

        public void ConfigureServices(IServiceCollection services)
        {
            //添加公众号Sdk集成
            services.AddMPublicAccountSdk()
                //使用内存缓存
                .AddDistributedMemoryCache();
        }

        public void Configure(IApplicationBuilder app)
        {
            //配置公众号Sdk
            app.UseMPublicAccountSdk()
                //使用分布式缓存缓存Access Token
                .UseWxDistributedCacheForAccessToken();
        }

Tips:

Configure(IApplicationBuilder) 方法：配置应用程序
ConfigureServices(IServiceCollection) ：将服务注册到中 IServiceCollection
ASP.NET Core 中的分布式缓存

4）调用Api

接下来就简单了，通过依赖注入的方式注入相关Api，比如构造函数注入：

    public HomeController(IMenuApi menuApi)
    {
        _menuApi = menuApi;
    }

Tips：

在 ASP.NET Core 中将依赖项注入到控制器

然后就可以使用了，如下面代码：

        var result = await _menuApi.CreateAsync(new CreateMenuInput()
        {
            Button = new List<MenuButtonBase>()
            {
                new ClickButton()
                {
                    Name = "今日歌曲",
                    Key = "V1001_TODAY_MUSIC"
                },
                new SubMenuButton()
                {
                    Name = "菜单",
                    SubButtons = new List<MenuButtonBase>()
                    {
                        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配置代码：

    public void ConfigureServices(IServiceCollection services)
    {
        //注册IWxEventsHandler,如需处理自定义事件消息,请务必实现IWxEventsHandler
        services.AddSingleton<IWxEventsHandler, TestWxEventsHandler>();
        services.AddMPublicAccountSdk()
            .AddDistributedMemoryCache()
            //添加服务器消息事件处理器
            .AddServerMessageHandler();
    }

    public void Configure(IApplicationBuilder app)
    {
        //配置公众号Sdk
        app.UseMPublicAccountSdk()
            //使用分布式缓存缓存Access Token
            .UseWxDistributedCacheForAccessToken();
    }

2）实现IWxEventsHandler

参考代码如下所示：

/// <summary>
/// 公众号事件消息处理程序
/// </summary>
public class TestWxEventsHandler : IWxEventsHandler
{
    /// <summary>
    /// 执行
    /// </summary>
    /// <param name="fromMessage"></param>
    /// <returns></returns>
    public async Task<ToMessageBase> Execute(IFromMessage fromMessage)
    {
        if (fromMessage is FromTextMessage)
        {
            //返回多图文
            var toMsg = new ToNewsMessage()
            {
                Articles = new List<ToNewsMessage.ArticleInfo>()
                {
                    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快速获得微信用户信息，参考代码如下所示：

//注意继承WxPublicAccountControllerBase
public class HomeController : WxPublicAccountControllerBase
{
    private readonly ILogger<HomeController> _logger;

    public HomeController(ILogger<HomeController> logger)
    {
        _logger = logger;
    }
    //设置了WxPublicAccountOAuthFilter的Action在缓存过期的情况下，将自动跳转到微信网页授权页面进行授权
    //OAuthLevel设置为OpenIdAndUserInfo允许获取粉丝信息
    [WxPublicAccountOAuthFilter(OAuthLevel = OAuthLevels.OpenIdAndUserInfo)]
    public async Task<IActionResult> 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

Install-Package Magicodes.Wx.PublicAccount.Sdk.Abp

2）添加模块依赖

[DependsOn(
    typeof(WxPublicAccountSdkModule)
)]

如需处理服务器事件消息，还需注册IWxEventsHandler：

context.Services.AddSingleton<IWxEventsHandler, WxEventsHandler>();

联系我们

订阅号

关注“麦扣聊技术”订阅号可以获得最新文章、教程、文档，并且加入微信生态群：

QQ群

编程交流群<85318032>（由于不经常在线，为了避免骚扰，设置了一定门槛）

文档官网&官方博客

文档官网：https://docs.xin-lai.com/
博客：http://www.cnblogs.com/codelove/

其他开源库

https://github.com/xin-lai
https://gitee.com/magicodes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Magicodes.Wx.Sdk

概述

如何贡献？

RoadMap

公众号

小程序

快速上手

1）安装包

2）基础配置

3）配置Sdk

4）调用Api

微信服务器事件、消息处理和被动消息回复

1）配置Sdk

2）实现IWxEventsHandler

MVC网页授权

Abp VNext集成

1）安装Magicodes.Wx.PublicAccount.Sdk.Abp

2）添加模块依赖

联系我们

订阅号

QQ群

文档官网&官方博客

其他开源库

Files

README.md

Latest commit

History

README.md

File metadata and controls

Magicodes.Wx.Sdk

概述

如何贡献？

RoadMap

公众号

小程序

快速上手

1）安装包

2）基础配置

3）配置Sdk

4）调用Api

微信服务器事件、消息处理和被动消息回复

1）配置Sdk

2）实现IWxEventsHandler

MVC网页授权

Abp VNext集成

1）安装Magicodes.Wx.PublicAccount.Sdk.Abp

2）添加模块依赖

联系我们

订阅号

QQ群

文档官网&官方博客

其他开源库