WebApi 项目集成企业微信和公众号 | 极客日志

C#WeChatAI

WebApi 项目集成企业微信和公众号

本文介绍了在 WebApi 项目中集成企业微信和微信公众号的技术方案。主要内容包括：配置依赖库（SKIT.FlurlHttpClient.Wechat），注册服务，使用 IMemoryCache 管理 AccessToken，实现回调验证与消息接收（文本/图片），通过异步任务队列处理耗时操作（如调用 LLM），以及简单的用户关联登录流程。代码基于 C# 实现。

CoderByte发布于 2026/3/28更新于 2026/4/143 浏览

前置工作

依赖库

其中：

企业微信：SKIT.FlurlHttpClient.Wechat.Work
公众号：SKIT.FlurlHttpClient.Wechat.Api

微信配置信息

需要准备这些配置信息：

企业微信：

public class WechatWorkOptions { 
    public string CorpId { get; set; } = string.Empty; // 应用 ID 
    public int AgentId { get; set; } // 应用密钥 
    public string Secret { get; set; } = string.Empty; // 回调 Token 
    public string CallbackToken { get; set; } = string.Empty; // 回调 EncodingAESKey 
    public string CallbackEncodingAESKey { get; set; } = string.Empty; 
}

公众号：

public class WechatApiClientOptions { 
    public string AppId { get; set; } = string.Empty; 
    public string AppSecret { get; set; } = .Empty; 
      CallbackToken { ; ; } = .Empty; 
      CallbackEncodingAESKey { ; ; } = .Empty; 
}

相关免费在线工具

RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。在线工具，Mermaid 预览与可视化编辑在线工具，online
Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。在线工具，Base64 文件转换器在线工具，online
Markdown 转 HTML
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。在线工具，Markdown 转 HTML在线工具，online
HTML 转 Markdown
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。在线工具，HTML 转 Markdown在线工具，online

// 企业微信 
builder.Services.AddSingleton<WechatWorkClient>(sp => { 
    var options = sp.GetRequiredService<IOptions<WechatWorkOptions>>().Value; 
    return WechatWorkClientBuilder.Create(options).Build(); 
}); 
// 公众号 
builder.Services.AddSingleton<WechatApiClient>(sp => { 
    var options = sp.GetRequiredService<IOptions<WechatMpOptions>>().Value; 
    return WechatApiClientBuilder.Create(options).Build(); 
});

public class WechatWorkTokenService( 
    WechatWorkClient client, 
    IMemoryCache cache, 
    IOptions<WechatWorkOptions> options 
) : IWechatWorkTokenService { 
    private const string CacheKey = "WechatWorkAccessToken"; 
    // 用于并发控制，防止瞬间高并发导致多次请求 Token 接口 
    private static readonly SemaphoreSlim Semaphore = new SemaphoreSlim(1, 1); 
    
    /// <summary> 
    /// 获取 AccessToken 
    /// </summary> 
    public async Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default) { 
        // 1. 尝试从缓存获取 
        if (cache.TryGetValue(CacheKey, out string? accessToken) && !string.IsNullOrEmpty(accessToken)) { 
            return accessToken; 
        } 
        
        // 2. 缓存未命中，加锁请求 
        await Semaphore.WaitAsync(cancellationToken); 
        try { 
            // 双重检查，防止排队等待的线程再次请求 
            if (cache.TryGetValue(CacheKey, out accessToken) && !string.IsNullOrEmpty(accessToken)) { 
                return accessToken; 
            } 
            
            // 3. 调用接口获取 Token 
            var request = new CgibinGetTokenRequest(); 
            var response = await client.ExecuteCgibinGetTokenAsync(request, cancellationToken); 
            if (!response.IsSuccessful()) { 
                throw new Exception($"获取 AccessToken 失败：{response.ErrorMessage} (Code: {response.ErrorCode})"); 
            } 
            accessToken = response.AccessToken; 
            
            // 4. 设置缓存 
            // 提前 5 分钟过期，确保在过期前刷新 
            // 如果 ExpiresIn 小于 300 秒，则设为一半时间 
            var expirySeconds = response.ExpiresIn > 300 ? response.ExpiresIn - 300 : response.ExpiresIn / 2; 
            var cacheEntryOptions = new MemoryCacheEntryOptions() 
                .SetAbsoluteExpiration(TimeSpan.FromSeconds(expirySeconds)); 
            cache.Set(CacheKey, accessToken, cacheEntryOptions); 
            return accessToken; 
        } finally { 
            Semaphore.Release(); 
        } 
    } 
}

[ApiController] 
[AllowAnonymous] 
[Route("api/wechat/work/callback")] 
public class WechatWorkController( 
    WechatWorkClient client, 
    IBackgroundTaskQueue queue, 
    ILogger<WechatWorkController> logger 
) : ControllerBase { 
    /// <summary> 
    /// 回调验证 (GET) 
    /// </summary> 
    [HttpGet] 
    public IActionResult Echo( 
        [FromQuery(Name = "msg_signature")] string msgSignature, 
        [FromQuery(Name = "timestamp")] string timestamp, 
        [FromQuery(Name = "nonce")] string nonce, 
        [FromQuery(Name = "echostr")] string echoStr 
    ) { 
        // 验证签名 
        var verifyResult = client.VerifyEventSignatureForEcho( 
            timestamp, nonce, echoStr, msgSignature, out string? replyEcho 
        ); 
        if (verifyResult.Result) { 
            logger.LogInformation("Echo verification successful. ReplyEcho: {ReplyEcho}", replyEcho); 
            return Content(replyEcho ?? string.Empty); 
        } 
        logger.LogWarning("Echo verification failed. Error: {Error}", verifyResult.Error?.Message); 
        return BadRequest($"Verify signature failed: {verifyResult.Error?.Message}"); 
    } 
}

/// <summary> 
/// 接收消息 (POST) 
/// </summary> 
[HttpPost] 
public async Task<IActionResult> Callback( 
    [FromQuery(Name = "msg_signature")] string msgSignature, 
    [FromQuery(Name = "timestamp")] string timestamp, 
    [FromQuery(Name = "nonce")] string nonce 
) { 
    // 必须读取原始 Request Body 流，而不能使用 [FromBody] 绑定 
    // 原因： 
    // 1. 微信签名验证依赖于原始请求体，任何空格、换行符的差异都会导致签名校验失败 
    // 2. 推送内容通常是加密的 XML，需要先获取原始字符串传给 SDK 进行解密 
    using var reader = new StreamReader(Request.Body); 
    var xml = await reader.ReadToEndAsync(); 
    logger.LogDebug("Callback Body (Length: {Length}): {Xml}", xml.Length, xml); 
    
    // 1. 验证签名 
    // 虽然 DeserializeEventFromXml 内部可能会包含解密过程，但显式验证签名是更安全的做法 
    var verifyResult = client.VerifyEventSignatureFromXml(timestamp, nonce, xml, msgSignature); 
    if (!verifyResult.Result) { 
        logger.LogWarning("Callback signature verification failed. Error: {Error}", verifyResult.Error?.Message); 
        return BadRequest($"Verify signature failed: {verifyResult.Error?.Message}"); 
    } 
    
    // 2. 使用 SKIT 库提供的扩展方法自动解密并反序列化 
    // 注意：需要在 WechatWorkClientOptions 中配置 PushToken 和 PushEncodingAESKey 
    WechatWorkEvent wechatEvent; 
    try { 
        wechatEvent = client.DeserializeEventFromXml(xml); 
        logger.LogInformation("Callback deserialized successfully. MessageType: {MessageType}, FromUser: {FromUser}, ToUser: {ToUser}", 
            wechatEvent.MessageType, wechatEvent.FromUserName, wechatEvent.ToUserName); 
    } catch (Exception ex) { 
        // 反序列化失败（通常是因为签名验证失败或解密失败） 
        logger.LogError(ex, "Callback deserialization failed."); 
        return BadRequest($"Deserialization failed: {ex.Message}"); 
    } 
    
    // 处理逻辑 
    if (string.Equals(wechatEvent.MessageType, "TEXT", StringComparison.OrdinalIgnoreCase)) { 
        // 再次反序列化为具体的文本消息事件以获取 Content 
        var textEvent = client.DeserializeEventFromXml<TextMessageEvent>(xml); 
        if (textEvent != null && !string.IsNullOrEmpty(textEvent.Content) && !string.IsNullOrEmpty(textEvent.FromUserName)) { 
            logger.LogInformation("Processing TEXT message from {FromUser}: {Content}", textEvent.FromUserName, textEvent.Content); 
            await ProcessTextMessageAsync(textEvent.FromUserName, textEvent.Content); 
        } 
    } else if (string.Equals(wechatEvent.MessageType, "IMAGE", StringComparison.OrdinalIgnoreCase)) { 
        var imageEvent = client.DeserializeEventFromXml<ImageMessageEvent>(xml); 
        if (imageEvent != null && !string.IsNullOrEmpty(imageEvent.MediaId) && !string.IsNullOrEmpty(imageEvent.FromUserName)) { 
            logger.LogInformation("Processing IMAGE message from {FromUser}: {MediaId}", textEvent.FromUserName, imageEvent.MediaId); 
            await ProcessImageMessageAsync(textEvent.FromUserName, imageEvent.MediaId); 
        } 
    } else { 
        logger.LogInformation("Ignored message type: {MessageType}", wechatEvent.MessageType); 
    } 
    return Ok("success"); 
}

/// <summary> 
/// 异步处理文本消息 
/// </summary> 
private async Task ProcessTextMessageAsync(string toUser, string content) { 
    await queue.QueueBackgroundWorkItemAsync(async (serviceProvider, token) => { 
        // 在后台任务中解析 Scoped 服务 
        var chatBot = serviceProvider.GetRequiredService<IChatBotService>(); 
        var logger = serviceProvider.GetRequiredService<ILogger<WechatWorkController>>(); 
        try { 
            logger.LogInformation("Processing background task for user {ToUser}", toUser); 
            // 1. 调用 ChatBot 获取回复 
            string reply = await chatBot.ProcessMessageAsync(content); 
            // 2. 发送回复 
            var accessToken = await _tokenService.GetAccessTokenAsync(); 
            var request = new CgibinMessageSendRequest { 
                AccessToken = accessToken, 
                AgentId = _agentId, 
                ToUserIdList = [toUser], 
                MessageType = "text", 
                MessageContentAsText = new CgibinMessageSendRequest.Types.TextMessage { Content = content } 
            }; 
            var response = await _client.ExecuteCgibinMessageSendAsync(request); 
            if (!response.IsSuccessful()){ 
                throw new Exception($"发送企业微信消息失败：{response.ErrorMessage} (Code: {response.ErrorCode})"); 
            } 
            logger.LogInformation("Reply sent to {ToUser}: {ReplyContent}", toUser, reply); 
        } catch (Exception ex) { 
            logger.LogError(ex, "Failed to process message for {ToUser}", toUser); 
        } 
    }); 
}

/// <summary> 
/// 异步处理图片消息 
/// </summary> 
private async Task ProcessImageMessageAsync(string toUser, string mediaId) { 
    await queue.QueueBackgroundWorkItemAsync(async (serviceProvider, token) => { 
        var chatBot = serviceProvider.GetRequiredService<IChatBotService>(); 
        var wechatService = serviceProvider.GetRequiredService<IWechatWorkService>(); 
        var tokenService = serviceProvider.GetRequiredService<IWechatWorkTokenService>(); 
        var logger = serviceProvider.GetRequiredService<ILogger<WechatWorkController>>(); 
        var wechatClient = serviceProvider.GetRequiredService<WechatWorkClient>(); 
        try { 
            logger.LogInformation("Processing background image task for user {ToUser}", toUser); 
            // 1. Download Image 
            var accessToken = await tokenService.GetAccessTokenAsync(token); 
            var request = new CgibinMediaGetRequest { 
                AccessToken = accessToken, 
                MediaId = mediaId 
            }; 
            var resp = await wechatClient.ExecuteCgibinMediaGetAsync(request, cancellationToken: token); 
            if (!resp.IsSuccessful()) { 
                logger.LogError("Failed to download image: {Error}", resp.ErrorMessage); 
                await wechatService.SendTextMessageAsync(toUser, "抱歉，无法获取图片内容。"); 
                return; 
            } 
            var bytes = resp.GetRawBytes(); 
            var mimeType = "image/jpeg"; 
            if (bytes.Length > 0 && bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4E && bytes[3] == 0x47) { 
                mimeType = "image/png"; 
            } 
            var items = new ChatMessageContentItemCollection { 
                new ImageContent(bytes, mimeType) 
            }; 
            // 2. Call ChatBot 
            var chatMessage = new ChatMessageContent(AuthorRole.User, items); 
            var reply = await chatBot.ProcessMessageAsync(chatMessage); 
            // 3. Send Reply 
            await wechatService.SendTextMessageAsync(toUser, reply); 
            logger.LogInformation("Reply sent to {ToUser}", toUser); 
        } catch (Exception ex) { 
            logger.LogError(ex, "Failed to process image message for {ToUser}", toUser); 
        } 
    }); 
}

/// <summary> 
/// 接收消息 (POST) 
/// </summary> 
[HttpPost] 
public async Task<IActionResult> Callback( 
    [FromQuery(Name = "msg_signature")] string? msgSignature, 
    [FromQuery(Name = "signature")] string? signature, 
    [FromQuery(Name = "timestamp")] string timestamp, 
    [FromQuery(Name = "nonce")] string nonce, 
    [FromQuery(Name = "encrypt_type")] string? encryptType 
) { 
    using var reader = new StreamReader(Request.Body); 
    var xml = await reader.ReadToEndAsync(); 
    _logger.LogDebug("Callback Body (Length: {Length}): {Xml}", xml.Length, xml); 
    
    // 1. 验证签名 
    // 如果是安全模式 (encryptType == "aes")，使用 VerifyEventSignatureFromXml (需要 msg_signature) 
    // 如果是明文模式，SDK 内部 DeserializeEventFromXml 也会做一些校验，但通常明文模式签名校验使用 signature 
    if (string.Equals(encryptType, "aes", StringComparison.OrdinalIgnoreCase)) { 
        if (string.IsNullOrEmpty(msgSignature)) { 
            return BadRequest("msg_signature is required for aes encryption"); 
        } 
        var verifyResult = _client.VerifyEventSignatureFromXml(timestamp, nonce, xml, msgSignature); 
        if (!verifyResult.Result) { 
            _logger.LogWarning("Callback signature verification failed. Error: {Error}", verifyResult.Error?.Message); 
            return BadRequest($"Verify signature failed: {verifyResult.Error?.Message}"); 
        } 
    } else { 
        // 明文模式，可以使用 signature 验证 (可选) 
        // var verifyResult = _client.VerifyEventSignatureForEcho(timestamp, nonce, signature); 
    } 
    
    // 2. 使用 SKIT 库自动解密并反序列化 
    WechatApiEvent wechatEvent; 
    try { 
        wechatEvent = _client.DeserializeEventFromXml(xml); 
        _logger.LogInformation("Callback deserialized successfully. MessageType: {MessageType}, FromUser: {FromUser}, ToUser: {ToUser}", 
            wechatEvent.MessageType, wechatEvent.FromUserName, wechatEvent.ToUserName); 
    } catch (Exception ex) { 
        _logger.LogError(ex, "Callback deserialization failed."); 
        return BadRequest($"Deserialization failed: {ex.Message}"); 
    } 
    
    switch (wechatEvent.MessageType?.ToLower()) { 
        case "text": 
            var textEvent = _client.DeserializeEventFromXml<TextMessageEvent>(xml); 
            if (!string.IsNullOrEmpty(textEvent.Content) && !string.IsNullOrEmpty(textEvent.FromUserName)) { 
                _logger.LogInformation("Processing TEXT message from {FromUser}: {Content}", textEvent.FromUserName, textEvent.Content); 
                var isSafetyMode = string.Equals(encryptType, "aes", StringComparison.OrdinalIgnoreCase); 
                var textReply = new TextMessageReply { 
                    ToUserName = textEvent.FromUserName, 
                    FromUserName = textEvent.ToUserName, 
                    MessageType = "text", 
                    Content = "这里是回复给用户的内容", 
                    CreateTimestamp = DateTimeOffset.Now.ToUnixTimeSeconds() 
                }; 
                var replyXml = _client.SerializeEventToXml(textReply, isSafetyMode); 
                return Content(replyXml, "application/xml"); 
            } 
            break; 
        default: 
            _logger.LogInformation("Ignored message type: {MessageType}", wechatEvent.MessageType); 
            break; 
    } 
    return Ok("success"); 
}

/// <summary> 
/// 企业微信登录 - 使用回调的 code 登录 
/// </summary> 
/// <param name="code"></param> 
/// <param name="state">一些让微信转发传给后端的参数，这里是单点认证项目的 session_id</param> 
[HttpGet("wecom/login")] 
public async Task<IActionResult> WecomLogin(string code, string? state = null) { 
    logger.LogInformation("企业微信登录，code: {code}, state: {state}, crop: {cropTag}", code, state, cropTag); 
    if (string.IsNullOrWhiteSpace(state)) { 
        return BadRequest(new ApiResponse { Message = "企业微信登录的 state 为空，无法获取 session" }); 
    } 
    var session = await authService.GetSession(state); 
    if (session == null) { 
        return NotFound(new ApiResponse { Message = $"session {state} 不存在！" }); 
    } 
    var userInfo = await wecomService.GetUserInfo(code); 
    if (userInfo == null) { 
        return BadRequest(new ApiResponse { Message = "获取 userinfo 错误！" }); 
    } 
    if (userInfo.Errcode != 0) { 
        return BadRequest(new ApiResponse { Message = $"获取用户信息失败，企微错误信息：{userInfo.Errmsg}" }); 
    } 
    var wechatUser = await wecomService.GetUser(userInfo.Userid); 
    if (wechatUser == null) { 
        return BadRequest(new ApiResponse { Message = "获取 user 错误！" }); 
    } 
    var user = await userRepo.Where(a => a.PhoneNumber == wechatUser.Userid).FirstAsync(); 
    // 用户不存在的话，自动创建用户 
    if (user == null) { 
        user = await accountService.CreateUser( 
            await accountService.GenerateUsername(wechatUser.Name), 
            wechatUser.Userid, 
            wechatUser.Name 
        ); 
        logger.LogInformation("用户 {Phone} 不存在，已创建新用户 {UserId}", wechatUser.Userid, user.Id); 
    } 
    try { 
        var url = await authService.LoginSessionAndGetUri(session, user, true); 
        logger.LogInformation("企业微信登录成功，跳转到链接：{url}", url); 
        return Redirect(url); 
    } catch (Exception ex) { 
        ex.ToExceptionless().Submit(); 
        return Problem($"企业微信登录失败：LoginSessionAndGetUri 失败 - {ex.Message}"); 
    } 
}

WebApi 项目集成企业微信和公众号

前置工作

依赖库

微信配置信息

更多推荐文章

相关免费在线工具

注册服务

管理 token

企业微信

验证回调

接收信息

异步处理信息

文本信息

图片信息

公众号

接入登录

WebApi 项目集成企业微信和公众号

前置工作

依赖库

微信配置信息

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

注册服务

管理 token

企业微信

验证回调

接收信息

异步处理信息

文本信息

图片信息

公众号

接入登录