SQLHelper 添加事务属性、最后的自增ID、异步版本的执行方法 (#121)

Api/Transmittal/SQLHelper.cs

@@ -1,4 +1,5 @@
 using System.Data;
+using System.Data.Common;
 using Milimoe.FunGame.Core.Interface.Base;
 using Milimoe.FunGame.Core.Library.Constant;
 using Milimoe.FunGame.Core.Model;
@@ -6,24 +7,77 @@ using Milimoe.FunGame.Core.Model;
 namespace Milimoe.FunGame.Core.Api.Transmittal
 {
     /// <summary>
-    /// 需要在Server中继承此类实现
+    /// 数据库助手类。这是一个抽象类，需要在Server中继承此类实现
     /// </summary>
     public abstract class SQLHelper : ISQLHelper, IDisposable
     {
+        /// <summary>
+        /// FunGame 类型
+        /// </summary>
         public abstract FunGameInfo.FunGame FunGameType { get; }
+
+        /// <summary>
+        /// 使用的数据库类型
+        /// </summary>
         public abstract SQLMode Mode { get; }
+
+        /// <summary>
+        /// SQL 脚本
+        /// </summary>
         public abstract string Script { get; set; }
+
+        /// <summary>
+        /// 命令类型
+        /// </summary>
         public abstract CommandType CommandType { get; set; }
+
+        /// <summary>
+        /// 数据库事务
+        /// </summary>
+        public abstract DbTransaction? Transaction { get; }
+
+        /// <summary>
+        /// 执行结果
+        /// </summary>
         public abstract SQLResult Result { get; }
+
+        /// <summary>
+        /// SQL 服务器信息
+        /// </summary>
         public abstract SQLServerInfo ServerInfo { get; }
-        public abstract int UpdateRows { get; }
+
+        /// <summary>
+        /// 上一次执行命令影响的行数
+        /// </summary>
+        public abstract int AffectedRows { get; }
+
+        /// <summary>
+        /// 上一次执行的命令是 Insert 时，返回的自增 ID，大于 0 有效
+        /// </summary>
+        public abstract long LastInsertId { get; }
+
+        /// <summary>
+        /// 上一次执行命令的查询结果集
+        /// </summary>
         public abstract DataSet DataSet { get; }
+
+        /// <summary>
+        /// SQL 语句参数
+        /// </summary>
         public abstract Dictionary<string, object> Parameters { get; }
+
+        /// <summary>
+        /// 上一次执行命令是否成功
+        /// </summary>
         public bool Success => Result == SQLResult.Success;
+
+        /// <summary>
+        /// 是否在每次执行命令后清除参数，默认为 true
+        /// </summary>
         public bool ClearParametersAfterExecute { get; set; } = true;
 
         /// <summary>
-        /// 执行一个命令
+        /// 执行现有命令（<see cref="Script"/>）
         /// </summary>
         /// <returns>影响的行数</returns>
         public abstract int Execute();
@@ -36,20 +90,46 @@ namespace Milimoe.FunGame.Core.Api.Transmittal
         public abstract int Execute(string script);
 
         /// <summary>
-        /// 查询DataSet
+        /// 异步执行现有命令（<see cref="Script"/>）
+        /// </summary>
+        /// <returns>影响的行数</returns>
+        public abstract Task<int> ExecuteAsync();
+
+        /// <summary>
+        /// 异步执行一个指定的命令
+        /// </summary>
+        /// <param name="script">命令</param>
+        /// <returns>影响的行数</returns>
+        public abstract Task<int> ExecuteAsync(string script);
+
+        /// <summary>
+        /// 执行现有命令（<see cref="Script"/>）查询 DataSet
         /// </summary>
         /// <returns>结果集</returns>
         public abstract DataSet ExecuteDataSet();
 
         /// <summary>
-        /// 执行指定的命令查询DataSet
+        /// 执行指定的命令查询 DataSet
         /// </summary>
         /// <param name="script">命令</param>
         /// <returns>结果集</returns>
         public abstract DataSet ExecuteDataSet(string script);
 
         /// <summary>
-        /// 执行指定的命令查询DataRow（可选实现）
+        /// 异步执行现有命令（<see cref="Script"/>）查询 DataSet
+        /// </summary>
+        /// <returns>结果集</returns>
+        public abstract Task<DataSet> ExecuteDataSetAsync();
+
+        /// <summary>
+        /// 异步执行指定的命令查询 DataSet
+        /// </summary>
+        /// <param name="script">命令</param>
+        /// <returns>结果集</returns>
+        public abstract Task<DataSet> ExecuteDataSetAsync(string script);
+
+        /// <summary>
+        /// 执行现有命令（<see cref="Script"/>）查询 DataRow（可选实现）
         /// </summary>
         /// <returns>结果行</returns>
         public virtual DataRow? ExecuteDataRow()
@@ -58,16 +138,40 @@ namespace Milimoe.FunGame.Core.Api.Transmittal
         }
 
         /// <summary>
-        /// 执行指定的命令查询DataRow（可选实现）
+        /// 执行指定的命令查询 DataRow（可选实现）
         /// </summary>
         /// <param name="script">命令</param>
         /// <returns>结果行</returns>
         public virtual DataRow? ExecuteDataRow(string script)
         {
-            DataSet dataSet = ExecuteDataSet(script);
+            ExecuteDataSet(script);
-            if (dataSet.Tables.Count > 0 && dataSet.Tables[0].Rows.Count > 0)
+            if (Success)
             {
-                return dataSet.Tables[0].Rows[0];
+                return DataSet.Tables[0].Rows[0];
+            }
+            return null;
+        }
+
+        /// <summary>
+        /// 异步执行现有命令（<see cref="Script"/>）查询 DataRow（可选实现）
+        /// </summary>
+        /// <returns>结果行</returns>
+        public virtual async Task<DataRow?> ExecuteDataRowAsync()
+        {
+            return await ExecuteDataRowAsync(Script);
+        }
+
+        /// <summary>
+        /// 异步执行指定的命令查询 DataRow（可选实现）
+        /// </summary>
+        /// <param name="script">命令</param>
+        /// <returns>结果行</returns>
+        public virtual async Task<DataRow?> ExecuteDataRowAsync(string script)
+        {
+            await ExecuteDataSetAsync(script);
+            if (Success)
+            {
+                return DataSet.Tables[0].Rows[0];
             }
             return null;
         }
@@ -102,6 +206,30 @@ namespace Milimoe.FunGame.Core.Api.Transmittal
             }
         }
         
+        /// <summary>
+        /// 异步执行一个 sql 脚本文件
+        /// </summary>
+        /// <param name="path"></param>
+        public virtual async Task ExecuteSqlFileAsync(string path)
+        {
+            if (!File.Exists(path))
+            {
+                throw new FileNotFoundException("SQL 脚本文件不存在", path);
+            }
+
+            string content = File.ReadAllText(path);
+            string[] commands = content.Split([";"], StringSplitOptions.RemoveEmptyEntries);
+
+            foreach (string command in commands)
+            {
+                string sql = command.Trim();
+                if (!string.IsNullOrEmpty(sql))
+                {
+                    await ExecuteAsync(sql);
+                }
+            }
+        }
+
         /// <summary>
         /// 关闭连接
         /// </summary>

Interface/Base/ISQLHelper.cs

@@ -1,4 +1,5 @@
 using System.Data;
+using System.Data.Common;
 using Milimoe.FunGame.Core.Library.Constant;
 using Milimoe.FunGame.Core.Model;
 
@@ -9,15 +10,20 @@ namespace Milimoe.FunGame.Core.Interface.Base
         public FunGameInfo.FunGame FunGameType { get; }
         public string Script { get; set; }
         public CommandType CommandType { get; set; }
+        public DbTransaction? Transaction { get; }
         public SQLResult Result { get; }
         public SQLServerInfo ServerInfo { get; }
-        public int UpdateRows { get; }
+        public int AffectedRows { get; }
+        public long LastInsertId { get; }
         public DataSet DataSet { get; }
         public bool Success { get; }
 
         public int Execute();
         public DataSet ExecuteDataSet();
         public DataRow? ExecuteDataRow();
+        public Task<int> ExecuteAsync();
+        public Task<DataSet> ExecuteDataSetAsync();
+        public Task<DataRow?> ExecuteDataRowAsync();
         public void Close();
         public void NewTransaction();
         public void Commit();