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