版本：Next

后端

1. API接口文档说明

CMS2.0基座配备了众多标准化且高效的核心业务模块，并提供了相应的外部接口。借助这些模块，插件能够迅速完成业务开发。以下是为二次开发的外部插件所提供的基座业务模块API接口清单。如需进一步扩展接口，请与产品研发团队联系。

2. 权限模块

提供与用户身份、用户鉴权、用户授权相关信息的API接口。

2.1 获取用户信息

依赖包：CMS.Unit.Authority

命名空间：CMS.Unit.Authority.Services.Abstractions

方法名：IUserService.GetUser

说明：根据用户id获取用户信息

参数

类型	名字	说明
Guid	id	用户id

返回值

返回对象类型：UserGetDTO，属性信息如下：

类型	名字	说明
Guid	Id	用户id
string	UserName	用户名
string	Name	姓名
List<Guid>	RoleIds	关联的角色id集合，未关联时为空集合
string	RolesDisplay	关联的角色全名称，未关联时为空字符串
Guid	OrganizationId	关联的组织架构id，未关联时为空id： 00000000-0000-0000-0000-000000000000
string	OrignizationDiaplsyName	关联的组织架构名称id全名称，为关联时为空字符串

例子

//1.从依赖注入容器中获取IUserService
IUserService userService = ...;

//2.获取用户id
Guid id = ...;

//3.根据用户id获取用户信息
var user = await userService.GetUser(id);

2.2 获取用户的角色信息

依赖包：CMS.Unit.Authority

命名空间：CMS.Unit.Authority.Services.Abstractions

方法名：IRoleService.GetRole

说明：根据角色id获取角色信息

参数

类型	名字	说明
Guid	id	角色id

返回值

返回对象类型：RoleGetDTO

类型	名字	说明
Guid	Id	角色id
string	Name	角色名称
string	Remark	备注

例子

//1.从依赖注入容器中获取IRoleService
IRoleService roleService = ...;

//2.获取角色id
Guid id = ...;

//3.根据角色id获取角色信息
var user = await roleService.GetRole(id);

3. 变量模块

提供与变量相关操作的API接口

3.1 订阅变量变化事件，监听变量的变化

依赖包：CMS.Unit.RuntimeValue.Abstractions
命名空间：CMS.Unit.RuntimeValue.Abstractions
事件名：IVariableDataCache.TagChanged
说明：通过订阅 IVariableDataCache.TagChanged 事件，您可以实时监控变量的变化。此事件会传递所有变量至事件处理函数，因此，业务层需在函数中筛选关注的变量。
注意事项：
（1）性能影响： 发布事件时，事件的发送者将阻塞流程。因此，强烈建议避免在事件处理函数中执行 I/O 操作、HTTP 接口访问或其他耗时操作，以防止对系统性能产生严重影响，导致整个系统响应延迟。
（2）高频率触发： 由于事件订阅了全量变量，触发频率可能非常高。
（3）异步处理： 鉴于事件触发频率很高，建议业务层在筛选关注变量后，使用 Task 启动新线程处理业务逻辑，以避免阻塞核心的变量监听功能，实现业务层与平台基座的解耦。
（4）并发管理： 如果业务层并发量大，必须优化代码设计和实施，以减少在高并发情况下的系统资源消耗，防止系统性能问题。
（5）代码安全： 安装并使用 CMS.CodeAnalysis 分析器来分析 IVariableDataCache.TagChanged 的使用情况。该工具能在使用不当时提供编译错误，帮助您提高代码质量。

事件处理函数输入参数

类型	名字	说明
object	sender	事件发送者
TagChangedEventArgs	e： TraceId Changeds	事件参数：追踪id 变量列表

返回值

N/A

例子

//1.从依赖注入容器中获取IVariableDataCache
IVariableDataCache cache=...;

cache.TagChanged+=(sender,e)=>
{
    //2.找出业务相关的变化变量
    var tags _=e.Changeds.Where(a=>......);
    
   //3.开启新线程处理业务，完成基座与插件解耦 
    _ = Task.Run(() =>
    {
        
    });
};

3.2 使用变量通道，监听变量的变化

依赖包：CMS.Unit.RuntimeValue.Abstractions
命名空间：CMS.Unit.RuntimeValue.Abstractions
方法名：IVariableDataCache.CreateChannel
说明：业务层可注册一个通道以监控变量变化。当变量发生变化时，通道的监听器处理函数将接收到所有变量，允许业务层筛选关注的变量进行处理。
（1）解耦和系统稳定性： 通过实现变量通道，基座的变量变化消息发布和业务层的变量变化消息订阅得到了有效解耦，从而避免了系统变量监听的阻塞引起系统整体响应延迟。
（2）优化并发处理： 如果业务并发量较高，需优化业务处理逻辑，以防止变量变化消息在通道中造成阻塞。
（3）高频率触发管理： 由于通道会监听所有变量，导致处理方法的触发频率较高。业务层应根据实际业务节奏采取合理策略，避免消息在通道中持续积压，确保流畅的消息处理。

创建通道参数

类型	名字	说明
string	name	通道的名字，命名时请加上与插件相关的防止和其他插件的通道名称重复；可以通过通道名称在日志中查询出订阅处理函数的耗时；
IVariableChannelListener	channelListener	通道监听器，业务处理入口
ILogger<VariableChannel>	logger	日志记录器
bool	waitListener	是否等待业务处理结束才开始下一个业务(是否有序)
TimeSpan?	timeout	监听者业务处理函数超时时间，作用于监者听处理函数的入参取消令牌（CancellationToken）参数
bool	continueCaptureContext	请使用默认值
IReadOnlySet<string>?	variableFilter	过滤变量，如果是空就不过滤

返回值

VariableChannel

返回对象需要存在下来，在不使用的时候需要进行释放(Dispose())

例子

//1.定义自己的通道监听，继承基座提供的IVariableChannelListener(变量通道监听器)接口，
public class MyVariableChannelListener : IVariableChannelListener
{
    /// <summary>
    /// 变量变化处理方法
    /// </summary>
    /// <param name="args">变量参数</param>
    /// <param name="token">取消令牌</param>
    /// <returns></returns>
    public async Task RunAsync(TagChangedEventArgs args, CancellationToken token)
    {
        //从全量变量中找出自己业务的变量信号
        var variables = args.Changeds.Where(a => ...);

        //链路追踪id
        var tranceId = args.TraceId;

        //开启新的线程处理业务，完成基座与插件解耦 
        _ = Task.Run(async() => 
        {
            await Task.CompletedTask;
        });
    }
}

//2.创建变量通道
//2.1 从依赖注入容器中获取IVariableDataCachev
IVariableDataCache cache=...;

//2.2 创建变量通道并保存下来，用于后续需要的地方释放通道
var variableChannel = cache.CreateChannel("channel-name", new MyVariableChannelListener(),waitListener:true,timeout:TimeSpan.FromSeconds(30),variableFilter:new HashSet<string> { "a1"});

//3. 在业务结束时需要释放通道，通道释放后如果还有变量变化的消息积压在通道中，消息会随着通道释放而销毁
variableChannel.Dispose();

3.3 变量读取

依赖包：CMS.Extensions.Variable
命名空间：CMS.Extensions.Variable
方法名：IVariableTypeDeterminer.ReadVariableAsync
说明：读取变量

参数

类型	名字	作用
IReadOnlyList<string>	names	需要读取的变量名
Guid	traceId	链路追踪id
CancellationToken	token	取消令牌

返回值

返回值类型：ReadWriteResult<IReadOnlyDictionary<string, DataQuality?>>

类型	名字	作用
ReadWriteCodeResult	Code	结果状态码枚举
IReadOnlyDictionary<string, IVariableValue?>	Content	读取结果内容，字典key时变量名，字典值时变量的值

ReadWriteCodeResult枚举如下

/// <summary>
/// 读写结果状态码
/// </summary>
public enum ReadWriteCodeResult : sbyte
{
    /// <summary>
    /// 没有初始化
    /// </summary>
    NotInited = -1,

    /// <summary>
    /// 成功
    /// </summary>
    Success = 0,

    /// <summary>
    /// 部分成功
    /// </summary>
    PartSuccess = 1,

    /// <summary>
    /// 失败
    /// </summary>
    Fail = 2,

    /// <summary>
    /// 其他
    /// </summary>
    Other = 4
}

IVariableValue描述

类型	名字	作用
object?	Value	读到的数据，已经转成 CLR 类型，如果有
VariableInfo?	Tag	读到的变量信息，如果有
DataQuality?	DataQuality	读到的数据质量，如果有
DateTime?	UpdateTime	读到的最后更新时间，如果有
ReadWriteMode	Mode	读到的变量读写方式：

例子

//1. 从依赖注入容器中获取IVariableTypeDeterminer
IVariableTypeDeterminer determiner = ...;

//2. 读取变量
var result = await determiner.ReadVariableAsync(new string[]{"a1","a2","a3"});

//3. 返回的结果信息准确信校验
... ...

//4.从结果中获取变量的值，例如a1
var a1Value =   result.Content["a1"]?.Value;

3.4 变量写入

依赖包：CMS.Extensions.Variable
命名空间：CMS.Extensions.Variable
方法名：IVariableTypeDeterminer.WriteVariableAsync
说明：给变量写入值

参数

类型	名字	作用
IReadOnlyDictionary<string, object?>	variables	要设置的变量值集合
CancellationToken	token	取消令牌
IEnumerable<string>?	notifyVariables	需要通知的变量，空则按变量类型自动判断是否需要通知
Guid?	traceId	链路追踪 Id

返回值

DataQuality 值与描述

值	描述	处理建议
-1	未初始化	无
0	成功	无
1	变量名不存在	只下发存在的变量名
2	变量格式错误	无
3	设备断开	排查一下设备连接状态
4	其他	无

ReadWriteCodeResult 值与描述

值	描述	处理建议
-1	没有初始化	无
0	全部成功	无
1	部分成功	无
2	全部失败	无
4	其他	无

例子

//1. 从依赖注入容器中获取IVariableTypeDeterminer
IVariableTypeDeterminer determiner=...;

//2. 批量变量设置值
var result=await determiner.WriteVariableAsync(new Dictionary<string, object?>
{
    ["a1"] = 123,
    ["a2"] = "123",
    ["a3"] = DateTime.Now,
    ["a4"] = true,
    ["a5"] = 1.1234,
});

//3. 对写入的结果相关处理
......

4. 数据管理模块

4.1 数据归档功能—新增归档表

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.AddFilingTableAsync
说明：给数据模块的数据表菜单树新增一个归档表节点；
如图：

参数

类型	名字	作用
Guid	folderId	文件夹 id
string	name	显示的表名字
int	sort	表排序 id
Action<FilingTable>?	settings	归档表字段设置，可以无

返回值

FilingTable

类型	名字	作用
Guid	Id	主键
Guid	FolderId	文件夹 id
string	Name	命名
int	Sort	排序
bool	Enable	启用/禁用
DateTime	CreateDateTime	创建时间
SelectMode	OperationMode	操作按钮选择模式
ICollection<OperationType>?	OperationTypes	操作按钮
SelectMode	FunctionMode	功能按钮选择模式
ICollection<FilingTableFunctionType>?	FunctionTypes	功能按钮
ICollection<string>?	ExtendedHeaders	扩展的 headers,默认[记录时间]
bool	CacheConfig_EnableCache	实时缓存
int	CacheConfig_QuantityLimit	缓存数量上限
int	CacheConfig_TimeSpanLimit	时间跨度上限
TimeUnit	CacheConfig_TimeSpanLimitUnit	时间跨度上限单位
string	CacheConfig_ClearCache	缓存清除
bool	StorageConfig_EnableClear	是否启用数据清除
int	StorageConfig_RetentionValue	保留范围(值)
TimeUnit	StorageConfig_RetentionUnit	保留范围(单位)
bool	StorageConfig_BackupBeforeClear	清除前备份
string	StorageConfig_BackupPath	备份路径

SelectMode

类型	名字	作用
All	All	包含所有
None	None	排除所有
Include	Include	包含
Exclude	Exclude	排除

例子

//1. 从依赖注入容器中获取 IFilingTableService
IFilingTableService fillingTableService=...;

//2. 生成或者获取文件夹id
Guid folderGuid=...;

//3. 添加归档表id
var result=await fillingTableService.AddFilingTableAsync(folderGuid,"汽车组BU",1,s=>{...});

4.2 数据归档功能—设置归档表字段配置

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.SetFilingTableFieldsAsync
说明：设置归档表的字段配置；

如图：

参数

类型	名字	作用
Guid	filingTableId	归档表 id
List<FilingTableField>	filingTableFields	归档表字段配置

FilingTableField

类型	名字	作用
string?	Id	主键
Guid	FilingTableId	归档表 id
string	FieldName	字段名称
FieldType	FieldType	字段类型
string	AssociatedVariable	关联变量
string	Formula	计算公式
int	Sort	排序

FieldType

类型	名字	作用
FieldType	Unknow	Unknow
FieldType	数值	数值
FieldType	文本	文本
FieldType	日期	日期

返回值

N/A

例子

//1.从依赖注入容器中获取 IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取归档表id
Guid fillingTableId=...;

//3.构造字段配置列表
List<FilingTableField> fields=...;

//4.给配置表设置字段配置
var result=await fillingTableService.SetFilingTableFieldsAsync(fillingTableId,fields);

4.3 数据归档功能—通过 id 获取归档表

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.GetFilingTableAsync
说明：通过 id 获取归档表在数据表菜单树中的节点信息；

参数

类型	名字	作用
Guid	filingTableId	归档表 id

返回值

FilingTable

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id
Guid fillingTableId=...;

//3.根据id获取聚合表信息
var filingTable=await fillingTableService.GetFilingTableAsync(fillingTableId);

4.4 数据归档功能—通过 id 获取归档表字段配置

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.GetFilingTableAsync
说明：根据归档表节点id获取字段配置信息列表

参数

类型	名字	作用
Guid	filingTableId	归档表 id
bool	queryHeader	是否查询header信息：false-不查询， true-查询

返回值

FilingTableField

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id
Guid fillingTableId=...;

//3.根据id获取聚合表字段配置信息
var filingTableFields=await fillingTableService.GetFilingTableFieldsAsync(fillingTableId,false);

4.5 数据归档功能—删除归档表

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.DeleteFilingTableAsync
说明：根据id删除聚合表节点；

参数

类型	名字	作用
Guid	filingTableId	归档表id

返回值

删除的表及引用的 Id 列表；

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id
Guid fillingTableId=...;

//3.根据id删除聚合表配置节点
await fillingTableService.DeleteFilingTableAsync(fillingTableId);

4.6 数据归档功能—往实时归档表写入数据

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.DataInsertAsync
说明：往实时归档表写入数据

参数

类型	名字	作用
Guid	tableId	归档表id
`List<string>`	columns	列名列表
`List<List<object>>`	dataList	数据列表，第一层列表表示数据值的行列表；第二层列表表示每行中的值列表，其值的索引要和columns中索引一致

返回值

批量的往实时归档表中写入数据

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id、构造列名列表、构造数据列表 参数
Guid fillingTableId=...;
List<string> columns = ...;
List<List<object>> dataList = ...;

//3.根据id删除聚合表配置节点
await fillingTableService.DataInsertAsync(fillingTableId,columns,dataList);

4.7 数据归档功能—对实时归档表数据进行更新

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.DataUpdateAsync
说明：对实时归档表数据进行更新

参数

类型	名字	作用
Guid	tableId	归档表id
`List<(string FieldName, string Operator, object Value)>`	conditions	`条件项属性(多个项时会进行与操作)：FieldName-字段名称，Operator-运算符('>' '<' '=' '!=')，Value-值；参数类型是元组类型`
`IDictionary<string, object?>`	dataList	待更新的数据值列表

返回值

批量的往实时归档表中写入数据

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id、构造列名列表、构造数据列表 参数
Guid fillingTableId=...;
List<(string FieldName, string Operator, object Value) conditions = ...;
IDictionary<string, object?> dataList = ...;

//3.根据id删除聚合表配置节点
await fillingTableService.DataUpdateAsync(fillingTableId,conditions,dataList);

4.8 数据归档功能—通过id清除归档表数据

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IFilingTableService.CleanupAsync
说明：通过id清除归档表数据
参数

类型	名字	作用
Guid	filingTableId	归档表 id

返回值

N/A

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id
Guid fillingTableId=...;

//3.通过id清除归档表数据
await fillingTableService.CleanupAsync(fillingTableId);

4.9 数据聚合功能—新增聚合表

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.AddAggregateTableAsync
说明：给数据模块的数据表菜单树新增一个聚合表节点；

参数

类型	名字	作用
Guid	folderId	文件夹 id
Guid	relativeTableId	关联表 id
NodeType	relativeType	关联类型
string	name	命名
int	sort	排序
Action<AggregateTable>?	settings	聚合表字段设置，可以无

返回值

AggregateTable

例子

//1.从依赖注入容器中获取IAggregateTableService
IAggregateTableService aggregateTableService=...;

//2.获取相关参数
Guid folderId=...;
Guid relativeTableId=...;
NodeType relativeType=...;
string name=...;
int sort=...;

//3.创建聚合表
var aggregateTable=await aggregateTableService.AddAggregateTableAsync(folderId,relativeTableId,relativeType,name,sort,table=>{...});

4.10 数据聚合功能—设置聚合表字段配置

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.SetAggregateTableFieldsAsync
说明：设置聚合表的字段配置；

参数

类型	名字	作用
Guid	aggregateTableId	聚合表 id
List<AggregateTableField>	aggregateTableFields	聚合表字段配置

AggregateTableField

类型	名字	作用
string?	Id	主键
Guid	AggregateTableId	聚合表 id
string	FieldName	字段名称
string?	RelativeFieldId	关联字段 Id
string	Formula	计算公式
GroupType	GroupType	分组方式
HandleType	HandleType	处理方式
FieldType	FieldType	字段类型
int	Sort	排序

返回值

N/A

例子

//1.从依赖注入容器中获取 IAggregateTableService
IAggregateTableService aggregateTableService=...;

//2.获取构造参数信息
Guid aggregateTableId=...;
List<AggregateTableField> aggregateTableFields=...;

//3.设置聚合表的字段配置
await aggregateTableService.SetAggregateTableFieldsAsync(aggregateTableId,aggregateTableFields);

4.11 数据聚合功能—通过 id 获取聚合表

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.GetAggregateTableAsync
说明：通过 id 获取聚合表在数据表菜单树中的节点信息；

参数

类型	名字	作用
Guid	filingTableId	聚合表 id

返回值

AggregateTable

类型	名字	作用
Guid	Id	主键
Guid	FolderId	文件夹 id
Guid	RelativeTableId	关联表 id
NodeType	RelativeType	关联类型
string	Name	命名
int	Sort	排序
bool	Enable	启用/禁用
DateTime	CreateDateTime	创建时间
PreConditionType	PreConditionType	满足条件:所有/任意
SelectMode	OperationMode	操作按钮选择模式
ICollection<OperationType>?	OperationTypes	操作按钮
SelectMode	FunctionMode	功能按钮选择模式
ICollection<FilingTableFunctionType>?	FunctionTypes	功能按钮
ICollection<string>?	ExtendedHeaders	扩展的 headers,默认[记录时间]
bool	StorageConfig_EnableClear	是否启用数据清除
int	StorageConfig_RetentionValue	保留范围(值)
TimeUnit	StorageConfig_RetentionUnit	保留范围(单位)
bool	StorageConfig_BackupBeforeClear	清除前备份
string	StorageConfig_BackupPath	备份路径

例子

//1.从依赖注入容器中获取AggregateTableService
IAggregateTableService aggregateTableService=...;

//2.获取聚合表id
Guid aggregateTableId=...;

//3.通过 id 获取聚合表
var aggregateTable = await aggregateTableService.GetAggregateTableAsync(aggregateTableId);

4.12 数据聚合功能—通过id获取聚合表字段配置

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.GetAggregateTableFieldsAsync
说明：根据聚合表节点id获取字段配置信息列表

参数

类型	名字	作用
Guid	aggregateTableId	聚合表 id
bool	queryHeader	是否查询 header

返回值

AggregateTableField

例子

//1.从依赖注入容器中获取AggregateTableService
IAggregateTableService aggregateTableService=...;

//2.获取聚合表id
Guid aggregateTableId=...;

//3.通过id获取聚合表字段配置
var result=await aggregateTableService.GetAggregateTableFieldsAsync(aggregateTableId,true);

4.13 数据聚合功能—删除聚合表

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.DeleteAggregateTableAsync
说明：根据id删除聚合表节点, 相关联的表都会删除

参数

类型	名字	作用
Guid	aggregateTableId	聚合表 id

返回值

删除的表及引用的 Id 列表

例子

//1.从依赖注入容器中获取AggregateTableService
IAggregateTableService aggregateTableService=...;

//2.获取聚合表id
Guid aggregateTableId=...;

//3.删除聚合表
await aggregateTableService.DeleteAggregateTableAsync(aggregateTableId);

4.14 数据聚合功能—往实时聚合表写入数据

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.DataInsertAsync
说明：往实时归档表写入数据

参数

类型	名字	作用
Guid	tableId	归档表id
`List<string>`	columns	列名列表
`List<List<object>>`	dataList	数据列表，第一层列表表示数据值的行列表；第二层列表表示每行中的值列表，其值的索引要和columns中索引一致

返回值

批量的往实时归档表中写入数据

例子

//1.从依赖注入容器中获取IFilingTableService
IAggregateTableService aggregateTableService=...;

//2.获取聚合表id、构造列名列表、构造数据列表 参数
Guid fillingTableId=...;
List<string> columns = ...;
List<List<object>> dataList = ...;

//3.根据id删除聚合表配置节点
await aggregateTableService.DataInsertAsync(fillingTableId,columns,dataList);

4.15 数据聚合功能—对实时聚合表数据进行更新

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.DataUpdateAsync
说明：对实时归档表数据进行更新

参数

类型	名字	作用
Guid	tableId	归档表id
`List<(string FieldName, string Operator, object Value)>`	conditions	条件项属性(多个项时会进行与操作)：FieldName-字段名称，Operator-运算符('>' '<' '=' '!=')，Value-值；参数类型是元组类型
`IDictionary<string, object?>`	dataList	待更新的数据值列表

返回值

批量的往实时归档表中写入数据

例子

//1.从依赖注入容器中获取IFilingTableService
IFilingTableService fillingTableService=...;

//2.获取聚合表id、构造列名列表、构造数据列表 参数
Guid fillingTableId=...;
List<(string FieldName, string Operator, object Value) conditions = ...;
IDictionary<string, object?> dataList = ...;

//3.根据id删除聚合表配置节点
await fillingTableService.DataUpdateAsync(fillingTableId,conditions,dataList);

4.16 数据聚合功能—通过id清除聚合表数据

依赖包：CMS.Unit.DataConfig.Abstractions
命名空间：CMS.Unit.DataConfig.Abstractions
方法名：IAggregateTableService.CleanupAsync
说明：通过id清除聚合表数据
参数

类型	名字	作用
Guid	aggregateTableId	聚合表 id

返回值

N/A

例子

//1.从依赖注入容器中获取AggregateTableService
IAggregateTableService aggregateTableService=...;

//2.获取聚合表id
Guid aggregateTableId=...;

//3.通过id清除聚合表数据
await aggregateTableService.CleanupAsync(aggregateTableId);

5. 项目服务管理模块

5.1 添加项目服务

依赖包：CMS.Project
命名空间：CMS.Project.Abstractions
抽象类名：IProjectService
说明：基座提供了项目服务管理模块，允许插件通过继承提供的 IProjectService 抽象类，将其服务集成至项目服务管理中，以便进行统一管理。同时，基座还提供了一个基础抽象类 BaseProjectService。为了实现高效的服务管理，建议插件继承此基础抽象类来开发自己的项目服务。

如图：

属性及方法

类型	名字	作用
string	Key	工程服务 key
int	Priority	工程服务优先级，值越大启动优先级越高
bool	AuthRequired	是否需要授权
bool	AllowTrial	是否允许试用
bool	AllowBaseAuth	是否包含在基础授权
ProjectServiceState	State	服务状态
string	Description	服务描述
方法	StartAsync	服务启动处理方法
方法	StopAsync	服务停止处理方法

例子

public class XXProjectService:BaseProjectService
{
    public override string Key => "ExternalPlugin.LongkongDemo";
    public override string Description => "隆控Demo服务";
    public override async Task StartAsync(IServiceProvider serviceProvider)
    {
        //开启服务....
        await base.StartAsync(serviceProvider);
    }

    public override async Task StopAsync(IServiceProvider serviceProvider)
    {
        //结束服务....
        await base.StopAsync(serviceProvider);
    }
}

6. 报警模块

6.1 报警监听事件

依赖包：CMS.Unit.Alarm.Abstractions
命名空间：CMS.Unit.Alarm.Abstractions.Event
事件名：VariableAlarmEventHandler.OnVariableAlarmEvent
说明：插件通过订阅报警监听事件，可以监测报警的发生并执行相关业务的处理；

事件处理函数输入参数

类型	名字	作用
VariableAlarmEvent	@event	事件参数

VariableAlarmEvent

类型	名字	作用
string	AlarmPointID	报警点ID
AlarmTriggerState	TriggerState	触发状态枚举
AlarmStateCacheItem	AlarmStateCache	报警的信息数据，该字段在2.11.0版本才支持

注意：事件参数在基座2.11.0版本之后才支持AlarmStateCache属性

AlarmTriggerState

/// <summary>
/// 报警触发类型
/// </summary>
public enum AlarmTriggerState
{
    /// <summary>
    /// 新增报警
    /// </summary>
    Inactive = 0,

    /// <summary>
    /// 激活的报警
    /// </summary>
    Active = 1,
}

返回值

N/A

例子

//1.从依赖注入容器中获取VariableAlarmEventHandler
VariableAlarmEventHandler variableAlarmEventHandler=...;

//2.注册报警事件
variableAlarmEventHandler.OnVariableAlarmEvent += (e)=>
{
   //3.开启新线程处理业务，完成基座与插件解耦 
    _ = Task.Run(() =>
    {

    });
};

6.2 根据报警点Id获取报警信息

待补充

如果有使用需求，请与盛原成产研开发人员沟通；

7. 日志管理模块

基座提供的日志管理模块如下

7. 1 添加登录日志

依赖包：MediatR
命名空间：MediatR
方法名：ISender.Send
说明：调用接口，往登录日志模块添加登录日志

参数

类型	名字	作用
LoginLogAddRequest	request	添加登录日志请求入参参数

LoginLogAddRequest

类型	名字	作用
LoginLogAddDTO	DTO	添加登录日志的数据传输对象

LoginLogAddDTO

类型	名字	作用
string	UserName	用户名称
LogType	Type	日志类型
DateTime	RecordTime	记录事件

LogType为枚举类型，定义如下

/// <summary>
/// 日志类型
/// </summary>
public enum LogType : byte
{
    /// <summary>
    /// 登录
    /// </summary>
    Login = 0,

    /// <summary>
    /// 退出登录
    /// </summary>
    Logout = 1,

    /// <summary>
    /// 写变量
    /// </summary>
    WriteTag = 2,

    /// <summary>
    /// 读变量
    /// </summary>
    ReadTag = 3,

    /// <summary>
    /// 添加
    /// </summary>
    Add = 4,

    /// <summary>
    /// 修改
    /// </summary>
    Modify = 5,

    /// <summary>
    /// 删除
    /// </summary>
    Delete = 6,

    /// <summary>
    /// 重置密码
    /// </summary>
    ResetPassword = 7,

    /// <summary>
    /// 授权
    /// </summary>
    AuthSetting = 8,
}

返回值

N/A

例子

//基座日志模块使用了MediatR中介者模式库，如需了解请看https://github.com/jbogard/MediatR
//1.从依赖注入容器中获取IMediator
IMediator mediator = ... ;

//2.构造入参
LoginLogAddDTO dto = ... ;

//3.发送日志
await mediator.Send(new LoginLogAddRequest());

7.2 添加设备日志

依赖包：MediatR
命名空间：MediatR
方法名：ISender.Send
说明：调用接口，往登录设备日志模块添加设备日志

参数

类型	名字	作用
DeviceLogAddRequest	request	添加日志的请求入参参数

DeviceLogAddRequest

类型	名字	作用
DeviceLogAddDTO	DTO	添加登录日志的数据传输对象

DeviceLogAddDTO

类型	名字	作用
string	Device	设备
string	Group	设备组
string	TagName	变量名
string	TagDescription	变量描述
Dictionary<string, string>	DynamicParams	动态参数
string	UserName	用户名称
LogType	Type	日志类型
DateTime	RecordTime	记录时间

返回值

N/A

例子

//基座日志模块使用了MediatR中介者模式库，如需了解请看https://github.com/jbogard/MediatR
//1.从依赖注入容器中获取IMediator
IMediator mediator = ... ;

//2.构造入参
DeviceLogAddDTO dto = ... ;

//3.发送日志
await mediator.Send(new DeviceLogAddRequest());

7.3 添加模块日志

依赖包：MediatR
命名空间：MediatR
方法名：ISender.Send
说明：调用接口，往登录模块日志模块添加模块日志

参数

类型	名字	作用
ModuleLogAddRequest	request	添加模块日志的请求入参参数

ModuleLogAddRequest

类型	名字	作用
ModuleLogAddDTO	DTO	添加日志的数据传输对象

ModuleLogAddDTO

类型	名字	作用
string	ModuleKey	模块 id
string	Target	目标
List<ModuleLogDynamicParam>	DynamicParamList	动态参数

ModuleLogDynamicParam

类型	名字	作用
string	Key	键
string[]	KeyArgs	键参数
string[]	OldValues	旧值列表
string[]	NewValues	新值列表

返回值

N/A

例子

//1.从依赖注入容器中获取IMediator
IMediator mediator = ... ;

//2.构造入参
ModuleLogAddDTO dto = ... ;

//3.发送日志
await mediator.Send(new ModuleLogAddRequest(dto));

1. API接口文档说明​

2. 权限模块​

2.1 获取用户信息​

2.2 获取用户的角色信息​

3. 变量模块​

3.1 订阅变量变化事件，监听变量的变化​

3.2 使用变量通道，监听变量的变化​

3.3 变量读取​

3.4 变量写入​

4. 数据管理模块​

4.1 数据归档功能—新增归档表​

4.2 数据归档功能—设置归档表字段配置​

4.3 数据归档功能—通过 id 获取归档表​

4.4 数据归档功能—通过 id 获取归档表字段配置​

4.5 数据归档功能—删除归档表​

4.6 数据归档功能—往实时归档表写入数据​

4.7 数据归档功能—对实时归档表数据进行更新​

4.8 数据归档功能—通过id清除归档表数据​

4.9 数据聚合功能—新增聚合表​

4.10 数据聚合功能—设置聚合表字段配置​

4.11 数据聚合功能—通过 id 获取聚合表​

4.12 数据聚合功能—通过id获取聚合表字段配置​

4.13 数据聚合功能—删除聚合表​

4.14 数据聚合功能—往实时聚合表写入数据​

4.15 数据聚合功能—对实时聚合表数据进行更新​

4.16 数据聚合功能—通过id清除聚合表数据​

5. 项目服务管理模块​

5.1 添加项目服务​

6. 报警模块​

6.1 报警监听事件​

6.2 根据报警点Id获取报警信息​

7. 日志管理模块​

7. 1 添加登录日志​

7.2 添加设备日志​

7.3 添加模块日志​

1. API接口文档说明

2. 权限模块

2.1 获取用户信息

2.2 获取用户的角色信息

3. 变量模块

3.1 订阅变量变化事件，监听变量的变化

3.2 使用变量通道，监听变量的变化

3.3 变量读取

3.4 变量写入

4. 数据管理模块

4.1 数据归档功能—新增归档表

4.2 数据归档功能—设置归档表字段配置

4.3 数据归档功能—通过 id 获取归档表

4.4 数据归档功能—通过 id 获取归档表字段配置

4.5 数据归档功能—删除归档表

4.6 数据归档功能—往实时归档表写入数据

4.7 数据归档功能—对实时归档表数据进行更新

4.8 数据归档功能—通过id清除归档表数据

4.9 数据聚合功能—新增聚合表

4.10 数据聚合功能—设置聚合表字段配置

4.11 数据聚合功能—通过 id 获取聚合表

4.12 数据聚合功能—通过id获取聚合表字段配置

4.13 数据聚合功能—删除聚合表

4.14 数据聚合功能—往实时聚合表写入数据

4.15 数据聚合功能—对实时聚合表数据进行更新

4.16 数据聚合功能—通过id清除聚合表数据

5. 项目服务管理模块

5.1 添加项目服务

6. 报警模块

6.1 报警监听事件

6.2 根据报警点Id获取报警信息

7. 日志管理模块

7. 1 添加登录日志

7.2 添加设备日志

7.3 添加模块日志