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

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher.
This is a prerelease version of Bitzsoft.Integrations.TeamWork.WeCom. 
dotnet add package Bitzsoft.Integrations.TeamWork.WeCom --version 1.0.0-alpha.9
                    


                    

                
NuGet\Install-Package Bitzsoft.Integrations.TeamWork.WeCom -Version 1.0.0-alpha.9
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Bitzsoft.Integrations.TeamWork.WeCom" Version="1.0.0-alpha.9" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Bitzsoft.Integrations.TeamWork.WeCom" Version="1.0.0-alpha.9" />
                    


                            Directory.Packages.props
                        

                    

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


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Bitzsoft.Integrations.TeamWork.WeCom --version 1.0.0-alpha.9
                    


                    

                
#r "nuget: Bitzsoft.Integrations.TeamWork.WeCom, 1.0.0-alpha.9"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Bitzsoft.Integrations.TeamWork.WeCom@1.0.0-alpha.9
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Bitzsoft.Integrations.TeamWork.WeCom&version=1.0.0-alpha.9&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Bitzsoft.Integrations.TeamWork.WeCom&version=1.0.0-alpha.9&prerelease
                    


                            Install as a Cake Tool

Bitzsoft.Integrations.TeamWork.WeCom

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

功能特性

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

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

认证机制（多 secret）

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

用途 secret 覆盖接口
通讯录 通讯录同步 Secret 部门、成员、SSO 用户身份
自建应用 应用 Secret 应用消息、审批
客户联系 客户联系 Secret 外部联系人、客户群

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

平台限制（抛 NotSupportedException）

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

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

安装

dotnet add package Bitzsoft.Integrations.TeamWork.WeCom

配置

{
  "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"
    }
  }
}
参数 必填 默认值 说明
CorpId 是 — 企业 CorpId
AgentId 是 — 应用 AgentId
Secrets:Contacts 是 — 通讯录同步 Secret
Secrets:Message 是 — 应用消息 Secret
Secrets:ExternalContact 否 — 客户联系 Secret（用客户联系能力时必填）
BaseUrl 否 https://qyapi.weixin.qq.com 服务端 API 基地址
OpenBaseUrl 否 https://open.work.weixin.qq.com 开放平台基地址（SSO）

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

注册服务

using Bitzsoft.Integrations.TeamWork.WeCom;

services.AddBitzsoftWeComTeamWork(configuration, "TeamWork:WeCom");

第三方请求日志

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

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

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftWeComTeamWork(configuration, "TeamWork:WeCom");

使用示例

// 核心接口按需注入
public class OrgService(ITeamWorkOrgProvider org)
{
    public Task<IReadOnlyList<EmployeeInfo>> GetMembers() => org.GetEmployeesAsync("1");
}

// 扩展接口（客户联系）使用前用 is 判断供应商是否实现
if (provider is ITeamWorkContactProvider contacts)
{
    var external = await contacts.GetExternalContactsAsync("staff1");
}

扩展接口

企业微信实现了 ITeamWorkContactProvider 客户联系接口，使用前用 is 判断。

目标框架

  • .NET 5.0
  • .NET 8.0
  • .NET 10.0

相关包

包名 说明
Bitzsoft.Integrations.TeamWork 抽象层
Bitzsoft.Integrations.TeamWork.All 聚合包
Bitzsoft.Integrations.Compatibility 基础工具库
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0-alpha.9 49 7/12/2026
1.0.0-alpha.8 305 7/1/2026
1.0.0-alpha.7 73 6/16/2026
1.0.0-alpha.6 74 6/16/2026
1.0.0-alpha.5 64 6/14/2026