ILinkai.Weixin.Sdk.SqlServer 1.0.5

ILinkai Weixin SDK

ILinkai微信SDK - 用于ilinkai.weixin.qq.com API的完整C#开发包

功能特性

• ✅ 完整的API封装（getUpdates、sendMessage、getUploadUrl等）
• ✅ 二维码扫码登录
• ✅ 消息收发（文本、图片、视频、文件、语音）
• ✅ CDN文件上传下载（AES-128-ECB加密）
• ✅ 长轮询消息监控
• ✅ 账户管理和持久化存储
• ✅ 会话状态管理
• ✅ 命令行工具(CLI)

安装

NuGet包

# 安装核心SDK
dotnet add package ILinkai.Weixin.Sdk

# 安装SQL Server存储扩展（可选）
dotnet add package ILinkai.Weixin.Sdk.SqlServer

从源码构建

# 克隆仓库
git clone <repository-url>
cd ilinkai-sdk

# 构建 SDK
dotnet build src/ILinkai.Weixin.Sdk

# 打包 NuGet 包（本地使用）
dotnet pack src/ILinkai.Weixin.Sdk -c Release -o ./nupkg
dotnet pack src/ILinkai.Weixin.Sdk.SqlServer -c Release -o ./nupkg

# 从本地包安装
dotnet add package ILinkai.Weixin.Sdk --source ./nupkg
dotnet add package ILinkai.Weixin.Sdk.SqlServer --source ./nupkg

CLI工具

# 构建 CLI 工具
dotnet build src/ILinkai.Weixin.Cli

# 作为全局工具安装（本地）
dotnet tool install -g --add-source ./nupkg ILinkai.Weixin.Cli

快速开始

1. 扫码登录

using ILinkai.Weixin.Sdk.Auth;

var loginService = new QRCodeLoginService("https://ilinkai.weixin.qq.com");

// 获取二维码
var startResult = await loginService.StartLoginAsync();
Console.WriteLine($"请扫描: {startResult.QRCodeUrl}");

// 等待登录完成
var waitResult = await loginService.WaitForLoginAsync(startResult.QRCode);

if (waitResult.Connected)
{
    Console.WriteLine($"登录成功！Token: {waitResult.BotToken}");
    
    // 保存账户
    var accountStore = new AccountStore();
    accountStore.SaveAccount(waitResult.AccountId, new WeixinAccountData
    {
        Token = waitResult.BotToken,
        BaseUrl = waitResult.BaseUrl
    });
}

2. 发送消息

using ILinkai.Weixin.Sdk;
using ILinkai.Weixin.Sdk.Messaging;

var apiClient = new WeixinApiClient(new WeixinApiClientOptions
{
    BaseUrl = "https://ilinkai.weixin.qq.com",
    Token = "your-bot-token"
});

var sendService = new MessageSendService(apiClient, "https://novac2c.cdn.weixin.qq.com/c2c");

// 发送文本
await sendService.SendTextAsync(
    toUserId: "user@im.wechat",
    text: "Hello!",
    contextToken: "context-token-from-message");

// 发送图片
await sendService.SendImageAsync(
    toUserId: "user@im.wechat",
    filePath: "/path/to/image.jpg",
    contextToken: "context-token-from-message",
    caption: "图片说明");

3. 监控消息

using ILinkai.Weixin.Sdk.Messaging;

var options = new MessageMonitorOptions
{
    BaseUrl = "https://ilinkai.weixin.qq.com",
    Token = "your-bot-token",
    AccountId = "your-account-id"
};

using var monitor = new MessageMonitorService(options);

monitor.MessageReceived += (sender, e) =>
{
    Console.WriteLine($"收到消息: {e.Context.Body}");
    Console.WriteLine($"发送者: {e.Context.From}");
    Console.WriteLine($"上下文令牌: {e.Context.ContextToken}");
};

monitor.ErrorOccurred += (sender, e) =>
{
    Console.WriteLine($"错误: {e.Error.Message}");
};

await monitor.StartAsync();

4. 上传文件

using ILinkai.Weixin.Sdk.Media;

var uploadService = new MediaUploadService(apiClient, cdnBaseUrl);

var uploaded = await uploadService.UploadImageAsync(
    filePath: "/path/to/image.jpg",
    toUserId: "user@im.wechat");

Console.WriteLine($"文件键: {uploaded.FileKey}");
Console.WriteLine($"下载参数: {uploaded.DownloadEncryptedQueryParam}");

5. 下载媒体

var downloadService = new MediaDownloadService(cdnBaseUrl);

var imageData = await downloadService.DownloadImageAsync(
    encryptQueryParam: "encrypted-param",
    aesKeyBase64: "base64-encoded-aes-key");

await downloadService.SaveMediaToFileAsync(imageData, "/save/path", "image.jpg");

6. 存储配置

SDK支持两种存储方式：文件存储（默认）和SQL Server存储。

文件存储（默认）

using ILinkai.Weixin.Sdk.Auth;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 默认使用文件存储
services.AddWeixinStorage();

// 或指定自定义状态目录
services.AddWeixinStorage("/custom/state/dir");

var serviceProvider = services.BuildServiceProvider();
var accountStore = serviceProvider.GetRequiredService<IAccountStore>();

SQL Server存储

using ILinkai.Weixin.Sdk.Auth;
using ILinkai.Weixin.Sdk.SqlServer;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 添加默认文件存储（可选）
services.AddWeixinStorage();

// 切换到SQL Server存储（会替换文件存储）
services.AddWeixinSqlServerStorage("Server=localhost;Database=WeixinAccounts;Trusted_Connection=True;");

var serviceProvider = services.BuildServiceProvider();
var accountStore = serviceProvider.GetRequiredService<IAccountStore>();

自定义DbContext配置

services.AddWeixinSqlServerStorage(options =>
{
    options.UseSqlServer("YourConnectionString", sqlOptions =>
    {
        sqlOptions.EnableRetryOnFailure(maxRetryCount: 3);
    });
});

初始化数据库

using ILinkai.Weixin.Sdk.SqlServer;
using Microsoft.EntityFrameworkCore;

var options = new DbContextOptionsBuilder<AccountDbContext>()
    .UseSqlServer("YourConnectionString")
    .Options;

using var context = new AccountDbContext(options);

// 创建数据库和表
context.Database.EnsureCreated();

// 或使用迁移（推荐生产环境）
// dotnet ef migrations add InitialCreate --project ILinkai.Weixin.Sdk.SqlServer
// dotnet ef database update

数据库表结构

CREATE TABLE Accounts (
    AccountId NVARCHAR(256) PRIMARY KEY,
    Token NVARCHAR(MAX),
    SavedAt DATETIME2,
    BaseUrl NVARCHAR(512),
    UserId NVARCHAR(256),
    CreatedAt DATETIME2 NOT NULL,
    UpdatedAt DATETIME2 NOT NULL
);

CREATE INDEX IX_Accounts_UserId ON Accounts(UserId);

CLI使用

安装插件并登录

ilinkai-weixin install

扫码登录

ilinkai-weixin login --base-url https://ilinkai.weixin.qq.com

发送消息

ilinkai-weixin send --to "user@im.wechat" --text "Hello" --token "your-token" --context-token "ctx-token"

监控消息

ilinkai-weixin monitor --account-id "your-account-id" --token "your-token"

账户管理

# 列出所有账户
ilinkai-weixin account list

# 显示账户详情
ilinkai-weixin account show "account-id"

API参考

WeixinApiClient

核心API客户端，提供与ilinkai.weixin.qq.com交互的所有方法。

QRCodeLoginService

二维码登录服务。

MessageMonitorService

消息监控服务，长轮询接收消息。

MessageSendService

消息发送服务。

MediaUploadService / MediaDownloadService

媒体文件上传下载服务，自动处理AES加密。

配置选项

WeixinApiClientOptions

错误处理

SDK定义了以下异常类型：

• WeixinApiException - API请求错误
• WeixinSessionPausedException - 会话已暂停
• CdnUploadException - CDN上传错误
• CdnDownloadException - CDN下载错误

try
{
    await sendService.SendTextAsync(to, text, contextToken);
}
catch (WeixinSessionPausedException ex)
{
    Console.WriteLine($"会话已暂停，{ex.RemainingMinutes}分钟后重试");
}
catch (WeixinApiException ex)
{
    Console.WriteLine($"API错误: {ex.Message}, StatusCode: {ex.StatusCode}");
}

项目结构

ilinkai-sdk/
├── src/
│   ├── ILinkai.Weixin.Sdk/           # SDK核心库
│   │   ├── Models/                   # 数据模型
│   │   ├── Auth/                     # 认证模块
│   │   │   ├── IAccountStore.cs      # 存储接口
│   │   │   ├── AccountStore.cs       # 文件存储实现
│   │   │   ├── ServiceCollectionExtensions.cs # DI扩展
│   │   │   ├── QRCodeLoginService.cs
│   │   │   └── SessionGuard.cs
│   │   ├── Cdn/                      # CDN加密/上传/下载
│   │   ├── Media/                    # 媒体处理
│   │   ├── Messaging/                # 消息收发
│   │   └── WeixinApiClient.cs        # API客户端
│   ├── ILinkai.Weixin.Sdk.SqlServer/ # SQL Server存储扩展
│   │   ├── Models/
│   │   │   └── AccountEntity.cs      # 实体模型
│   │   ├── AccountDbContext.cs       # EF Core DbContext
│   │   ├── SqlServerAccountStore.cs  # SQL Server存储实现
│   │   └── ServiceCollectionExtensions.cs # DI扩展
│   └── ILinkai.Weixin.Cli/           # 命令行工具
│       ├── Commands/                 # 命令模块
│       │   ├── ICommand.cs           # 命令接口
│       │   ├── CommandBase.cs        # 命令基类
│       │   ├── CommandRegistry.cs    # 命令注册中心
│       │   ├── InstallCommand.cs     # 安装命令
│       │   ├── LoginCommand.cs       # 登录命令
│       │   ├── SendCommand.cs        # 发送消息命令
│       │   ├── MonitorCommand.cs     # 监控命令
│       │   └── AccountCommand.cs     # 账户管理命令
│       └── Program.cs                # 入口
├── samples/
│   └── ILinkai.Weixin.Sample/        # 使用示例
│       ├── Examples/                 # 示例模块
│       │   ├── IExample.cs           # 示例接口
│       │   ├── ExampleBase.cs        # 示例基类
│       │   ├── ExampleRegistry.cs    # 示例注册中心
│       │   ├── LoginExample.cs       # 登录示例
│       │   ├── SendExample.cs        # 发送消息示例
│       │   ├── MonitorExample.cs     # 监控示例
│       │   ├── AccountExample.cs     # 账户管理示例
│       │   ├── UploadExample.cs      # 上传文件示例
│       │   ├── DownloadExample.cs    # 下载文件示例
│       │   ├── ConfigExample.cs      # 配置示例
│       │   ├── TypingExample.cs      # 输入状态示例
│       │   └── FullWorkflowExample.cs# 完整工作流示例
│       └── Program.cs                # 入口
└── ILinkai.Weixin.sln               # 解决方案文件

许可证

MIT License