Hi.Ltd.SqlServer 2026.5.27.1810

Hi.Ltd.SqlServer 使用说明文档

本类库是海蓝智能科技有限公司提供关于Sql Server数据库相关的操作方法的类库。
本类库仅供参考使用，不保证方法的有效性，请谨慎使用！

目录

1. 概述
2. 快速开始
3. Factory、SqlEntities 与 Auto 自动托管
4. 属性说明
5. 连接和基础操作
6. 数据库操作
7. 数据表操作
   • 7.1 判断数据表是否存在
   • 7.2 创建数据表
   • 7.3 修改数据表
   • 7.4 插入数据
   • 7.5 更新数据
   • 7.6 查询数据
   • 7.7 删除数据
   • 7.8 删除数据表
   • 7.9 复制数据表
   • 7.10 多表联查
8. 存储过程操作
9. 架构操作
10. 表类型操作
11. 执行操作
    • 11.1 异步执行自定义 SQL
12. 已知限制与索引/统计维护
13. ITools 只读统计

---

概述

Hi.Ltd.SqlServer 是一个用于与 SQL Server 数据库进行交互的 C# 类库，提供了完整的数据库、表、存储过程等对象的创建、查询、更新和删除功能。该类库采用面向对象的方式，通过 C# 类定义来映射数据库表结构，简化了数据库操作的复杂性。

主要特性

• 基于 C# 类的数据库表结构映射
• 支持数据库的创建、备份、还原、附加、分离等操作
• 支持数据表的创建、修改、查询、插入、更新、删除等操作
• 支持存储过程的创建、更新、删除等操作
• 支持数据库架构和表类型的操作
• 提供事务支持和多种执行方式
• 多表联查：一主一从、一主多从、多主多从（JoinTable / JoinTableMany / JoinTableMulti + MultiMasterJoinSpec），从表依赖 [ForeignKey] 元数据生成 JOIN
• 异步执行：IExecuteAsync 对自定义 commandText 提供 ExecuteNonQueryAsync、ExecuteScalarAsync、ExecuteReaderAsync 等（支持 CancellationToken）
• 多表主从插入：InsertMultiTable 在单事务内完成主表与多从表插入（自增主键通过 OUTPUT INSERTED 取值；批量时从表行数与主表对齐）
• 多表联查异步：IInqureMultiTableAsync 提供与 IInqureMultiTable 对等的 JoinTable / JoinTableMany / JoinTableMulti 异步方法
• 批量插入调优：SqlBulkInsertSettings 与 InsertTable / InsertTableAsync 重载可配置 BatchSize、TableLock、KeepIdentity、FireTriggers
• 索引与统计：IIndexMaintenance 封装 REBUILD / REORGANIZE / UPDATE STATISTICS（标识符校验）
• 只读统计（ITools）：ISqlServer 通过 ITools 提供列元数据、COUNT/SUM/TOP/GroupByCount 等，以及 T-SQL 对齐的 聚合扩展（如 COUNT_BIG、STRING_AGG）、窗口分析（LAG、PERCENTILE_CONT 等）、数学标量/逐列函数（PI、ROUND、POWER 等）；详见 ITools 只读统计。
• Factory 全局托管：Factory.SqlServer 统一持有 ISqlServer 句柄，提供 ConfigureSqlServer、InitialSqlServer、LoadModelAssembly / Synchronize 及 Result 包装的 CRUD（Insert/Update/Delete/Query 与 *Async）；与 [Auto] 配合可在 DML 前按需确保库表结构。详见 Factory、SqlEntities 与 Auto 自动托管。

已知限制与索引/统计维护

项	说明
多表主从插入	InsertMultiTable 已在单连接事务内实现：先插入主表（自增主键用 OUTPUT INSERTED 取值），再按从表类型逐行插入；批量主表时要求每个从表类型的行数与主表行数一致或为 0。useTableValuedParameter 当前与逐条路径等价（预留 TVP 加速）。
ITools	仅生成 单表、基于 可映射持久化列白名单 的只读 SQL；不生成 GROUPING SETS / CUBE / ROLLUP 及 GROUPING / GROUPING_ID；复杂语义请用 IExecute / IExecuteAsync 手写 T-SQL。部分函数有 最低 SQL Server 版本（见下文 ITools 专节）。
索引 DDL	通用 CREATE INDEX 未做模型级封装；请使用 IIndexMaintenance（RebuildIndex / ReorganizeIndex / UpdateStatistics）或下方模板配合 IExecute / IExecuteAsync。
超大数据集查询	联查/单表查询默认物化为 List<Dictionary<string, object>>；极大结果集请分页、ExecuteReader 自定义流式处理，或手写 SQL。

IExecute / IExecuteAsync 用索引与统计（请将方括号内标识符换成实际库名、架构、表名、索引名）：

-- 非聚集索引示例（按需改列与 INCLUDE）
CREATE NONCLUSTERED INDEX [IX_YourTable_YourColumn]
ON [dbo].[YourTable] ([YourColumn])
INCLUDE ([OtherColumn])
WITH (ONLINE = ON, DATA_COMPRESSION = ROW);  -- 企业版等环境支持 ONLINE 时

-- 重建索引
ALTER INDEX [IX_YourTable_YourColumn] ON [dbo].[YourTable] REBUILD WITH (ONLINE = ON);

-- 重组索引
ALTER INDEX [IX_YourTable_YourColumn] ON [dbo].[YourTable] REORGANIZE;

-- 更新统计信息（整表）
UPDATE STATISTICS [dbo].[YourTable] WITH FULLSCAN;  -- 或 SAMPLE 50 PERCENT

---

快速开始

初始化连接

var sql = SqlEntities.Create;
sql.DataSource = "(local)";      // 数据库服务器地址
sql.UserId = "sa";               // 登录用户名（可选，不填写则使用 Windows 身份验证）
sql.Password = "Demo123456";     // 登录密码（可选）
sql.InitialCatalog = "Hi.Ltd";   // 数据库名称
sql.Timeout = 10;                // 连接超时时间（秒），默认 15 秒

// 测试连接
bool connected = sql.Connection();

方式二：使用 Factory（全局 ISqlServer）

适合 进程内单例数据库访问、或与 InitialSqlServer / Factory.Insert 等封装配合的场景：

Factory.ConfigureSqlServer(c => { c.DataSource = "(local)"; c.InitialCatalog = "Hi.Ltd"; /* … */ });
Factory.LoadModelAssembly(typeof(Program).Assembly);
var report = Factory.InitialSqlServer(); // 全量同步已加载模型
var ok = Factory.SqlServer.Connection();

详见 Factory、SqlEntities 与 Auto 自动托管。

创建数据库和表

// 创建数据库
sql.CreateDatabase("Hi.Ltd");

// 定义表结构
[Table("Navigation", Schema = "dbo")]
public class NavigationTable
{
    [Key]
    public int Id { get; set; }
    [MaxLength(450)]
    public string Content { get; set; }
}

// 创建表
sql.CreateTable<NavigationTable>();

---

Factory、SqlEntities 与 Auto 自动托管

SqlEntities（显式 ISqlServer 实例）

成员	说明
SqlEntities.Create	公共静态只读字段，单例式默认入口（new SqlEntities()），适合自行持有引用并直接调用 ISqlServer 全量 API。
SqlEntities.CreateNew()	每次 新建 SqlEntities 实例；Factory 在句柄失效替换时使用，也可在测试中隔离实例。

自行 var sql = SqlEntities.Create 时，连接配置、异常与资源生命周期均由调用方负责；不经过 Factory 的句柄重建与 ExecuteSafe 包装。

Factory（全局句柄与模型同步）

Factory 为 静态 partial 类，托管一个全局 ISqlServer（默认来自 SqlEntities.CreateNew()），并缓存 连接参数快照（DataSource、InitialCatalog、UserId、Password、Timeout、Encrypt、TrustServerCertificate）。典型用法：

// 1）配置连接（会写回全局句柄并更新快照）
Factory.ConfigureSqlServer(c =>
{
    c.DataSource = "(local)";
    c.InitialCatalog = "Hi.Ltd";
    c.UserId = "sa";
    c.Password = "***";
});

// 2）加载模型程序集并全量同步（非 [Auto] 与 [Auto] 均参与，由 SchemaSyncOptions 筛选）
Factory.LoadModelAssembly(typeof(MyEntity).Assembly);
var syncReport = Factory.InitialSqlServer(); // 内部使用 Factory.SqlServer；等价于 InitialSqlServer(Factory.SqlServer, …)

// 3）使用全局句柄做任意 ISqlServer 操作（含 ITools）
var cnt = Factory.SqlServer.Count<MyEntity>();

// 4）可选：注入自定义 ISqlServer 实现
// Factory.SetSqlServer(myCustomSqlServer);

API	作用
Factory.SqlServer	获取全局句柄；内部 EnsureSqlServer()，必要时新建并 应用连接快照。
Factory.ConfigureSqlServer(Action<IConnection>)	在锁内配置当前句柄并 捕获快照。
Factory.SetSqlServer(ISqlServer)	替换全局句柄并捕获快照。
Factory.LoadModelAssembly(Assembly)	扫描程序集中的表模型并登记到 ModelAssemblyCatalog；返回候选类型列表。
Factory.ModelTypes	当前已登记的模型类型只读列表。
Factory.Synchronize(ISqlServer, SchemaSyncOptions)	对给定实例执行架构同步，返回 Result<SchemaSyncReport>。
Factory.InitialSqlServer(ISqlServer, Assembly, SchemaSyncOptions)	先 LoadModelAssembly（若传入程序集），再 Synchronize。
Factory.InitialSqlServer(Assembly, SchemaSyncOptions)	使用 全局 Factory.SqlServer 的便捷重载；若句柄疑似已释放会先 重建 再同步。

说明（与 [Auto] 的关系）：InitialSqlServer 文档约定为同步 非 [Auto] 与 [Auto] 两类模型；其中 [Auto] 表在运行期仍可在 DML 热路径上由 EnsureAutoArtifacts 按需补全工件；全量 Synchronize 成功后会 AutoTableRegistry.InvalidateEnsured()，下次 DML 会重新校验 Auto 就绪状态。

关于 Synchronize 告警（Report.Successed=false）的说明：

• 该告警常见于历史库漂移：表结构已演进，但对应 TVP（xxxType）或过程仍是旧版本。
• 典型现象是外层 Result.Successed=true，但 SchemaSyncReport.Successed=false，并出现“值不在预期的范围内”等业务层失败信息。
• 从 2026.4.21 起，UpdateTableType(database, table, schema) 在重建 TVP 前会先删除所有引用该 TVP 的过程（含历史命名过程），再执行类型重建，避免“类型被过程占用导致无法更新”的连锁失败。
• 若你在旧版本库上升级，建议先执行一次 Factory.InitialSqlServer(...) 或 Factory.Synchronize(...) 做全量收敛，再进入常规 DML 流程。

Factory CRUD 便捷 API（Result / 句柄自愈）

下列方法在 Factory.SqlServer 上执行对应 ISqlServer 调用，统一 Result<T> 风格，并在捕获 ObjectDisposedException / NullReferenceException 等「句柄失效」异常时 自动重建实例、应用连接快照并重试一次：

• 同步：Insert<T>、Insert<T>(string database, …)、Update<T>、Delete<T>(int id)、Delete<T>(T condition, bool fuzzy) 及带 database 的重载；Query<T>()、Query<T>(T condition, …)、Query<T>(string database, …) 等。
• 异步：InsertAsync、UpdateAsync、DeleteAsync、QueryAsync 等，支持 CancellationToken。

与直接 sql.InsertTable 的差异：Factory.Insert 等 不向外抛出 上述可恢复异常，而是转为失败 Result；且对标注 [Auto] 的类型，与 InsertTable 相同，会在调用链中触发 自动结构确保（库/表/表类型等，见下节）。

[Auto]（AutoAttribute）自动托管

将 [Auto] 与 [Table(...)] 同时标在 具体表 POCO 上时，该类型进入 自动托管 集合（ModelAssemblyCatalog.IsAutoManagedType 要求二者兼备；仅有 [Auto] 无 [Table] 的类型会被忽略）。

效果简述：

1. DML / 部分查询：通过 ISqlServer 的 InsertTable / UpdateTable / DeleteTable / InqureTable 及 显式接口实现 的 *Async 路径时，运行期会调用 SchemaSynchronizer.EnsureAutoArtifacts（及外键指向的其它 Auto 类型），在 当前目标数据库 上按需创建/对齐 库、表、用户定义表类型、MERGE 过程、外键 等（具体子集由内部选项 AutoOnly 等控制）。
2. Factory.Insert / Query 等：最终仍落到同一套 ISqlServer API，因此 [Auto] 行为与直连 SqlEntities 一致。
3. 全量架构同步：执行 Factory.Synchronize / InitialSqlServer 成功后，会 清空 Auto 就绪缓存，避免结构变更后与缓存不一致。

推荐实践：

• 业务表若希望 启动时一次对齐 且不在每条 DML 做按需确保：可 不加 [Auto]，仅在部署/启动时调用 Factory.InitialSqlServer(...)。
• 希望 省掉显式建表、由首次写入/查询兜底：对 POCO 使用 [Table(...), Auto]，并保证程序集已被 LoadModelAssembly 或在 InitialSqlServer 中加载。

属性文档：AutoAttribute 的 XML 说明见源码 Attributes/AutoAttribute.cs；本 README 的 TableAttribute 一节可与 [Auto] 联读。

在 Factory 上使用 ITools

ISqlServer 继承 ITools，因此：

var cols = Factory.SqlServer.Columns<MyEntity>();
var n = Factory.SqlServer.Count<MyEntity>();

统计扩展（CountBig、StringAgg、Lag、PercentileCont、Round 等）用法与 ITools 只读统计 专节相同，仅将接收者由局部 sql 换为 Factory.SqlServer 即可。

自动并发调度（默认开启，可选覆盖）

为支持高并发、高频查询与插入，本库在 InsertTable / InqureTable 主路径内置自动调度层，默认开箱即用，调用方式保持不变。

分级使用（默认省心 + 专家全控）

层级	适用对象	做法
L0 隐式默认	不改代码的存量项目	行为与历史版本一致：未显式设置 ConcurrencyScheduler 时，多个 ISqlServer 实例可能共用类库内的静态默认 DefaultConcurrencyScheduler；适合低争用或单实例全局 SqlEntities.Create。
L1 一行预设	希望「少配参、少踩共享调度器坑」的接入方	在配置好连接信息后调用 ApplyWorkloadPreset(SqlServerWorkloadPreset)：为本实例绑定独占的 DefaultConcurrencyScheduler + 预设对应的 SqlServerConcurrencyOptions（见 SqlServerWorkloadPresetMapper）。
L2 阈值微调	已用 L1 或默认，仅需改个别阈值	继续调用 ConfigureConcurrency(new SqlServerConcurrencyOptions { … })；未设置的项仍回退 DefaultConcurrencyPolicy 内置默认。
L3 完全自定义	SQL Server / 并发专家	直接赋值 ConcurrencyScheduler = 自定义 IConcurrencyScheduler，或组合 ApplyWorkloadPreset 后再替换调度器；压测规模仍只用 IConcurrencyStressProfile，勿与运行期调度混写。

L1 示例（推荐多线程 / 多 ISqlServer 实例时至少调用一次）：

var sql = SqlEntities.CreateNew(); // 或 SqlEntities.Create
sql.DataSource = "..."; sql.UserId = "..."; sql.Password = "..."; sql.InitialCatalog = "...";
sql.ApplyWorkloadPreset(SqlServerWorkloadPreset.Balanced);           // 与内置策略数值一致，但实例独占调度器
// sql.ApplyWorkloadPreset(SqlServerWorkloadPreset.HighThroughputInteractive); // Web/API 混合读写、短时洪峰
// sql.ApplyWorkloadPreset(SqlServerWorkloadPreset.LowContentionDedicated);   // 独占库/批处理，需自行压测与评审

默认行为：

• 用户继续调用原有 API（InsertTable / InqureTable），无需额外改造。
• 类库内部通过 IConcurrencyScheduler + IConcurrencyPolicy 判定高频/高并发并做排队调度。
• 当未提供自定义配置时，使用 DefaultConcurrencyScheduler 与 DefaultConcurrencyPolicy。

可选用户配置（覆盖默认阈值）：

var sql = SqlEntities.Create;
sql.ConfigureConcurrency(new SqlServerConcurrencyOptions
{
    MaxReadConcurrency = 128,
    MaxWriteConcurrency = 64,
    HighFrequencyThreshold = 1000
});

高 TPS 压测或回归场景下，若 HighFrequencyThreshold 过小，易在 1s 滑窗内触发「高频排队」路径，表现为 p95 升高、吞吐下降；可适当调大该值，或调用 ConcurrencyScheduler.ResetFrequencyWindow() 做阶段隔离。

扩展点：

• ISqlServer.ApplyWorkloadPreset(...)：按枚举绑定实例级 DefaultConcurrencyScheduler + 预设策略；映射表见 SqlServerWorkloadPresetMapper.ToConcurrencyOptions。
• ISqlServer.ConcurrencyScheduler：可替换为自定义调度器实现；实现方需提供 Enter、Policy 读写、CurrentPolicy 只读视图、ApplyOptions(SqlServerConcurrencyOptions)（与 ConfigureConcurrency 对齐），以及 ResetFrequencyWindow()（无滑窗语义时可空操作；用于阶段边界清空高频采样）。
• ISqlServer.ConfigureConcurrency(...)：内部委托 ConcurrencyScheduler.ApplyOptions，快速覆盖默认策略阈值（未设置项自动回退默认值）。

与压测配置的职责分离：

• 运行期调度（读写并发上限、高频滑窗、排队超时等）只由 SqlServerConcurrencyOptions / IConcurrencyPolicy / IConcurrencyScheduler 表达；不要把「压测线程数、请求数、混合时长、回归 P95/ops 门禁」写进调度选项，以免调用方误以为生产路径依赖这些字段。
• 压测规模与门禁由 IConcurrencyStressProfile（内置只读默认见 DefaultConcurrencyStressProfile.Instance，可变副本见 ConcurrencyStressProfile）描述；ISqlServer.ConcurrencyStressProfile 为可选注入（null 表示使用内置默认）。测试工程还可通过 App.config 中 RegressionTest.ConcurrencyStress.* 键（任选其一即生效）构造并挂载 profile。

并发专项回归

测试工程新增并发回归项（核心主路径）；规模与门禁读取 sql.ConcurrencyStressProfile ?? DefaultConcurrencyStressProfile.Instance：

• 多线程插入
• 多线程查询
• 混合读写高频

回归输出指标包含：ops/s、P50/P95、失败率、最大耗时，用于持续校验“稳定性 + 响应速度”。

并发回归内使用直通调度器。当 ISqlServer.ConcurrencyStressProfile 为 null（未显式注入）时，插入 / 查询 / 混合三段均只校验 fail==0，避免因共享 SQL 实例上偶发长尾（P95/ops）误杀回归。若要对任一段启用 P95/ops 门禁，请挂载 ConcurrencyStressProfile（或 App.config 中 RegressionTest.ConcurrencyStress.*，任选一键即整表生效）。

大表随机点查性能（测试工程可选）

在 Hi.Ltd.SqlServer.Test 的 App.config 中配置 RegressionTest.LargeReadPerf.TableName（及可选 Schema / IdColumn / MinId / MaxId / RequestCount / WorkerCount 等）后，控制台回归会在「统计工具」与「并发专项」之间执行 LargeReadPerfRegression：对指定表做 参数化 COUNT_BIG(*) WHERE Id=@rid 点查，多线程随机主键，输出 ops/s、P50/P95、max、ok/fail；默认在 FROM 上使用 WITH (NOLOCK) 以贴近高频只读压测（可用 DisableNolock=true 关闭）。MinOpsPerSec / MaxP95Ms 为 0 时不做吞吐与 P95 门禁（仅统计）；若需门禁则设正数。未配置 TableName 时该项跳过。

---

属性说明

下列特性均位于命名空间 Hi.Ltd.SqlServer（源码目录 src/Attributes）。若某类型在其它程序集中定义了 同名 特性（如 System.ComponentModel.DataAnnotations 的 Required、MaxLength 等），以本库元数据解析逻辑为准（与常见框架特性的等价关系见测试工程中的等价性校验）。

属性一览（专用于本库 SQL Server 映射）

特性类	声明目标	摘要
TableAttribute	类	表名与架构（[Table("Name", Schema = "dbo")]）。
DatabaseAttribute	类	覆盖该模型所在 逻辑数据库名（与连接串 InitialCatalog 解析配合）。
AutoAttribute	类	与 [Table] 联用，运行期 自动托管 库/表/类型等（见 Factory 专节）。
KeyAttribute	属性/字段	主键；默认 Identity + 必填语义。
ForeignKeyAttribute	属性/字段	外键及指向主表类型、级联选项。
ColumnAttribute	属性/字段	列名映射、顺序、TypeName 等。
DatabaseGeneratedAttribute	属性/字段	主键是否自增等。
RequiredAttribute	属性/字段/参数	非空。
MaxLengthAttribute	属性/字段/参数	字符串最大长度。
MinLengthAttribute	属性/字段/参数	字符串最小长度。
StringLengthAttribute	属性/字段/参数	最小与最大长度范围。
DecimalAttribute	属性/字段/参数	decimal 列映射为 T-SQL DECIMAL(p,s)（Precision/Scale）。
DigitAttribute	属性/字段/参数	已过时，请改用 DecimalAttribute；旧代码仍生效（Total→p，Count→s）。
NotMappedAttribute	类/属性/字段	不参与持久化映射。
ComplexTypeAttribute	类	复杂类型（无独立表）。
ConcurrencyCheckAttribute	属性/字段	乐观并发检查列。
TimestampAttribute	属性/字段	rowversion 语义（byte[]）。
FullTextAttribute	属性/字段/参数	标记全文相关列。
InversePropertyAttribute	属性/字段	双向导航反向属性名。
VisiableAttribute	属性/字段/参数	查询/展示可见性提示（不改变表结构）。

KeyAttribute

功能说明： 标识数据表的主键列。设置 [Key] 后，默认启用自增（Identity）和不可为空（Required）选项。

接口定义：

[Key]
public int Id { get; set; }

注意事项：

• 主键列默认自增，如需禁用需配合 DatabaseGeneratedAttribute 使用
• 主键列默认不可为空

---

DatabaseAttribute

功能说明： 指定 表模型类 映射到的逻辑数据库名称（类名在源码文件中为 DatabaseAttribute，与 DataBase 拼写不同）。

接口定义：

[Database("Hi.Ltd")]
public class Table
{
    // ...
}

参数说明：

• 构造函数参数 name：数据库名称；映射后通过 Name 属性读取。

---

TableAttribute

功能说明： 指定数据表的名称和架构。如未指定架构，默认为 "dbo"。

接口定义：

// 使用默认架构 dbo
[Table("Navigation")]
public class NavigationTable { }

// 指定架构
[Table("Navigation", Schema = "hi")]
public class NavigationTable { }

参数说明：

• name: 数据表名称
• Schema: 表架构名称（可选，默认为 "dbo"）

---

AutoAttribute

功能说明： 与 [Table] 联用时，将表模型标记为 运行期自动托管：在 InsertTable / UpdateTable / DeleteTable / InqureTable 及对应 *Async 显式实现路径中，按需调用 SchemaSynchronizer.EnsureAutoArtifacts，自动确保目标库上的 库、表、用户定义表类型、MERGE 过程、外键 等工件就绪；外键指向的其它类型若为 [Auto] 会一并递归确保。

接口定义：

[Table("Orders", Schema = "dbo"), Auto]
public class OrderRow
{
    [Key]
    public int Id { get; set; }
    // ...
}

注意事项：

• 必须同时存在 [Table]；仅有 [Auto] 无 [Table] 时框架 忽略 该类型（不参与 Auto 托管判定）。
• 全量 Factory.Synchronize / InitialSqlServer 完成后会 失效 Auto 就绪缓存，下次 DML 将重新校验。
• 更完整的场景说明、与 Factory / InitialSqlServer 的分工见 Factory、SqlEntities 与 Auto 自动托管。

---

DatabaseGeneratedAttribute

功能说明： 指定主键是否为自增列。未设置时，主键默认为自增（Identity）。

接口定义：

// 禁用自增
[Key, DatabaseGenerated(DatabaseGeneratedOption.None)]
public int Id { get; set; }

// 启用自增（默认）
[Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
public int Id { get; set; }

参数说明：

• DatabaseGeneratedOption.None: 非自增
• DatabaseGeneratedOption.Identity: 自增

注意事项：

• 必须与 [Key] 属性配合使用

---

MaxLengthAttribute

功能说明： 指定字符串字段的最大长度。未指定时，默认长度为 50。

接口定义：

[MaxLength(450)]
public string Content { get; set; }

参数说明：

• length: 最大字符长度（Unicode 字符）

注意事项：

• 超出长度可能引发异常或截断字符
• 建议根据实际需求设置合适的长度

---

RequiredAttribute

功能说明： 指定字段是否允许为空。未设置时，字段默认为可空。

接口定义：

[Required, MaxLength(450)]
public string Content { get; set; }  // 不可为空

[MaxLength(450)]
public string Note { get; set; }     // 可为空

---

ForeignKeyAttribute

功能说明： 定义外键关系，指定从表与主表的关联，以及主表删除或更新时对从表的影响。

接口定义：

[Table("Master", Schema = "dbo")]
public class MasterTable
{
    [Key]
    public int Id { get; set; }
    // ...
}

[Table("Slave", Schema = "dbo")]
public class SlaveTable
{
    [Key]
    public int Id { get; set; }
    
    // 默认 Restrict：如果从表有匹配记录，不允许对主表进行更新/删除
    [ForeignKey(typeof(MasterTable))]
    public int MasterId { get; set; }
    
    // Cascade：主表更新/删除时，同步更新/删除从表的匹配记录
    [ForeignKey(typeof(MasterTable), Option = TableDeleteOrUpdateOption.Cascade)]
    public int MasterId { get; set; }
    
    // Null：主表更新/删除时，将从表匹配记录的列设为 null
    [ForeignKey(typeof(MasterTable), Option = TableDeleteOrUpdateOption.Null)]
    public int? MasterId { get; set; }
}

参数说明：

• type: 主表类型
• Option: 级联操作选项
  • Restrict: 限制（默认）
  • Cascade: 级联
  • Null: 设为空

---

DecimalAttribute

功能说明： 为 decimal 属性声明 T-SQL DECIMAL(p,s)，与 SQL Server 文档用语一致：Precision = p，Scale = s。未标注时，建表命令仍默认 DECIMAL(18,0)。

接口定义：

[Decimal]                 // DECIMAL(18,0)
public decimal RowKey { get; set; }

[Decimal(18, 4)]          // DECIMAL(18,4)
public decimal Amount { get; set; }

与 DigitAttribute： DigitAttribute 已标记为过时；其 Total、Count 分别对应 p、s，命名易误导。新代码请统一使用 DecimalAttribute。若两者误标在同一属性上，仅以 DecimalAttribute 为准。

---

DigitAttribute（已过时）

迁移： 将 [Digit(10, 2)] 改为 [Decimal(10, 2)]；无参 [Digit] 与 [Decimal] 均对应 DECIMAL(18,0)。

---

ColumnAttribute

功能说明： 指定属性映射到的数据库列的名称、类型和顺序。

接口定义：

[Column("ColumnName")]
public string Name { get; set; }

[Column("ColumnName", Order = 1)]
public string Name { get; set; }

[Column("ColumnName", TypeName = "nvarchar(100)")]
public string Name { get; set; }

参数说明：

• name: 属性映射到的列的名称
• Order: 属性映射到的列的从零开始的顺序（可选）
• TypeName: 属性映射到的列的数据库提供程序特定的数据类型（可选）

注意事项：

• 当属性名与数据库列名不同时使用
• 可以指定列的顺序和数据类型

---

MinLengthAttribute

功能说明： 设置字符串类型的最小长度。默认长度为 0。

接口定义：

[MinLength(5)]
public string Name { get; set; }  // 最小长度为 5

参数说明：

• length: 字符串的最小长度

注意事项：

• 与 MaxLengthAttribute 配合使用可以设置字符串长度范围
• 用于数据验证

---

StringLengthAttribute

功能说明： 设置字符串的长度范围。默认最小值为 0，最大值为 500。

接口定义：

[StringLength(5, 100)]
public string Name { get; set; }  // 最小长度 5，最大长度 100

[StringLength()]  // 使用默认值：最小 0，最大 500
public string Description { get; set; }

参数说明：

• minimumLength: 最小长度
• maximumLength: 最大长度

注意事项：

• 同时设置最小和最大长度
• 用于数据验证

---

NotMappedAttribute

功能说明： 表示应从数据库映射中排除属性或类。使用此属性标记的属性或类不会被映射到数据库。

接口定义：

[NotMapped]
public string ComputedProperty { get; set; }  // 不映射到数据库

[NotMapped]
public class HelperClass { }  // 整个类不映射

注意事项：

• 用于排除不需要映射到数据库的属性
• 常用于计算属性、临时属性等

---

ComplexTypeAttribute

功能说明： 表示该类是复杂类型。复杂类型是实体类型的非标量属性，它允许在实体内组织标量属性。复杂类型没有键，并且除了父对象之外不能由实体框架管理。

接口定义：

[ComplexType]
public class Address
{
    [MaxLength(200)]
    public string Street { get; set; }
    [MaxLength(100)]
    public string City { get; set; }
}

[Table("User")]
public class User
{
    [Key]
    public int Id { get; set; }
    public Address Address { get; set; }  // 复杂类型属性
}

注意事项：

• 复杂类型不能有主键
• 复杂类型不能独立存在，必须作为实体类型的属性

---

ConcurrencyCheckAttribute

功能说明： 用于实现乐观并发控制。标记此属性的字段在更新时会检查并发冲突。

接口定义：

[ConcurrencyCheck]
public DateTime LastModified { get; set; }

注意事项：

• 用于乐观并发控制
• 更新时会检查该字段的值是否被其他操作修改

---

TimestampAttribute

功能说明： 用于实现乐观并发控制。标记此属性的字段会被视为时间戳字段，用于检测并发冲突。

接口定义：

[Timestamp]
public byte[] RowVersion { get; set; }

注意事项：

• 必须使用 byte[] 类型
• SQL Server 会自动管理该字段的值
• 用于乐观并发控制

---

FullTextAttribute

功能说明： 指定当前列支持全文搜索功能，提供了全文索引、全文查询等功能，以支持更灵活的文本搜索。

接口定义：

[FullText]
[MaxLength(450)]
public string Content { get; set; }

注意事项：

• 用于标记支持全文搜索的列
• 需要数据库配置全文索引

---

InversePropertyAttribute

功能说明： 用于指定导航属性的反向属性，以建立双向关联。

接口定义：

[Table("Order")]
public class Order
{
    [Key]
    public int Id { get; set; }
    public int CustomerId { get; set; }
    [ForeignKey("CustomerId")]
    public Customer Customer { get; set; }
}

[Table("Customer")]
public class Customer
{
    [Key]
    public int Id { get; set; }
    [InverseProperty("Customer")]
    public List<Order> Orders { get; set; }
}

参数说明：

• property: 同一关系的另一端的导航属性名称

注意事项：

• 用于建立双向导航关系
• 必须指定正确的反向属性名称

---

VisiableAttribute

功能说明： 用于指定表列是否可见。控制该列在查询或显示时是否可见。

接口定义：

[Visiable(true)]
public string VisibleColumn { get; set; }  // 可见

[Visiable(false)]
public string HiddenColumn { get; set; }  // 不可见

参数说明：

• visible: 是否可见，true 表示可见，false 表示不可见

注意事项：

• 用于控制列的可见性
• 不影响数据库表结构，主要用于查询和显示控制

---

连接和基础操作

连接属性

DataSource

功能说明： 数据库服务器地址或名称。

接口定义：

string DataSource { get; set; }

示例：

sql.DataSource = "(local)";
sql.DataSource = "localhost";
sql.DataSource = "192.168.1.100";

---

InitialCatalog

功能说明： 数据库名称。

接口定义：

string InitialCatalog { get; set; }

示例：

sql.InitialCatalog = "Hi.Ltd";

---

UserId

功能说明： 登录用户名。如不填写，则使用 Windows 身份验证。

接口定义：

string UserId { get; set; }

示例：

sql.UserId = "sa";

---

Password

功能说明： 登录密码。如不填写，则使用 Windows 身份验证。

接口定义：

string Password { get; set; }

示例：

sql.Password = "Demo123456";

---

Timeout

功能说明： 连接超时时间（秒）。默认值为 15 秒。

接口定义：

int Timeout { get; set; }

示例：

sql.Timeout = 10;

---

Connection 方法

Connection()

功能说明： 测试连接到数据库。

接口定义：

bool Connection();

返回值：

• true: 连接成功
• false: 连接失败

可能异常：

• SqlException: 数据库连接异常
• ArgumentException: 连接字符串无效

示例：

if (sql.Connection())
{
    Console.WriteLine("连接成功");
}

---

Connection(string database)

功能说明： 测试连接到指定数据库。

接口定义：

bool Connection(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 连接成功
• false: 连接失败

可能异常：

• SqlException: 数据库连接异常
• ArgumentException: 连接字符串无效或数据库不存在

示例：

if (sql.Connection("Hi.Ltd"))
{
    Console.WriteLine("连接成功");
}

---

数据库操作

判断数据库是否存在

ExistsDatabase()

功能说明： 判断当前数据库是否存在。

接口定义：

bool ExistsDatabase();

返回值：

• true: 数据库存在
• false: 数据库不存在

可能异常：

• SqlException: 数据库查询异常

示例：

if (sql.ExistsDatabase())
{
    Console.WriteLine("数据库存在");
}

---

ExistsDatabase(string database)

功能说明： 判断指定数据库是否存在。

接口定义：

bool ExistsDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 数据库存在
• false: 数据库不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 数据库名称为空

示例：

if (sql.ExistsDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库存在");
}

---

创建数据库

CreateDatabase()

功能说明： 创建数据库。如未指定数据库名称，则使用连接字符串中的 InitialCatalog，如为空则默认为 "Hi.Ltd"。

接口定义：

bool CreateDatabase();

返回值：

• true: 创建成功或数据库已存在
• false: 创建失败

可能异常：

• SqlException: 数据库创建异常
• UnauthorizedAccessException: 权限不足

示例：

if (sql.CreateDatabase())
{
    Console.WriteLine("数据库创建成功");
}

---

CreateDatabase(string database)

功能说明： 根据数据库名称创建数据库。如未指定路径，默认存储在 SQL Server 默认数据目录。

接口定义：

bool CreateDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 创建成功或数据库已存在
• false: 创建失败

可能异常：

• SqlException: 数据库创建异常
• ArgumentException: 数据库名称无效
• UnauthorizedAccessException: 权限不足

示例：

if (sql.CreateDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库创建成功");
}

---

CreateDatabase(string database, string path)

功能说明： 根据数据库名称和存储路径创建数据库。

接口定义：

bool CreateDatabase(string database, string path);

参数说明：

• database: 数据库名称
• path: 数据库文件存储路径

返回值：

• true: 创建成功或数据库已存在
• false: 创建失败

可能异常：

• SqlException: 数据库创建异常
• ArgumentException: 数据库名称或路径无效
• DirectoryNotFoundException: 路径不存在
• UnauthorizedAccessException: 权限不足

示例：

string path = @"C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\DATA";
if (sql.CreateDatabase("Hi.Ltd", path))
{
    Console.WriteLine("数据库创建成功");
}

---

删除数据库

DropDatabase()

功能说明： 删除当前数据库。如未指定数据库名称，则使用连接字符串中的 InitialCatalog。

接口定义：

bool DropDatabase();

返回值：

• true: 删除成功或数据库不存在
• false: 删除失败

可能异常：

• SqlException: 数据库删除异常（如数据库正在使用）
• UnauthorizedAccessException: 权限不足

注意事项：

• 删除操作不可逆，请谨慎使用
• 确保没有其他连接正在使用该数据库

示例：

if (sql.DropDatabase())
{
    Console.WriteLine("数据库删除成功");
}

---

DropDatabase(string database)

功能说明： 删除指定数据库。

接口定义：

bool DropDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 删除成功或数据库不存在
• false: 删除失败

可能异常：

• SqlException: 数据库删除异常（如数据库正在使用）
• ArgumentException: 数据库名称无效
• UnauthorizedAccessException: 权限不足

注意事项：

• 删除操作不可逆，请谨慎使用
• 确保没有其他连接正在使用该数据库

示例：

if (sql.DropDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库删除成功");
}

---

备份数据库

BackupDatabase()

功能说明： 备份默认数据库。如未指定数据库名称，则使用连接字符串中的 InitialCatalog。

接口定义：

bool BackupDatabase();

返回值：

• true: 备份成功
• false: 备份失败

可能异常：

• SqlException: 数据库备份异常
• UnauthorizedAccessException: 权限不足或路径不可写

示例：

if (sql.BackupDatabase())
{
    Console.WriteLine("数据库备份成功");
}

---

BackupDatabase(string database)

功能说明： 备份指定数据库。如未指定路径，默认存储在 SQL Server 默认备份目录。

接口定义：

bool BackupDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 备份成功
• false: 备份失败

可能异常：

• SqlException: 数据库备份异常或数据库不存在
• ArgumentException: 数据库名称无效
• UnauthorizedAccessException: 权限不足或路径不可写

示例：

if (sql.BackupDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库备份成功");
}

---

BackupDatabase(string database, string fileName)

功能说明： 备份指定数据库到指定文件。

接口定义：

bool BackupDatabase(string database, string fileName);

参数说明：

• database: 数据库名称
• fileName: 备份文件名称（不含路径）

返回值：

• true: 备份成功
• false: 备份失败

可能异常：

• SqlException: 数据库备份异常或数据库不存在
• ArgumentException: 数据库名称或文件名无效
• UnauthorizedAccessException: 权限不足或路径不可写

示例：

if (sql.BackupDatabase("Hi.Ltd", "backup"))
{
    Console.WriteLine("数据库备份成功");
}

---

BackupDatabase(string database, string fileName, string path)

功能说明： 备份指定数据库到指定路径的指定文件。

接口定义：

bool BackupDatabase(string database, string fileName, string path);

参数说明：

• database: 数据库名称
• fileName: 备份文件名称（不含路径）
• path: 备份文件存储路径

返回值：

• true: 备份成功
• false: 备份失败

可能异常：

• SqlException: 数据库备份异常或数据库不存在
• ArgumentException: 参数无效
• DirectoryNotFoundException: 路径不存在
• UnauthorizedAccessException: 权限不足或路径不可写

示例：

string path = @"C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\Backup";
if (sql.BackupDatabase("Hi.Ltd", "backup", path))
{
    Console.WriteLine("数据库备份成功");
}

---

还原数据库

RestoreDatabase()

功能说明： 还原默认数据库。如未指定数据库名称，则使用连接字符串中的 InitialCatalog。

接口定义：

bool RestoreDatabase();

返回值：

• true: 还原成功
• false: 还原失败

可能异常：

• SqlException: 数据库还原异常或备份文件不存在
• UnauthorizedAccessException: 权限不足

注意事项：

• 还原操作会覆盖现有数据库，请谨慎使用
• 确保没有其他连接正在使用该数据库

示例：

if (sql.RestoreDatabase())
{
    Console.WriteLine("数据库还原成功");
}

---

RestoreDatabase(string database)

功能说明： 还原指定数据库。

接口定义：

bool RestoreDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 还原成功
• false: 还原失败

可能异常：

• SqlException: 数据库还原异常或备份文件不存在
• ArgumentException: 数据库名称无效
• UnauthorizedAccessException: 权限不足

注意事项：

• 还原操作会覆盖现有数据库，请谨慎使用
• 确保没有其他连接正在使用该数据库

示例：

if (sql.RestoreDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库还原成功");
}

---

RestoreDatabase(string database, string fileName)

功能说明： 从指定文件还原数据库。

接口定义：

bool RestoreDatabase(string database, string fileName);

参数说明：

• database: 数据库名称
• fileName: 备份文件名称（不含路径）

返回值：

• true: 还原成功
• false: 还原失败

可能异常：

• SqlException: 数据库还原异常或备份文件不存在
• ArgumentException: 参数无效
• UnauthorizedAccessException: 权限不足

示例：

if (sql.RestoreDatabase("Hi.Ltd", "backup"))
{
    Console.WriteLine("数据库还原成功");
}

---

RestoreDatabase(string database, string fileName, string path)

功能说明： 从指定路径的指定文件还原数据库。

接口定义：

bool RestoreDatabase(string database, string fileName, string path);

参数说明：

• database: 数据库名称
• fileName: 备份文件名称（不含路径）
• path: 备份文件存储路径

返回值：

• true: 还原成功
• false: 还原失败

可能异常：

• SqlException: 数据库还原异常或备份文件不存在
• ArgumentException: 参数无效
• FileNotFoundException: 备份文件不存在
• UnauthorizedAccessException: 权限不足

示例：

string path = @"C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\Backup";
if (sql.RestoreDatabase("Hi.Ltd", "backup", path))
{
    Console.WriteLine("数据库还原成功");
}

---

附加数据库

AttachDatabase()

功能说明： 附加默认数据库。如未指定数据库名称，则使用连接字符串中的 InitialCatalog。

接口定义：

bool AttachDatabase();

返回值：

• true: 附加成功
• false: 附加失败

可能异常：

• SqlException: 数据库附加异常或数据文件不存在
• UnauthorizedAccessException: 权限不足

注意事项：

• 附加数据库时，所有数据文件（MDF 和 NDF）都必须可用
• 如果数据文件路径与首次创建时不同，需要指定当前路径

示例：

if (sql.AttachDatabase())
{
    Console.WriteLine("数据库附加成功");
}

---

AttachDatabase(string database)

功能说明： 附加指定数据库。

接口定义：

bool AttachDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 附加成功
• false: 附加失败

可能异常：

• SqlException: 数据库附加异常或数据文件不存在
• ArgumentException: 数据库名称无效
• UnauthorizedAccessException: 权限不足

示例：

if (sql.AttachDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库附加成功");
}

---

AttachDatabase(string database, string path)

功能说明： 从指定路径附加数据库。

接口定义：

bool AttachDatabase(string database, string path);

参数说明：

• database: 数据库名称
• path: 数据文件所在路径

返回值：

• true: 附加成功
• false: 附加失败

可能异常：

• SqlException: 数据库附加异常或数据文件不存在
• ArgumentException: 参数无效
• DirectoryNotFoundException: 路径不存在
• UnauthorizedAccessException: 权限不足

示例：

string path = @"C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\DATA";
if (sql.AttachDatabase("Hi.Ltd", path))
{
    Console.WriteLine("数据库附加成功");
}

---

分离数据库

DetachDatabase()

功能说明： 分离默认数据库。如未指定数据库名称，则使用连接字符串中的 InitialCatalog。

接口定义：

bool DetachDatabase();

返回值：

• true: 分离成功
• false: 分离失败

可能异常：

• SqlException: 数据库分离异常（如数据库正在使用）
• UnauthorizedAccessException: 权限不足

注意事项：

• 分离数据库会从 SQL Server 实例中移除数据库，但保留数据文件
• 请不要分离当前正在使用的数据库
• 分离后可以使用数据文件在其他 SQL Server 实例上附加

示例：

if (sql.DetachDatabase())
{
    Console.WriteLine("数据库分离成功");
}

---

DetachDatabase(string database)

功能说明： 分离指定数据库。

接口定义：

bool DetachDatabase(string database);

参数说明：

• database: 数据库名称

返回值：

• true: 分离成功
• false: 分离失败

可能异常：

• SqlException: 数据库分离异常（如数据库正在使用）
• ArgumentException: 数据库名称无效
• UnauthorizedAccessException: 权限不足

注意事项：

• 分离数据库会从 SQL Server 实例中移除数据库，但保留数据文件
• 请不要分离当前正在使用的数据库

示例：

if (sql.DetachDatabase("Hi.Ltd"))
{
    Console.WriteLine("数据库分离成功");
}

---

数据表操作

判断数据表是否存在

ExistsTable<T>()

功能说明： 判断数据表是否存在。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool ExistsTable<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 表存在
• false: 表不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 表类型无效

示例：

[Table("Navigation", Schema = "dbo")]
public class NavigationTable { }

if (sql.ExistsTable<NavigationTable>())
{
    Console.WriteLine("表存在");
}

---

ExistsTable<T>(string database)

功能说明： 判断指定数据库中的数据表是否存在。

接口定义：

bool ExistsTable<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 表存在
• false: 表不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsTable<NavigationTable>("Hi.Ltd"))
{
    Console.WriteLine("表存在");
}

---

ExistsTable<T>(string database, string table)

功能说明： 判断指定数据库中的指定数据表是否存在。

接口定义：

bool ExistsTable<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 表存在
• false: 表不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsTable<NavigationTable>("Hi.Ltd", "Navigation"))
{
    Console.WriteLine("表存在");
}

---

创建数据表

CreateTable<T>()

功能说明： 创建数据表。如果表已存在则跳过。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool CreateTable<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 创建成功或表已存在
• false: 创建失败

可能异常：

• SqlException: 表创建异常
• ArgumentException: 表类型无效或缺少必要属性
• UnauthorizedAccessException: 权限不足

示例：

[Table("Navigation", Schema = "dbo")]
public class NavigationTable
{
    [Key]
    public int Id { get; set; }
    [MaxLength(450)]
    public string Content { get; set; }
}

if (sql.CreateTable<NavigationTable>())
{
    Console.WriteLine("表创建成功");
}

---

CreateTable<T>(string database)

功能说明： 在指定数据库下创建数据表。

接口定义：

bool CreateTable<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 创建成功或表已存在
• false: 创建失败

可能异常：

• SqlException: 表创建异常或数据库不存在
• ArgumentException: 参数无效

示例：

sql.CreateTable<NavigationTable>("Hi.Ltd");

---

CreateTable<T>(string database, string table)

功能说明： 在指定数据库下创建指定名称的数据表。

接口定义：

bool CreateTable<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 创建成功或表已存在
• false: 创建失败

可能异常：

• SqlException: 表创建异常或数据库不存在
• ArgumentException: 参数无效

示例：

sql.CreateTable<NavigationTable>("Hi.Ltd", "NewNavigation");

---

CreateTable<T>(string database, string table, string schema)

功能说明： 在指定数据库下创建指定架构、指定名称的数据表。

接口定义：

bool CreateTable<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 创建成功或表已存在
• false: 创建失败

可能异常：

• SqlException: 表创建异常或数据库/架构不存在
• ArgumentException: 参数无效

示例：

sql.CreateTable<NavigationTable>("Hi.Ltd", "NewNavigation", "hi");

---

修改数据表

AlterTable<T>()

功能说明： 修改数据表结构。将表类结构与数据库中的表进行比对，如有差异则进行修改（新增列、修改数据类型等）。

接口定义：

void AlterTable<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

可能异常：

• SqlException: 表修改异常
• ArgumentException: 表类型无效

注意事项：

• 此操作具有一定风险，建议仅在测试环境使用
• 操作不可逆转，删除的列无法找回
• 修改数据类型可能导致数据丢失

示例：

sql.AlterTable<NavigationTable>();

---

AlterTable<T>(string database)

功能说明： 在指定数据库中修改数据表结构。

接口定义：

void AlterTable<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

可能异常：

• SqlException: 表修改异常或数据库不存在
• ArgumentException: 参数无效

示例：

sql.AlterTable<NavigationTable>("Hi.Ltd");

---

AlterTable<T>(string database, string table)

功能说明： 在指定数据库中修改指定数据表结构。

接口定义：

void AlterTable<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

可能异常：

• SqlException: 表修改异常
• ArgumentException: 参数无效

示例：

sql.AlterTable<NavigationTable>("Hi.Ltd", "Navigation");

---

AlterTable<T>(string database, string table, string schema)

功能说明： 在指定数据库中修改指定架构的指定数据表结构。

接口定义：

void AlterTable<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构

可能异常：

• SqlException: 表修改异常
• ArgumentException: 参数无效

示例：

sql.AlterTable<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

DropColumn<T>(string database, string table, string schema, string column)

功能说明： 移除指定数据库中的指定数据表中的指定列。

接口定义：

void DropColumn<T>(string database, string table, string schema, string column) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构名称
• column: 表列名

可能异常：

• SqlException: 列删除异常（如列有关联的索引、约束或触发器）
• ArgumentException: 参数无效

注意事项：

• 删除列是一个敏感操作，会永久删除表中的数据
• 执行前请确保已备份重要数据
• 如果列有关联的索引、约束或触发器，需要先删除这些依赖项
• 建议在生产环境前在测试环境充分测试

示例：

sql.DropColumn<NavigationTable>("Hi.Ltd", "Navigation", "dbo", "Note");

---

RenameColumn<T>(string database, string table, string schema, string column, string newColumn)

功能说明： 重命名指定数据库中的指定数据表中的指定列。此方法针对表类中列名称有改动，仅更改当前数据库中列名称，而不删除表列中的数据。

接口定义：

// 注意：此方法在实现中是 protected 方法，不是公开接口的一部分
// 如需重命名列，可以使用 ExecuteNonQuery 执行 SQL 命令
bool RenameColumn<T>(string database, string table, string schema, string column, string newColumn) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构名称
• column: 表列名（原名称）
• newColumn: 新的表列名

返回值：

• true: 重命名成功
• false: 重命名失败

可能异常：

• SqlException: 列重命名异常（如列有相关的索引、约束或触发器）
• ArgumentException: 参数无效

注意事项：

• 重命名过程会修改系统目录中的元数据，但不会修改与列相关联的现有数据
• 执行前请确保已备份数据，并在生产环境前在测试环境充分测试
• 如果列有相关的索引、约束或触发器，可能需要先删除这些依赖项，然后再执行修改列名的操作
• 重命名列会影响引用该列的所有存储过程、视图、触发器等对象
• 重要提示： 此方法在实现中是 protected 方法，不是 ISqlServer 公开接口的一部分。如需重命名列，建议使用 ExecuteNonQuery 方法执行 SQL 命令：

  string sqlCommand = $"EXEC sp_rename '[{schema}].[{table}].[{column}]', '{newColumn}', 'COLUMN';";
  sql.ExecuteNonQuery(database, sqlCommand);
  

示例：

// 使用 ExecuteNonQuery 执行列重命名
string sqlCommand = "EXEC sp_rename '[dbo].[Navigation].[Note]', 'NewNote', 'COLUMN';";
sql.ExecuteNonQuery("Hi.Ltd", sqlCommand);

---

RenameTable<T>(string table, string newTable)

功能说明： 重命名指定数据表。在进行此操作之前，请确定数据库已经指定并存在。

接口定义：

void RenameTable<T>(string table, string newTable) where T : class, new();

参数说明：

• table: 数据表名称
• newTable: 新的数据表名称

可能异常：

• SqlException: 表重命名异常（如表正在使用或有依赖对象）
• ArgumentException: 参数无效

注意事项：

• 重命名会影响数据库中引用原始表的所有存储过程、触发器、视图等对象
• 确保在重命名表之前备份数据
• 确保没有正在使用表的相关对象

示例：

sql.RenameTable<NavigationTable>("Navigation", "NewNavigation");

---

RenameTable<T>(string database, string table, string newTable)

功能说明： 重命名指定数据库中的指定数据表。

接口定义：

void RenameTable<T>(string database, string table, string newTable) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• newTable: 新的数据表名称

可能异常：

• SqlException: 表重命名异常
• ArgumentException: 参数无效

示例：

sql.RenameTable<NavigationTable>("Hi.Ltd", "Navigation", "NewNavigation");

---

插入数据

InsertTable<T>(T content)

功能说明： 向数据表中插入一条数据。

接口定义：

bool InsertTable<T>(T content) where T : class, new();

类型参数：

• T: 数据表结构类型

参数说明：

• content: 待插入的数据对象

返回值：

• true: 插入成功
• false: 插入失败

可能异常：

• SqlException: 插入异常（如违反约束、数据类型不匹配等）
• ArgumentException: 参数无效
• InvalidOperationException: 主键冲突（如果主键非自增且已存在）

注意事项：

• 如果主键设置了自增，不需要设置 Id 值
• 如果主键未设置自增，必须设置 Id 值
• 必须满足所有约束条件（外键、非空等）

示例：

var content = new NavigationTable
{
    DateTime = DateTime.Now,
    Content = "这是一个导航表",
    Note = string.Empty
};

if (sql.InsertTable(content))
{
    Console.WriteLine("插入成功");
}

---

InsertTable<T>(string database, T content)

功能说明： 向指定数据库的数据表中插入一条数据。

接口定义：

bool InsertTable<T>(string database, T content) where T : class, new();

参数说明：

• database: 数据库名称
• content: 待插入的数据对象

返回值：

• true: 插入成功
• false: 插入失败

可能异常：

• SqlException: 插入异常或数据库不存在
• ArgumentException: 参数无效

示例：

sql.InsertTable("Hi.Ltd", content);

---

InsertTable<T>(string database, string table, T content)

功能说明： 向指定数据库的指定数据表中插入一条数据。

接口定义：

bool InsertTable<T>(string database, string table, T content) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• content: 待插入的数据对象

返回值：

• true: 插入成功
• false: 插入失败

可能异常：

• SqlException: 插入异常
• ArgumentException: 参数无效

示例：

sql.InsertTable("Hi.Ltd", "Navigation", content);

---

InsertTable<T>(string database, string table, string schema, T content)

功能说明： 向指定数据库的指定架构、指定数据表中插入一条数据。

接口定义：

bool InsertTable<T>(string database, string table, string schema, T content) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• content: 待插入的数据对象

返回值：

• true: 插入成功
• false: 插入失败

可能异常：

• SqlException: 插入异常
• ArgumentException: 参数无效

示例：

sql.InsertTable("Hi.Ltd", "Navigation", "dbo", content);

---

InsertTable<T>(List<T> contents)

功能说明： 批量向数据表中插入多条数据。

接口定义：

bool InsertTable<T>(List<T> contents) where T : class, new();

参数说明：

• contents: 待插入的数据对象列表

返回值：

• true: 全部插入成功
• false: 部分或全部插入失败

可能异常：

• SqlException: 插入异常
• ArgumentException: 参数无效或列表为空

示例：

var contents = new List<NavigationTable>
{
    new NavigationTable { DateTime = DateTime.Now, Content = "导航1", Note = "" },
    new NavigationTable { DateTime = DateTime.Now, Content = "导航2", Note = "" },
    new NavigationTable { DateTime = DateTime.Now, Content = "导航3", Note = "" }
};

if (sql.InsertTable(contents))
{
    Console.WriteLine("批量插入成功");
}

---

InsertTable<T>(string database, List<T> contents)

功能说明： 批量向指定数据库的数据表中插入多条数据。

接口定义：

bool InsertTable<T>(string database, List<T> contents) where T : class, new();

参数说明：

• database: 数据库名称
• contents: 待插入的数据对象列表

返回值：

• true: 全部插入成功
• false: 部分或全部插入失败

可能异常：

• SqlException: 插入异常
• ArgumentException: 参数无效

示例：

sql.InsertTable("Hi.Ltd", contents);

---

InsertTable<T>(string database, string table, List<T> contents)

功能说明： 批量向指定数据库的指定数据表中插入多条数据。

接口定义：

bool InsertTable<T>(string database, string table, List<T> contents) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• contents: 待插入的数据对象列表

返回值：

• true: 全部插入成功
• false: 部分或全部插入失败

可能异常：

• SqlException: 插入异常
• ArgumentException: 参数无效

示例：

sql.InsertTable("Hi.Ltd", "Navigation", contents);

---

InsertTable<T>(string database, string table, string schema, List<T> contents)

功能说明： 批量向指定数据库的指定架构、指定数据表中插入多条数据。

接口定义：

bool InsertTable<T>(string database, string table, string schema, List<T> contents) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• contents: 待插入的数据对象列表

返回值：

• true: 全部插入成功
• false: 部分或全部插入失败

可能异常：

• SqlException: 插入异常
• ArgumentException: 参数无效

示例：

sql.InsertTable("Hi.Ltd", "Navigation", "dbo", contents);

---

更新数据

UpdateTable<T>(T content)

功能说明： 更新数据表中的一条数据。更新数据必须指定唯一主键，否则将无法确定更新哪条数据。

接口定义：

bool UpdateTable<T>(T content) where T : class, new();

类型参数：

• T: 数据表结构类型

参数说明：

• content: 待更新的数据对象（必须包含主键值）

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 更新异常（如违反约束、主键不存在等）
• ArgumentException: 参数无效或主键未设置
• InvalidOperationException: 未找到匹配的记录

注意事项：

• 必须指定主键值
• 只更新非主键字段
• 必须满足所有约束条件

示例：

var content = new NavigationTable
{
    Id = 1,  // 必须指定主键
    DateTime = DateTime.Now,
    Content = "更新后的内容",
    Note = "更新后的备注"
};

if (sql.UpdateTable(content))
{
    Console.WriteLine("更新成功");
}

---

UpdateTable<T>(string database, T content)

功能说明： 更新指定数据库的数据表中的一条数据。

接口定义：

bool UpdateTable<T>(string database, T content) where T : class, new();

参数说明：

• database: 数据库名称
• content: 待更新的数据对象

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTable("Hi.Ltd", content);

---

UpdateTable<T>(string database, string table, T content)

功能说明： 更新指定数据库的指定数据表中的一条数据。

接口定义：

bool UpdateTable<T>(string database, string table, T content) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• content: 待更新的数据对象

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTable("Hi.Ltd", "Navigation", content);

---

UpdateTable<T>(string database, string table, string schema, T content)

功能说明： 更新指定数据库的指定架构、指定数据表中的一条数据。

接口定义：

bool UpdateTable<T>(string database, string table, string schema, T content) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• content: 待更新的数据对象

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTable("Hi.Ltd", "Navigation", "dbo", content);

---

UpdateTable<T>(List<T> contents)

功能说明： 批量更新数据表中的多条数据。

接口定义：

bool UpdateTable<T>(List<T> contents) where T : class, new();

参数说明：

• contents: 待更新的数据对象列表（每个对象必须包含主键值）

返回值：

• true: 全部更新成功
• false: 部分或全部更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效或列表为空

示例：

var contents = new List<NavigationTable>
{
    new NavigationTable { Id = 1, Content = "更新1", Note = "" },
    new NavigationTable { Id = 2, Content = "更新2", Note = "" },
    new NavigationTable { Id = 3, Content = "更新3", Note = "" }
};

if (sql.UpdateTable(contents))
{
    Console.WriteLine("批量更新成功");
}

---

UpdateTable<T>(string database, List<T> contents)

功能说明： 批量更新指定数据库的数据表中的多条数据。

接口定义：

bool UpdateTable<T>(string database, List<T> contents) where T : class, new();

参数说明：

• database: 数据库名称
• contents: 待更新的数据对象列表

返回值：

• true: 全部更新成功
• false: 部分或全部更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTable("Hi.Ltd", contents);

---

UpdateTable<T>(string database, string table, List<T> contents)

功能说明： 批量更新指定数据库的指定数据表中的多条数据。

接口定义：

bool UpdateTable<T>(string database, string table, List<T> contents) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• contents: 待更新的数据对象列表

返回值：

• true: 全部更新成功
• false: 部分或全部更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTable("Hi.Ltd", "Navigation", contents);

---

UpdateTable<T>(string database, string table, string schema, List<T> contents)

功能说明： 批量更新指定数据库的指定架构、指定数据表中的多条数据。

接口定义：

bool UpdateTable<T>(string database, string table, string schema, List<T> contents) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• contents: 待更新的数据对象列表

返回值：

• true: 全部更新成功
• false: 部分或全部更新失败

可能异常：

• SqlException: 更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTable("Hi.Ltd", "Navigation", "dbo", contents);

---

查询数据

InqureTable<T>()

功能说明： 查询表的最新的前 1000 条数据。

接口定义：

List<T> InqureTable<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• List<T>: 查询结果集合，如果无数据则返回空列表

可能异常：

• SqlException: 查询异常
• ArgumentException: 表类型无效

示例：

var results = sql.InqureTable<NavigationTable>();
foreach (var item in results)
{
    Console.WriteLine($"Id: {item.Id}, Content: {item.Content}");
}

---

InqureTable<T>(string database)

功能说明： 查询指定数据库表中最新的前 1000 条数据。

接口定义：

List<T> InqureTable<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常或数据库不存在
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>("Hi.Ltd");

---

InqureTable<T>(string database, string table)

功能说明： 查询指定数据库中指定表的最新的前 1000 条数据。

接口定义：

List<T> InqureTable<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>("Hi.Ltd", "Navigation");

---

InqureTable<T>(string database, string table, string schema)

功能说明： 查询指定数据库中指定架构的表的最新的前 1000 条数据。

接口定义：

List<T> InqureTable<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

InqureTable<T>(uint inqureCount)

功能说明： 查询表的数据，指定查询数量。

接口定义：

List<T> InqureTable<T>(uint inqureCount) where T : class, new();

参数说明：

• inqureCount: 查询记录数量

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>(100);  // 查询前 100 条

---

InqureTable<T>(string database, uint inqureCount)

功能说明： 查询指定数据库表的数据，指定查询数量。

接口定义：

List<T> InqureTable<T>(string database, uint inqureCount) where T : class, new();

参数说明：

• database: 数据库名称
• inqureCount: 查询记录数量

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>("Hi.Ltd", 100);

---

InqureTable<T>(string database, string table, uint inqureCount)

功能说明： 查询指定数据库中指定表的数据，指定查询数量。

接口定义：

List<T> InqureTable<T>(string database, string table, uint inqureCount) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• inqureCount: 查询记录数量

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>("Hi.Ltd", "Navigation", 100);

---

InqureTable<T>(string database, string table, string schema, uint inqureCount)

功能说明： 查询指定数据库中指定架构的表的数据，指定查询数量。

接口定义：

List<T> InqureTable<T>(string database, string table, string schema, uint inqureCount) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• inqureCount: 查询记录数量

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable<NavigationTable>("Hi.Ltd", "Navigation", "dbo", 100);

---

InqureTable<T>(T condition, bool fuzzy = true)

功能说明： 根据条件查询表的数据。支持模糊查询。

接口定义：

List<T> InqureTable<T>(T condition, bool fuzzy = true) where T : class, new();

参数说明：

• condition: 查询条件对象（设置需要查询的字段值）
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

注意事项：

• 模糊查询仅对字符串类型字段有效
• 如果字段值为 null 或默认值，则不会作为查询条件

示例：

var condition = new NavigationTable
{
    Content = "导航"  // 模糊查询包含"导航"的记录
};

var results = sql.InqureTable(condition, fuzzy: true);

---

InqureTable<T>(string database, T condition, bool fuzzy = true)

功能说明： 在指定数据库中根据条件查询表的数据。

接口定义：

List<T> InqureTable<T>(string database, T condition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable("Hi.Ltd", condition);

---

InqureTable<T>(string database, string table, T condition, bool fuzzy = true)

功能说明： 在指定数据库的指定表中根据条件查询数据。

接口定义：

List<T> InqureTable<T>(string database, string table, T condition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable("Hi.Ltd", "Navigation", condition);

---

InqureTable<T>(string database, string table, string schema, T condition, bool fuzzy = true)

功能说明： 在指定数据库的指定架构、指定表中根据条件查询数据。

接口定义：

List<T> InqureTable<T>(string database, string table, string schema, T condition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable("Hi.Ltd", "Navigation", "dbo", condition);

---

InqureTable<T>(T startCondition, T endCondition, bool fuzzy = true)

功能说明： 根据起始和结束条件查询表的数据（范围查询）。

接口定义：

List<T> InqureTable<T>(T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var startCondition = new NavigationTable { Id = 1 };
var endCondition = new NavigationTable { Id = 100 };
var results = sql.InqureTable(startCondition, endCondition);

---

InqureTable<T>(string database, T startCondition, T endCondition, bool fuzzy = true)

功能说明： 在指定数据库中根据起始和结束条件查询数据。

接口定义：

List<T> InqureTable<T>(string database, T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable("Hi.Ltd", startCondition, endCondition);

---

InqureTable<T>(string database, string table, T startCondition, T endCondition, bool fuzzy = true)

功能说明： 在指定数据库的指定表中根据起始和结束条件查询数据。

接口定义：

List<T> InqureTable<T>(string database, string table, T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable("Hi.Ltd", "Navigation", startCondition, endCondition);

---

InqureTable<T>(string database, string table, string schema, T startCondition, T endCondition, bool fuzzy = true)

功能说明： 在指定数据库的指定架构、指定表中根据起始和结束条件查询数据。

接口定义：

List<T> InqureTable<T>(string database, string table, string schema, T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• List<T>: 查询结果集合

可能异常：

• SqlException: 查询异常
• ArgumentException: 参数无效

示例：

var results = sql.InqureTable("Hi.Ltd", "Navigation", "dbo", startCondition, endCondition);

---

多表联查

本节说明在 当前连接库 下，通过 IInqureMultiTable（由 ITable / ISqlServer 聚合）进行 JOIN 查询 的用法。返回值均为 Result<List<Dictionary<string, object>>>：每行是一个字典，键为输出列别名（如 m_Id、j1_Name），值为列值。

场景对照

场景	推荐 API
一主一从	JoinTable<T1, T2>()、JoinTable<T1,T2>(T1 condition, bool fuzzy)、JoinTable<T1,T2>(分页…)
一主多从（星型：从表均指向同一主表 T）	JoinTableMany<T>(IReadOnlyList<Type> joinedTableTypes, JoinType joinType = JoinType.Left) 及带条件、分页重载
多主多从（多张主表 + 主表间显式连接 + 从表挂到指定主表）	JoinTableMulti(MultiMasterJoinSpec spec) 及带条件、分页重载

JoinTable<T>() 的语义

• JoinTable<T>() 仅查询主表 T 的列，不包含任何 JOIN（与名称中的「多表」易混淆，已以接口注释为准）。
• 若要对 单主表 T 挂多个从表，请使用 JoinTableMany<T>(…)。

一主多从：JoinTableMany<T>

功能说明： 主表为 T，按 joinedTableTypes 顺序依次 LEFT JOIN（或指定 JoinType）。每个从表类型须：

• 为 class 且具备公共无参构造函数（与全库 where T : class, new() 约定一致）；
• 含 [ForeignKey(typeof(T))] 指向主表 T，以便解析外键列与主键列。

接口定义（节选）：

Result<List<Dictionary<string, object>>> JoinTableMany<T>(
    IReadOnlyList<Type> joinedTableTypes,
    JoinType joinType = JoinType.Left) where T : class, new();

Result<List<Dictionary<string, object>>> JoinTableMany<T>(
    T condition, bool fuzzy,
    IReadOnlyList<Type> joinedTableTypes,
    JoinType joinType = JoinType.Left) where T : class, new();

Result<List<Dictionary<string, object>>> JoinTableMany<T>(
    int pageIndex, int pageSize,
    IReadOnlyList<Type> joinedTableTypes,
    string orderByColumn = null, bool isDescending = true,
    JoinType joinType = JoinType.Left) where T : class, new();

分页说明： orderByColumn 建议写带主表别名前缀，如 m.Id；仅写列名时由内部按主表别名 m 限定。分页使用 ORDER BY … OFFSET … FETCH NEXT …（SQL Server 2012+）。

示例：

var types = new Type[] { typeof(OrderLine), typeof(OrderLog) };
var r = sql.JoinTableMany<Order>(types, JoinType.Left);
if (r.Successed) { /* r.Value 为字典行列表 */ }

多主多从：MultiMasterJoinSpec 与 JoinTableMulti

功能说明： 通过 MultiMasterJoinSpec.Create() 流式构建：

• AddMaster(Type, alias, …) / AddMaster<T>(alias, …)：主表（首表为 FROM 根表）；
• AddMasterLink(leftAlias, leftCol, rightAlias, rightCol, joinType)：主表之间的 JOIN；多主时 须恰好 主表数 − 1 条，且 第 i 条的 RightAlias 必须等于第 i+1 张主表的别名（用于稳定生成 JOIN 顺序）；
• AddSlave(Type, masterAlias, …) / AddSlave<T>(masterAlias, …)：从表挂在 masterAlias 对应的主表上；外键默认由 [ForeignKey(typeof(主表类型))] 解析，解析不到时可传列名覆盖参数。

构建完成后调用 JoinTableMulti(spec)、JoinTableMulti(spec, conditionModelType, condition, conditionMasterAlias, fuzzy) 或分页重载。

示例（两主、各一从）：

var spec = MultiMasterJoinSpec.Create()
    .AddMaster(typeof(Department), "d")
    .AddMaster(typeof(Employee), "e")
    .AddMasterLink("d", "Id", "e", "DeptId", JoinType.Inner)
    .AddSlave(typeof(DeptExt), "d", JoinType.Left)
    .AddSlave(typeof(EmpLog), "e", JoinType.Left)
    .Build();

var r = sql.JoinTableMulti(spec);

表模型类型校验：Native.ValidateTableModelType

功能说明： 当 API 以 Type（运行时）传入表模型、而编译期没有 where T : class, new() 约束时，由 Native.ValidateTableModelType(Type, string parameterName = null) 校验：

• 必须为 class、非 abstract；
• 必须具有 公共无参构造函数（与 new() 约束等价）。

调用时机： JoinMasterDescriptor / JoinSlaveDescriptor 构造时已自动调用；若你自行扩展基于 Type 的入口，应在生成 SQL 前调用，与 ExecuteCommand<T> 系列保持一致。

实现说明：JoinMultiMasterCommand 与 ExecuteCommand

• JoinMultiMasterCommand 继承 非泛型 ExecuteCommand（与 InqureTableCommand<T> 等并列），不继承 ExecuteCommand<T>：因为不存在单一主表泛型 T，表名/架构/列元数据均来自 MultiMasterJoinSpec。
• 内部 SQL 由 JoinMultiMasterCommand.BuildSql / BuildSql(…条件…) / BuildPagedSql 生成；条件参数绑定通过基类上的 InqureParameterInjectionForModel 转发到既有的 InqureParameterInjection<T>。

---

删除数据

DeleteTable<T>(int index)

功能说明： 根据主键索引删除对应数据。

接口定义：

int DeleteTable<T>(int index) where T : class, new();

类型参数：

• T: 数据表结构类型

参数说明：

• index: 主键索引值

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常（如违反外键约束等）
• ArgumentException: 参数无效

注意事项：

• 如果存在外键约束且设置为 Restrict，删除可能失败
• 删除操作不可逆，请谨慎使用

示例：

int affectedRows = sql.DeleteTable<NavigationTable>(1);
if (affectedRows > 0)
{
    Console.WriteLine($"成功删除 {affectedRows} 条记录");
}

---

DeleteTable<T>(string database, int index)

功能说明： 在指定数据库中根据主键索引删除对应数据。

接口定义：

int DeleteTable<T>(string database, int index) where T : class, new();

参数说明：

• database: 数据库名称
• index: 主键索引值

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable<NavigationTable>("Hi.Ltd", 1);

---

DeleteTable<T>(string database, string table, int index)

功能说明： 在指定数据库的指定表中根据主键索引删除对应数据。

接口定义：

int DeleteTable<T>(string database, string table, int index) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• index: 主键索引值

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable<NavigationTable>("Hi.Ltd", "Navigation", 1);

---

DeleteTable<T>(string database, string table, string schema, int index)

功能说明： 在指定数据库的指定架构、指定表中根据主键索引删除对应数据。

接口定义：

int DeleteTable<T>(string database, string table, string schema, int index) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• index: 主键索引值

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable<NavigationTable>("Hi.Ltd", "Navigation", "dbo", 1);

---

DeleteTable<T>(T condition, bool fuzzy = true)

功能说明： 根据条件删除表数据。支持模糊查询。

接口定义：

int DeleteTable<T>(T condition, bool fuzzy = true) where T : class, new();

参数说明：

• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

注意事项：

• 删除操作不可逆，请谨慎使用
• 建议先使用查询方法确认要删除的数据

示例：

var condition = new NavigationTable { Content = "测试" };
int affectedRows = sql.DeleteTable(condition, fuzzy: true);

---

DeleteTable<T>(string database, T condition, bool fuzzy = true)

功能说明： 在指定数据库中根据条件删除表数据。

接口定义：

int DeleteTable<T>(string database, T condition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable("Hi.Ltd", condition);

---

DeleteTable<T>(string database, string table, T condition, bool fuzzy = true)

功能说明： 在指定数据库的指定表中根据条件删除数据。

接口定义：

int DeleteTable<T>(string database, string table, T condition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable("Hi.Ltd", "Navigation", condition);

---

DeleteTable<T>(string database, string table, string schema, T condition, bool fuzzy = true)

功能说明： 在指定数据库的指定架构、指定表中根据条件删除数据。

接口定义：

int DeleteTable<T>(string database, string table, string schema, T condition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• condition: 查询条件对象
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable("Hi.Ltd", "Navigation", "dbo", condition);

---

DeleteTable<T>(T startCondition, T endCondition, bool fuzzy = true)

功能说明： 根据起始和结束条件删除表的数据（范围删除）。

接口定义：

int DeleteTable<T>(T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

注意事项：

• 删除操作不可逆，请谨慎使用
• 建议先使用查询方法确认要删除的数据范围

示例：

var startCondition = new NavigationTable { Id = 1 };
var endCondition = new NavigationTable { Id = 100 };
int affectedRows = sql.DeleteTable(startCondition, endCondition);

---

DeleteTable<T>(string database, T startCondition, T endCondition, bool fuzzy = true)

功能说明： 在指定数据库中根据起始和结束条件删除数据。

接口定义：

int DeleteTable<T>(string database, T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable("Hi.Ltd", startCondition, endCondition);

---

DeleteTable<T>(string database, string table, T startCondition, T endCondition, bool fuzzy = true)

功能说明： 在指定数据库的指定表中根据起始和结束条件删除数据。

接口定义：

int DeleteTable<T>(string database, string table, T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable("Hi.Ltd", "Navigation", startCondition, endCondition);

---

DeleteTable<T>(string database, string table, string schema, T startCondition, T endCondition, bool fuzzy = true)

功能说明： 在指定数据库的指定架构、指定表中根据起始和结束条件删除数据。

接口定义：

int DeleteTable<T>(string database, string table, string schema, T startCondition, T endCondition, bool fuzzy = true) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构
• startCondition: 起始查询条件
• endCondition: 结束查询条件
• fuzzy: 是否模糊查询，默认为 true

返回值：

• int: 成功执行返回受影响的行数，否则返回 -1

可能异常：

• SqlException: 删除异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.DeleteTable("Hi.Ltd", "Navigation", "dbo", startCondition, endCondition);

---

删除数据表

DropTable<T>()

功能说明： 从数据库中删除指定的表。

接口定义：

bool DropTable<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 删除成功或表不存在
• false: 删除失败

可能异常：

• SqlException: 表删除异常（如表正在使用或有依赖对象）
• ArgumentException: 表类型无效

注意事项：

• 删除操作不可逆，会永久删除表及其所有数据
• 确保没有其他对象（存储过程、视图、触发器）依赖该表
• 建议在生产环境前在测试环境充分测试

示例：

if (sql.DropTable<NavigationTable>())
{
    Console.WriteLine("表删除成功");
}

---

DropTable<T>(string database)

功能说明： 从指定数据库中删除表。

接口定义：

bool DropTable<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 删除成功或表不存在
• false: 删除失败

可能异常：

• SqlException: 表删除异常
• ArgumentException: 参数无效

示例：

sql.DropTable<NavigationTable>("Hi.Ltd");

---

DropTable<T>(string database, string table)

功能说明： 从指定数据库中删除指定数据表。

接口定义：

bool DropTable<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 删除成功或表不存在
• false: 删除失败

可能异常：

• SqlException: 表删除异常
• ArgumentException: 参数无效

示例：

sql.DropTable<NavigationTable>("Hi.Ltd", "Navigation");

---

DropTable<T>(string database, string table, string schema)

功能说明： 从指定数据库中删除指定架构的指定数据表。

接口定义：

bool DropTable<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构

返回值：

• true: 删除成功或表不存在
• false: 删除失败

可能异常：

• SqlException: 表删除异常
• ArgumentException: 参数无效

示例：

sql.DropTable<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

复制数据表

CopyTable<T>(string newTable, bool noData = false)

功能说明： 复制表。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool CopyTable<T>(string newTable, bool noData = false) where T : class, new();

类型参数：

• T: 数据表结构类型

参数说明：

• newTable: 复制后数据表名称
• noData: 是否一同复制表数据，默认为 false（复制数据）

返回值：

• true: 复制成功
• false: 复制失败

可能异常：

• SqlException: 表复制异常
• ArgumentException: 参数无效

示例：

// 复制表结构和数据
sql.CopyTable<NavigationTable>("Navigation_Backup", noData: false);

// 只复制表结构，不复制数据
sql.CopyTable<NavigationTable>("Navigation_Backup", noData: true);

---

CopyTable<T>(string table, string newTable, bool noData = false)

功能说明： 复制指定表。

接口定义：

bool CopyTable<T>(string table, string newTable, bool noData = false) where T : class, new();

参数说明：

• table: 数据表名称
• newTable: 复制后数据表名称
• noData: 是否一同复制表数据，默认为 false

返回值：

• true: 复制成功
• false: 复制失败

可能异常：

• SqlException: 表复制异常
• ArgumentException: 参数无效

示例：

sql.CopyTable<NavigationTable>("Navigation", "Navigation_Backup");

---

CopyTable<T>(string table, string schema, string newTable, string newSchema, bool noData = false)

功能说明： 复制指定架构的指定表。

接口定义：

bool CopyTable<T>(string table, string schema, string newTable, string newSchema, bool noData = false) where T : class, new();

参数说明：

• table: 数据表名称
• schema: 数据表架构名称
• newTable: 复制后数据表名称
• newSchema: 复制后数据表架构名称
• noData: 是否一同复制表数据，默认为 false

返回值：

• true: 复制成功
• false: 复制失败

可能异常：

• SqlException: 表复制异常
• ArgumentException: 参数无效

示例：

sql.CopyTable<NavigationTable>("Navigation", "dbo", "Navigation_Backup", "dbo", noData: false);

---

存储过程操作

判断存储过程是否存在

ExistsProcedure<T>()

功能说明： 判断存储过程是否存在。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool ExistsProcedure<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 存储过程存在
• false: 存储过程不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 表类型无效

示例：

if (sql.ExistsProcedure<NavigationTable>())
{
    Console.WriteLine("存储过程存在");
}

---

ExistsProcedure<T>(string table)

功能说明： 判断存储过程是否存在。

接口定义：

bool ExistsProcedure<T>(string table) where T : class, new();

参数说明：

• table: 数据表名称

返回值：

• true: 存储过程存在
• false: 存储过程不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsProcedure<NavigationTable>("Navigation"))
{
    Console.WriteLine("存储过程存在");
}

---

ExistsProcedure<T>(string table, string schema)

功能说明： 判断存储过程是否存在。

接口定义：

bool ExistsProcedure<T>(string table, string schema) where T : class, new();

参数说明：

• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 存储过程存在
• false: 存储过程不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsProcedure<NavigationTable>("Navigation", "dbo"))
{
    Console.WriteLine("存储过程存在");
}

---

ExistsProcedure<T>(string database, string table, string schema)

功能说明： 判断存储过程是否存在。

接口定义：

bool ExistsProcedure<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 存储过程存在
• false: 存储过程不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsProcedure<NavigationTable>("Hi.Ltd", "Navigation", "dbo"))
{
    Console.WriteLine("存储过程存在");
}

---

创建存储过程

CreateProcedure<T>()

功能说明： 创建存储过程。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool CreateProcedure<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 创建成功或存储过程已存在
• false: 创建失败

可能异常：

• SqlException: 存储过程创建异常
• ArgumentException: 表类型无效

示例：

if (sql.CreateProcedure<NavigationTable>())
{
    Console.WriteLine("存储过程创建成功");
}

---

CreateProcedure<T>(string table)

功能说明： 创建存储过程。

接口定义：

bool CreateProcedure<T>(string table) where T : class, new();

参数说明：

• table: 数据表名称

返回值：

• true: 创建成功或存储过程已存在
• false: 创建失败

可能异常：

• SqlException: 存储过程创建异常
• ArgumentException: 参数无效

示例：

sql.CreateProcedure<NavigationTable>("Navigation");

---

CreateProcedure<T>(string table, string schema)

功能说明： 创建存储过程。

接口定义：

bool CreateProcedure<T>(string table, string schema) where T : class, new();

参数说明：

• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 创建成功或存储过程已存在
• false: 创建失败

可能异常：

• SqlException: 存储过程创建异常
• ArgumentException: 参数无效

示例：

sql.CreateProcedure<NavigationTable>("Navigation", "dbo");

---

CreateProcedure<T>(string database, string table, string schema)

功能说明： 创建存储过程。

接口定义：

bool CreateProcedure<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 创建成功或存储过程已存在
• false: 创建失败

可能异常：

• SqlException: 存储过程创建异常
• ArgumentException: 参数无效

示例：

sql.CreateProcedure<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

更新存储过程

UpdateProcedure<T>()

功能说明： 更新存储过程。如果存储过程不存在，则新建一个；如果表结构有变动，则进行更新。

接口定义：

bool UpdateProcedure<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 存储过程更新异常
• ArgumentException: 表类型无效

示例：

if (sql.UpdateProcedure<NavigationTable>())
{
    Console.WriteLine("存储过程更新成功");
}

---

UpdateProcedure<T>(string table)

功能说明： 更新存储过程。

接口定义：

bool UpdateProcedure<T>(string table) where T : class, new();

参数说明：

• table: 数据表名称

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 存储过程更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateProcedure<NavigationTable>("Navigation");

---

UpdateProcedure<T>(string table, string schema)

功能说明： 更新存储过程。

接口定义：

bool UpdateProcedure<T>(string table, string schema) where T : class, new();

参数说明：

• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 存储过程更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateProcedure<NavigationTable>("Navigation", "dbo");

---

UpdateProcedure<T>(string database, string table, string schema)

功能说明： 更新存储过程。

接口定义：

bool UpdateProcedure<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 存储过程更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateProcedure<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

删除存储过程

DropProcedure<T>()

功能说明： 移除存储过程。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool DropProcedure<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 删除成功或存储过程不存在
• false: 删除失败

可能异常：

• SqlException: 存储过程删除异常
• ArgumentException: 表类型无效

示例：

if (sql.DropProcedure<NavigationTable>())
{
    Console.WriteLine("存储过程删除成功");
}

---

DropProcedure<T>(string table)

功能说明： 移除存储过程。

接口定义：

bool DropProcedure<T>(string table) where T : class, new();

参数说明：

• table: 数据表名称

返回值：

• true: 删除成功或存储过程不存在
• false: 删除失败

可能异常：

• SqlException: 存储过程删除异常
• ArgumentException: 参数无效

示例：

sql.DropProcedure<NavigationTable>("Navigation");

---

DropProcedure<T>(string table, string schema)

功能说明： 移除存储过程。

接口定义：

bool DropProcedure<T>(string table, string schema) where T : class, new();

参数说明：

• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 删除成功或存储过程不存在
• false: 删除失败

可能异常：

• SqlException: 存储过程删除异常
• ArgumentException: 参数无效

示例：

sql.DropProcedure<NavigationTable>("Navigation", "dbo");

---

DropProcedure<T>(string database, string table, string schema)

功能说明： 移除存储过程。

接口定义：

bool DropProcedure<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 删除成功或存储过程不存在
• false: 删除失败

可能异常：

• SqlException: 存储过程删除异常
• ArgumentException: 参数无效

示例：

sql.DropProcedure<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

架构操作

判断架构是否存在

ExistsSchema(string database, string schema)

功能说明： 检测表架构是否存在。

接口定义：

bool ExistsSchema(string database, string schema);

参数说明：

• database: 数据库名称
• schema: 表架构名称

返回值：

• true: 架构存在
• false: 架构不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsSchema("Hi.Ltd", "dbo"))
{
    Console.WriteLine("架构存在");
}

---

创建架构

CreateSchema(string schema)

功能说明： 创建表架构。

接口定义：

bool CreateSchema(string schema);

参数说明：

• schema: 表架构名称

返回值：

• true: 创建成功或架构已存在
• false: 创建失败

可能异常：

• SqlException: 架构创建异常
• ArgumentException: 架构名称无效
• UnauthorizedAccessException: 权限不足

示例：

if (sql.CreateSchema("hi"))
{
    Console.WriteLine("架构创建成功");
}

---

删除架构

DropSchema(string schema)

功能说明： 删除表架构。

接口定义：

bool DropSchema(string schema);

参数说明：

• schema: 表架构名称

返回值：

• true: 删除成功或架构不存在
• false: 删除失败

可能异常：

• SqlException: 架构删除异常（如架构中有对象存在）
• ArgumentException: 架构名称无效
• UnauthorizedAccessException: 权限不足

注意事项：

• 删除架构前，需要先删除架构中的所有对象（表、视图、存储过程等）
• 不能删除系统架构（如 dbo、sys 等）

示例：

if (sql.DropSchema("hi"))
{
    Console.WriteLine("架构删除成功");
}

---

表类型操作

判断表类型是否存在

ExistsTableType<T>()

功能说明： 判断用户定义表类型是否存在。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool ExistsTableType<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 表类型存在
• false: 表类型不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 表类型无效

示例：

if (sql.ExistsTableType<NavigationTable>())
{
    Console.WriteLine("表类型存在");
}

---

ExistsTableType<T>(string database)

功能说明： 判断用户定义表类型是否存在。

接口定义：

bool ExistsTableType<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 表类型存在
• false: 表类型不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsTableType<NavigationTable>("Hi.Ltd"))
{
    Console.WriteLine("表类型存在");
}

---

ExistsTableType<T>(string database, string table)

功能说明： 判断用户定义表类型是否存在。

接口定义：

bool ExistsTableType<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 表类型存在
• false: 表类型不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsTableType<NavigationTable>("Hi.Ltd", "Navigation"))
{
    Console.WriteLine("表类型存在");
}

---

ExistsTableType<T>(string database, string table, string schema)

功能说明： 判断用户定义表类型是否存在。

接口定义：

bool ExistsTableType<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 表类型存在
• false: 表类型不存在

可能异常：

• SqlException: 数据库查询异常
• ArgumentException: 参数无效

示例：

if (sql.ExistsTableType<NavigationTable>("Hi.Ltd", "Navigation", "dbo"))
{
    Console.WriteLine("表类型存在");
}

---

创建表类型

CreateTableType<T>()

功能说明： 创建用户定义表类型。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool CreateTableType<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 创建成功或表类型已存在
• false: 创建失败

可能异常：

• SqlException: 表类型创建异常
• ArgumentException: 表类型无效

示例：

if (sql.CreateTableType<NavigationTable>())
{
    Console.WriteLine("表类型创建成功");
}

---

CreateTableType<T>(string database)

功能说明： 创建用户定义表类型。

接口定义：

bool CreateTableType<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 创建成功或表类型已存在
• false: 创建失败

可能异常：

• SqlException: 表类型创建异常
• ArgumentException: 参数无效

示例：

sql.CreateTableType<NavigationTable>("Hi.Ltd");

---

CreateTableType<T>(string database, string table)

功能说明： 创建用户定义表类型。

接口定义：

bool CreateTableType<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 创建成功或表类型已存在
• false: 创建失败

可能异常：

• SqlException: 表类型创建异常
• ArgumentException: 参数无效

示例：

sql.CreateTableType<NavigationTable>("Hi.Ltd", "Navigation");

---

CreateTableType<T>(string database, string table, string schema)

功能说明： 创建用户定义表类型。

接口定义：

bool CreateTableType<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 表架构

返回值：

• true: 创建成功或表类型已存在
• false: 创建失败

可能异常：

• SqlException: 表类型创建异常
• ArgumentException: 参数无效

示例：

sql.CreateTableType<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

更新表类型

UpdateTableType<T>()

功能说明： 更新用户定义表类型。如果当前用户定义表已经存在，则删除旧的定义表，然后重新创建；如果不存在则执行创建表。

接口定义：

bool UpdateTableType<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 表类型更新异常
• ArgumentException: 表类型无效

注意事项：

• 更新操作会先删除旧的表类型，然后创建新的
• 如果表类型正在被使用，更新可能失败
• UpdateTableType<T>(string database, string table, string schema) 会先删除引用该 TVP 的过程，再重建 TVP；用于处理历史库中“类型被旧过程占用”导致的更新失败。
• 更新路径内部会对创建命令关闭“仅不存在时创建”保护（即强制重建），避免被 IF NOT EXISTS 短路导致类型列未刷新。

示例：

if (sql.UpdateTableType<NavigationTable>())
{
    Console.WriteLine("表类型更新成功");
}

---

UpdateTableType<T>(string database)

功能说明： 更新用户定义表类型。

接口定义：

bool UpdateTableType<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 表类型更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTableType<NavigationTable>("Hi.Ltd");

---

UpdateTableType<T>(string database, string table)

功能说明： 更新用户定义表类型。

接口定义：

bool UpdateTableType<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 表类型更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTableType<NavigationTable>("Hi.Ltd", "Navigation");

---

UpdateTableType<T>(string database, string table, string schema)

功能说明： 更新用户定义表类型。

接口定义：

bool UpdateTableType<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 更新成功
• false: 更新失败

可能异常：

• SqlException: 表类型更新异常
• ArgumentException: 参数无效

示例：

sql.UpdateTableType<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

删除表类型

DropTableType<T>()

功能说明： 删除用户定义表类型。使用表类中定义的数据库、表名和架构信息。

接口定义：

bool DropTableType<T>() where T : class, new();

类型参数：

• T: 数据表结构类型

返回值：

• true: 删除成功或表类型不存在
• false: 删除失败

可能异常：

• SqlException: 表类型删除异常（如表类型正在使用）
• ArgumentException: 表类型无效

注意事项：

• 如果表类型正在被存储过程或其他对象使用，删除可能失败

示例：

if (sql.DropTableType<NavigationTable>())
{
    Console.WriteLine("表类型删除成功");
}

---

DropTableType<T>(string database)

功能说明： 删除用户定义表类型。

接口定义：

bool DropTableType<T>(string database) where T : class, new();

参数说明：

• database: 数据库名称

返回值：

• true: 删除成功或表类型不存在
• false: 删除失败

可能异常：

• SqlException: 表类型删除异常
• ArgumentException: 参数无效

示例：

sql.DropTableType<NavigationTable>("Hi.Ltd");

---

DropTableType<T>(string database, string table)

功能说明： 删除用户定义表类型。

接口定义：

bool DropTableType<T>(string database, string table) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称

返回值：

• true: 删除成功或表类型不存在
• false: 删除失败

可能异常：

• SqlException: 表类型删除异常
• ArgumentException: 参数无效

示例：

sql.DropTableType<NavigationTable>("Hi.Ltd", "Navigation");

---

DropTableType<T>(string database, string table, string schema)

功能说明： 删除用户定义表类型。

接口定义：

bool DropTableType<T>(string database, string table, string schema) where T : class, new();

参数说明：

• database: 数据库名称
• table: 数据表名称
• schema: 数据表架构

返回值：

• true: 删除成功或表类型不存在
• false: 删除失败

可能异常：

• SqlException: 表类型删除异常
• ArgumentException: 参数无效

示例：

sql.DropTableType<NavigationTable>("Hi.Ltd", "Navigation", "dbo");

---

执行操作

异步执行自定义 SQL

功能说明： ISqlServer 继承 IExecuteAsync，可在高频场景下对 自定义 commandText 使用 ADO.NET 异步 API（OpenAsync、ExecuteNonQueryAsync、ExecuteScalarAsync、ExecuteReaderAsync 等），并统一返回 Task<Result<T>>，支持 CancellationToken。

与同步 IExecute 的对应关系（节选）：

同步	异步
ExecuteScalar(string commandText)	ExecuteScalarAsync(string commandText, CancellationToken cancellationToken = default)
ExecuteNonQuery(string commandText)	ExecuteNonQueryAsync(string commandText, CancellationToken cancellationToken = default)
ExecuteReader(string commandText, int commandTimeout)	ExecuteReaderAsync(string commandText, int commandTimeout, CancellationToken cancellationToken = default)
TransactionExecuteScalar(…) / NoneDataBaseExecuteScalar(…) 等	同名 *Async 重载

示例：

CancellationToken ct = default;
var r = await sql.ExecuteNonQueryAsync(
    "UPDATE dbo.Navigation SET Content=@c WHERE Id=@id",
    commandTimeout: 30,
    cancellationToken: ct);

完整签名见源码中的 IExecuteAsync。

---

执行属性

CommandTimeout

功能说明： 执行命令超时等待时间，默认单位：秒，默认值为 30 秒。

接口定义：

int CommandTimeout { get; set; }

示例：

sql.CommandTimeout = 60;  // 设置超时时间为 60 秒

---

ExecuteScalar 方法

ExecuteScalar(string commandText)

功能说明： 执行查询，并返回由查询返回的结果集中的第一行的第一列。其他列或行将被忽略。

接口定义：

object ExecuteScalar(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。返回的最大字符数为 2033 个字符。

可能异常：

• SqlException: SQL 执行异常
• ArgumentException: 命令文本无效
• InvalidOperationException: 连接未打开

示例：

object result = sql.ExecuteScalar("SELECT COUNT(*) FROM Navigation");
int count = Convert.ToInt32(result);

---

ExecuteScalar(string database, string commandText)

功能说明： 在指定数据库中执行查询，并返回结果集中的第一行的第一列。

接口定义：

object ExecuteScalar(string database, string commandText);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常或数据库不存在
• ArgumentException: 参数无效

示例：

object result = sql.ExecuteScalar("Hi.Ltd", "SELECT COUNT(*) FROM Navigation");

---

ExecuteScalar(string commandText, int commandTimeout)

功能说明： 执行查询，并返回结果集中的第一行的第一列，指定超时时间。

接口定义：

object ExecuteScalar(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效

示例：

object result = sql.ExecuteScalar("SELECT COUNT(*) FROM Navigation", 60);

---

ExecuteScalar(string database, string commandText, int commandTimeout)

功能说明： 在指定数据库中执行查询，并返回结果集中的第一行的第一列，指定超时时间。

接口定义：

object ExecuteScalar(string database, string commandText, int commandTimeout);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效

示例：

object result = sql.ExecuteScalar("Hi.Ltd", "SELECT COUNT(*) FROM Navigation", 60);

---

ExecuteNonQuery 方法

ExecuteNonQuery(string commandText)

功能说明： 执行 Transact-SQL 语句并返回受影响的行数。

接口定义：

int ExecuteNonQuery(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常
• ArgumentException: 命令文本无效
• InvalidOperationException: 连接未打开

示例：

int affectedRows = sql.ExecuteNonQuery("UPDATE Navigation SET Content = 'Updated' WHERE Id = 1");

---

ExecuteNonQuery(string database, string commandText)

功能说明： 在指定数据库中执行 Transact-SQL 语句并返回受影响的行数。

接口定义：

int ExecuteNonQuery(string database, string commandText);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常
• ArgumentException: 参数无效

示例：

int affectedRows = sql.ExecuteNonQuery("Hi.Ltd", "UPDATE Navigation SET Content = 'Updated' WHERE Id = 1");

---

ExecuteNonQuery(string commandText, int commandTimeout)

功能说明： 执行 Transact-SQL 语句并返回受影响的行数，指定超时时间。

接口定义：

int ExecuteNonQuery(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效

示例：

int affectedRows = sql.ExecuteNonQuery("UPDATE Navigation SET Content = 'Updated' WHERE Id = 1", 60);

---

ExecuteNonQuery(string database, string commandText, int commandTimeout)

功能说明： 在指定数据库中执行 Transact-SQL 语句并返回受影响的行数，指定超时时间。

接口定义：

int ExecuteNonQuery(string database, string commandText, int commandTimeout);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效

示例：

int affectedRows = sql.ExecuteNonQuery("Hi.Ltd", "UPDATE Navigation SET Content = 'Updated' WHERE Id = 1", 60);

---

ExecuteReader 方法

ExecuteReader(string commandText, int commandTimeout)

功能说明： 执行查询并返回结果集。使用当前连接的数据库执行查询。

接口定义：

List<Dictionary<string, object>> ExecuteReader(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• List<Dictionary<string, object>>: 查询结果集合，每个字典表示一行数据，键为列名，值为列值

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效
• InvalidOperationException: 连接未打开

注意事项：

• 使用当前连接字符串中指定的数据库
• 返回的结果集中，字典的键为列名（区分大小写），值为列值
• 如果列值为 DBNull，则字典中的值为 null
• 适用于需要获取完整结果集的查询操作

示例：

var results = sql.ExecuteReader("SELECT * FROM Navigation", 60);
foreach (var row in results)
{
    foreach (var kvp in row)
    {
        Console.WriteLine($"{kvp.Key}: {kvp.Value}");
    }
}

---

事务执行方法

TransactionExecuteScalar(string commandText)

功能说明： 启用事务执行查询，并返回由查询返回的结果集中的第一行的第一列。该方法主要用于判断、删除、复制数据表等操作。

接口定义：

object TransactionExecuteScalar(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。返回的最大字符数为 2033 个字符。

可能异常：

• SqlException: SQL 执行异常或事务失败
• ArgumentException: 命令文本无效

注意事项：

• 方法会自动开启事务，执行完成后提交或回滚
• 如果执行失败，事务会自动回滚

示例：

object result = sql.TransactionExecuteScalar("SELECT COUNT(*) FROM Navigation");

---

TransactionExecuteScalar(string database, string commandText)

功能说明： 启用事务并指定数据库执行查询，并返回结果集中的第一行的第一列。

接口定义：

object TransactionExecuteScalar(string database, string commandText);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常或事务失败
• ArgumentException: 参数无效

示例：

object result = sql.TransactionExecuteScalar("Hi.Ltd", "SELECT COUNT(*) FROM Navigation");

---

TransactionExecuteScalar(string commandText, int commandTimeout)

功能说明： 启用事务执行查询，并返回结果集中的第一行的第一列，指定超时时间。

接口定义：

object TransactionExecuteScalar(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常、事务失败或超时
• ArgumentException: 参数无效

示例：

object result = sql.TransactionExecuteScalar("SELECT COUNT(*) FROM Navigation", 60);

---

TransactionExecuteScalar(string database, string commandText, int commandTimeout)

功能说明： 启用事务并指定数据库执行查询，并返回结果集中的第一行的第一列，指定超时时间。

接口定义：

object TransactionExecuteScalar(string database, string commandText, int commandTimeout);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常、事务失败或超时
• ArgumentException: 参数无效

示例：

object result = sql.TransactionExecuteScalar("Hi.Ltd", "SELECT COUNT(*) FROM Navigation", 60);

---

TransactionExecuteNonQuery(string commandText)

功能说明： 启用事务执行 Transact-SQL 语句并返回受影响的行数。

接口定义：

int TransactionExecuteNonQuery(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常或事务失败
• ArgumentException: 命令文本无效

注意事项：

• 方法会自动开启事务，执行完成后提交或回滚
• 如果执行失败，事务会自动回滚

示例：

int affectedRows = sql.TransactionExecuteNonQuery("UPDATE Navigation SET Content = 'Updated' WHERE Id = 1");

---

TransactionExecuteNonQuery(string database, string commandText)

功能说明： 启用事务并指定数据库执行 Transact-SQL 语句并返回受影响的行数。

接口定义：

int TransactionExecuteNonQuery(string database, string commandText);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常或事务失败
• ArgumentException: 参数无效

示例：

int affectedRows = sql.TransactionExecuteNonQuery("Hi.Ltd", "UPDATE Navigation SET Content = 'Updated' WHERE Id = 1");

---

TransactionExecuteNonQuery(string commandText, int commandTimeout)

功能说明： 启用事务执行 Transact-SQL 语句并返回受影响的行数，指定超时时间。

接口定义：

int TransactionExecuteNonQuery(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常、事务失败或超时
• ArgumentException: 参数无效

示例：

int affectedRows = sql.TransactionExecuteNonQuery("UPDATE Navigation SET Content = 'Updated' WHERE Id = 1", 60);

---

TransactionExecuteNonQuery(string database, string commandText, int commandTimeout)

功能说明： 启用事务并指定数据库执行 Transact-SQL 语句并返回受影响的行数，指定超时时间。

接口定义：

int TransactionExecuteNonQuery(string database, string commandText, int commandTimeout);

参数说明：

• database: 数据库名称
• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常、事务失败或超时
• ArgumentException: 参数无效

示例：

int affectedRows = sql.TransactionExecuteNonQuery("Hi.Ltd", "UPDATE Navigation SET Content = 'Updated' WHERE Id = 1", 60);

---

无数据库执行方法

NoneDataBaseExecuteScalar(string commandText)

功能说明： 无指定数据库执行查询，并返回结果集中的第一行的第一列。

接口定义：

object NoneDataBaseExecuteScalar(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常
• ArgumentException: 命令文本无效

示例：

object result = sql.NoneDataBaseExecuteScalar("SELECT @@VERSION");

---

NoneDataBaseExecuteScalar(string commandText, int commandTimeout)

功能说明： 无指定数据库执行查询，并返回结果集中的第一行的第一列，指定超时时间。

接口定义：

object NoneDataBaseExecuteScalar(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效

示例：

object result = sql.NoneDataBaseExecuteScalar("SELECT @@VERSION", 60);

---

NoneDataBaseExecuteNonQuery(string commandText)

功能说明： 无指定数据库执行 Transact-SQL 语句并返回受影响的行数。

接口定义：

int NoneDataBaseExecuteNonQuery(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常
• ArgumentException: 命令文本无效

示例：

int affectedRows = sql.NoneDataBaseExecuteNonQuery("CREATE DATABASE TestDB");

---

NoneDataBaseExecuteNonQuery(string commandText, int commandTimeout)

功能说明： 无指定数据库执行 Transact-SQL 语句并返回受影响的行数，指定超时时间。

接口定义：

int NoneDataBaseExecuteNonQuery(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常或超时
• ArgumentException: 参数无效

示例：

int affectedRows = sql.NoneDataBaseExecuteNonQuery("CREATE DATABASE TestDB", 60);

---

NoneDataBaseTransactionExecuteScalar(string commandText)

功能说明： 无指定数据库启用事务执行查询，并返回结果集中的第一行的第一列。

接口定义：

object NoneDataBaseTransactionExecuteScalar(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常或事务失败
• ArgumentException: 命令文本无效

示例：

object result = sql.NoneDataBaseTransactionExecuteScalar("SELECT @@VERSION");

---

NoneDataBaseTransactionExecuteScalar(string commandText, int commandTimeout)

功能说明： 无指定数据库启用事务执行查询，并返回结果集中的第一行的第一列，指定超时时间。

接口定义：

object NoneDataBaseTransactionExecuteScalar(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• object: 结果集中的第一行的第一列，如果结果集为空，则为 null。

可能异常：

• SqlException: SQL 执行异常、事务失败或超时
• ArgumentException: 参数无效

示例：

object result = sql.NoneDataBaseTransactionExecuteScalar("SELECT @@VERSION", 60);

---

NoneDataBaseTransactionExecuteNonQuery(string commandText)

功能说明： 无指定数据库启用事务执行 Transact-SQL 语句并返回受影响的行数。

接口定义：

int NoneDataBaseTransactionExecuteNonQuery(string commandText);

参数说明：

• commandText: Transact-SQL 命令字符串

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常或事务失败
• ArgumentException: 命令文本无效

示例：

int affectedRows = sql.NoneDataBaseTransactionExecuteNonQuery("CREATE DATABASE TestDB");

---

NoneDataBaseTransactionExecuteNonQuery(string commandText, int commandTimeout)

功能说明： 无指定数据库启用事务执行 Transact-SQL 语句并返回受影响的行数，指定超时时间。

接口定义：

int NoneDataBaseTransactionExecuteNonQuery(string commandText, int commandTimeout);

参数说明：

• commandText: Transact-SQL 命令字符串
• commandTimeout: 命令超时时间（秒）

返回值：

• int: 受影响的行数

可能异常：

• SqlException: SQL 执行异常、事务失败或超时
• ArgumentException: 参数无效

示例：

int affectedRows = sql.NoneDataBaseTransactionExecuteNonQuery("CREATE DATABASE TestDB", 60);

---

ITools 只读统计

范围：聚合、窗口分析、数学函数（命名贴近 T-SQL，在单表与列白名单约束下生成只读查询。）

ITools 由 ISqlServer 聚合暴露，实现类型为 SqlServerBase 的 partial 方法（Statistics.cs、Statistics.Aggregates.cs、Statistics.WindowAnalytics.cs、Statistics.Math.cs）。所有涉及 列名 的参数必须是表 POCO 上 已映射的持久化属性名（与 GetMappedPersistenceProperties / Native.GetOrAddMappedPersistenceProperties 一致），非法列名在客户端即返回失败 Result；类型或 T-SQL 不合法 时通常由 SQL Server 报错并反映为失败结果。

能力概览与版本要求

类别	代表 API	SQL Server 最低版本提示
聚合扩展	CountBig、StDev/StDevP/Var/VarP、ChecksumAgg、ApproxCountDistinct、StringAgg	STRING_AGG：2017+；APPROX_COUNT_DISTINCT：2019（兼容级别 150 等环境）
窗口 / 分析	Lag/Lead、FirstValue/LastValue、CumeDist、PercentRank、PercentileCont/PercentileDisc（有序集 + 窗口重载）	PERCENTILE_CONT/DISC：2012+ 引擎；目标库 compatibility_level 须 ≥ 110（否则常见 10762）
数学	Pi、Rand（可选种子）、Abs/Round/Power/Atn2 等对列逐元生成表达式	与实例支持的标量函数一致
既有统计	Columns、Count、Sum/Avg/Min/Max、Top、GroupByCount 等	与原有约定相同

用例示例

聚合与 STRING_AGG（分隔符参数化，禁止拼接进 SQL）：

// 多列分别 SUM（既有）
var sumR = sql.Sum<Order>(nameof(Order.Amount), nameof(Order.Tax));

// COUNT_BIG(*) 与 COUNT(*) 语义区分（bigint）
var big = sql.CountBig<Order>("YourDatabase");

// 每列一个 APPROX_COUNT_DISTINCT（多列 = 多个独立近似 distinct）
var approx = sql.ApproxCountDistinct<Customer>(nameof(Customer.Email));

// STRING_AGG：WITHIN GROUP (ORDER BY …)，分隔符用参数绑定
var codes = new[] { nameof(Order.Code) };
var agg = sql.StringAgg<Order>(", ", codes, nameof(Order.LineNote));

窗口：StatisticWindowPartitionOrder（必填 ORDER BY 列；可选 PARTITION BY；可选半开时间 [RangeStart, RangeEndExclusive) + RangeTimeColumns）：

// 按 Id 排序，Lag 上一行的 Id；默认值为 null（SQL NULL）
var win = new StatisticWindowPartitionOrder(
    orderByColumns: new[] { nameof(Order.Id) },
    partitionByColumns: new[] { nameof(Order.CustomerId) },
    ascending: true);

var lagR = sql.Lag<Order>(nameof(Order.Id), offset: 1, defaultValue: null, window: win);
if (lagR.Successed)
{
    foreach (var row in lagR.Content)
    {
        // 行为字典：含表列 + 分析列别名如 Lag_Id
    }
}

// 有序集聚合：整表标量，fraction 在 [0,1] 内，内部以安全数值字面量写入 T-SQL
var p50 = sql.PercentileCont<Order>(0.5, nameof(Order.Amount));

数学：Pi/Rand 与逐列表级表达式（返回 StatisticAggregateRow）：

var pi = sql.Pi();                         // SELECT CAST(PI() AS FLOAT)
var rnd = sql.Rand(12345);                 // RAND(seed)，与表行无关

var roundR = sql.Round<Order>(nameof(Order.Amount), length: 2, function: 0);
var powR = sql.Power<Order>(nameof(Order.Amount), exponent: 1.05);

异步： 各 API 均提供 *Async 重载（多数为 Task.FromResult 包装同步路径；CountBigAsync 等使用 ExecuteScalarAsync）。用法与同步一致并传入 CancellationToken。

约束与限制

1. 列白名单：PARTITION BY、ORDER BY、WITHIN GROUP (ORDER BY …)、STRING_AGG 的值列与排序列等，一律须为映射列名；不支持任意 SQL 标识符绕过校验（LAG/LEAD 的 字符串默认值重载 除外，该重载由调用方自行保证语法与安全，禁止拼接未转义的用户输入）。
2. 单表、无 CUBE 生成器：不生成带 GROUPING SETS / ROLLUP / CUBE 的查询，不提供 GROUPING / GROUPING_ID 的封装；需要时请使用 IExecute.ExecuteReader（及带 Action<SqlCommand> 配置参数的重载）编写完整 T-SQL。
3. 结果集形态：Top、窗口分析等多行 API 返回 Result<IReadOnlyList<Dictionary<string, object>>>，可能较大；大表请自行限制范围或改用自定义 SQL / 分页。
4. 有序分位数：PercentileCont/PercentileDisc 的 fraction 须在 [0, 1]；有序集聚合中分位数以 有限数值字面量 形式写入语句（非用户拼接字符串）；空集或无效数据时标量可能为 null（Result<double?>）。另：目标库 compatibility_level ≥ 110 时 PERCENTILE_CONT/DISC 才可用；不足时常见 SQL 10762（与实例大版本、仅「引擎 2012+」提示并不总能划等号，以库级别为准）。排障可展开 Result：ResultDiagnostics.FormatFailure / TryFindSqlExceptionNumber(…, 10762, …)。
5. LAST_VALUE：LastValue(..., useUnboundedFollowingFrame: true)（默认）追加 ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING，以贴近「分区末尾值」常见语义；false 时使用引擎默认窗口帧，语义不同，需自行理解 T-SQL。
6. 版本与兼容级别：即使实例版本满足，数据库 兼容级别 过低仍可能导致 STRING_AGG、APPROX_COUNT_DISTINCT、PERCENTILE_CONT/DISC 等失败，请在目标环境验证；需要时将 ALTER DATABASE … SET COMPATIBILITY_LEVEL 提到 至少 110（分位数）/ 2017+ 能力对应级别 等。

---

文档说明

本文档涵盖了 Hi.Ltd.SqlServer 类库的所有主要功能和方法。文档分为以下部分：

• 概述: 类库简介和主要特性
• 快速开始: 安装和基本使用示例
• Factory、SqlEntities 与 Auto: 全局句柄、InitialSqlServer、CRUD 封装与 [Auto] 自动托管说明
• 属性说明: 所有可用的数据注解属性（含 AutoAttribute）
• 连接和基础操作: 数据库连接配置和基本操作
• 数据库操作: 数据库的创建、删除、备份、恢复等操作
• 数据表操作: 表的创建、修改、插入、更新、查询、删除、复制等操作
• 存储过程操作: 存储过程的创建、更新、删除等操作
• 架构操作: 数据库架构的创建、删除等操作
• 表类型操作: 用户定义表类型的创建、更新、删除等操作
• 执行操作: SQL 命令的执行方法，包括 ExecuteScalar、ExecuteNonQuery、ExecuteReader 等
• ITools 只读统计: 聚合、窗口分析、数学等只读统计 API 与约束说明

使用建议

1. 生产环境使用前：请在测试环境充分测试所有操作
2. 数据备份：在执行删除、修改等操作前，请确保已备份重要数据
3. 异常处理：建议使用 try-catch 块捕获可能的异常
4. 性能优化：对于批量操作，建议使用批量方法而不是循环调用单条方法
5. 事务使用：对于需要保证原子性的操作，使用事务执行方法

常见问题

1. 连接失败：检查服务器地址、用户名、密码是否正确，以及网络连接是否正常
2. 权限不足：确保数据库用户具有执行相应操作的权限
3. 表不存在：在执行表操作前，先使用 ExistsTable 方法检查表是否存在
4. 外键约束：删除或更新数据时，注意外键约束的影响

---

列级 Attributes（Tier3）使用说明

本节补充 src/Attributes 的列级能力，重点说明普通表（CREATE TABLE）与 TVP（CREATE TYPE ... AS TABLE）的差异。

统一解析入口

• 列名统一由 GetPhysicalColumnName 解析：优先 ColumnAttribute.Name，否则使用属性名。
• 列类型统一由 GetColumnSqlTypeSpec 解析：Computed > Column.TypeName > Timestamp(byte[]) > MaxLength/Decimal > CLR 默认映射。
• 后缀统一由 GetColumnTrailingKeywords 解析：COLLATE、SPARSE、ROWGUIDCOL。
• 自增统一由 GetIdentityFragment 解析：IdentityColumn 优先，其次 DatabaseGenerated。
• 默认值统一由 GetDefaultSql 解析：DefaultSqlAttribute 映射为 DEFAULT ...。

普通表与 TVP 差异

• 普通表路径：完整支持上述 Tier3 特性。
• TVP 路径：对不支持项采用“受控降级”——不输出无效片段、不抛异常中断流程。
• TVP 降级时会输出两类提示：
  • 脚本注释前缀：-- Hi.Ltd.SqlServer TVP:
  • 命令实例诊断：CreateTableTypeCommand<T>.TvpSanitizationMessages

常用用例

[Table("OrderLine")]
public class OrderLine
{
    [Key, IdentityColumn(1000, 1), Column("LineId")]
    public int Id { get; set; }

    [Column("Amount", TypeName = "decimal(18,4)")]
    public decimal Amount { get; set; }

    [Collation(SqlCollations.Chinese_PRC_CI_AS)]
    [MaxLength(64)]
    public string Name { get; set; }

    [DefaultSql("(getdate())")]
    public DateTime CreatedAt { get; set; }

    [Persisted("[Amount] * 2", persisted: true)]
    public decimal DoubleAmount { get; set; }

    [Timestamp]
    public byte[] RowVersion { get; set; }
}

关键规则

• DecimalAttribute 与 DigitAttribute 同时存在时，优先 DecimalAttribute。
• PersistedAttribute 在普通表输出 AS (...) [PERSISTED]；在 TVP 中会降级并给出提示。
• CollationAttribute 支持两种写法：字符串（会做格式校验）与 SqlCollations 预设常量（推荐，减少手写拼写错误，且可用于特性参数）。
  • 预设已内置常用规则：SqlCollations.Chinese_PRC_*、SqlCollations.Latin1_General_*、SqlCollations.SQL_Latin1_General_CP1_CI_AS。
  • 运行期强类型可使用 SqlCollation.Custom("Your_Collation")；可用 IsLegacy 判断是否为历史兼容规则。
  • SqlCollation 支持忽略大小写相等比较（Equals / == / !=），例如：SqlCollation.Chinese_PRC_CI_AS == SqlCollation.Custom("chinese_prc_ci_as") 为 true。
  • 支持类型转换：SqlCollation -> string（隐式），string -> SqlCollation（显式，带校验）。

SqlCollation 运行期示例

var preset = SqlCollation.Chinese_PRC_CI_AS;
SqlCollation custom = (SqlCollation)"Chinese_PRC_CI_AS";
bool same = preset == custom;              // true（忽略大小写）
string raw = preset;                       // 隐式转 string
bool legacy = SqlCollation.SQL_Latin1_General_CP1_CI_AS.IsLegacy;

• TimestampAttribute 在普通表映射 rowversion；在 TVP 中回退为可存储类型并给出提示。
• 插入命令会跳过“自增主键 + 计算列”，避免生成不可写列插入语句。

---

技术支持

文档版本: 2026.04.20.0954 最后更新: 2026年
维护者: chustange

如有问题或建议，请联系：

• 公司: 海蓝智能科技有限公司
• 版权: © 2026 海蓝智能科技有限公司 保留所有权利

---

免责声明: 本类库仅供公司内部参考使用，不保证方法的有效性，请谨慎使用！