概述

最簡潔最易於使用的微信Sdk，包括公眾號Sdk、小程式Sdk、企業微信Sdk等，以及Abp VNext整合。

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

如何貢獻？

如何快速封裝一個微信介面？（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）
  •  個性化選單介面
  •  獲取自定義選單配置

•  訂閱通知

  •  選用模板
  •  刪除模板
  •  獲取公眾號類目
  •  獲取模板中的關鍵詞
  •  獲取所屬類目的公共模板
  •  獲取私有模板列表
  •  傳送訂閱通知

•  客服訊息

  •  客服管理（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）

•  對話能力

  •  顧問管理
    •  新增顧問
    •  獲取顧問資訊
    •  修改顧問資訊
    •  刪除顧問
    •  獲取服務號顧問列表
    •  生產顧問二維碼
    •  掃顧問二維碼後的事件推送
    •  獲取顧問聊天記錄
    •  設定快捷回覆與關注自動回覆
    •  獲取快捷回覆與關注自動回覆
    •  設定離線自動回覆與敏感詞
    •  獲取離線自動回覆與敏感詞
    •  新建顧問分組
    •  獲取顧問分組列表
    •  獲取顧問分組資訊
    •  分組內新增顧問
    •  分組內刪除顧問
    •  獲取顧問所在分組
    •  刪除顧問分組
  •  客戶管理
    •  為顧問分配客戶
    •  為顧問移除客戶
    •  獲取顧問的客戶列表
    •  為客戶更好顧問
    •  修改客戶暱稱
    •  查詢客戶所屬顧問
    •  查詢指定顧問和客戶的關係
  •  標籤管理
    •  新建標籤型別
    •  刪除標籤型別
    •  為標籤新增可選值
    •  獲取標籤和可選值
    •  為客戶設定標籤
    •  查詢客戶標籤
    •  根據標籤值刷選客戶
    •  刪除客戶標籤
    •  設定自定義客戶資訊
    •  獲取自定義客戶資訊
  •  素材管理
    •  新增小程式卡片素材
    •  查詢小程式卡片素材
    •  刪除 小程式卡片素材
    •  新增圖片素材
    •  查詢圖片素材
    •  刪除圖片素材
    •  新增文字素材
    •  查詢文字素材
    •  刪除文字素材
  •  群發任務管理
    •  新增群發任務
    •  獲取群發任務列表
    •  獲取指定群發任務資訊
    •  修改群發任務
    •  取消群發任務

•  素材管理（IMediaApi）

  •  新增臨時素材（UploadAsync）
  •  獲取臨時素材
  •  新增永久素材
  •  獲取永久素材
  •  刪除永久素材
  •  修改永久圖文素材
  •  獲取素材總數
  •  獲取素材列表

•  圖文訊息留言管理

•  使用者管理

  •  使用者標籤管理
  •  設定使用者備註名
  •  獲取使用者基本資訊（UnionID機制）
  •  獲取使用者列表
  •  獲取使用者地理位置
  •  黑名單管理

•  賬號管理

  •  生產帶引數的二維碼
  •  長連結轉短連結介面
  •  短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();
        }

4）呼叫Api

接下來就簡單了，通過依賴注入的方式注入相關Api，比如建構函式注入：

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

然後就可以使用了，如下面程式碼：

        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>();