SQLHelper(中文注释版)

SQLHelper类：

 

代码

   1 using System;
   2 using System.Data;
   3 using System.Xml;
   4 using System.Data.SqlClient;
   5 using System.Collections;
   6 
   7 namespace hkszyy
   8 {
   9     /// <summary>
  10     /// SqlServer数据访问帮助类
  11     /// </summary>
  12     public sealed class SqlHelper
  13     {
  14         #region 私有构造函数和方法
  15 
  16         private SqlHelper() {}
  17 
  18         /// <summary>
  19         /// 将SqlParameter参数数组(参数值)分配给SqlCommand命令.
  20         /// 这个方法将给任何一个参数分配DBNull.Value;
  21         /// 该操作将阻止默认值的使用.
  22         /// </summary>
  23         /// <param name="command">命令名</param>
  24         /// <param name="commandParameters">SqlParameters数组</param>
  25         private static void AttachParameters(SqlCommand command, SqlParameter[] commandParameters)
  26         {
  27             if( command == null ) throw new ArgumentNullException( "command" );
  28             if( commandParameters != null )
  29             {
  30                 foreach (SqlParameter p in commandParameters)
  31                 {
  32                     if( p != null )
  33                     {
  34                         // 检查未分配值的输出参数,将其分配以DBNull.Value.
  35                         if ( ( p.Direction == ParameterDirection.InputOutput || p.Direction == ParameterDirection.Input ) && 
  36                             (p.Value == null))
  37                         {
  38                             p.Value = DBNull.Value;
  39                         }
  40                         command.Parameters.Add(p);
  41                     }
  42                 }
  43             }
  44         }
  45 
  46         /// <summary>
  47         /// 将DataRow类型的列值分配到SqlParameter参数数组.
  48         /// </summary>
  49         /// <param name="commandParameters">要分配值的SqlParameter参数数组</param>
  50         /// <param name="dataRow">将要分配给存储过程参数的DataRow</param>
  51         private static void AssignParameterValues(SqlParameter[] commandParameters, DataRow dataRow)
  52         {
  53             if ((commandParameters == null) || (dataRow == null)) 
  54             {
  55                 return;
  56             }
  57 
  58             int i = 0;
  59             // 设置参数值
  60             foreach(SqlParameter commandParameter in commandParameters)
  61             {
  62                 // 创建参数名称,如果不存在,只抛出一个异常.
  63                 if( commandParameter.ParameterName == null || 
  64                     commandParameter.ParameterName.Length <= 1 )
  65                     throw new Exception( 
  66                         string.Format("请提供参数{0}一个有效的名称{1}.", i, commandParameter.ParameterName ) );
  67                 // 从dataRow的表中获取为参数数组中数组名称的列的索引.
  68                 // 如果存在和参数名称相同的列,则将列值赋给当前名称的参数.
  69                 if (dataRow.Table.Columns.IndexOf(commandParameter.ParameterName.Substring(1)) != -1)
  70                     commandParameter.Value = dataRow[commandParameter.ParameterName.Substring(1)];
  71                 i++;
  72             }
  73         }
  74 
  75         /// <summary>
  76         /// 将一个对象数组分配给SqlParameter参数数组.
  77         /// </summary>
  78         /// <param name="commandParameters">要分配值的SqlParameter参数数组</param>
  79         /// <param name="parameterValues">将要分配给存储过程参数的对象数组</param>
  80         private static void AssignParameterValues(SqlParameter[] commandParameters, object[] parameterValues)
  81         {
  82             if ((commandParameters == null) || (parameterValues == null)) 
  83             {
  84                 return;
  85             }
  86 
  87             // 确保对象数组个数与参数个数匹配,如果不匹配,抛出一个异常.
  88             if (commandParameters.Length != parameterValues.Length)
  89             {
  90                 throw new ArgumentException("参数值个数与参数不匹配.");
  91             }
  92 
  93             // 给参数赋值
  94             for (int i = 0, j = commandParameters.Length; i < j; i++)
  95             {
  96                 // If the current array value derives from IDbDataParameter, then assign its Value property
  97                 if (parameterValues[i] is IDbDataParameter)
  98                 {
  99                     IDbDataParameter paramInstance = (IDbDataParameter)parameterValues[i];
 100                     if( paramInstance.Value == null )
 101                     {
 102                         commandParameters[i].Value = DBNull.Value; 
 103                     }
 104                     else
 105                     {
 106                         commandParameters[i].Value = paramInstance.Value;
 107                     }
 108                 }
 109                 else if (parameterValues[i] == null)
 110                 {
 111                     commandParameters[i].Value = DBNull.Value;
 112                 }
 113                 else
 114                 {
 115                     commandParameters[i].Value = parameterValues[i];
 116                 }
 117             }
 118         }
 119 
 120         /// <summary>
 121         /// 预处理用户提供的命令,数据库连接/事务/命令类型/参数
 122         /// </summary>
 123         /// <param name="command">要处理的SqlCommand</param>
 124         /// <param name="connection">数据库连接</param>
 125         /// <param name="transaction">一个有效的事务或者是null值</param>
 126         /// <param name="commandType">命令类型 (存储过程,命令文本, 其它.)</param>
 127         /// <param name="commandText">存储过程名或都T-SQL命令文本</param>
 128         /// <param name="commandParameters">和命令相关联的SqlParameter参数数组,如果没有参数为'null'</param>
 129         /// <param name="mustCloseConnection"><c>true</c> 如果连接是打开的,则为true,其它情况下为false.</param>
 130         private static void PrepareCommand(SqlCommand command, SqlConnection connection, SqlTransaction transaction, CommandType commandType, string commandText, SqlParameter[] commandParameters, out bool mustCloseConnection )
 131         {
 132             if( command == null ) throw new ArgumentNullException( "command" );
 133             if( commandText == null || commandText.Length == 0 ) throw new ArgumentNullException( "commandText" );
 134 
 135             // If the provided connection is not open, we will open it
 136             if (connection.State != ConnectionState.Open)
 137             {
 138                 mustCloseConnection = true;
 139                 connection.Open();
 140             }
 141             else
 142             {
 143                 mustCloseConnection = false;
 144             }
 145 
 146             // 给命令分配一个数据库连接.
 147             command.Connection = connection;
 148 
 149             // 设置命令文本(存储过程名或SQL语句)
 150             command.CommandText = commandText;
 151 
 152             // 分配事务
 153             if (transaction != null)
 154             {
 155                 if( transaction.Connection == null ) throw new ArgumentException( "The transaction was rollbacked or commited, please provide an open transaction.", "transaction" );
 156                 command.Transaction = transaction;
 157             }
 158 
 159             // 设置命令类型.
 160             command.CommandType = commandType;
 161 
 162             // 分配命令参数
 163             if (commandParameters != null)
 164             {
 165                 AttachParameters(command, commandParameters);
 166             }
 167             return;
 168         }
 169 
 170         #endregion 私有构造函数和方法结束
 171 
 172         #region ExecuteNonQuery命令
 173 
 174         /// <summary>
 175         /// 执行指定连接字符串,类型的SqlCommand.
 176         /// </summary>
 177         /// <remarks>
 178         /// 示例:  
 179         ///  int result = ExecuteNonQuery(connString, CommandType.StoredProcedure, "PublishOrders");
 180         /// </remarks>
 181         /// <param name="connectionString">一个有效的数据库连接字符串</param>
 182         /// <param name="commandType">命令类型 (存储过程,命令文本, 其它.)</param>
 183         /// <param name="commandText">存储过程名称或SQL语句</param>
 184         /// <returns>返回命令影响的行数</returns>
 185         public static int ExecuteNonQuery(string connectionString, CommandType commandType, string commandText)
 186         {
 187             return ExecuteNonQuery(connectionString, commandType, commandText, (SqlParameter[])null);
 188         }
 189 
 190         /// <summary>
 191         /// 执行指定连接字符串,类型的SqlCommand.如果没有提供参数,不返回结果.
 192         /// </summary>
 193         /// <remarks>
 194         /// 示例:  
 195         ///  int result = ExecuteNonQuery(connString, CommandType.StoredProcedure, "PublishOrders", new SqlParameter("@prodid", 24));
 196         /// </remarks>
 197         /// <param name="connectionString">一个有效的数据库连接字符串</param>
 198         /// <param name="commandType">命令类型 (存储过程,命令文本, 其它.)</param>
 199         /// <param name="commandText">存储过程名称或SQL语句</param>
 200         /// <param name="commandParameters">SqlParameter参数数组</param>
 201         /// <returns>返回命令影响的行数</returns>
 202         public static int ExecuteNonQuery(string connectionString, CommandType commandType, string commandText, params SqlParameter[] commandParameters)
 203         {
 204             if( connectionString == null || connectionString.Length == 0 ) throw new ArgumentNullException( "connectionString" );
 205 
 206             using (SqlConnection connection = new SqlConnection(connectionString))
 207             {
 208                 connection.Open();
 209 
 210                 return ExecuteNonQuery(connection, commandType, commandText, commandParameters);
 211             }
 212         }
 213 
 214         /// <summary>
 215         /// 执行指定连接字符串的存储过程,将对象数组的值赋给存储过程参数,
 216         /// 此方法需要在参数缓存方法中探索参数并生成参数.
 217         /// </summary>
 218         /// <remarks>
 219         /// 这个方法没有提供访问输出参数和返回值.
 220         /// 示例:  
 221         ///  int result = ExecuteNonQuery(connString, "PublishOrders", 24, 36);
 222         /// </remarks>
 223         /// <param name="connectionString">一个有效的数据库连接字符串/param>
 224         /// <param name="spName">存储过程名称</param>
 225         /// <param name="parameterValues">分配到存储过程输入参数的对象数组</param>
 226         /// <returns>返回受影响的行数</returns>
 227         public static int ExecuteNonQuery(string connectionString, string spName, params object[] parameterValues)
 228         {
 229             if( connectionString == null || connectionString.Length == 0 ) throw new ArgumentNullException( "connectionString" );
 230             if( spName == null || spName.Length == 0 ) throw new ArgumentNullException( "spName" );
 231 
 232             // 如果存在参数值
 233             if ((parameterValues != null) && (parameterValues.Length > 0)) 
 234             {
 235                 // 从探索存储过程参数(加载到缓存)并分配给存储过程参数数组.
 236                 SqlParameter[] commandParameters = SqlHelperParameterCache.GetSpParameterSet(connectionString, spName);
 237 
 238                 // 给存储过程参数赋值
 239                 AssignParameterValues(commandParameters, parameterValues);
 240 
 241                 return ExecuteNonQuery(connectionString, CommandType.StoredProcedure, spName, commandParameters);
 242             }
 243             else 
 244             {
 245                 // 没有参数情况下
 246                 return ExecuteNonQuery(connectionString, CommandType.StoredProcedure, spName);
 247             }
 248         }
 249 
 250         /// <summary>
 251         /// 执行指定数据库连接对象的命令 
 252         /// </summary>
 253         /// <remarks>
 254         /// 示例:  
 255         ///  int result = ExecuteNonQuery(conn, CommandType.StoredProcedure, "PublishOrders");
 256         /// </remarks>
 257         /// <param name="connection">一个有效的数据库连接对象</param>
 258         /// <param name="commandType">命令类型(存储过程,命令文本或其它.)</param>
 259         /// <param name="commandText">存储过程名称或T-SQL语句</param>
 260         /// <returns>返回影响的行数</returns>
 261         public static int ExecuteNonQuery(SqlConnection connection, CommandType commandType, string commandText)
 262         {
 263             return ExecuteNonQuery(connection, commandType, commandText, (SqlParameter[])null);
 264         }
 265 
 266         /// <summary>
 267         /// 执行指定数据库连接对象的命令
 268         /// </summary>
 269         /// <remarks>
 270         /// 示例:  
 271         ///  int result = ExecuteNonQuery(conn, CommandType.StoredProcedure, "PublishOrders", new SqlParameter("@prodid", 24));
 272         /// </remarks>
 273         /// <param name="connection">一个有效的数据库连接对象</param>
 274         /// <param name="commandType">命令类型(存储过程,命令文本或其它.)</param>
 275         /// <param name="commandText">T存储过程名称或T-SQL语句</param>
 276         /// <param name="commandParameters">SqlParamter参数数组</param>
 277         /// <returns>返回影响的行数</returns>
 278         public static int ExecuteNonQuery(SqlConnection connection, CommandType commandType, string commandText, params SqlParameter[] commandParameters)
 279         {    
 280             if( connection == null ) throw new ArgumentNullException( "connection" );
 281 
 282             // 创建SqlCommand命令,并进行预处理
 283             SqlCommand cmd = new SqlCommand();
 284             bool mustCloseConnection = false;
 285             PrepareCommand(cmd, connection, (SqlTransaction)null, commandType, commandText, commandParameters, out mustCloseConnection );
 286             
 287             // Finally, execute the command
 288             int retval = cmd.ExecuteNonQuery();
 289             
 290             // 清除参数,以便再次使用.
 291             cmd.Parameters.Clear();
 292             if( mustCloseConnection )
 293                 connection.Close();
 294             return retval;
 295         }
 296 
 297         /// <summary>
 298         /// 执行指定数据库连接对象的命令,将对象数组的值赋给存储过程参数.
 299         /// </summary>
 300         /// <remarks>
 301         /// 此方法不提供访问存储过程输出参数和返回值
 302         /// 示例:  
 303         ///  int result = ExecuteNonQuery(conn, "PublishOrders", 24, 36);
 304         /// </remarks>
 305         /// <param name="connection">一个有效的数据库连接对象</param>
 306         /// <param name="spName">存储过程名</param>
 307         /// <param name="parameterValues">分配给存储过程输入参数的对象数组</param>
 308         /// <returns>返回影响的行数</returns>
 309         public static int ExecuteNonQuery(SqlConnection connection, string spName, params object[] parameterValues)
 310         {
 311             if( connection == null ) throw new ArgumentNullException( "connection" );
 312             if( spName == null || spName.Length == 0 ) throw new ArgumentNullException( "spName" );
 313 
 314             // 如果有参数值
 315             if ((parameterValues != null) && (parameterValues.Length > 0)) 
 316             {
 317                 // 从缓存中加载存储过程参数
 318                 SqlParameter[] commandParameters = SqlHelperParameterCache.GetSpParameterSet(connection, spName);
 319 
 320                 // 给存储过程分配参数值
 321                 AssignParameterValues(commandParameters, parameterValues);
 322 
 323                 return ExecuteNonQuery(connection, CommandType.StoredProcedure, spName, commandParameters);
 324             }
 325             else 
 326             {
 327                 return ExecuteNonQuery(connection, CommandType.StoredProcedure, spName);
 328             }
 329         }
 330 
 331         /// <summary>
 332         /// 执行带事务的SqlCommand.
 333         /// </summary>
 334         /// <remarks>
 335         /// 示例.:  
 336         ///  int result = ExecuteNonQuery(trans, CommandType.StoredProcedure, "PublishOrders");
 337         /// </remarks>
 338         /// <param name="transaction">一个有效的数据库连接对象</param>
 339         /// <param name="commandType">命令类型(存储过程,命令文本或其它.)</param>
 340         /// <param name="commandText">存储过程名称或T-SQL语句</param>
 341         /// <returns>返回影响的行数/returns>
 342         public static int ExecuteNonQuery(SqlTransaction transaction, CommandType commandType, string commandText)
 343         {
 344             return ExecuteNonQuery(transaction, commandType, commandText, (SqlParameter[])null);
 345         }
 346 
 347         /// <summary>
 348         /// 执行带事务的SqlCommand(指定参数).
 349         /// </summary>
 350         /// <remarks>
 351         /// 示例:  
 352         ///  int result = ExecuteNonQuery(trans, CommandType.StoredProcedure, "GetOrders", new SqlParameter("@prodid", 24));
 353         /// </remarks>
 354         /// <param name="transaction">一个有效的数据库连接对象</param>
 355         /// <param name="commandType">命令类型(存储过程,命令文本或其它.)</param>
 356         /// <param name="commandText">存储过程名称或T-SQL语句</param>
 357         /// <param name="commandParameters">SqlParamter参数数组</param>
 358         /// <returns>返回影响的行数</returns>
 359         public static int ExecuteNonQuery(SqlTransaction transaction, CommandType commandType, string commandText, params SqlParameter[] commandParameters)
 360         {
 361             if( transaction == null ) throw new ArgumentNullException( "transaction" );
 362             if( transaction != null && transaction.Connection == null ) throw new ArgumentException( "The transaction was rollbacked or commited, please provide an open transaction.", "transaction" );
 363 
 364             // 预处理
 365             SqlCommand cmd = new SqlCommand();
 366             bool mustCloseConnection = false;
 367             PrepareCommand(cmd, transaction.Connection, transaction, commandType, commandText, commandParameters, out mustCloseConnection );
 368                 
 369             // 执行
 370             int retval = cmd.ExecuteNonQuery();
 371                 
 372             // 清除参数集,以便再次使用.
 373             cmd.Parameters.Clear();
 374             return retval;
 375         }
 376 
 377         /// <summary>
 378         /// 执行带事务的SqlCommand(指定参数值).
 379         /// </summary>
 380         /// <remarks>
 381         /// 此方法不提供访问存储过程输出参数和返回值
 382         /// 示例:  
 383         ///  int result = ExecuteNonQuery(conn, trans, "PublishOrders", 24, 36);
 384         /// </remarks>
 385         /// <param name="transaction">一个有效的数据库连接对象</param>
 386         /// <param name="spName">存储过程名</param>
 387         /// <param name="parameterValues">分配给存储过程输入参数的对象数组</param>
 388         /// <returns>返回受影响的行数</returns>
 389         public static int ExecuteNonQuery(SqlTransaction transaction, string spName, params object[] parameterValues)
 390         {
 391             if( transaction == null ) throw new ArgumentNullException( "transaction" );
 392             if( transaction != null && transaction.Connection == null ) throw new ArgumentException( "The transaction was rollbacked or commited, please provide an open transaction.", "transaction" );
 393             if( spName == null || spName.Length == 0 ) throw new ArgumentNullException( "spName" );
 394 
 395             // 如果有参数值
 396             if ((parameterValues != null) && (parameterValues.Length > 0)) 
 397             {
 398                 // 从缓存中加载存储过程参数,如果缓存中不存在则从数据库中检索参数信息并加载到缓存中. ()
 399                 SqlParameter[] commandParameters = SqlHelperParameterCache.GetSpParameterSet(transaction.Connection, spName);
 400 
 401                 // 给存储过程参数赋值
 402                 AssignParameterValues(commandParameters, parameterValues);
 403 
 404                 // 调用重载方法
 405                 return ExecuteNonQuery(transaction, CommandType.StoredProcedure, spName, commandParameters);
 406             }
 407             else 
 408             {
 409                 // 没有参数值
 410                 return