SqlDataReader 从 SQL 数据库读取仅向前的结果序列。 它不会将完整结果加载到 DataSet 中,因此适合在结果行到达时进行处理。
本文中的示例假定一个名为 connection 的已打开 SqlConnection 指向 AdventureWorks 示例数据库。
C# 示例要求 using Microsoft.Data.SqlClient;。 使用 SqlDbType 或 CommandBehavior 的示例也需要 using System.Data;。
读取行
基本阅读流程如下:
- 使用
ExecuteReader或ExecuteReaderAsync执行命令。 - 解析当前结果的列序数。
- 对每一行调用一次
Read。 - 在调用类型化的获取器之前,先使用
IsDBNull检查可空列。 - 在重复使用连接或读取输出参数前,先丢弃读取器。
该示例缓存列序数,使用类型化获取器,并检查可为空的 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 请求无行的列元数据。 架构信息描述当前结果集。 进入下一个结果后再次请求。 根据查询和服务器权限,一些基表元数据可能不可用。