使用 DataReader 检索数据

SqlDataReader 从 SQL 数据库读取仅向前的结果序列。 它不会将完整结果加载到 DataSet 中,因此适合在结果行到达时进行处理。

本文中的示例假定一个名为 connection 的已打开 SqlConnection 指向 AdventureWorks 示例数据库。

C# 示例要求 using Microsoft.Data.SqlClient;。 使用 SqlDbType 或 CommandBehavior 的示例也需要 using System.Data;。

读取行

基本阅读流程如下:

  1. 使用 ExecuteReader 或 ExecuteReaderAsync 执行命令。
  2. 解析当前结果的列序数。
  3. 对每一行调用一次 Read。
  4. 在调用类型化的获取器之前,先使用 IsDBNull 检查可空列。
  5. 在重复使用连接或读取输出参数前,先丢弃读取器。

该示例缓存列序数,使用类型化获取器,并检查可为空的 Color 列:

using var command = new SqlCommand("""
    SELECT ProductID, Name, Color
    FROM Production.Product
    WHERE ProductSubcategoryID = @subcategoryId
    ORDER BY ProductID;
    """, connection);
command.Parameters.Add("@subcategoryId", SqlDbType.Int).Value = 2;

using SqlDataReader reader = command.ExecuteReader();
int idOrdinal = reader.GetOrdinal("ProductID");
int nameOrdinal = reader.GetOrdinal("Name");
int colorOrdinal = reader.GetOrdinal("Color");

while (reader.Read())
{
    int id = reader.GetInt32(idOrdinal);
    string name = reader.GetString(nameOrdinal);
    string? color = reader.IsDBNull(colorOrdinal)
        ? null
        : reader.GetString(colorOrdinal);

    Console.WriteLine($"{id} | {name} | {color ?? "(no color)"}");
}

对 NULL 值调用 GetString 会抛出 SqlNullValueException,因此请先检查 IsDBNull。

HasRows 报告当前结果是否包含行,但通常你可以直接调用 Read 。 对于空结果,第一次 Read 调用返回 false:

using var command = new SqlCommand("""
    SELECT ProductID
    FROM Production.Product
    WHERE ProductID = @productId;
    """, connection);
command.Parameters.Add("@productId", SqlDbType.Int).Value = -1;

using SqlDataReader reader = command.ExecuteReader();
Console.WriteLine($"HasRows: {reader.HasRows}");
Console.WriteLine($"First Read: {reader.Read()}");

对于较大的值,使用CommandBehavior.SequentialAccess执行,并使用GetStream、GetTextReader或GetXmlReader。 更多信息请参见 SqlClient 流支持。

关闭 DataReader

处理完成后立即释放读取器。 即使行处理抛出异常,await using 或 using 语句也会关闭它。

输出参数、输入/输出参数和存储过程返回值在读取器关闭前都不是最终的:

using var command = new SqlCommand("""
    SELECT TOP (5) ProductID, Name
    FROM Production.Product
    ORDER BY ProductID;
    SET @count = @@ROWCOUNT;
    """, connection);

SqlParameter count = command.Parameters.Add("@count", SqlDbType.Int);
count.Direction = ParameterDirection.Output;

using (SqlDataReader reader = command.ExecuteReader())
{
    while (reader.Read())
    {
        Console.WriteLine(reader.GetString(1));
    }
}

Console.WriteLine($"Rows returned: {count.Value}");

如果没有多重激活结果集(MARS),打开的读取器会保持连接忙碌,另一个命令无法在该连接上执行。 启用 MARS 后,单个连接上的独立命令可能有待处理结果,但这些操作仍然不是线程安全的。 更多信息请参见 多个活跃结果集。

如果命令传递了 CommandBehavior.CloseConnection,则关闭读取器也会关闭连接。 否则,开启连接的代码仍负责释放该连接。

读取受影响的行数

RecordsAffected 报告命令中由 INSERT、UPDATE 和 DELETE 语句更改的行。 读取器关闭后再读取它。 本例回滚了更新:

using SqlTransaction transaction = connection.BeginTransaction();
using var command = new SqlCommand("""
    UPDATE Production.Product
    SET ModifiedDate = ModifiedDate
    WHERE ProductID IN (706, 707);

    SELECT ProductID, Name
    FROM Production.Product
    WHERE ProductID IN (706, 707)
    ORDER BY ProductID;
    """, connection, transaction);

SqlDataReader reader = command.ExecuteReader();
using (reader)
{
    while (reader.Read())
    {
        Console.WriteLine($"{reader.GetInt32(0)} | {reader.GetString(1)}");
    }
}

Console.WriteLine($"RecordsAffected: {reader.RecordsAffected}");
transaction.Rollback();

对于仅限 SELECT 的命令,RecordsAffected 为 -1。 SET NOCOUNT ON 抑制计数,也使值保持在 -1。

通过使用 NextResult 检索多个结果集

一个命令或存储过程可以返回多个结果。 完全处理当前结果,然后调用 NextResult 或 NextResultAsync:

using var command = new SqlCommand("""
    SELECT TOP (3) ProductID, Name
    FROM Production.Product
    ORDER BY ProductID;

    SELECT COUNT(*) AS ProductCount
    FROM Production.Product;
    """, connection);

using SqlDataReader reader = command.ExecuteReader();
int result = 1;

do
{
    Console.WriteLine($"Result {result++}: {reader.FieldCount} column(s)");
    while (reader.Read())
    {
        var values = new object[reader.FieldCount];
        reader.GetValues(values);
        Console.WriteLine(string.Join(" | ", values));
    }
}
while (reader.NextResult());

每个结果的列数、名称、序数和类型都可能发生变化。 在true返回NextResult后,重新计算缓存的序数。

同一读卡器一次只能有一个异步操作待处理。 请先等待 ReadAsync、NextResultAsync 或异步字段操作完成,然后再开始对同一读卡器执行另一个操作。

从 DataReader 中获取架构信息

调用 GetColumnSchema 获取当前结果各列的强类型描述。 当现有代码需要在GetSchemaTable中使用该模式时,调用DataTable:

using var command = new SqlCommand("""
    SELECT ProductID, Name, Color
    FROM Production.Product;
    """, connection);

using SqlDataReader reader = command.ExecuteReader(
    CommandBehavior.SchemaOnly);

foreach (System.Data.Common.DbColumn column in reader.GetColumnSchema())
{
    Console.WriteLine(
        $"{column.ColumnOrdinal}: {column.ColumnName} " +
        $"({column.DataTypeName}), nullable={column.AllowDBNull}");
}

CommandBehavior.SchemaOnly 请求无行的列元数据。 架构信息描述当前结果集。 进入下一个结果后再次请求。 根据查询和服务器权限,一些基表元数据可能不可用。