GaoXinLibrary.TencentSDK 1.0.13

GaoXinLibrary.TencentSDK

腾讯平台统一 .NET 服务端 SDK，整合 企业微信（Wecom） 与 微信（小程序、公众号、开放平台、QQ 互联） 核心接口。

一个包覆盖腾讯主流开放平台，开箱即用、接口对齐官方文档、支持依赖注入与多实例。

✨ 特性

• 🎯 统一包 — 微信小程序、公众号、开放平台、QQ 互联、企业微信，一个 NuGet 包全部搞定
• 🔌 依赖注入友好 — 提供 AddWechatMiniProgram / AddWechatOfficial / AddWechatOpen / AddQQConnect / AddWecom 扩展方法，开箱即注入
• 🔑 Keyed Services 多实例 — 同一平台注册多套凭证（如多个企业微信应用），通过 [FromKeyedServices("name")] 注入
• 🔄 access_token 自动管理 — 内置缓存与自动刷新，无需手动维护 Token 生命周期
• 🛡️ 消息回调加解密 — 企业微信与公众号回调消息的签名校验、AES 加解密一站式支持
• 📦 会话内容存档 — 企业微信会话存档原生 SDK 封装（含 RSA 解密）
• 🔄 瞬态故障自动重试 — 网络抖动、连接超时、服务端 5xx 等临时性故障自动按指数退避重试，可通过 RetryOptions 配置
• 🎯 多目标框架 — 同时支持 .NET 8 / .NET 9 / .NET 10，各版本自动匹配对应的 Microsoft.Extensions.* 包
• 📖 XML 文档注释 — 所有公开 API 均附带完整 XML 文档，IDE 智能提示开箱即用

📦 安装

NuGet 包管理器

dotnet add package GaoXinLibrary.TencentSDK

Package Manager Console

Install-Package GaoXinLibrary.TencentSDK

要求

🗂️ 功能概览

微信（Wechat）

小程序 — WechatMiniProgramClient

公众号 — WechatOfficialClient

开放平台 — WechatOpenClient

QQ 互联 — QQConnectClient

企业微信（Wecom） — WecomClient

🚀 快速开始

微信小程序

using GaoXinLibrary.TencentSDK.Wechat;
using GaoXinLibrary.TencentSDK.Wechat.Core;

// 创建客户端
var client = WechatMiniProgramClient.Create(new WechatMiniProgramOptions
{
    AppId     = "your_appid",
    AppSecret = "your_appsecret"
});

// 小程序登录：通过 js_code 换取 session 信息
var session = await client.Auth.Code2SessionAsync("js_code_from_wx_login");
Console.WriteLine($"OpenId: {session.OpenId}, SessionKey: {session.SessionKey}");

// 获取手机号
var phone = await client.Auth.GetPhoneNumberAsync("phone_code_from_button");
Console.WriteLine($"手机号: {phone.PhoneNumber}");

// 生成小程序码
var qrCodeBytes = await client.QrCode.GetUnlimitedQrCodeAsync("scene_value", "pages/index/index");

// 发送订阅消息
await client.SubscribeMessage.SendAsync(new { /* ... */ });

// 内容安全检测
var result = await client.Security.MsgSecCheckAsync("待检测的文本内容");

微信公众号

using GaoXinLibrary.TencentSDK.Wechat;
using GaoXinLibrary.TencentSDK.Wechat.Core;
using GaoXinLibrary.TencentSDK.Wechat.Models.OfficialAccount;

var client = WechatOfficialClient.Create(new WechatOfficialOptions
{
    AppId                 = "your_appid",
    AppSecret             = "your_appsecret",
    CallbackToken         = "your_callback_token",         // 消息回调用
    CallbackEncodingAesKey = "your_43char_encoding_aes_key" // 消息回调用
});

// OAuth 网页授权
var authUrl = client.OAuth.BuildAuthUrl(redirectUri: "https://example.com/callback");
// 用户同意后，通过 code 换取用户信息
// var userInfo = await client.OAuth.GetUserInfoAsync("code_from_callback");

// 发送模板消息
await client.TemplateMessage.SendAsync(new
{
    touser      = "OPENID",
    template_id = "TEMPLATE_ID",
    url         = "https://example.com",
    data        = new { /* 模板数据 */ }
});

// JS-SDK 签名
var jsConfig = await client.JsSdk.GetConfigAsync("https://example.com/page");

// 拉黑用户 / 取消拉黑
await client.User.BatchBlacklistAsync(new BatchBlacklistRequest
{
    OpenIdList = new() { "OPENID_1", "OPENID_2" }
});
await client.User.BatchUnblacklistAsync(new BatchBlacklistRequest
{
    OpenIdList = new() { "OPENID_1" }
});

// 迁移场景：转换 OpenId
var changed = await client.User.ChangeOpenIdAsync(new ChangeOpenIdRequest
{
    FromAppId = "gh_91ae50dfeb1c",
    OpenIdList = new() { "OLD_OPENID" }
});

// 服务号二维码（永久字符串场景值）
var qr = await client.QrCode.CreatePermanentAsync("scene:campaign-2026");
var qrImageUrl = client.QrCode.BuildShowUrl(qr.Ticket!);

// 扫码打开小程序规则（服务号二维码）
await client.QrCode.AddOrUpdateJumpRuleAsync(new QrcodeJumpAddRequest
{
    Prefix = "http://weixin.qq.com/q/kZgfwMTm72Wxxxx",
    AppId = "wxxxxxx",
    Path = "pages/index/index",
    IsEdit = 0
});

// 长信息与短链
var shortResp = await client.QrCode.GenerateShortLinkAsync(new ShortLinkGenerateRequest
{
    LongData = "https://example.com/very/long/path",
    ExpireSeconds = 86400
});
var longResp = await client.QrCode.FetchShortLinkAsync(new ShortLinkFetchRequest
{
    ShortKey = shortResp.ShortKey!
});

// 微信发票（商户开票）—— 设置并查询联系方式
await client.Invoice.SetContactAsync(new InvoiceSetContactRequest
{
    Contact = new InvoiceContactInfo
    {
        Phone = "88888888",
        TimeOut = 12345
    }
});
var contact = await client.Invoice.GetContactAsync();

// 开票平台：获取识别码链接 / 创建卡券模板
var invoiceUrl = await client.Invoice.GetPlatformInvoiceUrlAsync();
var card = await client.Invoice.CreatePlatformCardAsync(new InvoicePlatformCreateCardRequest
{
    InvoiceInfo = new InvoicePlatformCardInfo
    {
        BaseInfo = new InvoicePlatformCardBaseInfo
        {
            Payee = "某某科技有限公司",
            LogoUrl = "https://example.com/logo.png"
        }
    }
});

// 极速开发票：获取商户专属抬头链接
var titleUrl = await client.Invoice.GetSelectTitleUrlAsync(new InvoiceGetSelectTitleUrlRequest
{
    BizName = "某某科技"
});

// 上传临时素材（ReadOnlyMemory 版本）
ReadOnlyMemory<byte> imageBytes = await File.ReadAllBytesAsync("demo.jpg");
var tempUpload = await client.Material.UploadTempMaterialAsync(imageBytes, "demo.jpg", "image");

// 下载临时素材（byte[] / ReadOnlyMemory 两种形式）
var tempBytes = await client.Material.DownloadTempMaterialBytesAsync(tempUpload.MediaId);
var tempReadOnly = await client.Material.DownloadTempMaterialReadOnlyAsync(tempUpload.MediaId);

// 新增永久素材（ReadOnlyMemory 版本）
var permanent = await client.Material.AddPermanentMaterialAsync(imageBytes, "demo.jpg", "image");

微信开放平台（网站扫码登录）

using GaoXinLibrary.TencentSDK.Wechat;
using GaoXinLibrary.TencentSDK.Wechat.Core;

var client = WechatOpenClient.Create(new WechatOpenOptions
{
    AppId     = "your_open_appid",
    AppSecret = "your_open_appsecret"
});

// 构造扫码登录 URL
var loginUrl = client.WebLogin.BuildAuthUrl("https://example.com/callback", state: "random_state");

// 用户扫码后，通过 code 换取 access_token 和用户信息
// var tokenInfo = await client.WebLogin.GetAccessTokenAsync("code_from_callback");
// var userInfo  = await client.WebLogin.GetUserInfoAsync(tokenInfo.AccessToken, tokenInfo.OpenId);

QQ 互联（网站 QQ 登录）

using GaoXinLibrary.TencentSDK.Wechat;
using GaoXinLibrary.TencentSDK.Wechat.Core;

var client = QQConnectClient.Create(new QQConnectOptions
{
    AppId     = "your_qq_appid",
    AppSecret = "your_qq_appkey"
});

// 构造 QQ 登录 URL
var loginUrl = client.Login.BuildAuthUrl("https://example.com/callback", state: "random_state");

// 用户授权后，通过 code 换取 access_token → openid → 用户信息
// var token    = await client.Login.GetAccessTokenAsync("code_from_callback");
// var openId   = await client.Login.GetOpenIdAsync(token.AccessToken);
// var userInfo = await client.Login.GetUserInfoAsync(token.AccessToken, openId);

企业微信

using GaoXinLibrary.TencentSDK.Wecom;
using GaoXinLibrary.TencentSDK.Wecom.Core;
using GaoXinLibrary.TencentSDK.Wecom.Models.User;
using GaoXinLibrary.TencentSDK.Wecom.Models.Message;
using GaoXinLibrary.TencentSDK.Wecom.Models.Meeting;
using GaoXinLibrary.TencentSDK.Wecom.Models.Document;
using GaoXinLibrary.TencentSDK.Wecom.Models.Calendar;
using GaoXinLibrary.TencentSDK.Wecom.Models.Invoice;

var client = WecomClient.Create(new WecomOptions
{
    CorpId     = "your_corpid",
    CorpSecret = "your_corpsecret",
    AgentId    = 1000001
});

// 发送文本消息（@all 发送给所有人）— 便捷方法
var resp = await client.Message.SendTextAsync("Hello, 企业微信!", toUser: "@all");
Console.WriteLine($"MsgId: {resp.MsgId}");

// 发送 Markdown 消息
await client.Message.SendMarkdownAsync("## 通知\n> 这是一条 **Markdown** 消息", toUser: "@all");

// 撤回消息 — 使用 Request Model
await client.Message.RecallMessageAsync(new RecallMessageRequest { MsgId = resp.MsgId });

// 获取成员信息
var user = await client.User.GetUserAsync("zhangsan");
Console.WriteLine($"姓名: {user.Name}, 手机: {user.Mobile}");

// userid 转 openid — 使用 Request Model
var openId = await client.User.ConvertUserIdToOpenIdAsync(new ConvertToOpenIdRequest
{
    UserId = "zhangsan"
});

// 手机号获取 userid
var uid = await client.User.GetUserIdByMobileAsync(new GetUserIdByMobileRequest
{
    Mobile = "13800000000"
});

// 批量删除成员
await client.User.BatchDeleteUsersAsync(new BatchDeleteUserRequest
{
    UserIdList = ["user1", "user2"]
});

// 获取部门列表
var depts = await client.Department.GetDepartmentListAsync();

// Webhook 群机器人
await client.Webhook.SendTextAsync("YOUR_WEBHOOK_KEY", "机器人消息");
await client.Webhook.SendMarkdownAsync("YOUR_WEBHOOK_KEY", "## 告警\n> 服务异常");

// 获取当前应用信息（AgentId 自动取自 WecomOptions，无需手动传入）
var agentInfo = await client.Agent.GetAgentAsync();
Console.WriteLine($"应用名称: {agentInfo.Name}");

// 获取 / 创建 / 删除应用自定义菜单（AgentId 自动注入）
var buttons = await client.Menu.GetMenuAsync();
await client.Menu.DeleteMenuAsync();

// OAuth 网页授权
var oauthUrl = client.OAuth.BuildAuthUrl(
    redirectUri: "https://your-domain.com/callback",
    agentId: 1000001);

// 创建预约会议
var meeting = await client.Meeting.CreateMeetingAsync(new CreateMeetingRequest
{
    Title        = "项目周会",
    AdminUserId  = "zhangsan",
    MeetingStart = DateTimeOffset.UtcNow.AddHours(1).ToUnixTimeSeconds(),
    MeetingEnd   = DateTimeOffset.UtcNow.AddHours(2).ToUnixTimeSeconds()
});

// 新建文档
var doc = await client.Document.CreateDocAsync(new CreateDocRequest
{
    DocName = "会议纪要",
    DocType = 1 // 1-文档, 3-表格
});

// 创建日历
var calId = await client.Calendar.CreateCalendarAsync(new CreateCalendarRequest
{
    Calendar = new CalendarInfo
    {
        Summary     = "团队日程",
        Description = "技术团队共享日历"
    }
});

// 查询电子发票
var invoice = await client.Invoice.GetInvoiceInfoAsync(new GetInvoiceInfoRequest
{
    CardId       = "CARD_ID",
    EncryptCode  = "ENCRYPT_CODE"
});

💡 API 设计说明：所有 POST 接口的方法均接受强类型 Request Model 作为参数，每个 Model 均包含完整的 [JsonPropertyName] 和 XML 文档注释。部分高频接口（如消息发送）额外提供便捷方法（SendTextAsync / SendMarkdownAsync 等）。

💉 依赖注入

基本用法

using GaoXinLibrary.TencentSDK.Wechat.Extensions;
using GaoXinLibrary.TencentSDK.Wecom.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 注册微信小程序
builder.Services.AddWechatMiniProgram(options =>
{
    options.AppId     = "mini_appid";
    options.AppSecret = "mini_secret";
});

// 注册微信公众号
builder.Services.AddWechatOfficial(options =>
{
    options.AppId                  = "official_appid";
    options.AppSecret              = "official_secret";
    options.CallbackToken          = "callback_token";
    options.CallbackEncodingAesKey = "encoding_aes_key";
});

// 注册微信开放平台
builder.Services.AddWechatOpen(options =>
{
    options.AppId     = "open_appid";
    options.AppSecret = "open_secret";
});

// 注册 QQ 互联
builder.Services.AddQQConnect(options =>
{
    options.AppId     = "qq_appid";
    options.AppSecret = "qq_appkey";
});

// 注册企业微信
builder.Services.AddWecom(options =>
{
    options.CorpId     = "your_corpid";
    options.CorpSecret = "your_corpsecret";
    options.AgentId    = 1000001;
});

注册后可以通过构造函数注入门面客户端或子服务接口：

// 方式一：注入门面客户端
public class MyController(WecomClient wecom, WechatMiniProgramClient miniProgram)
{
    public async Task SendNotification()
    {
        await wecom.Message.SendTextAsync("通知内容", toUser: "@all");
    }

    public async Task<string> MiniProgramLogin(string code)
    {
        var session = await miniProgram.Auth.Code2SessionAsync(code);
        return session.OpenId;
    }
}

// 方式二：注入子服务接口（推荐，便于单元测试 Mock）
public class NotificationService(IMessageService messageService, IUserService userService)
{
    public async Task NotifyUserAsync(string userId, string content)
    {
        var user = await userService.GetUserAsync(userId);
        if (user != null)
        {
            await messageService.SendTextAsync(content, toUser: userId);
        }
    }

    public async Task<string> GetOpenIdAsync(string userId)
    {
        // POST 接口使用强类型 Request Model
        return await userService.ConvertUserIdToOpenIdAsync(
            new ConvertToOpenIdRequest { UserId = userId });
    }
}

多实例注册（Keyed Services）

当同一平台需要注册多套凭证时（例如企业微信有多个应用），使用带 name 参数的重载：

// 注册多个企业微信应用
builder.Services.AddWecom("agent1", opt =>
{
    opt.CorpId = "corp1"; opt.CorpSecret = "secret1"; opt.AgentId = 1000001;
});
builder.Services.AddWecom("agent2", opt =>
{
    opt.CorpId = "corp1"; opt.CorpSecret = "secret2"; opt.AgentId = 1000002;
});

// 注册多个小程序
builder.Services.AddWechatMiniProgram("appA", opt =>
{
    opt.AppId = "appid_a"; opt.AppSecret = "secret_a";
});
builder.Services.AddWechatMiniProgram("appB", opt =>
{
    opt.AppId = "appid_b"; opt.AppSecret = "secret_b";
});

通过 [FromKeyedServices] 注入指定实例：

public class MultiAgentService(
    [FromKeyedServices("agent1")] IMessageService msgAgent1,
    [FromKeyedServices("agent2")] IMessageService msgAgent2)
{
    public async Task NotifyBothAsync(string content)
    {
        await msgAgent1.SendTextAsync(content, toUser: "@all");
        await msgAgent2.SendTextAsync(content, toUser: "@all");
    }
}

从配置文件绑定（IConfiguration）

所有 DI 扩展方法均支持直接传入 IConfiguration（如 IConfigurationSection），自动绑定到对应的 Options 类，无需手动编写委托：

// appsettings.json
{
  "WechatMiniProgram": {
    "AppId": "mini_appid",
    "AppSecret": "mini_secret"
  },
  "WechatOfficial": {
    "AppId": "official_appid",
    "AppSecret": "official_secret",
    "CallbackToken": "callback_token",
    "CallbackEncodingAesKey": "encoding_aes_key"
  },
  "WechatOpen": {
    "AppId": "open_appid",
    "AppSecret": "open_secret"
  },
  "QQConnect": {
    "AppId": "qq_appid",
    "AppSecret": "qq_appkey"
  },
  "Wecom": {
    "CorpId": "your_corpid",
    "CorpSecret": "your_corpsecret",
    "AgentId": 1000001
  }
}

using GaoXinLibrary.TencentSDK.Wechat.Extensions;
using GaoXinLibrary.TencentSDK.Wecom.Extensions;

var builder = WebApplication.CreateBuilder(args);
var config = builder.Configuration;

// 从配置节绑定（单实例）
builder.Services.AddWechatMiniProgram(config.GetSection("WechatMiniProgram"));
builder.Services.AddWechatOfficial(config.GetSection("WechatOfficial"));
builder.Services.AddWechatOpen(config.GetSection("WechatOpen"));
builder.Services.AddQQConnect(config.GetSection("QQConnect"));
builder.Services.AddWecom(config.GetSection("Wecom"));

多实例同样支持 IConfiguration 绑定：

// appsettings.json
{
  "WecomAgent1": {
    "CorpId": "corp1",
    "CorpSecret": "secret1",
    "AgentId": 1000001
  },
  "WecomAgent2": {
    "CorpId": "corp1",
    "CorpSecret": "secret2",
    "AgentId": 1000002
  }
}

// 带 key 的多实例 + IConfiguration
builder.Services.AddWecom("agent1", config.GetSection("WecomAgent1"));
builder.Services.AddWecom("agent2", config.GetSection("WecomAgent2"));

builder.Services.AddWechatMiniProgram("appA", config.GetSection("MiniProgramA"));
builder.Services.AddWechatMiniProgram("appB", config.GetSection("MiniProgramB"));

💡 所有 Options 类的属性均支持 IConfiguration 绑定，包括 RetryOptions、HttpTimeout 等嵌套/复杂类型。

⚙️ 配置参数

微信配置 — WechatOptions（基类）

QQConnectOptions（继承 WechatOptions）

企业微信配置 — WecomOptions

🔐 消息回调（企业微信示例）

在 ASP.NET Core 中接入企业微信消息回调：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddWecom(opt =>
{
    opt.CorpId                 = "your_corpid";
    opt.CorpSecret             = "your_corpsecret";
    opt.AgentId                = 1000001;
    opt.CallbackToken          = "your_callback_token";
    opt.CallbackEncodingAesKey = "your_43char_encoding_aes_key";
});

var app = builder.Build();

// GET — 验证回调 URL
app.MapGet("/wecom/callback", (
    string msg_signature, string timestamp, string nonce, string echostr,
    ICallbackService callback) =>
{
    var plain = callback.VerifyUrl(msg_signature, timestamp, nonce, echostr);
    return Results.Content(plain);
});

// POST — 接收消息与事件
app.MapPost("/wecom/callback", async (
    string msg_signature, string timestamp, string nonce,
    HttpRequest request, ICallbackService callback) =>
{
    using var reader = new StreamReader(request.Body);
    var body = await reader.ReadToEndAsync();

    var msg = callback.DecryptAndParse(msg_signature, timestamp, nonce, body);
    switch (msg)
    {
        case CallbackTextMessage text:
            var reply = CallbackReplyBuilder.BuildText(
                text.FromUserName, text.ToUserName, "收到你的消息了！");
            return Results.Content(callback.EncryptReply(reply), "application/xml");

        case CallbackClickEvent click:
            // 处理菜单点击事件
            break;

        case CallbackTemplateCardEvent cardEvent:
            // 处理模版卡片事件
            break;
    }
    return Results.Content("");
});

app.Run();

📂 项目结构

GaoXinLibrary.TencentSDK/
├── Core/                                  # 核心基础设施（共享基类 + 平台子类）
│   ├── TencentConstants.cs                #   统一常量定义（HttpClient 名称、OAuth URL）
│   ├── TencentBaseResponse.cs             #   响应基类（ErrCode / ErrMsg）
│   ├── TencentException.cs                #   异常基类
│   ├── TencentAccessTokenProvider.cs      #   access_token 管理基类（缓存 / 刷新 / 手动设置 / 共享 Token）
│   ├── TencentTokenCrypto.cs              #   共享 Token 加解密工具（ChaCha20-Poly1305）
│   ├── TencentHttpClient.cs               #   HTTP 客户端基类（Get / Post / 反序列化 / 瞬态重试）
│   ├── TencentRetryOptions.cs             #   瞬态故障重试配置（指数退避）
│   ├── TencentCryptoHelper.cs             #   消息加解密基类（AES-256-CBC / SHA1 签名）
│   ├── WechatOptions.cs                   #   微信配置基类
│   ├── WechatMiniProgramOptions.cs        #   小程序配置
│   ├── WechatOfficialOptions.cs           #   公众号配置
│   ├── WechatOpenOptions.cs               #   开放平台配置
│   ├── QQConnectOptions.cs                #   QQ 互联配置
│   ├── WechatHttpClient.cs                #   微信 HTTP 客户端
│   ├── WechatAccessTokenProvider.cs       #   微信 access_token 管理
│   ├── WechatBaseResponse.cs              #   微信响应类
│   ├── WechatCryptoHelper.cs              #   微信消息加解密
│   ├── JsApiTicketProvider.cs             #   公众号 JS-SDK Ticket 缓存与共享
│   ├── WecomOptions.cs                    #   企业微信配置类
│   ├── WecomHttpClient.cs                 #   企业微信 HTTP 客户端
│   ├── WecomAccessTokenProvider.cs        #   企业微信 access_token 管理
│   ├── WecomBaseResponse.cs               #   企业微信响应类
│   ├── WecomCryptoHelper.cs               #   企业微信消息加解密
│   ├── WecomTicketProvider.cs             #   企业微信 JS-SDK Ticket 缓存与共享
│   ├── HexHelper.cs                       #   十六进制工具
│   └── Finance/                           #   会话内容存档原生 SDK
│       ├── FinanceSdk.cs                  #     Finance SDK 封装
│       └── FinanceNativeMethods.cs        #     P/Invoke 声明
├── Models/                                # 数据模型（按产品 × 模块划分，每个类独立文件）
│   ├── MiniProgram/                       #   小程序（104 个模型类）
│   ├── OfficialAccount/                   #   公众号（187 个模型类，含回调消息）
│   ├── OpenPlatform/                      #   开放平台
│   ├── QQConnect/                         #   QQ 互联
│   └── Wecom/                             #   企业微信
│       ├── User/                          #     成员
│       ├── Department/                    #     部门
│       ├── Tag/                           #     标签
│       ├── Message/                       #     消息（含模版卡片）
│       ├── Webhook/                       #     群机器人
│       ├── Agent/                         #     应用
│       ├── Menu/                          #     菜单
│       ├── Media/                         #     素材
│       ├── GroupChat/                      #     群聊
│       ├── OAuth/                         #     OAuth
│       ├── JsSdk/                         #     JS-SDK
│       ├── Callback/                      #     回调消息
│       ├── Kf/                            #     客服
│       ├── Checkin/                       #     打卡
│       ├── Approval/                      #     审批
│       ├── MsgAudit/                      #     会话存档
│       ├── CorpGroup/                     #     企业互联
│       ├── LinkedCorp/                    #     互联企业
│       ├── Export/                        #     异步导出
│       ├── AsyncImport/                   #     异步导入
│       ├── SecondVerify/                  #     二次验证
│       ├── Security/                      #     安全管理
│       ├── AdvancedAccount/               #     高级功能账号
│       ├── OperationLog/                  #     操作日志
│       ├── AccountId/                     #     账号 ID 管理
│       ├── IpRange/                       #     IP 段查询
│       ├── ExternalContact/               #     客户联系
│       ├── CorpPay/                       #     企业支付
│       ├── Email/                         #     邮件
│       ├── Document/                      #     文档
│       ├── Calendar/                      #     日程
│       ├── Meeting/                       #     会议
│       ├── Wedrive/                       #     微盘
│       ├── Living/                        #     直播
│       ├── Dial/                          #     公费电话
│       ├── Report/                        #     汇报
│       ├── Hr/                            #     人事助手
│       ├── MeetingRoom/                   #     会议室
│       ├── Invoice/                       #     电子发票
│       ├── SmartSheet/                    #     智能表格
│       └── CollectForm/                   #     收集表
├── Services/                              # 服务层（按产品 × 模块划分，每个接口 / 实现独立文件）
│   ├── MiniProgram/                       #   小程序（13 对 I*Service / *Service）
│   ├── OfficialAccount/                   #   公众号（17 对 I*Service / *Service）
│   ├── OpenPlatform/                      #   开放平台
│   ├── QQConnect/                         #   QQ 互联
│   └── Wecom/                             #   企业微信
│       ├── User/                          #     成员管理
│       ├── Department/                    #     部门管理
│       ├── Tag/                           #     标签管理
│       ├── Message/                       #     应用消息
│       ├── Webhook/                       #     群机器人
│       ├── Agent/                         #     应用管理
│       ├── Menu/                          #     菜单接口
│       ├── Media/                         #     素材管理
│       ├── GroupChat/                      #     群聊会话
│       ├── OAuth/                         #     OAuth
│       ├── JsSdk/                         #     JS-SDK
│       ├── Callback/                      #     消息回调
│       ├── SmartRobot/                    #     智能机器人
│       ├── Kf/                            #     微信客服
│       ├── Checkin/                       #     打卡
│       ├── Approval/                      #     审批
│       ├── MsgAudit/                      #     会话存档
│       ├── CorpGroup/                     #     企业互联
│       ├── LinkedCorp/                    #     互联企业
│       ├── Export/                        #     异步导出
│       ├── AsyncImport/                   #     异步导入
│       ├── SecondVerify/                  #     二次验证
│       ├── Security/                      #     安全管理
│       ├── AdvancedAccount/               #     高级功能账号
│       ├── OperationLog/                  #     操作日志
│       ├── AccountId/                     #     账号 ID 管理
│       ├── IpRange/                       #     IP 段查询
│       ├── ExternalContact/               #     客户联系
│       ├── CorpPay/                       #     企业支付
│       ├── Email/                         #     邮件
│       ├── Document/                      #     文档
│       ├── Calendar/                      #     日程
│       ├── Meeting/                       #     会议
│       ├── Wedrive/                       #     微盘
│       ├── Living/                        #     直播
│       ├── Dial/                          #     公费电话
│       ├── Report/                        #     汇报
│       ├── Hr/                            #     人事助手
│       ├── MeetingRoom/                   #     会议室
│       ├── Invoice/                       #     电子发票
│       ├── SmartSheet/                    #     智能表格
│       └── CollectForm/                   #     收集表
├── Extensions/                            # DI 扩展
│   ├── WechatServiceCollectionExtensions.cs
│   └── WecomServiceCollectionExtensions.cs
├── WechatMiniProgramClient.cs             # 小程序主客户端
├── WechatOfficialClient.cs                # 公众号主客户端
├── WechatOpenClient.cs                    # 开放平台主客户端
├── QQConnectClient.cs                     # QQ 互联主客户端
├── WecomClient.cs                         # 企业微信主客户端
└── GaoXinLibrary.TencentSDK.csproj        # 项目文件（多目标 net8.0;net9.0;net10.0）

🔧 进阶用法

跨服务共享 Token

多台服务器部署时，只需一台主服务器持有真实的 AppSecret 向腾讯 API 获取 token，其他备服务器通过主服务器的接口获取加密后的 token，无需存储 AppSecret。

加密算法使用 ChaCha20-Poly1305，密钥由 ShareSecret 经 SHA-256 派生，格式为 Base64( nonce[12] + ciphertext[N] + tag[16] )。

主服务器（持有 AppSecret，对外暴露加密 Token 接口）

// Program.cs
builder.Services.AddWecom(opt =>
{
    opt.CorpId     = "your_corpid";
    opt.CorpSecret = "your_corpsecret"; // 仅主服务器配置
    opt.AgentId    = 1000001;
    opt.ShareSecret = "any-strong-shared-secret"; // 与备服务器约定

    // 可选：Token 刷新时推送到 Redis / 消息队列等
    opt.OnTokenChanged = async (newToken, ct) =>
    {
        await redis.StringSetAsync("wecom:token", newToken);
    };
});

// Controller — 对外暴露加密 Token 接口（建议加鉴权）
[HttpGet("/internal/wecom/token")]
public async Task<IActionResult> GetSharedToken([FromServices] WecomClient client)
{
    var result = await client.GetSharedAccessTokenAsync();
    // result.Token     — ChaCha20-Poly1305 加密后的 token（Base64）
    // result.ExpiresIn — 主服务器侧 token 的剩余有效秒数
    return Ok(new { token = result.Token, expires_in = result.ExpiresIn });
}

备服务器（无 AppSecret，从主服务器拉取加密 Token）

// Program.cs
builder.Services.AddWecom(opt =>
{
    opt.CorpId      = "your_corpid";
    opt.AgentId     = 1000001;
    opt.ShareSecret  = "any-strong-shared-secret"; // 与主服务器一致
    opt.TokenShareUrl = "https://main-server/internal/wecom/token"; // 主服务器接口
    // 不需要配置 CorpSecret
});

// 注入后正常使用，SDK 自动在 token 过期时请求主服务器接口并解密
public class MyService(WecomClient client)
{
    public async Task NotifyAsync()
        => await client.Message.SendTextAsync("Hello!", toUser: "@all");
}

也可直接使用加解密工具类

using GaoXinLibrary.TencentSDK.Core;

// 加密（主服务器侧）
string encrypted = TencentTokenCrypto.Encrypt(plainToken, "shared-secret");

// 解密（备服务器侧）
string plainToken = TencentTokenCrypto.Decrypt(encrypted, "shared-secret");

备服务器响应的 expires_in 会被 SDK 原样用于设置本地缓存过期时间，确保备服务器的缓存节奏与主服务器保持一致，避免过早或过晚失效。

跨服务共享 jsapi_ticket

jsapi_ticket 同样有调用频率限制（企业级每小时 400 次，应用级每小时 100 次），SDK 内置了与 access_token 相同的缓存与共享机制。

公众号 jsapi_ticket 共享

// 主服务器
builder.Services.AddWechatOfficial(opt =>
{
    opt.AppId     = "official_appid";
    opt.AppSecret = "official_secret";
    opt.TicketShareSecret = "ticket-shared-secret"; // 与备服务器约定

    // 可选：Ticket 刷新时推送到 Redis 等
    opt.OnTicketChanged = async (newTicket, ct) =>
    {
        await redis.StringSetAsync("official:ticket", newTicket);
    };
});

// Controller — 对外暴露加密 Ticket 接口
[HttpGet("/internal/official/ticket")]
public async Task<IActionResult> GetSharedTicket([FromServices] WechatOfficialClient client)
{
    var result = await client.GetSharedTicketAsync();
    return Ok(new { token = result.Token, expires_in = result.ExpiresIn });
}

// 备服务器
builder.Services.AddWechatOfficial(opt =>
{
    opt.AppId     = "official_appid";
    opt.AppSecret = "official_secret";
    opt.TicketShareSecret = "ticket-shared-secret";
    opt.TicketShareUrl    = "https://main-server/internal/official/ticket";
});

企业微信 jsapi_ticket 共享

企业微信有 两种 jsapi_ticket：

• 企业级 jsapi_ticket（用于 wx.config）
• 应用级 jsapi_ticket（用于 wx.agentConfig）

两者均支持独立的缓存、共享、手动设置和刷新。

// 主服务器
builder.Services.AddWecom(opt =>
{
    opt.CorpId     = "your_corpid";
    opt.CorpSecret = "your_corpsecret";
    opt.AgentId    = 1000001;

    // 企业级 jsapi_ticket 共享
    opt.JsApiTicketShareSecret = "jsapi-ticket-secret";
    opt.OnJsApiTicketChanged = async (ticket, ct) =>
    {
        await redis.StringSetAsync("wecom:jsapi_ticket", ticket);
    };

    // 应用级 jsapi_ticket 共享
    opt.AgentTicketShareSecret = "agent-ticket-secret";
    opt.OnAgentTicketChanged = async (ticket, ct) =>
    {
        await redis.StringSetAsync("wecom:agent_ticket", ticket);
    };
});

// Controller — 对外暴露加密 Ticket 接口
[HttpGet("/internal/wecom/jsapi-ticket")]
public async Task<IActionResult> GetSharedJsApiTicket([FromServices] WecomClient client)
{
    var result = await client.GetSharedJsApiTicketAsync();
    return Ok(new { token = result.Token, expires_in = result.ExpiresIn });
}

[HttpGet("/internal/wecom/agent-ticket")]
public async Task<IActionResult> GetSharedAgentTicket([FromServices] WecomClient client)
{
    var result = await client.GetSharedAgentTicketAsync();
    return Ok(new { token = result.Token, expires_in = result.ExpiresIn });
}

// 备服务器
builder.Services.AddWecom(opt =>
{
    opt.CorpId  = "your_corpid";
    opt.AgentId = 1000001;

    // 企业级 jsapi_ticket 从主服务器获取
    opt.JsApiTicketShareSecret = "jsapi-ticket-secret";
    opt.JsApiTicketShareUrl    = "https://main-server/internal/wecom/jsapi-ticket";

    // 应用级 jsapi_ticket 从主服务器获取
    opt.AgentTicketShareSecret = "agent-ticket-secret";
    opt.AgentTicketShareUrl    = "https://main-server/internal/wecom/agent-ticket";
});

手动管理 jsapi_ticket

// ── 公众号 ──
var ticket = await officialClient.GetTicketAsync();       // 自动缓存
await officialClient.RefreshTicketAsync();                 // 强制刷新
officialClient.InvalidateTicketCache();                    // 使缓存失效
officialClient.SetTicket("external_ticket");               // 手动设置

// ── 企业微信（企业级） ──
var jsTicket = await wecomClient.GetJsApiTicketAsync();    // 自动缓存
await wecomClient.RefreshJsApiTicketAsync();               // 强制刷新
wecomClient.InvalidateJsApiTicketCache();                  // 使缓存失效
wecomClient.SetJsApiTicket("external_ticket");             // 手动设置

// ── 企业微信（应用级） ──
var agentTicket = await wecomClient.GetAgentTicketAsync(); // 自动缓存
await wecomClient.RefreshAgentTicketAsync();               // 强制刷新
wecomClient.InvalidateAgentTicketCache();                  // 使缓存失效
wecomClient.SetAgentTicket("external_ticket");             // 手动设置

🔄 瞬态故障自动重试

SDK 内置了瞬态故障自动重试机制，当遇到网络抖动、连接超时、服务端 5xx 等临时性故障时，会按指数退避策略自动重试。此机制与 Token 失效重试独立，两者可叠加工作。

可重试的故障类型：

• 网络层错误（连接失败、DNS 解析失败等 HttpRequestException）
• HTTP 请求超时（TaskCanceledException，非用户主动取消）
• 服务端错误（HTTP 5xx 状态码）

配置参数 — TencentRetryOptions：

// 使用默认重试配置（2 次重试，500ms 起始延迟，指数退避）
var client = WecomClient.Create(new WecomOptions
{
    CorpId     = "your_corpid",
    CorpSecret = "your_corpsecret",
    AgentId    = 1000001
    // RetryOptions 默认已启用，无需额外配置
});

// 自定义重试策略
var client2 = WecomClient.Create(new WecomOptions
{
    CorpId     = "your_corpid",
    CorpSecret = "your_corpsecret",
    AgentId    = 1000001,
    RetryOptions = new TencentRetryOptions
    {
        MaxRetries   = 3,                              // 最多重试 3 次
        InitialDelay = TimeSpan.FromMilliseconds(200),  // 首次重试等待 200ms
        MaxDelay     = TimeSpan.FromSeconds(10)          // 单次最多等待 10s
    }
});

// 禁用重试
var client3 = WecomClient.Create(new WecomOptions
{
    CorpId     = "your_corpid",
    CorpSecret = "your_corpsecret",
    AgentId    = 1000001,
    RetryOptions = new TencentRetryOptions { MaxRetries = 0 }
});

💡 设计说明：瞬态重试工作在 Token 重试的内层，即每次使用某个 Token 发起请求时，先尝试瞬态重试；若所有重试均失败且错误为 Token 失效，再触发 Token 刷新。这避免了网络问题被误判为 Token 失效。

自定义 HttpClient

传入自定义的 HttpClient 实例（例如添加代理、自定义 Handler）：

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.com:8080"),
    UseProxy = true
};
var httpClient = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(60) };

var client = WecomClient.Create(new WecomOptions
{
    CorpId     = "your_corpid",
    CorpSecret = "your_corpsecret",
    AgentId    = 1000001
}, httpClient);

手动管理 access_token

// 获取当前有效的 access_token（自动缓存，未过期时直接返回）
var token = await client.GetAccessTokenAsync();

// 强制刷新并获取新的 access_token（异步，遇到 token 失效错误时推荐使用）
var newToken = await client.RefreshAccessTokenAsync();

// 仅使缓存失效（下次调用 GetAccessTokenAsync 时重新获取）
client.InvalidateAccessTokenCache();

// 手动设置 access_token（适用于外部统一管理 Token 的场景）
client.SetAccessToken("your_external_token");

// 手动设置 access_token 并指定有效期
client.SetAccessToken("your_external_token", TimeSpan.FromSeconds(3600));

异常处理

SDK 在 API 调用失败时会抛出 TencentException，包含错误码和错误信息：

using GaoXinLibrary.TencentSDK.Core;

try
{
    await client.Message.SendTextAsync("Hello!", toUser: "@all");
}
catch (TencentException ex)
{
    Console.WriteLine($"API 错误 [{ex.ErrCode}]: {ex.Message}");
    // ex.ErrCode — 平台官方错误码
    // ex.Message — 错误描述
}

📋 API 参考

所有公开类型均附带完整的 XML 文档注释。在 Visual Studio / VS Code / Rider 中，悬停即可查看方法签名、参数说明和使用示例。

构建时自动生成 XML 文档文件（GenerateDocumentationFile = true），也可集成 DocFX 等工具生成在线文档。

许可证

MIT