Senparc.Weixin.Work 企业微信模块

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

然后，打开解决方案或项目所在目录，按 Ctrl+~，打开终端面板，进入需要添加 Senparc.Weixin.Work 的模块的项目的目录，输入：

dotnet add package Senparc.Weixin.Work

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

<ItemGroup>
    <PackageReference Include="Senparc.Weixin.Work" Version="3.14.10" />
</ItemGroup>

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

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

dotnet add package Senparc.Weixin.Work

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

<ItemGroup>
    <PackageReference Include="Senparc.Weixin.Work" Version="3.14.10" />
</ItemGroup>

"SenparcWeixinSetting": {
  //以下为 Senparc.Weixin 的 SenparcWeixinSetting 微信配置
  //注意：所有的字符串值都可能被用于字典索引，因此请勿留空字符串（但可以根据需要，删除对应的整条设置）！

  //微信全局
  "IsDebug": true,

  //以下不使用的参数可以删除，key 修改后将会失效

  //企业微信
  "WeixinCorpId": "#{WeixinCorpId}#",
  "WeixinCorpAgentId": "#{WeixinCorpAgentId}#",
  "WeixinCorpSecret": "#{WeixinCorpSecret}#",
  "WeixinCorpToken": "#{WeixinCorpToken}#",
  "WeixinCorpEncodingAESKey": "#{WeixinCorpEncodingAESKey}#"

  //可以追加更多其他平台的配置信息
}

MessageHandler 用于处理企业微信对话窗口的消息。

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

自定义 MessageHandler

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

WorkCustomMessageHandler.cs 本项目参考文件：

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

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

中间件方式承载 MessageHandler

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

app.UseMessageHandlerForWork("/WorkAsync", WorkCustomMessageHandler.GenerateMessageHandler, options =>
{
    options.AccountSettingFunc = context =>  Senparc.Weixin.Config.SenparcWeixinSetting;
});

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

测试 /WorkAsync

本项目参考文件：

测试 /Work

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

Controller 方式承载 MessageHandler

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

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

WorkController.cs 本项目参考文件：

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

测试 /Work

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

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

注意：
1、高级接口的配置和 MessageHandler 没有关联，两者可以独立或配合使用。
2、由于企业微信使用 CorpId + Secret 来定位（区别）每个应用的授权信息，因此，SDK 中将两者合并成一个唯一参数，命名为 AppKey，可通过 AccessTokenContainer.BuildingKey(string corpId, string corpSecret) 方法获取合成后的 AppKey。
3、企业微信 SDK 内几乎所有高级接口的第一个参数同时支持传入 AppKey 或 AccessToken，通常名称为 accessTokenOrAppKey，SDK 会根据参数特征自动识别输入的是 AppKey 还是 AccessToken，并做区分处理。

使用 AppKey 调用接口（推荐）

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

public async Task<IActionResult> TryApiTryApiByAppKey()
{
    // 获取注册信息
    var workWeixinSetting = Config.SenparcWeixinSetting.WorkSetting;
    // 获取 AppKey
    var appKey = AccessTokenContainer.BuildingKey(workWeixinSetting);
    //发送请求
    try
    {
        //发送文字提醒
        var result = await Senparc.Weixin.Work.AdvancedAPIs.MassApi.SendTextAsync(appKey, "001", "这是一条来企业微信的消息");
        return Content("OK");
    }
    catch (ErrorJsonResultException ex)
    {
        return Content($"出错啦：{ex.Message}");
    }
}

workWeixinSetting 参数，必须是已经经过注册的企业微信信息（内部包括 CorpId 和 Secret），这样即使AccessToken 过期，SDK也会全自动处理。如果是未经过注册的 CorpId 和 Secret，则需要先获取 AccessToken，然后调用接口。

本项目参考文件：

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

public async Task<IActionResult> TryApiByAccessToken()
{
    // 获取注册信息
    var workWeixinSetting = Config.SenparcWeixinSetting.WorkSetting;
    // 获取 AccessToken
    var accessToken = await AccessTokenContainer.GetTokenAsync(workWeixinSetting.WeixinCorpId, workWeixinSetting.WeixinCorpSecret);
    //发送请求
    try
    {
        //发送文字提醒
        var result = await Senparc.Weixin.Work.AdvancedAPIs.MassApi.SendTextAsync(accessToken, "001", "这是一条来企业微信的消息");
        return Content("OK");
    }
    catch (ErrorJsonResultException ex)
    {
        return Content($"出错啦：{ex.Message}");
    }
}

注意：使用 AccessToken 方式调用接口，无法保证当前 AccessToken 的有效性，因此建议使用前进行有效性校验，并使用 try-catch 方式捕获 AccessToken 不可用的异常，然后进行重试。因此直接使用 AccessToken 调用接口的方式并不推荐在常规情况下使用。

本项目参考文件：

JSSDK 用于提供微信内置浏览器接口的能力，例如转发控制、调用摄像头权限（拍照、视频）、文件上传、关闭窗口、唤起扫码窗口，等等。

要在内置浏览器中只用 JSSDK，分为“服务端获取签名信息”和“网页端配置 JSSDK”两步。

企业微信的网页端 JSSDK 配置，和公众号类似，不过多了一个名为 wx.agentConfig() 的配置方法。这里介绍常规的方法，wx.agentConfig() 配套方法请见【JSSDK（agentConfig】标签。

服务端获取签名信息

后端通过 JSSDKHelper.GetJsSdkUiPackageAsync() 方法即可自动获取前端所需的所有 JSSDK 运行所需参数：

public async Task<ActionResult> Index()
{
    // 当前 URL
    var url = "https://sdk.work.weixin.senparc.com/JSSDK/";
    // 获取企业微信配置
    var workSetting = Senparc.Weixin.Config.SenparcWeixinSetting.WorkSetting;
    // 获取 JsApiTicket（保密信息，不可外传）
    var jsApiTicket = await JsApiTicketContainer.GetTicketAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, false);
    // 获取 UI 打包信息
    var jsApiUiPackage = await JSSDKHelper.GetJsApiUiPackageAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, url, jsApiTicket, false);

    ViewData["jsApiUiPackage"] = jsApiUiPackage;
    return View();
}

本项目参考文件：

网页端配置 JSSDK

后端配置完成的参数，直接在前端 JS 中使用 wx.config 进行设置，例如以下代码将完成从企业微信内转发网页到个人微信：

$(function(){
    wx.config({
            beta: true,// 必须这么写，否则wx.invoke调用形式的jsapi会有问题
            debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
            appId: '@jsApiUiPackage.AppId', // 必填，企业微信的corpID
            timestamp: @jsApiUiPackage.Timestamp, // 必填，生成签名的时间戳
            nonceStr: '@jsApiUiPackage.NonceStr', // 必填，生成签名的随机串
            signature: '@jsApiUiPackage.Signature',// 必填，签名，见 附录-JS-SDK使用权限签名算法
            jsApiList: ['shareWechatMessage'] // 必填，需要使用的JS接口列表，凡是要调用的接口都需要传进来
        });

        wx.checkJsApi({
            jsApiList: ['shareWechatMessage'], // 需要检测的JS接口列表，所有JS接口列表见附录2,
            success: function(res) {
                // 以键值对的形式返回，可用的api值true，不可用为false
                // 如：{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
                //alert("wx.config success:"+JSON.stringify(res));
            }
        });
});

wx.ready(function(){
    // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});

wx.error(function(res){
    // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
    console.log(res);
    alert(res);
}

function invoke(){
    wx.invoke(
    "shareWechatMessage", {
            title: '企业微信JSSDK 演示-转发', // 分享标题
            desc: '来自 Senparc.Weixin.Work', // 分享描述
            link: 'https://sdk.work.weixin.senparc.com/JSSDK', // 分享链接
            imgUrl: '' // 分享封面
    }, function(res) {
    if (res.err_msg == "shareWechatMessage:ok") {
        }
        }
    );
}

HTML 页面进行触发：<a href="javascript:void(0)" onclick="invoke()">转发到微信</a>

本项目参考文件：

更多设置详情请参考：JS-SDK说明文档。

wx.agentConfig() 用于某些特定的接口（如审批流接口、剪切板接口等），但一般前提都需要先使用到常规的 JSSDK（参考【JSSDK（常规）】标签），因此这是一个增加项。

wx.agentConfig() 同样分为服务器端和客户端两部分。

服务端获取签名信息

后端除了后端通过 JSSDKHelper.GetJsSdkUiPackageAsync() 方法获取常规 JSSDK 运行所需参数以外，还需要使用同一个方法，传入不同参数来获取 agetntConfig 的对应参数：

public async Task<ActionResult> AgentConfig()
{
    //此处演示同时支持多个应用的注册，请参考 appsettings.json 文件
    var workSetting = Senparc.Weixin.Config.SenparcWeixinSetting["企业微信审批"] as ISenparcWeixinSettingForWork;
    var url = "https://sdk.weixin.senparc.com/Work/Approval";

    //获取 UI 信息包

    /* 注意：
    * 所有应用中，jsApiUiPackage 是必备的
    */
    var jsApiTicket = await JsApiTicketContainer.GetTicketAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, false);
    var jsApiUiPackage = await JSSDKHelper.GetJsApiUiPackageAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, url, jsApiTicket, false);
    ViewData["jsApiUiPackage"] = jsApiUiPackage;

    /* 注意：
    * 1、这里需要使用 WeixinCorpAgentId，而不是 WeixinCorpId
    * 2、agentJsApiUiPackage 是否需要提供，请参考官方文档，此处演示了最复杂的情况
    */
    ViewData["thirdNo"] = DateTime.Now.Ticks + Guid.NewGuid().ToString("n");
    ViewData["corpId"] = workSetting.WeixinCorpId;
    ViewData["agentId"] = workSetting.WeixinCorpAgentId;
    var agentConfigJsApiTicket = await JsApiTicketContainer.GetTicketAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, true);
    var agentJsApiUiPackage = await JSSDKHelper.GetJsApiUiPackageAsync(workSetting.WeixinCorpId, workSetting.WeixinCorpSecret, url, agentConfigJsApiTicket, true);
    ViewData["agentJsApiUiPackage"] = agentJsApiUiPackage;

    return View();
}

注意：上述方法中，使用了 Senparc.Weixin.Config.SenparcWeixinSetting["企业微信审批"] 来获取与之前不同的微信配置，请参考本项目中 appsetting.json 文件中的设置方法：

"Items": {
  //添加多个企业微信应用
  "企业微信审批": {
    "WeixinCorpId": "#{WeixinCorpId2}#",
    "WeixinCorpAgentId": "#{WeixinCorpAgentId2}#",
    "WeixinCorpSecret": "#{WeixinCorpSecret2}#",
    "WeixinCorpToken": "#{WeixinCorpToken2}#",
    "WeixinCorpEncodingAESKey": "#{WeixinCorpEncodingAESKey2}#"
  }

此方法对所有其他模块也通用（如公众号、小程序、微信支付等）。

本项目参考文件：

网页端配置 JSSDK

网页端除了进行常规的 JSSDK 配置以外，还需要在执行特定的 JsApi 方法之前，添加 wx.agentConfig() 的配置：

function invoke(){
    wx.agentConfig({
        corpid: '@ViewData["corpId"]', // 必填，企业微信的corpid，必须与当前登录的企业一致
        agentid: '@ViewData["agentId"]', // 必填，企业微信的应用id （e.g. 1000247）
        timestamp: @agentJsApiUiPackage.Timestamp, // 必填，生成签名的时间戳
        nonceStr: '@agentJsApiUiPackage.NonceStr', // 必填，生成签名的随机串
        signature: '@agentJsApiUiPackage.Signature',// 必填，签名，见附录-JS-SDK使用权限签名算法
        jsApiList: ['thirdPartyOpenPage'], //必填，传入需要使用的接口名称
        success: function(res) {

            // 回调
            wx.invoke('thirdPartyOpenPage', {
                "oaType": "10001",// String
                //"templateId": "C4NxepvGj51gbkeGXHQgYRArW96WrxRinNfyCxo7N",//SYS
                "templateId":"247bcb886d0374a0a1f749c52794ba1a_622421053",// Open
                "thirdNo": "",// String
                "extData": {
                    'fieldList': [{
                        'title': '审批类型',
                        'type': 'text',
                        'value': '文章审批',
                    },
                    {
                        'title': '预览',
                        'type': 'link',
                        'value': 'https://weixin.senparc.com',
                    }],
                }
            },
            function(res) {
                // 输出接口的回调信息
                console.log(res);
                alert('wx.invoke result:'+JSON.stringify(res));
            });
        },
        fail: function(res) {
            if(res.errMsg.indexOf('function not exist') > -1){
                alert('版本过低请升级')
            }
            else{
                alert('wx.invoke fail:'+JSON.stringify(res));
            }
        }
    });
}

HTML 页面进行触发：<a href="javascript:void(0)" onclick="invoke()">点击唤起审批流程</a>

本项目参考文件：

当你需要在网页上获取用户的 UserId、头像、称呼等信息的时候，就需要使用 OAuth 2.0 的方式和微信服务器通讯。

更多信息请参考官方文档：网页授权登录。

SDK 已经封装了所有相关的过程，您只需要参考示例进行简单的 3 步配置即可。

第一步：设置登录页面

登录页面中需要设置官方 OAuth 2.0 的请求 URL（称为 AuthorizeUrl），并带上登录成功后的 returnUrl。

由于微信授权具有两种方式：snsapi_userinfo 和 snsapi_base，企业自建应用使用 snsapi_base，因此本示例中使用此方式进行介绍 snsapi_base（默认）的 AuthorizeUrl 获取的方式（此方式也是所有场景下兼容的方式）：

public IActionResult Index(string returnUrl)
{
    // 设置自己的 URL
    var url = "https://4424-222-93-135-159.ngrok.io";

    //此页面引导用户点击授权
    var oauthUrl =
        OAuth2Api.GetCode(_corpId, $"{url}/OAuth2/BaseCallback?returnUrl={returnUrl.UrlEncode()}",
            null, null);//snsapi_base方式回调地址

    ViewData["UrlBase"] = oauthUrl;
    ViewData["returnUrl"] = returnUrl;

    return View();
}

上述 returnUrl 参数一般为跳转到登陆页面之前的 URL，也可以是希望用户完成授权之后跳转到的 URL。

注意：上述的网址和路径需要在公众号后台匹配成你自己服务器的地址（参考文档：网页授权登录）。

本项目参考文件：

第二步：前端登录页面设置

登录页面最终的功能是引导用户打开 AuthorizeUrl，可以直接使用连接的方式：

<a href="@ViewData["UrlBase"]">点击这里测试snsapi_base</a>

本项目参考文件：

第三步：配置登陆后回调页面

授权成功后，网页将自动跳转到第一步中设置的回调 URL（$"{url}/OAuth2/BaseCallback?returnUrl={returnUrl.UrlEncode()}"）：

public async Task BaseCallback(string code, string returnUrl)
{
    if (string.IsNullOrEmpty(code))
    {
        return Content("您拒绝了授权！");
    }

    try
    {
        var appKey = AccessTokenContainer.BuildingKey(_workWeixinSetting);
        var accessToken = await AccessTokenContainer.GetTokenAsync(_corpId, _corpSecret);
        //获取用户信息 测试链接：https://open.work.weixin.qq.com/wwopen/devtool/interface?doc_id=10019
        var oauthResult = await OAuth2Api.GetUserIdAsync(accessToken, code);
        var userId = oauthResult.UserId;
        GetMemberResult result = await MailListApi.GetMemberAsync(appKey, userId);

        if (result.errcode != ReturnCode_Work.请求成功)
        {
            return Content("错误：" + result.errmsg);
        }

        ViewData["returnUrl"] = returnUrl;

        /* 注意：
        * 实际适用场景，此处应该跳转到 returnUrl，不要停留在 Callback页面上。
        * 因为当用户刷新此页面 URL 时，实际 code 等参数已失效，用户会受到错误信息。
        */
        return View(result);
    }
    catch (Exception ex)
    {
        return Content("错误：" + ex.Message);
    }
}

上述代码中，传入的 returnUrl 即第一步 Index() 方法中传入到 AuthorizeUrl 中的 returnUrl，当所有用户信息获取、保存等操作完成后，借助 returnUrl 跳转到登陆之前的页面，完成整个闭环的登录操作。

本项目参考文件：

自定义菜单是企业微信应用界面的重要元素，菜单的使用分为 设置 和 使用 两个环节。

设置

方法一：在企业微信后台【应用管理】中，某个应用设置界面中，【功能】区域【自定义菜单】中设置（不使用开发模式），此处略。

方法二：使用代码进行设置（只需要执行一次，建议放在管理员后台，手动运行），如：

public async Task CreateMenuTest()
{
    ButtonGroup bg = new ButtonGroup();

    //单击
    bg.button.Add(new SingleClickButton()
    {
        name = "单击测试",
        key = "OneClick",
        type = MenuButtonType.click.ToString(),//默认已经设为此类型，这里只作为演示
    });

    //二级菜单
    var subButton = new SubButton()
    {
        name = "二级菜单"
    };
    subButton.sub_button.Add(new SingleClickButton()
    {
        key = "SubClickRoot_Text",
        name = "返回文本"
    });
    subButton.sub_button.Add(new SingleViewButton()
    {
        url = "https://weixin.senparc.com",
        name = "Url跳转"
    });
    bg.button.Add(subButton);

    var workWeixinSetting = Config.SenparcWeixinSetting.WorkSetting;
    var appKey = AccessTokenContainer.BuildingKey(workWeixinSetting);
    int agentId;
    if (!int.TryParse(workWeixinSetting.WeixinCorpAgentId, out agentId))
    {
        throw new WeixinException("WeixinCorpAgentId 必须为整数！");
    }
    var result = await CommonApi.CreateMenuAsync(appKey, agentId, bg);

    Assert.IsNotNull(result);
    Assert.AreEqual("ok", result.errmsg);
}

使用

设置完菜单后，当客户端点击菜单时，微信服务器会自动推送响应的回调信息到消息 URL（即已经设置好的 MessageHandler 内），只需在 WorkCustomMessageHandler 中重写（override）对应的方法即可。如针对上述 方法二 已经设定生效的菜单，当用户点击【单击测试】按钮时，我们可以在 WorkCustomMessageHandler 中进行接收和处理：

public override IWorkResponseMessageBase OnEvent_ClickRequest(RequestMessageEvent_Click requestMessage)
{
    var reponseMessage = CreateResponseMessage();

    if (requestMessage.EventKey == "SubClickRoot_Text")
    {
        reponseMessage.Content = "您点击了【返回文本】按钮";
    }
    else
    {
        reponseMessage.Content = "您点击了其他事件按钮";
    }

    return reponseMessage;
}

本项目参考文件：