HaiTangYunchi.library.Update API 调用手册

概述

HaiTang.library.Update 类提供了与 2018k API 接口的完整封装，包括软件更新、用户管理、卡密验证、云变量操作等功能。本库支持多 API 地址故障转移、健康检测和加密通信。

快速开始

初始化

软件实例初始化

using HaiTang.library;
Update update = new();  // 实例化更新对象
var softwareInfo = await update.InitializationAsync("软件ID", "开发者密钥", "可选机器码");

用户初始化

var userInfo = await update.InitializationUserAsync("软件ID", "开发者密钥", "邮箱", "密码");

软件实例方法

1. 检测软件实例状态

bool isValid = await update.GetSoftCheck("软件ID", "开发者密钥", "可选机器码");

• 参数:

• ID: 程序实例ID

• key: 开发者密钥

• Code: 机器码（可选，为空时自动获取）

• 返回值: bool - 实例是否有效

2. 获取软件信息

初始化后直接调用

using HaiTang.library;
Update update = new();  // 实例化更新对象
var softwareInfo = await update.InitializationAsync("软件ID", "开发者密钥", "可选机器码");
string softwareId = softwareInfo.softwareId;        // 实例ID
string version = softwareInfo.versionNumber;       // 版本号
string name = softwareInfo.softwareName;            // 软件名称
string updateInfo = softwareInfo.versionInformation; // 更新内容
string notice = softwareInfo.notice;                // 公告
string downloadLink = softwareInfo.downloadLink;    // 下载链接
int visits = softwareInfo.numberOfVisits;        // 访问量
bool isItEffective = softwareInfo.isItEffective ;       // 是否激活
long expirationDate = softwareInfo.expirationDate;// 过期时间戳(毫秒)

方法获取特定信息

3. 卡密相关操作

检查卡密状态

bool isValid = await update.GetIsItEffective();

• 返回值: bool - 卡密是否有效

获取卡密信息

string expireDate = await update.GetExpirationDate();    // 过期时间戳
string remarks = await update.GetRemarks();              // 备注
string days = await update.GetNumberOfDays();            // 有效期天数
string authId = await update.GetNetworkVerificationId(); // 卡密ID

激活卡密

var (success, message) = await update.ActivationKey("卡密ID");

• 参数: authId - 卡密ID

• 返回值: (bool, string) - (成功标志, 消息)

创建卡密

string result = await update.CreateNetworkAuthentication(30, "测试卡密"."程序实例ID");
// 返回JSON格式的卡密信息

• 参数:

• day: 有效期天数

• remark: 卡密备注

• ID: 程序实例ID

解绑/换绑

var (success, message) = await update.ReplaceBind("卡密ID", "新机器码");

• 参数:

• AuthId: 卡密ID

• Code: 新机器码（为空则解绑）

4. 云变量操作

获取云变量

string value = await update.GetCloudVariables("变量名");

• 参数: VarName - 云端变量名称

• 返回值: string - 变量值

设置/更新云变量

var (success, message) = await update.updateCloudVariables("变量名", "新值");

• 参数:

• VarKey: 变量名

• Value: 变量值

• 返回值: (bool, string) - (成功标志, 消息)

5. 其他操作

发送消息

string response = await update.MessageSend("需要发送的消息");
// 返回服务器响应JSON 无实际意义

检查强制更新

bool forceUpdate = await update.GetMandatoryUpdate();

获取服务器时间戳

string timestamp = await update.GetTimeStamp();

获取剩余使用时间

long remainingTime = await update.GetRemainingUsageTime();

• 返回值:

• -1: 永久

• 0: 已过期

• 1: 未注册

• 其他: 剩余时间戳（毫秒）

用户管理方法

1. 用户注册

bool success = await update.CustomerRegister("email", "password", "nickName", "avatarUrl", "captcha");

• 参数:

• email: 邮箱

• password: 密码

• nickName: 昵称（可选）

• avatarUrl: 头像URL（可选）

• captcha: 验证码（可选）

• 返回值: bool - 注册是否成功

2. 获取用户信息

获取全部用户信息

string userInfoJson = await update.GetUserInfo();
// 返回格式化的JSON字符串

获取特定用户信息

string userId = await update.GetUserId();          // 用户ID
string avatar = await update.GetUserAvatar();      // 用户头像
string nickname = await update.GetUserNickname();  // 用户昵称
string email = await update.GetUserEmail();        // 用户邮箱
string balance = await update.GetUserBalance();    // 账户余额/时长
bool license = await update.GetUserLicense();      // 是否授权
string loginTime = await update.GetUserTimeCrypt();// 登录时间戳

3. 卡密充值

string result = await update.Recharge("卡密ID");
// 返回服务器响应JSON

工具方法

1.常用方法

Tools.GetMachineCodeEx();  							// 获取机器码
Tools.GenerateRandomString(int length,int type);	// 生成随机字符
Tools.GenerateSalt(int length = 64);  				// 生成随机盐值，默认为64字节
Tools.Sha256(string input);							// 生成SHA256哈希值
Tools.Sha512(string input);							// 生成SHA512哈希值
Tools.upgrade(string downloadLink);		        	// 启动更新程序

2.程序更新

Tools.upgrade(string downloadLink);	// 启动更新程序

3.AES加密 自动IV

Tools.Encrypt(string plainText,string key);		// AES加密
Tools.Decrypt(string cipherText, string key);	// AES解密

4.AES加密 自动IV带盐值和密码

Tools.Encrypt(string plainText, string password, string salt);	// AES加密
Tools.Decrypt(string cipherText, string password, string salt);	// AES解密

Log日志类方法

Log 类是一个静态日志工具类，提供按天分割的日志文件记录功能。日志文件默认存储在应用程序根目录下的 Logs 文件夹中

日志格式

{时间戳} [{日志级别}] {类名}.{方法名} - {消息内容} {异常信息}
示例：2025-12-01 15:02:46.1234 [INFO] OrderService.ProcessOrder - 开始处理订单 #1001

类方法

Debug(string message)

描述 记录 Debug 级别的日志消息，通常用于开发阶段的调试信息记录。

参数

• message (string): 要记录的调试信息

调用示例

// 记录调试信息
Log.Debug("开始处理用户请求，参数: {param}");
Log.Debug("缓存命中率: {rate}%");
Log.Debug("内存使用情况: {used}/{total} MB");

输出示例

Info(string message)

描述 记录 Info 级别的日志消息，用于记录应用程序的正常运行状态信息。

参数

• message (string): 要记录的一般信息

调用示例

输出示例

Warn(string message)

描述 记录 Warn 级别的日志消息，用于记录可能需要关注的潜在问题或异常情况。

参数

• message (string): 要记录的警告信息

调用示例

输出示例

Error(string message)

描述 记录 Error 级别的日志消息，用于记录不影响应用程序继续运行的错误。

参数

• message (string): 要记录的错误信息

调用示例

输出示例

Error(Exception ex, string message)

描述 记录 Error 级别的日志消息，包含异常详细信息，用于记录包含异常详细信息的错误。

参数

• ex (Exception): 相关的异常对象

• message (string): 要记录的错误描述信息

调用示例

<

输出示例

Fatal(string message)

描述 记录 Fatal 级别的日志消息，用于记录导致应用程序无法继续运行的严重错误。

参数

• message (string): 要记录的严重错误信息

调用示例

输出示例

全局捕获异常

对于没捕获的异常记录，我们可以试着在全局异常捕获中记录未处理的异常，方便以后在日志中查看未知异常

1. 控制台应用程序

2. WinForms 应用程序

3. WPF 应用程序

缓存机制

软件信息缓存

• 缓存时间: 5分钟

• 相关方法:

• GetCachedSoftwareInfo(): 获取缓存

• SetCachedSoftwareInfo(): 设置缓存

• IsCacheValid(): 检查缓存有效性

• ClearStaticCache(): 清除缓存

用户信息缓存

• 缓存时间: 5分钟

• 相关方法:

• GetCachedUserInfo(): 获取缓存

• SetCachedUserInfo(): 设置缓存

• IsUserCacheValid(): 检查缓存有效性

• ClearUserCache(): 清除缓存

故障转移机制

健康检测

• 自动检测 API 地址健康状态

• 5分钟缓存检测结果

• 支持多个备用地址自动切换

网络检查

• 自动检测网络连接状态

• 网络不可用时返回 NULL;

注意事项

1. 初始化顺序: 调用具体方法前需要先调用对应的初始化方法

2. 异步操作: 所有API调用都是异步的，需要使用 await

3. 错误处理: 建议对每个API调用进行异常捕获

4. 网络状态: 在网络不稳定时可能有重试机制

5. 缓存: 注意缓存可能导致数据不是实时最新的

6. 线程安全: 大多数方法是线程安全的，但建议避免并发初始化

示例代码

完整软件验证流程

用户登录和充值

这个调用手册涵盖了 HaiTang.library.Update 类的主要公开 API 方法，包括参数说明、返回值说明和使用示例。使用时请根据实际需求选择合适的API方法。