Bitzsoft.Integrations.TeamWork.WeCom 1.0.0-alpha.10

Bitzsoft.Integrations.TeamWork.WeCom

企业微信协同办公服务实现 — 对接企业微信服务端 API。

功能特性

基于 Bitzsoft.Integrations.TeamWork 抽象层实现：

• 组织架构：部门列表（全量/子树过滤）、成员增删改查（department/*、user/*）
• 消息推送：文本应用消息、文本卡片消息（message/send）
• 审批流：发起审批（oa/applyevent XML）、状态查询（oa/getapprovaldetail）
• SSO 登录：OAuth2 扫码授权、code 换用户身份（auth/getuserinfo）、用户敏感信息（auth/getuserdetail）
• 健康检查：通讯录调用探活
• 客户联系（企业微信特有）：外部联系人列表、客户群列表
• 第三方请求日志：内置 RequestLogging DelegatingHandler，记录所有出站 HTTP 请求与响应

认证机制（多 secret）

企业微信采用应用级权限隔离，不同业务线使用不同 secret 换取的 access_token，互不通用：

WeComTokenManager 按用途（WeComTokenScope）独立缓存三类 access_token，双重检查锁 + SemaphoreSlim 防并发刷新，提前 300 秒过期。各 API 调用按需取对应用途令牌。当服务端返回 token 失效类错误码（42001/40014/42009）时，自动失效对应用途的缓存令牌，下次调用强制刷新。

平台限制（抛 NotSupportedException）

企业微信暂未提供以下能力，对应接口抛 NotSupportedException：

• 统一待办（ITeamWorkTodoProvider 全部）：平台无统一待办 API，建议审批回调 + 自建待办中台。
• 消息撤回（RecallMessageAsync）：应用消息不支持撤回。
• 审批撤回（RecallApprovalAsync）：不支持 API 撤回审批。
• 令牌刷新（RefreshAccessTokenAsync）：OAuth2 无刷新令牌，需重新授权。
• 添加外部联系人（AddExternalContactAsync）：外部联系人通过成员分享添加。

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.TeamWork.WeCom

PackageReference

<PackageReference Include="Bitzsoft.Integrations.TeamWork.WeCom" Version="1.0.0" />

配置

appsettings.json

{
  "TeamWork": {
    "WeCom": {
      "CorpId": "企业 CorpId",
      "AgentId": 1000002,
      "Secrets": {
        "Contacts": "通讯录同步 Secret",
        "Message": "应用消息 Secret",
        "ExternalContact": "客户联系 Secret"
      },
      "BaseUrl": "https://qyapi.weixin.qq.com",
      "OpenBaseUrl": "https://open.work.weixin.qq.com"
    }
  }
}

配置在 DI 注册时经 WeComOptionsValidator 校验，必填项缺失或 URL 非 HTTPS 将启动即失败。

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.TeamWork.WeCom;

builder.Services.AddBitzsoftWeComTeamWork(
    builder.Configuration, "TeamWork:WeCom");

委托配置

builder.Services.AddBitzsoftWeComTeamWork(opts =>
{
    opts.CorpId = "your-corp-id";
    opts.AgentId = 1000002;
    opts.Secrets = new WeComSecrets
    {
        Contacts = "your-contacts-secret",
        Message = "your-message-secret"
    };
});

第三方请求日志

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认使用 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftWeComTeamWork(configuration, "TeamWork:WeCom");

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftWeComTeamWork(configuration, "TeamWork:WeCom");

使用示例

核心接口

using Bitzsoft.Integrations.TeamWork.Interfaces;
using Bitzsoft.Integrations.TeamWork.Models.Message;

public class OrgService(ITeamWorkOrgProvider org)
{
    public Task<IReadOnlyList<EmployeeInfo>> GetMembers() => org.GetEmployeesAsync("1");
}

public class NoticeService(ITeamWorkMessageProvider message)
{
    public Task<MessageSendResult> NotifyAsync(string userId) =>
        message.SendWorkNotificationAsync(new WorkNotificationRequest
        {
            ToUserIds = new[] { userId },
            Content = "企业微信应用消息"
        });
}

扩展接口（客户联系）

企业微信实现了 ITeamWorkContactProvider 客户联系接口，使用前用 is 判断供应商是否实现：

if (provider is ITeamWorkContactProvider contacts)
{
    var external = await contacts.GetExternalContactsAsync("staff1");
    var groups = await contacts.GetCustomerGroupsAsync();
}

SSO 单点登录

var sso = (ITeamWorkSsoProvider)provider;

var authUrl = sso.GetAuthorizationUrl("https://app/callback", state: "xyz");
var token = await sso.GetAccessTokenAsync(code, "https://app/callback");
var user = await sso.GetUserInfoAsync(token.AccessToken);

核心类型一览

依赖

相关包

• Bitzsoft.Integrations.TeamWork -- 协同办公抽象层
• Bitzsoft.Integrations.TeamWork.All -- 聚合包（自动注册全部供应商）
• Bitzsoft.Integrations.TeamWork.DingTalk -- 钉钉实现
• Bitzsoft.Integrations.TeamWork.Feishu -- 飞书实现
• Bitzsoft.Integrations.Compatibility -- 基础工具库