AccessEntryCore 使用指南¶

版本: 1.6.3 | 命名空间: AS | 目标框架: .NET Standard 2.0 | 公司: 武汉达意信息技术有限公司

一、概述¶

AccessEntryCore 是一个 .NET Standard 2.0 权限控制核心库，提供完整的软件许可证管理、用户认证、产品发布与更新管理、消息通信等功能。该库通过 HTTP 协议与远程服务器通信，支持本地数据缓存与服务器同步。

核心功能¶

功能模块	说明
用户管理	注册、登录、权限控制（游客/开发者/管理员）
产品管理	产品发布、搜索、收藏、审核
许可证（Token）管理	秘钥生成、激活、调用消耗、绑定管理
版本更新	产品版本发布、文件上传/下载
消息系统	用户间消息发送、已读/取消
数据缓存	本地 `MyData` 缓存 + 服务器增量同步
### 核心依赖

Newtonsoft.Json (13.0.1) — JSON 序列化
System.Drawing.Common (8.0.7) — 图片处理（Logo/图标等）

二、快速开始¶

2.1 安装¶

通过 NuGet 包管理器安装：

Install-Package AccessEntryCore -Version 1.6.3

或在项目中添加对 AccessEntryCore.dll 的引用。

2.2 命名空间引入¶

using AS;

2.3 用户登录¶

try
{
    // 登录（支持邮箱或用户名）
    var user = Service.Login("user@example.com", "password123", keepOnline: true);

    Console.WriteLine($"登录成功！用户名: {user.Name}");
    Console.WriteLine($"权限等级: {user.Power}");  // guest / manager / administrator
}
catch (ServiceErrorException ex)
{
    Console.WriteLine($"登录失败: {ex.Message}");
}

2.4 自动登录¶

如果在之前的登录中设置了 keepOnline: true，下次启动时会自动尝试登录：

// 静态构造函数会自动调用 AutoLogin()
// 也可以手动调用：
var user = Service.AutoLogin();

if (user != null)
{
    Console.WriteLine("自动登录成功");
}

2.5 登出¶

// 登出并通知服务器
Service.SignOut(server_signout: true);

// 仅本地登出（不清除服务器 Session）
Service.SignOut(server_signout: false);

三、用户管理¶

3.1 User 模型¶

用户是系统的核心实体，权限分三级：

权限级别	枚举值	说明
普通用户	`Power.guest`	默认级别
开发者	`Power.manager`	可创建产品、生成秘钥
管理员	`Power.administrator`	系统最高权限

3.2 创建用户¶

// 创建用户
var newUser = new User("user@example.com", "password123", UserType.Individual, name: "张三", tel: "13800138000");
newUser.Update();  // 保存到服务器

3.3 获取用户信息¶

// 通过 ID 获取（优先使用本地缓存）
var user = Service.GetUser(12345);

// 通过 ID 强制从服务器获取
var userFromServer = Service.GetUser(12345, FromServer: true);

// 通过邮箱获取
var userByEmail = Service.GetUser("user@example.com");

// 获取所有用户列表（仅管理员）
var allUsers = Service.GetUserList();

3.4 用户属性¶

var user = Service.User;

Console.WriteLine($"ID: {user.ID}");
Console.WriteLine($"昵称: {user.Name}");
Console.WriteLine($"邮箱: {user.Email}");
Console.WriteLine($"电话: {user.Tel}");
Console.WriteLine($"权限: {user.Power}");
Console.WriteLine($"账户类型: {user.UserType}");
Console.WriteLine($"创建时间: {user.Create}");
Console.WriteLine($"是否可用: {user.IsEnable}");
Console.WriteLine($"创建者ID: {user.Creater}");

// 获取拥有的所有许可证
var tokens = user.Tokens;

3.5 权限检查¶

// 检查当前用户是否对某个 User 对象有编辑权
if (user.HaveAuthority)
{
    user.Name = "新昵称";
    user.Update();
}
else
{
    Console.WriteLine("没有编辑权限");
}

// 或者直接抛异常
user.ThrowIfNotAuthority();

四、产品管理¶

4.1 Product 模型¶

产品是需要授权访问的软件或服务。每个产品有一个管理员（Administrator），只有管理员和系统管理员可以编辑产品。

4.2 创建产品¶

// 需要先登录（具备 developer 或以上权限）
Service.Login("developer@example.com", "password123");

var product = new Product("我的软件产品", "这是一款用于XXX的软件", img: @"C:\logo.png", url: "https://example.com");
product.KeyWords = "关键词1,关键词2";
product.IsPublic = true;  // 设置为公开可搜索
product.Update();

4.3 获取产品¶

// 通过 ID 获取（优先本地缓存）
var product = Service.GetProduct(123);

// 通过 ID 强制从服务器获取
var product = Service.GetProduct(123, FromServer: true);

// 获取当前用户管理的产品列表
var myProducts = Service.GetProductByAdministrator();

// 搜索公开产品
var searchResults = Service.GetProductList(index: 0, PageSize: 20, SearchText: "关键词");

// 获取公开产品总数
var totalCount = Service.GetProductCount();

4.4 产品属性¶

var product = Service.GetProduct(123);

Console.WriteLine($"产品名: {product.Name}");
Console.WriteLine($"说明: {product.Note}");
Console.WriteLine($"网址: {product.Url}");
Console.WriteLine($"图标: {product.Img}");
Console.WriteLine($"管理员ID: {product.AdministratorUserId}");
Console.WriteLine($"关键词: {product.KeyWords}");
Console.WriteLine($"是否公开: {product.IsPublic}");
Console.WriteLine($"是否可用: {product.IsEnable}");
Console.WriteLine($"是否通过审核: {product.IsPassed}");
Console.WriteLine($"最新版本: {product.LastVersionString}");
Console.WriteLine($"密钥数量: {product.TokensCount}");
Console.WriteLine($"密钥上限: {product.TokensLimit}");

4.5 产品收藏¶

// 添加收藏
product.IsLike = true;

// 取消收藏
product.IsLike = false;

// 查看收藏列表
var likeList = Product.LikeList;

五、许可证（Token）管理¶

Token 是整个权限控制系统的核心，表示用户对某个产品的使用许可。

5.1 计费模式¶

模式	枚举值	说明
按次数	`UseType.ForEvery`	每调用一次消耗一次
按天数	`UseType.ForDays`	从激活日起算N天
截止日期	`UseType.ForSpecialTime`	使用到指定日期
永久有效	`UseType.Forever`	不限次数和时间

5.2 绑定方式¶

方式	枚举值	说明
绑定用户	`BindingType.User`	绑定到特定用户
绑定计算机	`BindingType.Computer`	绑定到特定设备
绑定软件	`BindingType.Software`	绑定到软件本身
多重绑定	`BindingType.MultiUser`	支持多个用户激活

5.3 创建许可证¶

// 需要先登录
Service.Login("developer@example.com", "password123");

var product = Service.GetProduct(123);

// 创建按次数的许可证
var token1 = new Token(UseType.ForEvery, "基础版许可", product, times: 1000, BindingType.User, note: "测试用");
token1.Update();

// 创建按天数的许可证
var token2 = new Token(UseType.ForDays, "30天试用许可", product, times: 30, BindingType.Computer, note: "新用户试用");
token2.Update();

// 创建按截止日期的许可证
var token3 = new Token(UseType.ForSpecialTime, "年度许可", product, new DateTime(2025, 12, 31), BindingType.User, note: "年度订阅");
token3.Update();

5.4 激活许可证¶

// 通过秘钥字符串获取 Token
var token = Service.GetToken("your-token-string-here");

// 激活（会自动绑定到当前用户或计算机）
token.Activity();

// 激活并绑定到指定用户
token.Activity(owner: 12345);

// 取消激活
token.CancelActivity();

5.5 调用（消耗）许可证¶

在用户使用软件功能时，需要调用许可证进行计费：

var token = Service.GetToken("your-token-string-here");

// 必须先激活
token.Activity();

// 消耗 1 次
token.Invoke();

// 消耗指定次数
token.Invoke(count: 10);

// 检查当前状态
TokenStatus status = token.Status;
switch (status)
{
    case TokenStatus.NoActivity:
        Console.WriteLine("未激活");
        break;
    case TokenStatus.Valid:
        Console.WriteLine("有效");
        break;
    case TokenStatus.ExpiresOfTime:
        Console.WriteLine("次数用尽");
        break;
    case TokenStatus.ExpiresOfDays:
        Console.WriteLine("天数到期");
        break;
    case TokenStatus.Banner:
        Console.WriteLine("已被封禁");
        break;
    case TokenStatus.ReCall:
        Console.WriteLine("产品已下架");
        break;
}

5.6 许可证属性¶

Console.WriteLine($"名称: {token.Name}");
Console.WriteLine($"秘钥字符串: {token.Token_String}");
Console.WriteLine($"创建时间: {token.Create}");
Console.WriteLine($"激活时间: {token.Activeity_Date}");
Console.WriteLine($"创建者ID: {token.CreaterUserId}");
Console.WriteLine($"产品ID: {token.ProductId}");
Console.WriteLine($"绑定类型: {token.BindingType}");
Console.WriteLine($"计费模式: {token.UseType}");
Console.WriteLine($"剩余次数: {token.Times}");
Console.WriteLine($"到期时间: {token.EndTime}");
Console.WriteLine($"是否有效: {token.IsValid}");
Console.WriteLine($"状态: {token.Status}");

// 查看使用记录
var usageRecords = token.Used(index: 0, pagesize: 20);
foreach (var record in usageRecords)
{
    Console.WriteLine($"{record.BeginTime} ~ {record.EndTime}: {record.Used} 次");
}

5.7 许可证查询¶

// 获取当前用户创建的 Token
var myTokens = Service.GetTokenByCreater(index: 0, PageSize: 100);
var myTokenCount = Service.GetTokenCountByCreater();

// 获取产品的所有 Token（仅管理员）
var productTokens = product.GetTokens(0, 20);

// 获取当前用户/计算机拥有的所有 Token
var allMyTokens = Service.Tokens;

// 通过秘钥字符串查询
var token = Service.GetToken("your-token-string");

六、产品更新管理¶

6.1 创建版本更新¶

var product = Service.GetProduct(123);

// 通过 Version 对象创建
var update = new Product_Update(product, new Version("2.0.0"), "修复了若干Bug，新增功能X");
update.Update();  // 先保存，获取 ID

// 通过字符串版本号创建
var update2 = new Product_Update(product, "2.1.0", "性能优化");
update2.Update();

// 上传更新文件
update.Upload(@"C:\Release\MyApp_v2.0.0.zip");

6.2 查询更新¶

// 获取产品的所有更新历史
var updates = product.GetUpdates(index: 0, PageSize: 10);

// 获取最新版本
var latestVersion = product.LastVersion;
Console.WriteLine($"最新版本: {product.LastVersionString}");

// 通过 ID 获取
var update = Service.GetProductUpdate(12345);

6.3 文件下载¶

var update = product.LastVersion;

if (update != null && update.HasFile)
{
    Console.WriteLine($"文件名: {update.FileName}");
    Console.WriteLine($"文件大小: {update.FileSize} bytes");
    Console.WriteLine($"下载地址: {update.DownloadUri}");

    // 下载文件
    update.Download(@"C:\Downloads\update.zip");

    // 或异步下载
    update.DownloadAsync(@"C:\Downloads\update.zip");
}

6.4 文件上传事件¶

// 监听上传进度
update.UploadProgressChanged += (sender, e) =>
{
    Console.WriteLine($"上传进度: {e.ProgressPercentage}%");
};

// 监听上传完成
update.UploadDataCompleted += (sender, e) =>
{
    Console.WriteLine("上传完成!");
};

// 监听下载进度
update.DownloadProgressChanged += (sender, e) =>
{
    Console.WriteLine($"下载进度: {e.ProgressPercentage}%");
};

// 监听下载完成
update.DownloadDataCompleted += (sender, e) =>
{
    Console.WriteLine("下载完成!");
};

七、自定义标签（Tags）¶

每个模型对象（User、Product、Token、Message）都支持自定义键值对标签，用于存储业务相关的临时数据。

var token = Service.GetToken("your-token-string");

// 添加/修改标签
token.Tags["custom_field_1"] = "some value";
token.Tags["order_id"] = "ORDER-12345";

// 读取标签
var value = token.Tags["custom_field_1"];
Console.WriteLine(value ?? "不存在");

// 检查是否存在
if (token.Tags.ContainsKey("order_id"))
{
    Console.WriteLine("找到了订单号");
}

// 遍历所有标签
foreach (var kv in token.Tags)
{
    Console.WriteLine($"{kv.Key} = {kv.Value}");
}

// 删除标签
token.Tags.Remove("temp_data");

// 清空所有标签
token.Tags.RemoveAll();

// 标签修改后需要 Update 才能持久化到服务器
token.Update();

注意: Tags 修改后会自动标记父对象为 IsChanged = true，但仍需调用 Update() 才会同步到服务器。

八、消息系统¶

8.1 发送消息¶

// 需要先登录
Service.Login("sender@example.com", "password123");

// 发送消息给指定用户
Service.SendMessage(
    to: "recipient_user_id",
    text: "您好，关于您的产品授权需要更新",
    tags: new Dictionary<string, string>
    {
        { "type", "notification" },
        { "priority", "high" }
    }
);

8.2 接收消息¶

// 获取当前用户的消息列表
var messages = Service.ReceiveMessages(page: 1, limit: 20);

foreach (var msg in messages)
{
    Console.WriteLine($"发送者: {msg.From}");
    Console.WriteLine($"内容: {msg.Text}");
    Console.WriteLine($"时间: {msg.SendTime}");

    // 标记已读
    msg.AreRead();
}

// 获取未读消息数量
var unreadCount = Service.NotReadMessagesCount();

// 获取特定消息
var message = Service.GetMessage(msgId: 12345);

// 取消已发送的消息
message.Cancel();

九、数据缓存与同步¶

9.1 MyData 本地缓存¶

MyData 类提供本地数据缓存功能，存储在 %AppData%\Adtp\MyData.json，用于加速频繁访问的数据查询。

// 获取本地缓存的用户
var cachedUser = MyData.Root.GetUser(12345);

// 获取本地缓存的产品
var cachedProduct = MyData.Root.GetProduct(123);

// 手动触发与服务器同步（初始化时会自动执行一次）
MyData.Root.Synchronization();

// 手动保存缓存
MyData.Root.Save();

9.2 缓存策略¶

Service.GetUser(id) 和 Service.GetProduct(id) 默认优先从本地缓存读取
传递 FromServer: true 可以强制从服务器获取最新数据
启动时会自动执行 Synchronization() 进行增量同步
当缓存中不存在数据时，自动从服务器获取并加入缓存

十、事件系统¶

10.1 登录/登出事件¶

// 登录成功时触发
Service.OnLogined += (sender, e) =>
{
    Console.WriteLine($"用户 {Service.User.Name} 已登录");
};

// 登出时触发
Service.OnSignOut += (sender, e) =>
{
    Console.WriteLine("用户已登出");
};

10.2 许可证激活变化事件¶

// Token 激活或取消激活时触发
Service.ActivityChanged += (sender, token) =>
{
    Console.WriteLine($"Token 状态变化: {token.Token_String}");
    // 刷新 UI 或重新查询
};

十一、异常处理¶

11.1 异常类型¶

异常类	说明
`LocalErrorException`	客户端本地检查产生的异常
`ServiceErrorException`	服务器返回的异常
`TokenNotFoundException`	找不到指定的秘钥
`TokenNotValidException`	秘钥无效或过期

11.2 错误码¶

ErrorEnum 定义了完整的错误码：

错误码	值	说明
`输入的ID值错误`	1001	请求参数中的ID格式错误
`此用户名不存在`	1006	登录时用户不存在
`用户名和密码不匹配`	1007	登录密码错误
`Session不正确`	1009	会话过期或无效
`请先登录后再进行操作`	1011	未登录执行了需登录的操作
`此用户名已经存在`	1012	注册时用户名冲突
`没有权限操作此对象`	1013	无权操作目标对象
`服务器内部产生错误`	1014	服务器500错误
`使用次数已经用完`	1017	Token次数耗尽
`此许可已经到期`	1019	Token过期
`此许可已经到期或是次数已经用完`	1020	Token过期或次数耗尽
`此Token不可重复激活`	1021	尝试重复激活Token
`其他原因`	9999	未分类的错误

11.3 异常处理示例¶

try
{
    Service.Login("user@example.com", "wrong_password");
}
catch (LocalErrorException ex)
{
    Console.WriteLine($"本地错误 [{ex.ErrorCode}]: {ex.Message}");
}
catch (ServiceErrorException ex)
{
    Console.WriteLine($"服务端错误 [{ex.ErrorCode}]: {ex.Message}");
}
catch (TokenNotValidException ex)
{
    Console.WriteLine($"秘钥无效: {ex.Message}");
}

十二、完整场景示例¶

场景：软件开发商发布产品并进行授权管理¶

using AS;

try
{
    // 1. 登录开发者账户
    Service.Login("developer@example.com", "password123", keepOnline: true);

    // 2. 创建产品
    var product = new Product("数据备份大师", "企业级数据备份解决方案", url: "https://backup.example.com");
    product.IsPublic = true;
    product.Update();
    Console.WriteLine($"产品创建成功，ID: {product.ID}");

    // 3. 生成许可证
    var tokenMonthly = new Token(UseType.ForDays, "月度订阅", product, times: 30, BindingType.User, note: "月付用户");
    tokenMonthly.Update();

    var tokenYearly = new Token(UseType.ForSpecialTime, "年度订阅", product, DateTime.Now.AddYears(1), BindingType.User);
    tokenYearly.Update();

    var tokenPerUse = new Token(UseType.ForEvery, "按次计费", product, times: 10000, BindingType.Computer, note: "大客户专用");
    tokenPerUse.Update();

    Console.WriteLine($"月度许可: {tokenMonthly.Token_String}");
    Console.WriteLine($"年度许可: {tokenYearly.Token_String}");
    Console.WriteLine($"按次许可: {tokenPerUse.Token_String}");

    // 4. 发布新版本
    var update = new Product_Update(product, new Version("1.0.0"), "初始版本发布");
    update.Update();
    update.Upload(@"C:\Builds\BackupMaster_v1.0.0.zip");

    // 5. 下发许可证给客户（客户侧代码）
    // var clientToken = Service.GetToken("许可字符串");
    // clientToken.Activity();
    // clientToken.Invoke();

    // 6. 查阅许可证使用情况
    var allTokens = product.GetTokens(0, 100);
    foreach (var t in allTokens)
    {
        Console.WriteLine($"许可: {t.Name}, 状态: {t.Status}, 剩余: {t.Times}");
    }

    // 7. 登出
    Service.SignOut();
}
catch (ServiceErrorException ex)
{
    Console.WriteLine($"操作失败: {ex.Message} (错误码: {ex.ErrorCode})");
}

场景：客户端软件验证许可证¶

using AS;

public class LicenseValidator
{
    public static bool ValidateAndUseLicense(string licenseKey)
    {
        try
        {
            // 自动登录（如果有缓存的Session）
            Service.AutoLogin();

            // 获取并激活许可证
            var token = Service.GetToken(licenseKey);
            if (token == null)
            {
                Console.WriteLine("无效的许可证");
                return false;
            }

            if (token.Activeity_Date == null)
            {
                token.Activity();
            }

            // 检查状态
            if (token.Status != TokenStatus.Valid)
            {
                Console.WriteLine($"许可证状态异常: {token.Status}");
                return false;
            }

            // 消耗一次使用
            token.Invoke();
            Console.WriteLine($"验证通过，剩余可用次数: {token.Times}");

            return true;
        }
        catch (TokenNotValidException ex)
        {
            Console.WriteLine($"许可证验证失败: {ex.Message}");
            return false;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"未知错误: {ex.Message}");
            return false;
        }
    }
}

十三、数据模型关系图¶

┌──────────┐     创建/管理      ┌──────────────┐
│   User   │ ─────────────────> │   Product    │
│ (管理员)  │                    │  (产品)      │
└──────────┘                    └──────┬───────┘
     │                                │
     │ 拥有                           │ 关联
     ▼                                ▼
┌──────────┐                    ┌──────────────┐
│  Token   │ ◄──────────────── │   Product    │
│ (许可证)  │      绑定到产品     │  _Update     │
└────┬─────┘                    │ (产品更新)    │
     │                          └──────────────┘
     │ 使用记录
     ▼
┌──────────────┐
│ Tokens_Used  │
│ (使用记录)    │
└──────────────┘

┌──────────┐     绑定到设备     ┌──────────────┐
│  Token   │ ─────────────────> │  Computer    │
│ (许可证)  │                    │  (本机)      │
└──────────┘                    └──────────────┘

十四、注意事项¶

登录前置条件: 大多数写操作（创建产品、生成Token、发送消息等）需要先登录
权限检查: 修改对象前请确保 HaveAuthority 为 true，或调用 ThrowIfNotAuthority() 主动校验
数据持久化: 修改对象属性后必须调用 Update() 才会保存到服务器；调用 Refresh() 会丢弃本地修改并从服务器重新获取
Token 激活: Token 必须先激活（Activity()）才能调用（Invoke()），激活是不可逆的（除非 CancelActivity()）
测试模式: Debug 编译下自动启用 TestMode = true，会在 UserAgent 中添加 (TestMode) 标记
Session 缓存: 启用 keepOnline 后登录信息会加密存储在 %AppData%\Adtp\user.adtp，有效期30天
图片处理: 设置 Img 属性时支持文件路径或 Base64 字符串两种方式，自动转换为 Base64 存储
线程安全: HTTP 通信使用同步方式（.Result 阻塞），在 UI 线程中调用时需要注意避免阻塞

十五、API 速查表¶

Service 静态类¶

方法	说明
`Service.Login(username, password, keepOnline)`	用户登录
`Service.AutoLogin()`	自动登录（使用缓存Session）
`Service.SignOut(server_signout)`	登出
`Service.GetUser(id, FromServer)`	获取用户
`Service.GetUser(email)`	通过邮箱获取用户
`Service.GetUserList()`	获取所有用户（管理员）
`Service.GetProduct(id, FromServer)`	获取产品
`Service.GetProductList(index, pageSize, searchText)`	搜索产品列表
`Service.GetProductCount()`	获取公开产品总数
`Service.GetProductByAdministrator()`	获取当前用户管理的产品
`Service.GetToken(id)`	通过ID获取Token
`Service.GetToken(tokenString)`	通过秘钥字符串获取Token
`Service.GetTokenByCreater(index, pageSize)`	获取创建的Token列表
`Service.GetTokenCountByCreater()`	获取创建的Token总数
`Service.GetComputer(id)`	获取计算机信息
`Service.GetProductUpdate(id)`	获取产品更新
`Service.GetTokensUsed(id)`	获取Token使用记录
`Service.SendMessage(to, text, tags)`	发送消息
`Service.ReceiveMessages(page, limit)`	接收消息列表
`Service.GetMessage(msgid)`	获取消息详情
`Service.CancelMessage(msgid)`	取消消息
`Service.ReadMessage(msgid, to_id)`	标记消息已读
`Service.NotReadMessagesCount()`	未读消息数量
`Service.TestConnectAsync()`	测试服务器连接

Service 属性¶

属性	说明
`Service.User`	当前登录用户
`Service.Tokens`	当前拥有的所有Token
`Service.Computer`	当前计算机信息
`Service.Power`	当前用户权限等级
`Service.TestMode`	测试模式开关

Base 基类方法¶

方法	说明
`Update()`	保存/更新到服务器
`Refresh()`	从服务器刷新（丢弃本地修改）
`Clone()`	克隆对象
`Equals(Base right)`	比较两个对象是否相同