Senparc.Weixin.WxOpen 微信小程序模块

首先，确认已经安装好 VS Code 以及 dotnet 命令行（安装 .NET SDK 后会自动安装）。

然后，打开解决方案或项目所在目录，按 Ctrl+~，打开终端面板：

进入需要添加 Senparc.Weixin.WxOpen 的模块的项目的目录，输入：

dotnet add package Senparc.Weixin.WxOpen

安装完成后，可查看对应 .csproj 文件，被添加引用，如：

<ItemGroup>
    <PackageReference Include="Senparc.Weixin.WxOpen" Version="3.14.10.1" />
</ItemGroup>

首先，确认已经安装好 dotnet 命令行（安装 .NET SDK 后会自动安装）。

进入需要添加 Senparc.Weixin.WxOpen 的模块的项目的目录，输入：

dotnet add package Senparc.Weixin.WxOpen

安装完成后，可查看对应 .csproj 文件，被添加引用，如：

<ItemGroup>
    <PackageReference Include="Senparc.Weixin.WxOpen" Version="3.14.10.1" />
</ItemGroup>

  "SenparcWeixinSetting": {
    "IsDebug": true,

    //小程序
    "WxOpenAppId": "#{WxOpenAppId}#",
    "WxOpenAppSecret": "#{WxOpenAppSecret}#",
    "WxOpenToken": "#{WxOpenToken}#",
    "WxOpenEncodingAESKey": "#{WxOpenEncodingAESKey}#"
  }

MessageHandler 用于处理小程序客服对话窗口的消息以及其他微信服务器的推送信息。

SDK 已经为开发者准备好了所有需要的基础功能，开发者只需要创建一个自定义的子类，补充需要自定义的业务逻辑。

自定义 MessageHandler

当前示例中，我们给自定义的 MessageHandler 取名 CustomWxOpenMessageHandler。

CustomWxOpenMessageHandler.cs 本项目参考文件：

CustomWxOpenMessageHandler.cs 中所有演示的重写（override）方法中，只有 DefaultResponseMessageAsync() 方法是必须重写的，其他所有 OnXxxRequestAsync() 方法都为可选，当用户发送的消息，找不到对应重写方法时，则调用 DefaultResponseMessageAsync() 方法。

MessageHandler 有两种承载方式，使其可以被外部（微信服务器）通过 URL 访问到。分别是中间件方式（推荐）和 Controller 方式。两种方式所使用的 CustomWxOpenMessageHandler 是通用的，因此可以随时切换和共存。

中间件方式承载 MessageHandler

中间件方式是推荐的方式，也是最简化的方式，无需创建任何新文件，只需在 Program.cs 文件所有 Senparc.Weixin 注册代码执行后的下方，引入中间件：

app.UseMessageHandlerForWxOpen("/WxOpenAsync", CustomWxOpenMessageHandler.GenerateMessageHandler, options =>
{
    options.AccountSettingFunc = context =>  Senparc.Weixin.Config.SenparcWeixinSetting;
});
                

完成后，即可通过Url 域名/WxOpenAsync 访问 MessageHandler，设置为公众号后台的消息 URL。

测试 /WxOpenAsync

本项目参考文件：

更多中间件方式请参考：《在 .NET Core 2.0/3.0 中使用 MessageHandler 中间件》（同样适用于 .NET 6.0 及以上，用法和公众号相同）。

Controller 方式承载 MessageHandler

当中间件的方式满足不了需求时，可以使用 Controller 将执行过程“展开”，对每一步执行进行更加精确的控制或干预。

使用 Controller 方式，需要创建 2 个 Action（ActionName 都为 Index），分别对应微信后台验证（Get 请求），以及真实消息推送（Post 请求）。本项目示例位于 WxOpenController.cs 中。

WxOpenController.cs 本项目参考文件：

完成后，即可通过Url 域名/WxOpen 访问 MessageHandler，设置为公众号后台的消息 URL。

测试 /WxOpen

更多 Controller 方式请参考：《了解MessageHandler》（推荐使用全套异步方法，基本用法和公众号相同）

完成 Program.cs 文件中的常规注册后，即可在程序的任意地方使用高级接口。

注意：
1、高级接口的配置和 MessageHandler 没有关联，两者可以独立或配合使用。
2、SDK 内几乎所有高级接口的第一个参数同时支持传入 AppId 或 AccessToken，通常名称为 appIdOrAccessToken，SDK 会根据参数特征自动识别输入的是 AppId 还是 AccessToken，并做区分处理。

使用 AppId 调用接口（推荐）

例如，我们可以在任意一个方法中调用一个高级接口：

using Senparc.Weixin.WxOpen.AdvancedAPIs;

var appId = Senparc.Weixin.Config.SenparcWeixinSetting.WxOpenAppId;
var openId = "xxx";
var content = "这是一条客服消息";
var result = await CustomApi.SendTextAsync(appId, openId, content);//发送客服消息

appId 参数，必须是已经经过注册的，这样即使 AccessToken 过期，SDK也会全自动处理。如果是未经过注册的 appId，则需要先获取 AccessToken，然后调用接口。

使用 AccessToken 调用接口（不推荐）

var accessToken = Senparc.Weixin.MP.CommonApi.GetTokenAsync(appId, appSecret);//获取 AccessToken
var openId = "xxx";
var content = "这是一条客服消息";
var result = await CustomApi.SendTextAsync(accessToken, openId, content);//发送客服消息

注意：
1、使用 AccessToken 方式调用接口，无法保证当前 AccessToken 的有效性，因此建议使用前进行有效性校验，并使用 try-catch 方式捕获 AccessToken 不可用的异常，然后进行重试。因此直接使用 AccessToken 调用接口的方式并不推荐在常规情况下使用。
2、小程序和公众号使用相同的 AccessToken 获取接口，因此，此处调用了 Senparc.Weixin.MP 类库中公众号的相同方法。因为 Senparc.Weixin.WxOpen 模块默认已经依赖了 Senparc.Weixin.MP，所以不必再手动安装 MP 模块。

准备开发

开发小程序客户端（手机微信内展示的小程序界面），需要使用 微信开发者工具。

微信小程序示例项目参考文件：

上述示例项目打开后如下图所示：

小程序客户端可以使用类似 Ajax 的功能对服务器端发送请求，并且获取响应信息（一般为 JSON）。

放置触发请求的按钮

在完成【客户端开发】的基本准备工作后，在页面上（如 /pages/index/index.wxml），创建一个按钮，用于触发请求：

<button type="primary" bindtap="doRequest" 
hover-class="other-button-hover" class="btn-DoRequest">
获取数据
</button>

上述代码中，type、class、hover-class 分别设置了按钮的类型、常规样式、点击样式，bindtap="doRequest" 指定了点击之后，由 doRequest() 方法（function）进行处理。

本项目参考文件：

请求服务器方法

doRequest() 方法写在 index.js 文件中：

//处理wx.request请求
doRequest:function(){
  var that = this;
  wx.request({
    url: wx.getStorageSync('domainName') + '/WxOpen/RequestData',
    data: { nickName : that.data.userInfo.nickName},
    method: 'POST', // OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT
    header: { 'content-type':'application/x-www-form-urlencoded'}, 
    success: function(res){
      // success
      var json = res.data;
      //模组对话框
      wx.showModal({
        title: '收到消息',
        content: json.msg,
        showCancel:false,
        success: function(res) {
          if (res.confirm) {
            console.log('用户点击确定')
          }
        }
      });
    },
    fail: function() {
      // fail
    },
    complete: function() {
      // complete
    }
  })
},

上述代码中：

1. wx.request(...) 方法用于向服务器端发起请求，类似其他 JS 框架中的 axios.get() / .post() 或 $.ajax() 等。
2. url 用于指定需要发送到的 API 地址。其中，wx.getStorageSync('domainName') 用于灵活指定开发环境或生产环境的域名（见本目录 app.js 文件。
3. data 用于存放需要提交的数据，此处我们从本地数据中心取 userInfo.nickName，当用户登陆后，即可取到微信昵称，否则为 undefined。
4. method 为请求的方法名称，当前使用 POST 方式提交。
5. header 用于指定当前请求 Header 中的参数，通常也可以在 JWT 模式中提供用于用户身份验证的 Token。
6. success 为当前请求成功响应（200）后的回调，示例中的代码展示了当收到成功信息后，弹出一个模组对话框，显示返回的内容，并在点击【确定】按钮后，在控制台输出相关日志。
7. fail 和 complete 方法分别用于处理失败的请求，以及整个请求完成后的统一操作。

本项目参考文件：

服务器端接口

服务器端可以使用各类能够接受请求的方式，如页面、MVC 中的 Action、Web Api、中间件（Middleware），甚至 aspx、ashx 等。

上述请求地址在本地环境下为：https://localhost:44367/WxOpen/RequestData，我们在 WxOpenController 下面创建一个 RequestData 的 Action 用于接收请求：

[HttpPost]
public ActionResult RequestData(string nickName)
{
    var data = new
    {
        msg = string.Format("服务器时间：{0}，昵称：{1}", SystemTime.Now.LocalDateTime, nickName)
    };
    return Json(data);
}

本项目参考文件：

测试

点击【获取数据】按钮：

由于当前没有登录，所以昵称无法获取到，登陆后即可显示昵称。

提示：登录操作请见【登录】标签。

点击【确定】按钮：

简介

大部分的小程序都需要识别用的身份信息（OpenId）以及获取用户的头像、昵称等信息为用户提供身份识别、个性化信息展示的服务。此时就需要使用到小程序登录接口。

客户端 - 进入登录页

用户的登录是在小程序端发起的，一般而言可以做一个独立的页面用于放置说明及登录按钮。首先，在入口网页放置一个入口按钮：

<button bindtap="getUserInfo"> 获取头像昵称 </button>

点击按钮后，触发 .js 文件中的 getUserInfo() 方法：

  getUserInfo: function(){
    wx.navigateTo({
      url: '../Login/Login',
    })
  }

此按钮将引导页面跳转到独立的 Login 页面。

本项目参考文件：

客户端 - 登录页

登录页包含系统登录展示、隐私协议等内容，并包含一个触发最终小程序客户端登录事件的按钮：

<!--pages/Login/Login.wxml-->
<view class="auth-notice">
      <text class="auth-notice">您好，</text><open-data type="userNickName" id="login-nickname"></open-data>，
      <text class="auth-notice">当前小程序为 Senparc.Weixin SDK 的功能体验小程序，包括了订阅消息、获取用户授权信息、手机号、WebSocket、客服消息等演示内容，大部分内容需要授权后进行，点击【获取头像昵称】按钮进行授权，才能进入测试页面。</text>
      <text class="auth-notice">如果您不希望授权，请直接关闭此页面。</text>
      <button class="auth-btn" bindtap="getUserInfo"> 获取头像昵称 </button>
</view>

本项目参考文件：

【获取头像昵称】按钮绑定了方法 getUserInfo()，在 Login.js 中添加：

var app = getApp()
getUserInfo: function (e) {
    var that = this;
    app.getUserInfo(e, function(userInfo){
      app.globalData.userInfo = userInfo
      that.setData({
        userInfo: userInfo,
        hasUserInfo: true
      });
      wx.navigateTo({
        url: '../index/index',
      })
    });
  }

本项目参考文件：

上述代码中，使用 var app = getApp() 引入了全局方法（代码在根目录 app.js中），其中，app.getUserInfo() 方法代码如下（为了更加贴近实际使用场景，我们将 登录 + 获取用户信息 放在连贯的代码中展示）：

getUserInfo:function(cb,callback){
    var that = this
    if(this.globalData.userInfo){
      typeof cb == "function" && cb(this.globalData.userInfo)
    }else{
    //获取userInfo并校验
    console.log('准备调用 wx.getUserProfile');
    wx.getUserProfile({
      desc: '用于完善会员资料', // 声明获取用户个人信息后的用途，后续会展示在弹窗中，请谨慎填写
      success: function (userInfoRes) {
        console.log('get getUserProfile', userInfoRes);
        that.globalData.userInfo = userInfoRes.userInfo
        typeof cb == "function" && cb(that.globalData.userInfo)
        typeof callback == "function" && callback(userInfoRes.userInfo)

        //调用登录接口
        wx.login({
            success: function (res) {
              //换取openid & session_key
              wx.request({
                url: wx.getStorageSync('domainName') + '/WxOpen/OnLogin',
                method: 'POST',
                header: { 'content-type': 'application/x-www-form-urlencoded' },
                data: {
                  code: res.code
                },
                success:function(json){
                  console.log('wx.login - request-/WxOpen/OnLogin Result:', json);
                  var result = json.data;
                  if(result.success)
                  {
                    wx.setStorageSync('sessionId', result.sessionId);
                    //校验
                    wx.request({
                      url: wx.getStorageSync('domainName') + '/WxOpen/CheckWxOpenSignature',
                      method: 'POST',
                      header: { 'content-type': 'application/x-www-form-urlencoded' },
                      data: {
                        sessionId: result.sessionId,//wx.getStorageSync('sessionId'),
                        rawData:userInfoRes.rawData,
                        signature:userInfoRes.signature
                      },
                      success:function(json){
                        console.log(json.data);
                        if(!json.data.success){
                          alert(json.data.msg);
                        }
                      }
                    });

                    //解密数据（建议放到校验success回调函数中，此处仅为演示）
                    wx.request({
                      url: wx.getStorageSync('domainName') + '/WxOpen/DecodeEncryptedData',
                      method: 'POST',
                      header: { 'content-type': 'application/x-www-form-urlencoded' },
                      data: {
                        'type':"userInfo",
                        sessionId: result.sessionId,//wx.getStorageSync('sessionId'),
                        encryptedData: userInfoRes.encryptedData,
                        iv: userInfoRes.iv
                      },
                      success:function(json){
                        console.log('数据解密：', json.data);
                      }
                    });
                  }else{
                    console.log('储存session失败！',json);
                  }
                }
              })
            }
          })
        }
      });
    }
  }

上述代码是整个微信登录客户端的核心代码。

其中：

1. wx.getUserProfile 用于调起获取用户信息的接口，此接口本身和登录行为本身无直接联系，但是为了保证用户信息的正确性，后续需要在登录成功后的回调中使用到其中的加密信息来获取真实的用户信息，因此需要首先触发。
2. wx.login 是小程序客户端的登录接口，其中 success 为登录自后的回调函数。在回调函数中，我们使用 wx.request 向服务器端 /WxOpen/OnLogin 地址发送一条请求，带上 success 回调的参数 res.code，其中将使用 code 利用服务器端的 API 换取 session_key，并储存在服务器端，同时生成临时的用户身份标记 SessionId 并返回给客户端。
   成功回调后，再使用 wx.setStorageSync('sessionId', result.sessionId); 将收到的 SessionId 储存在本地缓存中。
   
3. 虽然 userInfoRes.rawData 已经提供了明文的用户信息，但并不能确保其是安全（未经篡改或完整）的，因此需要向服务器发送请求，验证其真实性。
   继续使用 wx.request 方法请求 /WxOpen/CheckWxOpenSignature 地址，发送 sessionId以及第 1 步中获取到的 userInfoRes.rawData 以及 userInfoRes.signature，校验信息的真实性。验证通过后，可以在客户端直接使用 rawData。

   注意：有的开发者会把经过验证后的 rawData 发送给服务器保存，认为此信息是有效的，这是具有风险的做法，应当抛弃，正确的做法是使用上述代码中后续的方式（/WxOpen/DecodeEncryptedData）发送 userInfoRes.encryptedData 给服务器解密。因为：第一，rawData 从被验证成功到明文发送给服务器的过程中无法确保是否被篡改；第二，明文传输用户的敏感信息容易被监听和窃取，这种做法本身不应该出现在整个项目的任何地方。

4. 真实性（签名）验证通过后，继续使用 wx.request 请求服务器 /WxOpen/DecodeEncryptedData 地址，发送 sessionId以及第 1 步中获取到的 userInfoRes.encryptedData 以及 userInfoRes.iv，服务器端将解密 encryptedData 获得用户信息，并储存。

本项目参考文件：

服务器端 - OnLogin

服务器端 /WxOpen/OnLogin 代码如下：

[HttpPost]
public ActionResult OnLogin(string code)
{
    try
    {
        var jsonResult = SnsApi.JsCode2Json(WxOpenAppId, WxOpenAppSecret, code);
        if (jsonResult.errcode == ReturnCode.请求成功)
        {
            //Session["WxOpenUser"] = jsonResult;//使用Session保存登陆信息（不推荐）
            //使用SessionContainer管理登录信息（推荐）
            var unionId = "";
            var sessionBag = SessionContainer.UpdateSession(null, jsonResult.openid, jsonResult.session_key, unionId);

            //注意：生产环境下SessionKey属于敏感信息，不能进行传输！
            return Json(new { success = true, msg = "OK", sessionId = sessionBag.Key, sessionKey = sessionBag.SessionKey/* 此参数千万不能暴露给客户端！处仅作演示！ */ });
        }
        else
        {
            return Json(new { success = false, msg = jsonResult.errmsg });
        }
    }
    catch (Exception ex)
    {
        return Json(new { success = false, msg = ex.Message });
    }
}

特别注意：SessionKey 是非常敏感的信息，上述代码只是做演示，向客户端证明已经生成，实际开发过程中不可传递到客户端！

本项目参考文件：

服务器端 - CheckWxOpenSignature

服务器端 /WxOpen/CheckWxOpenSignature 代码如下：

[HttpPost]
public ActionResult CheckWxOpenSignature(string sessionId, string rawData, string signature)
{
    try
    {
        var checkSuccess = Senparc.Weixin.WxOpen.Helpers.EncryptHelper.CheckSignature(sessionId, rawData, signature);
        return Json(new { success = checkSuccess, msg = checkSuccess ? "签名校验成功" : "签名校验失败" });
    }
    catch (Exception ex)
    {
        return Json(new { success = false, msg = ex.Message });
    }
}

本项目参考文件：

服务器端 - DecodeEncryptedData

服务器端 /WxOpen/DecodeEncryptedData 代码如下：

public async Task<IActionResult> DecodeEncryptedData(string type, string sessionId, string encryptedData, string iv)
{
    DecodeEntityBase decodedEntity = null;

    try
    {
        switch (type.ToUpper())
        {
            case "USERINFO"://wx.getUserInfo()
                decodedEntity = EncryptHelper.DecodeUserInfoBySessionId(
                    sessionId,
                    encryptedData, iv);
                break;
            default:
                break;
        }
    }
    catch (Exception ex)
    {
        WeixinTrace.SendCustomLog("EncryptHelper.DecodeUserInfoBySessionId 方法出错",
            $@"sessionId: {sessionId}
encryptedData: {encryptedData}
iv: {iv}
sessionKey: { (await SessionContainer.CheckRegisteredAsync(sessionId)
        ? (await SessionContainer.GetSessionAsync(sessionId)).SessionKey
        : "未保存sessionId")}

异常信息：
{ex.ToString()}
");
    }

    //检验水印
    var checkWatermark = false;
    if (decodedEntity != null)
    {
        checkWatermark = decodedEntity.CheckWatermark(WxOpenAppId);

        //保存用户信息（可选）
        if (checkWatermark && decodedEntity is DecodedUserInfo decodedUserInfo)
        {
            var sessionBag = await SessionContainer.GetSessionAsync(sessionId);
            if (sessionBag != null)
            {
                await SessionContainer.AddDecodedUserInfoAsync(sessionBag, decodedUserInfo);
            }
        }
    }

    //注意：此处仅为演示，敏感信息请勿传递到客户端！
    return Json(new
    {
        success = checkWatermark,
        //decodedEntity = decodedEntity,
        msg = $"水印验证：{(checkWatermark ? "通过" : "不通过")}"
    });
}

本项目参考文件：

完成

完成代码后，运行服务器端程序和小程序客户端，在客户端中点击【获取头像昵称】按钮，进入登录页面，点击【获取头像昵称】按钮，即可看到弹出系统确认授权对话窗口：

点击【允许】按钮，即可自动完成整个自动登录、用户信息抓取过程：

此时，再点击【获取数据】按钮，即可看到已经获取到的用户信息：

注意：小程序获取手机号的接口，进行过一次升级，先前在客户端直接获取手机号的方式已经被淘汰（示例中左侧【获取手机号】按钮），目前最新的接口是使用 code 到服务器端后台获取手机号（示例中右侧【获取手机号（Code）】按钮。

当用户点击后，系统进行授权提示：

点击【允许】按钮，通过访问后端接口，获取到手机号：

客户端

在 Index.wxml 文件中放置按钮：

<button open-type="getPhoneNumber" bindgetphonenumber="getUserPhoneNumber" type="primary"
        class="btn-DoRequest" hover-class="other-button-hover" >获取手机号（code）</button>

本项目参考文件：

上述代码中，open-type="getPhoneNumber" 指定了当前按钮获取手机号的用途，bindgetphonenumber="getUserPhoneNumber" 指定了处理方法为 getUserPhoneNumber（对应于 .js 文件中）：

getUserPhoneNumber:function(e){
    wx.request({
      url: wx.getStorageSync('domainName') + '/WxOpen/GetUserPhoneNumber?code=' + e.detail.code,
      success: function (res) {
        // success
        var json = res.data;

        if(!json.success){
          wx.showModal({
            title: '解密过程发生异常',
            content: json.msg,
            showCancel: false
          });          
          return;
        }

        //模组对话框
        var phoneNumberData = json.phoneInfo;
        var msg = '手机号：' + phoneNumberData.phoneNumber+
          '\r\n手机号（不带区号）：' + phoneNumberData.purePhoneNumber+
          '\r\n区号（国别号）' + phoneNumberData.countryCode+
          '\r\n水印信息：' + JSON.stringify(phoneNumberData.watermark);

        wx.showModal({
          title: '收到服务器端通过 code 获取的手机号信息',
          content: msg,
          showCancel: false
        });
      }
    })
  }

当用户点击按钮，并授权手机号后，就会触发上述方法，通过 e 参数提供的 e.code，将其提交给服务器后台 /WxOpen/GetUserPhoneNumber 地址，后台将使用 code 换取用户的手机号，然后进行储存或返回给前端。上述代码的模组对话框只是演示作用，实际项目中一般不需要再次弹出信息。

本项目参考文件：

后端代码 - GetUserPhoneNumber

public async Task GetUserPhoneNumber(string code)
{
    try
    {
        var result = await BusinessApi.GetUserPhoneNumberAsync(WxOpenAppId, code);
        return Json(new { success = true, phoneInfo = result.phone_info });
    }
    catch (Exception ex)
    {
        return Json(new { success = false, msg = ex.Message });
    }
}

本项目参考文件：

更多接口用法，可参考【获取手机号】中的方法，参考客户端（.wxml、.js）以及后端（WxController.cs）文件，用法几乎都是一致的。

后端本项目参考文件：

客户端参考文件：