SqlDataReader.xml

<docs>
  <members name="SqlDataReader">
    <SqlDataReader>
      <summary>
        Provides a way of reading a forward-only stream of rows from a SQL Server database. This class cannot be inherited.
      </summary>
      <remarks>
        <format type="text/markdown"><![CDATA[  
## Remarks  
To create a <xref:Microsoft.Data.SqlClient.SqlDataReader>, you must call the <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> method of the <xref:Microsoft.Data.SqlClient.SqlCommand> object, instead of directly using a constructor.  

While the <xref:Microsoft.Data.SqlClient.SqlDataReader> is being used, the associated <xref:Microsoft.Data.SqlClient.SqlConnection> is busy serving the <xref:Microsoft.Data.SqlClient.SqlDataReader>, and no other operations can be performed on the <xref:Microsoft.Data.SqlClient.SqlConnection> other than closing it. This is the case until the <xref:Microsoft.Data.SqlClient.SqlDataReader.Close%2A> method of the <xref:Microsoft.Data.SqlClient.SqlDataReader> is called. For example, you cannot retrieve output parameters until after you call <xref:Microsoft.Data.SqlClient.SqlDataReader.Close%2A>.  

Changes made to a result set by another process or thread while data is being read may be visible to the user of the `SqlDataReader`. However, the precise behavior is timing dependent.  

<xref:Microsoft.Data.SqlClient.SqlDataReader.IsClosed%2A> and <xref:Microsoft.Data.SqlClient.SqlDataReader.RecordsAffected%2A> are the only properties that you can call after the <xref:Microsoft.Data.SqlClient.SqlDataReader> is closed. Although the <xref:Microsoft.Data.SqlClient.SqlDataReader.RecordsAffected%2A> property may be accessed while the <xref:Microsoft.Data.SqlClient.SqlDataReader> exists, always call <xref:Microsoft.Data.SqlClient.SqlDataReader.Close%2A> before returning the value of <xref:Microsoft.Data.SqlClient.SqlDataReader.RecordsAffected%2A> to guarantee an accurate return value.  

When using sequential access (<xref:System.Data.CommandBehavior.SequentialAccess?displayProperty=nameWithType>), an <xref:System.InvalidOperationException> will be raised if the <xref:Microsoft.Data.SqlClient.SqlDataReader> position is advanced and another read operation is attempted on the previous column.  

> [!NOTE]
>  For optimal performance, <xref:Microsoft.Data.SqlClient.SqlDataReader> avoids creating unnecessary objects or making unnecessary copies of data. Therefore, multiple calls to methods such as <xref:Microsoft.Data.SqlClient.SqlDataReader.GetValue%2A> return a reference to the same object. Use caution if you are modifying the underlying value of the objects returned by methods such as <xref:Microsoft.Data.SqlClient.SqlDataReader.GetValue%2A>.  

## Examples  
The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection>, a <xref:Microsoft.Data.SqlClient.SqlCommand>, and a <xref:Microsoft.Data.SqlClient.SqlDataReader>. The example reads through the data, writing it out to the console window. The code then closes the <xref:Microsoft.Data.SqlClient.SqlDataReader>. The <xref:Microsoft.Data.SqlClient.SqlConnection> is closed automatically at the end of the `using` code block.  

[!code-csharp[SqlDataReader_Read Example#1](~/../sqlclient/doc/samples/SqlDataReader_Read.cs#1)]

]]></format>
        </remarks>
    </SqlDataReader>
    <Close>
      <summary>
        Closes the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> object.
      </summary>
      <remarks>
        <format type="text/markdown"><![CDATA[  
## Remarks  
You must ensure the <xref:Microsoft.Data.SqlClient.SqlDataReader.Close%2A> method is called when you are through using the <xref:Microsoft.Data.SqlClient.SqlDataReader> before using the associated <xref:Microsoft.Data.SqlClient.SqlConnection> for any other purpose. The `Close` method may either be called directly or through the `Dispose` method, disposing directly or in the context of [the using statement](https://learn.microsoft.com/dotnet/csharp/language-reference/language-specification/statements#the-using-statement) block.

The `Close` method populates the values for output parameters, return values and `RecordsAffected` on the <xref:Microsoft.Data.SqlClient.SqlDataReader> by consuming any pending results. This may be a long operation depending on the amount of data to be consumed. If output values, return values, and `RecordsAffected` are not important to your application, the time to close may be shortened by calling the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method of the associated <xref:Microsoft.Data.SqlClient.SqlCommand> object before the `Close` method is called.

> [!CAUTION]
>  Do not call `Close` or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](https://learn.microsoft.com/dotnet/standard/garbage-collection/).  

## Examples  
The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection>, a <xref:Microsoft.Data.SqlClient.SqlCommand>, and a <xref:Microsoft.Data.SqlClient.SqlDataReader>. The example reads through the data, writing it out to the console window. The code then closes the <xref:Microsoft.Data.SqlClient.SqlDataReader>. The <xref:Microsoft.Data.SqlClient.SqlConnection> is closed automatically at the end of the `using` code block.  

[!code-csharp[SqlDataReader_Close Example#1](~/../sqlclient/doc/samples/SqlDataReader_Close.cs#1)]

]]></format>
        </remarks>
    </Close>
    <Connection>
      <summary>
        Gets the <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> associated with the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </summary>
      <value>
        The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> associated with the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </value>
    </Connection>
    <Depth>
      <summary>
        Gets a value that indicates the depth of nesting for the current row.
      </summary>
      <value>
        The depth of nesting for the current row.
      </value>
      <remarks>
        The outermost table has a depth of zero. The .NET Framework Data Provider for SQL Server does not support nesting and always returns zero.
      </remarks>
    </Depth>
    <Dispose>
      <param name="disposing">
        To be added.
      </param>
      <summary>
        To be added.
      </summary>
      <remarks>
        To be added.
      </remarks>
    </Dispose>
    <FieldCount>
      <summary>
        Gets the number of columns in the current row.
      </summary>
      <value>
        When not positioned in a valid recordset, 0; otherwise the number of columns in the current row. The default is -1.
      </value>
      <remarks>
        Executing a query that, by its nature, does not return rows (such as a DELETE query), sets <see cref="P:Microsoft.Data.SqlClient.SqlDataReader.FieldCount" /> to 0. However. this should not be confused with a query that returns 0 rows (such as <c>SELECT * FROM &lt;table&gt; WHERE 1 = 2</c>) in which case <see cref="P:Microsoft.Data.SqlClient.SqlDataReader.FieldCount" /> returns the number of columns in the table, including hidden fields. Use <see cref="P:Microsoft.Data.SqlClient.SqlDataReader.VisibleFieldCount" /> to exclude hidden fields.
      </remarks>
      <exception cref="T:System.NotSupportedException">
        There is no current connection to an instance of SQL Server.
      </exception>
    </FieldCount>
    <GetBoolean>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a Boolean.
      </summary>
      <returns>
        The value of the column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a Boolean, or an exception is generated.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetBoolean>
    <GetByte>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a byte.
      </summary>
      <returns>
        The value of the specified column as a byte.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a byte.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetByte>
    <GetBytes>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <param name="dataIndex">
        The index within the field from which to begin the read operation.
      </param>
      <param name="buffer">
        The buffer into which to read the stream of bytes.
      </param>
      <param name="bufferIndex">
        The index within the <paramref name="buffer" /> where the write operation is to start.
      </param>
      <param name="length">
        The maximum length to copy into the buffer.
      </param>
      <summary>
        Reads a stream of bytes from the specified column offset into the buffer an array starting at the given buffer offset.
      </summary>
      <returns>
        The actual number of bytes read.
      </returns>
      <remarks>
        <para>
          <b>GetBytes</b> returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if <b>GetBytes</b> has already been used to obtain bytes from the field. This may be the case, for example, if the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is reading a large data structure into a buffer. For more information, see the <see cref="F:System.Data.CommandBehavior.SequentialAccess" /> setting for <see cref="T:System.Data.CommandBehavior" />.
        </para>
        <para>
          If you pass a buffer that is <see langword="null" />, <b>GetBytes</b> returns the length of the entire field in bytes, not the remaining size based on the buffer offset parameter.
        </para>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a byte array.
        </para>
      </remarks>
    </GetBytes>
    <GetChar>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a single character.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        Not supported for <see cref="T:Microsoft.Data.SqlClient" />.
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetChar>
    <GetChars>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <param name="dataIndex">
        The index within the field from which to begin the read operation.
      </param>
      <param name="buffer">
        The buffer into which to read the stream of bytes.
      </param>
      <param name="bufferIndex">
        The index within the <paramref name="buffer" /> where the write operation is to start.
      </param>
      <param name="length">
        The maximum length to copy into the buffer.
      </param>
      <summary>
        Reads a stream of characters from the specified column offset into the buffer as an array starting at the given buffer offset.
      </summary>
      <returns>
        The actual number of characters read.
      </returns>
      <remarks>
        <format type="text/markdown"><![CDATA[  
## Remarks  
<xref:Microsoft.Data.SqlClient.SqlDataReader.GetChars%2A> returns the number of available characters in the field. Frequently this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the <xref:Microsoft.Data.SqlClient.SqlDataReader> is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for <xref:System.Data.CommandBehavior>.  

The actual number of characters read can be less than the requested length, if the end of the field is reached. If you pass a buffer that is `null`, <xref:Microsoft.Data.SqlClient.SqlDataReader.GetChars%2A> returns the length of the entire field in characters, not the remaining size based on the buffer offset parameter.  

No conversions are performed; therefore. the data retrieved must already be a character array.  

> [!NOTE]
>  The <xref:Microsoft.Data.SqlClient.SqlDataReader.GetChars%2A> method returns 0 when `dataIndex` is negative.  

]]></format>
      </remarks>
    </GetChars>
    <GetColumnSchema>
      <summary>
        Gets the read-only column schema collection.
      </summary>
      <returns>
        The read-only column schema collection.
      </returns>
      <remarks>
        This method is an implementation of <see cref="M:System.Data.Common.IDbColumnSchemaGenerator.GetColumnSchema" /> method, which enables the use of the <see cref="T:System.Data.Common.IDbColumnSchemaGenerator" /> interface to populate the <see cref="T:System.Data.Common.DbColumn" /> schema metadata without using a <see cref="T:System.Data.DataTable" />.
      </remarks>
    </GetColumnSchema>
    <GetData>
      <param name="i">
        A column ordinal.
      </param>
      <summary>
        Returns an <see cref="T:System.Data.IDataReader" /> for the specified column ordinal.
      </summary>
      <returns>
        The <see cref="T:System.Data.IDataReader" /> instance for the specified column ordinal.
      </returns>
    </GetData>
    <GetDataTypeName>
      <param name="i">
        The zero-based ordinal position of the column to find.
      </param>
      <summary>
        Gets a string representing the data type of the specified column.
      </summary>
      <returns>
        The string representing the data type of the specified column.
      </returns>
      <remarks>
        Returns the name of the back-end data type. <c>numeric</c> is a synonym in SQL Server for the <c>decimal</c> data type. <b>GetDataTypeName</b> will return "decimal" for a column defined as either decimal or numeric.
      </remarks>
    </GetDataTypeName>
    <GetDateTime>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.DateTime" /> object.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a <see cref="T:System.DateTime" /> object.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetDateTime>
    <GetDateTimeOffset>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Retrieves the value of the specified column as a <see cref="T:System.DateTimeOffset" /> object.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a <see cref="T:System.DateTimeOffset" /> object.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetDateTimeOffset>
    <GetDecimal>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Decimal" /> object.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a <see cref="T:System.Decimal" /> object.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetDecimal>
    <GetDouble>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a double-precision floating point number.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed. Therefore, the data retrieved must already be a double-precision floating point number.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetDouble>
    <GetEnumerator>
      <summary>
        Returns an <see cref="T:System.Collections.IEnumerator" /> that iterates through the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </summary>
      <returns>
        An <see cref="T:System.Collections.IEnumerator" /> for the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </returns>
      <remarks>
        Although you can use this method to retrieve an explicit enumerator, in languages that support a <c>foreach</c> construct, it is simpler to use the looping construct directly in order to iterate through the rows in the data reader.
      </remarks>
    </GetEnumerator>
    <GetFieldType>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the <see cref="T:System.Type" /> that is the data type of the object.
      </summary>
      <returns>
        The <see cref="T:System.Type" /> that is the data type of the object. If the type does not exist on the client, in the case of a User-Defined Type (UDT) returned from the database, <b>GetFieldType</b> returns null.
      </returns>
    </GetFieldType>
    <GetFieldValue>
      <typeparam name="T">
        The type of the value to be returned.
      </typeparam>
      <param name="i">
        The column to be retrieved.
      </param>
      <summary>
        Synchronously gets the value of the specified column as a type. <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetFieldValueAsync``1(System.Int32,System.Threading.CancellationToken)" /> is the asynchronous version of this method.
      </summary>
      <returns>
        The returned type object.
      </returns>
      <remarks>
        <para>
          <typeparamref name="T" /> can be one of the following types:
        </para>
        <list type="bullet">
          <item><description>Boolean (<c>bool</c>)</description></item>
          <item><description>Byte</description></item>
          <item><description>Char</description></item>
          <item><description>DateOnly (.NET 6 or later)</description></item>
          <item><description>DateTime</description></item>
          <item><description>DateTimeOffset</description></item>
          <item><description>Decimal</description></item>
          <item><description>Double</description></item>
          <item><description>Single (<c>float</c>)</description></item>
          <item><description>Guid</description></item>
          <item><description>Int16 (<c>short</c>)</description></item>
          <item><description>Int32 (<c>int</c>)</description></item>
          <item><description>Int64 (<c>long</c>)</description></item>
          <item><description>SqlBoolean</description></item>
          <item><description>SqlByte</description></item>
          <item><description>SqlDateTime</description></item>
          <item><description>SqlDecimal</description></item>
          <item><description>SqlDouble</description></item>
          <item><description>SqlGuid</description></item>
          <item><description>SqlInt16</description></item>
          <item><description>SqlInt32</description></item>
          <item><description>SqlInt64</description></item>
          <item><description>SqlMoney</description></item>
          <item><description>SqlSingle</description></item>
          <item><description>SqlString</description></item>
          <item><description>SqlVector</description></item>
          <item><description>Stream</description></item>
          <item><description>String</description></item>
          <item><description>TextReader</description></item>
          <item><description>TimeOnly (.NET 6 or later)</description></item>
          <item><description>XmlReader</description></item>
          <item><description>UDT, which can be any CLR type marked with <see cref="T:Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute" />.</description></item>
        </list>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support">SqlClient Streaming Support</see>.
        </para>
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>The connection drops or is closed during the data retrieval.</description></item>
          <item><description>The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed during the data retrieval.</description></item>
          <item><description>There is no data ready to be read (for example, the first <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> hasn't been called, or returned false).</description></item>
          <item><description>Tried to read a previously-read column in sequential mode.</description></item>
          <item><description>There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.</description></item>
        </list>
      </exception>
      <exception cref="T:System.IndexOutOfRangeException">
        Trying to read a column that does not exist.
      </exception>
      <exception cref="T:System.Data.SqlTypes.SqlNullValueException">
        The value of the column was null (<see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> == <see langword="true" />), retrieving a non-SQL type.
      </exception>
      <exception cref="T:System.InvalidCastException"><typeparamref name="T" /> doesn't match the type returned by SQL Server or cannot be cast.</exception>
    </GetFieldValue>
    <GetFieldValueAsync>
      <typeparam name="T">
        The type of the value to be returned.
      </typeparam>
      <param name="i">
        The column to be retrieved.
      </param>
      <param name="cancellationToken">
        The cancellation instruction, which propagates a notification that operations should be canceled. This does not guarantee the cancellation. A setting of <see langword="CancellationToken.None" /> makes this method equivalent to <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" />. The returned task must be marked as cancelled.
      </param>
      <summary>
        Asynchronously gets the value of the specified column as a type. <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetFieldValue``1(System.Int32)" /> is the synchronous version of this method.
      </summary>
      <returns>
        The returned type object.
      </returns>
      <remarks>
        <para>
          <typeparamref name="T" /> can be one of the following types:
        </para>
        <list type="bullet">
          <item><description>Boolean (<c>bool</c>)</description></item>
          <item><description>Byte</description></item>
          <item><description>Char</description></item>
          <item><description>DateOnly (.NET 6 or later)</description></item>
          <item><description>DateTime</description></item>
          <item><description>DateTimeOffset</description></item>
          <item><description>Decimal</description></item>
          <item><description>Double</description></item>
          <item><description>Single (<c>float</c>)</description></item>
          <item><description>Guid</description></item>
          <item><description>Int16 (<c>short</c>)</description></item>
          <item><description>Int32 (<c>int</c>)</description></item>
          <item><description>Int64 (<c>long</c>)</description></item>
          <item><description>SqlBoolean</description></item>
          <item><description>SqlByte</description></item>
          <item><description>SqlDateTime</description></item>
          <item><description>SqlDecimal</description></item>
          <item><description>SqlDouble</description></item>
          <item><description>SqlGuid</description></item>
          <item><description>SqlInt16</description></item>
          <item><description>SqlInt32</description></item>
          <item><description>SqlInt64</description></item>
          <item><description>SqlMoney</description></item>
          <item><description>SqlSingle</description></item>
          <item><description>SqlString</description></item>
          <item><description>SqlVector</description></item>
          <item><description>Stream</description></item>
          <item><description>String</description></item>
          <item><description>TextReader</description></item>
          <item><description>TimeOnly (.NET 6 or later)</description></item>
          <item><description>XmlReader</description></item>
          <item><description>UDT, which can be any CLR type marked with <see cref="T:Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute" />.</description></item>
        </list>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support">SqlClient Streaming Support</see>.
        </para>
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>The connection drops or is closed during the data retrieval.</description></item>
          <item><description>The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed during the data retrieval.</description></item>
          <item><description>There is no data ready to be read (for example, the first <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> hasn't been called, or returned false).</description></item>
          <item><description>Tried to read a previously-read column in sequential mode.</description></item>
          <item><description>There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.</description></item>
        </list>
      </exception>
      <exception cref="T:System.IndexOutOfRangeException">
        Trying to read a column that does not exist.
      </exception>
      <exception cref="T:System.Data.SqlTypes.SqlNullValueException">
        The value of the column was null (<see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> == <see langword="true" />), retrieving a non-SQL type.
      </exception>
      <exception cref="T:System.InvalidCastException"><typeparamref name="T" /> doesn't match the type returned by SQL Server or cannot be cast.</exception>
    </GetFieldValueAsync>
    <GetFloat>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a single-precision floating point number.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed. Therefore, the data retrieved must already be a single-precision floating point number.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetFloat>
    <GetGuid>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a globally unique identifier (GUID).
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a GUID.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetGuid>
    <GetInt16>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a 16-bit signed integer.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a 16-bit signed integer.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetInt16>
    <GetInt32>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a 32-bit signed integer.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a 32-bit signed integer.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetInt32>
    <GetInt64>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a 64-bit signed integer.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a 64-bit signed integer.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetInt64>
    <GetName>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the name of the specified column.
      </summary>
      <returns>
        The name of the specified column.
      </returns>
    </GetName>
    <GetOrdinal>
      <param name="name">
        The name of the column.
      </param>
      <summary>
        Gets the column ordinal, given the name of the column.
      </summary>
      <returns>
        The zero-based column ordinal.
      </returns>
      <remarks>
        <para>
          <b>GetOrdinal</b> performs a case-sensitive lookup first. If it fails, a second, case-insensitive search occurs (a case-insensitive comparison is done using the database collation). Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter 'i' in "file". The method throws an <see cref="T:System.IndexOutOfRangeException" /> exception if the zero-based column ordinal is not found. <b>GetOrdinal</b> is kana-width insensitive.
        </para>
        <para>
          Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call <b>GetOrdinal</b> within a loop. Save time by calling <b>GetOrdinal</b> once and assigning the results to an integer variable for use within the loop.
        </para>
      </remarks>
      <example>
        <para>
          The following example demonstrates how to use the <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetOrdinal(System.String)" /> method.
        </para>
        <!-- SqlDataReader_GetOrdinal -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Program
          {
              static void Main()
              {
                  string str = "Data Source=(local);Initial Catalog=Northwind;"
                             + "Integrated Security=SSPI";
                  ReadGetOrdinal(str);
              }
          
              private static void ReadGetOrdinal(string connectionString)
              {
                  string queryString = "SELECT DISTINCT CustomerID FROM dbo.Orders;";
                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      SqlCommand command = new SqlCommand(queryString, connection);
                      connection.Open();
          
                      SqlDataReader reader = command.ExecuteReader();
          
                      // Call GetOrdinal and assign value to variable.
                      int customerID = reader.GetOrdinal("CustomerID");
          
                      // Use variable with GetString inside of loop.
                      while (reader.Read())
                      {
                          Console.WriteLine("CustomerID={0}", reader.GetString(customerID));
                      }
          
                      // Call Close when done reading.
                      reader.Close();
                  }
              }
          }
        </code>
      </example>
      <exception cref="T:System.IndexOutOfRangeException">
        The name specified is not a valid column name.
      </exception>
    </GetOrdinal>
    <GetProviderSpecificFieldType>
      <param name="i">
        An <see cref="T:System.Int32" /> representing the column ordinal.
      </param>
      <summary>
        Gets an <see langword="Object" /> that is a representation of the underlying provider-specific field type.
      </summary>
      <returns>
        Gets an <see cref="T:System.Object" /> that is a representation of the underlying provider-specific field type.
      </returns>
    </GetProviderSpecificFieldType>
    <GetProviderSpecificValue>
      <param name="i">
        An <see cref="T:System.Int32" /> representing the column ordinal.
      </param>
      <summary>
        Gets an <see langword="Object" /> that is a representation of the underlying provider specific value.
      </summary>
      <returns>
        An <see cref="T:System.Object" /> that is a representation of the underlying provider specific value.
      </returns>
    </GetProviderSpecificValue>
    <GetProviderSpecificValues>
      <param name="values">
        An array of <see cref="T:System.Object" /> into which to copy the column values.
      </param>
      <summary>
        Gets an array of objects that are a representation of the underlying provider specific values.
      </summary>
      <returns>
        The array of objects that are a representation of the underlying provider specific values.
      </returns>
    </GetProviderSpecificValues>
    <GetSchemaTable>
      <summary>
        Returns a <see cref="T:System.Data.DataTable" /> that describes the column metadata of the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </summary>
      <returns>
        A <see cref="T:System.Data.DataTable" /> that describes the column metadata.
      </returns>
      <remarks>
        <format type="text/markdown"><![CDATA[  
## Remarks  
The <xref:Microsoft.Data.SqlClient.SqlDataReader.GetSchemaTable%2A> method returns the following metadata about each column:  

|DataReader column|Description|  
|-----------------------|-----------------|  
|AllowDBNull|Set if the consumer can set the column to a null value or if the provider cannot determine whether the consumer can set the column to a null value. Otherwise, not set. A column may contain null values, even if it cannot be set to a null value.|  
|BaseCatalogName|The name of the catalog in the data store that contains the column. NULL if the base catalog name cannot be determined. The default of this column is a null value.|  
|BaseColumnName|The name of the column in the data store. This might be different than the column name returned in the ColumnName column if an alias was used. A null value if the base column name cannot be determined or if the rowset column is derived, but not identical to, a column in the data store. The default of this column is a null value.|  
|BaseSchemaName|The name of the schema in the data store that contains the column. A null value if the base schema name cannot be determined. The default of this column is a null value.|  
|BaseServerName|The name of the instance of Microsoft SQL Server used by the <xref:Microsoft.Data.SqlClient.SqlDataReader>.|  
|BaseTableName|The name of the table or view in the data store that contains the column. A null value if the base table name cannot be determined. The default of this column is a null value.|  
|ColumnName|The name of the column; this might not be unique. If this cannot be determined, a null value is returned. This name always reflects the most recent renaming of the column in the current view or command text.|  
|ColumnOrdinal|The zero-based ordinal of the column. This column cannot contain a null value.|  
|ColumnSize|The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type. For `nvarchar(MAX)`, `varchar(MAX)`, and `varbinary(MAX)` columns stored in a SQL Server database, the maximum size is 2GB. If these columns are stored and accessed as files, the limit on maximum size is imposed by the file system. This value changes when using the `Type System Version` keyword in the connection string.  For new types they are represented as downlevel types. The MAX data types return the normal 4k for `nvarchar` and 8000 for `varchar`. For more information, see the [Transact-SQL reference](https://learn.microsoft.com/sql/t-sql/language-reference).|
|DataTypeName|Returns a string representing the data type of the specified column.|  
|IsAliased|`true`: The column name is an alias.<br /><br /> `false`: The column name is not an alias.|  
|IsAutoIncrement|`true`: The column assigns values to new rows in fixed increments.<br /><br /> `false`: The column does not assign values to new rows in fixed increments. The default of this column is `false`.|  
|IsColumnSet|`true`: The column is a sparse column that is a member of a column set.|  
|IsExpression|`true`: The column is an expression.<br /><br /> `false`: The column is not an expression.|  
|IsHidden|`true`: The column is hidden.<br /><br /> `false`: The column is not hidden.|  
|IsIdentity|`true`: The column is an identity column.<br /><br /> `false`: The column is not an identity column.|  
|IsKey|`true`: The column is one of a set of columns in the rowset that, taken together, uniquely identify the row. The set of columns with `IsKey` set to `true` must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a base table primary key, a unique constraint or a unique index.<br /><br /> `false`: The column is not required to uniquely identify the row.|  
|IsLong|`true`: The column contains a Binary Long Object (BLOB) that contains very long data. The definition of very long data is provider-specific.<br /><br /> `false`: The column does not contain a Binary Long Object (BLOB) that contains very long data.|  
|IsReadOnly|`true`: The column cannot be modified.<br /><br /> `false`: The column can be modified.|  
|IsRowVersion|`true`: The column contains a persistent row identifier that cannot be written to, and has no meaningful value except to identity the row.<br /><br /> `false`: The column does not contain a persistent row identifier that cannot be written to, and has no meaningful value except to identity the row.|  
|IsUnique|`true`: Column is of type `timestamp`.<br /><br /> `false`: Column is not of type `timestamp`.|  
|NonVersionedProviderType|The type of the column irrespective of the current `Type System Version` specified in the connection string. The returned value is from the <xref:System.Data.SqlDbType> enumeration.|  
|NumericPrecision|If `ProviderType` is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. If `ProviderType` is not a numeric data type, this is 255.|  
|NumericScale|If `ProviderType` is DBTYPE_DECIMAL or DBTYPE_NUMERIC, the number of digits to the right of the decimal point. Otherwise, this is 255.|  
|ProviderSpecificDataType|Returns the provider-specific data type of the column based on the `Type System Version` keyword in the connection string.|  
|ProviderType|The indicator of the column's data type. If the data type of the column varies from row to row, this must be Object. This column cannot contain a null value.|  
|UdtAssemblyQualifiedName|If the column is a user-defined type (UDT), this is the qualified name of the UDT's assembly as per <xref:System.Type.AssemblyQualifiedName%2A>. If the column is not a UDT, this is null.|  
|XmlSchemaCollectionDatabase|The name of the database where the schema collection for this XML instance is located, if the row contains information about an XML column. This value is `null` (`Nothing` in Visual Basic) if the collection is defined within the current database. It is also null if there is no schema collection, in which case the `XmlSchemaCollectionName` and `XmlSchemaCollectionOwningSchema` columns are also null.|  
|XmlSchemaCollectionName|The name of the schema collection for this XML instance, if the row contains information about an XML column. This value is `null` (`Nothing` in Visual Basic) if there is no associated schema collection. If the value is null, the `XmlSchemaCollectionDatabase` and `XmlSchemaCollectionOwningSchema` columns are also null.|  
|XmlSchemaCollectionOwningSchema|The owning relational schema where the schema collection for this XML instance is located, if the row contains information about an XML column. This value is `null` (`Nothing` in Visual Basic) if the collection is defined within the current database. It is also null if there is no schema collection, in which case the `XmlSchemaCollectionDatabase` and `XmlSchemaCollectionName` columns are also null.|  

> [!NOTE]
>  To make sure that metadata columns return the correct information, you must call <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data.  

]]></format>
        </remarks>
      <exception cref="T:System.InvalidOperationException">
        The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed.
      </exception>
    </GetSchemaTable>
    <GetSqlBinary>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlBinary" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlBinary" />.
      </returns>
      <remarks>
        No conversions are performed; therefore the data retrieved must already be a binary structure or an exception is generated.
      </remarks>
    </GetSqlBinary>
    <GetSqlBoolean>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlBoolean" />.
      </summary>
      <returns>
        The value of the column.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a Boolean or an exception is generated.
      </remarks>
    </GetSqlBoolean>
    <GetSqlByte>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlByte" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlByte" />.
      </returns>
      <remarks>
        No conversions are performed; therefore the data retrieved must already be a byte, or an exception is generated.
      </remarks>
    </GetSqlByte>
    <GetSqlBytes>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as <see cref="T:System.Data.SqlTypes.SqlBytes" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlBytes" />.
      </returns>
    </GetSqlBytes>
    <GetSqlChars>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as <see cref="T:System.Data.SqlTypes.SqlChars" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlChars" />.
      </returns>
    </GetSqlChars>
    <GetSqlDateTime>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlDateTime" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlDateTime" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a date/time value, or an exception is generated.
      </remarks>
    </GetSqlDateTime>
    <GetSqlDecimal>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlDecimal" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlDecimal" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a decimal value, or an exception is generated.
      </remarks>
    </GetSqlDecimal>
    <GetSqlDouble>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlDouble" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlDouble" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a double-precision floating-point number, or an exception is generated.
      </remarks>
    </GetSqlDouble>
    <GetSqlGuid>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlGuid" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlGuid" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a GUID, or an exception is generated.
      </remarks>
    </GetSqlGuid>
    <GetSqlInt16>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlInt16" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlInt16" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a 16-bit signed integer, or an exception is generated.
      </remarks>
    </GetSqlInt16>
    <GetSqlInt32>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlInt32" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlInt32" />.
      </returns>
      <remarks>
        No conversions are performed; therefore the data retrieved must already be a 32-bit signed integer, or an exception is generated.
      </remarks>
    </GetSqlInt32>
    <GetSqlInt64>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlInt64" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlInt64" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a 64-bit signed integer, or an exception is generated.
      </remarks>
    </GetSqlInt64>
    <GetSqlJson>
      <param name="i"></param>
      <summary>Gets the value of the specified column as a <see cref="T:Microsoft.Data.SqlTypes.SqlJson"/>.</summary>
      <returns>A <see cref="T:Microsoft.Data.SqlTypes.SqlJson"/> object representing the column at the given ordinal.</returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a JSON string, or an exception is generated.
      </remarks>
    </GetSqlJson>
    <GetSqlVector>
      <param name="i"></param>
      <summary>
        Gets the value of the specified column as a <see cref="T:Microsoft.Data.SqlTypes.SqlVector`1"/>.
      </summary>
      <returns>
        A <see cref="T:Microsoft.Data.SqlTypes.SqlVector`1"/> object representing the column at the given ordinal.
      </returns>
      <exception cref="T:System.ArgumentOutOfRangeException">
        The index passed was outside the range of 0 to <see cref="P:System.Data.DataTableReader.FieldCount" /> - 1
      </exception>
      <exception cref="T:System.InvalidOperationException">
        An attempt was made to read or access columns in a closed <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </exception>
      <exception cref="T:System.InvalidCastException">
        The retrieved data is not compatible with the <see cref="T:Microsoft.Data.SqlTypes.SqlVector`1" /> type.
      </exception>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a vector value, or an exception is generated.
      </remarks>
    </GetSqlVector>
    <GetSqlMoney>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlMoney" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlMoney" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a decimal value, or an exception is generated.
      </remarks>
    </GetSqlMoney>
    <GetSqlSingle>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlSingle" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlSingle" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a single precision floating point number, or an exception is generated.
      </remarks>
    </GetSqlSingle>
    <GetSqlString>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a <see cref="T:System.Data.SqlTypes.SqlString" />.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlTypes.SqlString" />.
      </returns>
      <remarks>
        No conversions are performed; therefore, the data retrieved must already be a string, or an exception is generated.
      </remarks>
    </GetSqlString>
    <GetSqlValue>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Returns the data value in the specified column as a SQL Server type.
      </summary>
      <returns>
        The value of the column expressed as a <see cref="T:System.Data.SqlDbType" />.
      </returns>
      <remarks>
        <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetSqlValue(System.Int32)" /> returns data using the native SQL Server types. To retrieve data using the .NET Framework types, see <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetValue(System.Int32)" />.
      </remarks>
    </GetSqlValue>
    <GetSqlValues>
      <param name="values">
        An array of <see cref="T:System.Object" /> into which to copy the values. The column values are expressed as SQL Server types.
      </param>
      <summary>
        Fills an array of <see cref="T:System.Object" /> that contains the values for all the columns in the record, expressed as SQL Server types.
      </summary>
      <returns>
        An integer indicating the number of columns copied.
      </returns>
      <remarks>
        Returns the values for all the columns in the record in a single call, using the SQL type system instead of the CLR type system. The length of the <see cref="T:System.Object" /> array does not need to match the number of columns in the record. You can pass an <see cref="T:System.Object" /> array that contains fewer than the number of columns contained in the record. Only the amount of data the <see cref="T:System.Object" /> array holds is copied to the array, starting at the column with ordinal 0. You can also pass an <see cref="T:System.Object" /> array whose length is more than the number of columns contained in the resulting row. Any remaining columns are untouched.
      </remarks>
      <exception cref="T:System.ArgumentNullException"><paramref name="values" /> is null.</exception>
    </GetSqlValues>
    <GetSqlXml>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as an XML value.
      </summary>
      <returns>
        A <see cref="T:System.Data.SqlTypes.SqlXml" /> value that contains the XML stored within the corresponding field.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be an XML value.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.ArgumentOutOfRangeException">
        The index passed was outside the range of 0 to <see cref="P:System.Data.DataTableReader.FieldCount" /> - 1
      </exception>
      <exception cref="T:System.InvalidOperationException">
        An attempt was made to read or access columns in a closed <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </exception>
      <exception cref="T:System.InvalidCastException">
        The retrieved data is not compatible with the <see cref="T:System.Data.SqlTypes.SqlXml" /> type.
      </exception>
    </GetSqlXml>
    <GetStream>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Retrieves binary, image, varbinary, UDT, and variant data types as a <see cref="T:System.IO.Stream" />.
      </summary>
      <returns>
        A stream object.
      </returns>
      <remarks>
        <para>
          <see cref="P:System.IO.Stream.ReadTimeout" /> defaults to the value of <see cref="P:Microsoft.Data.SqlClient.SqlCommand.CommandTimeout" /> ; but you can modify <see cref="P:System.IO.Stream.ReadTimeout" /> via <b>GetStream</b>.
        </para>
        <para>
          Null values will be returned as an empty (zero bytes) <see cref="T:System.IO.Stream" />. <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetBytes(System.Int32,System.Int64,System.Byte[],System.Int32,System.Int32)" /> will raise an <see cref="T:System.InvalidOperationException" /> exception when used on an object returned by <b>GetStream</b> when <see cref="F:System.Data.CommandBehavior.SequentialAccess" /> is in effect. <see cref="T:Microsoft.Data.SqlClient.SqlException" /> exceptions raised from <see cref="T:System.IO.Stream" /> are thrown as <see cref="T:System.IO.IOException" /> exceptions; check the inner exception for the <see cref="T:Microsoft.Data.SqlClient.SqlException" />.
        </para>
        <para>
          The following <see cref="T:System.IO.Stream" /> members are not available for objects returned by <b>GetStream</b>:
        </para>
        <list type="bullet">
          <item><description>BeginWrite</description></item>
          <item><description>EndWrite</description></item>
          <item><description>Length</description></item>
          <item><description>Position</description></item>
          <item><description>Seek</description></item>
          <item><description>SetLength</description></item>
          <item><description>Write</description></item>
          <item><description>WriteByte</description></item>
          <item><description>WriteTimeout</description></item>
        </list>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support">SqlClient Streaming Support</see>
        </para>
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>The connection drops or is closed during the data retrieval.</description></item>
          <item><description>The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed during the data retrieval.</description></item>
          <item><description>There is no data ready to be read (for example, the first <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> hasn't been called, or returned false).</description></item>
          <item><description>Tried to read a previously-read column in sequential mode.</description></item>
          <item><description>There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.</description></item>
        </list>
      </exception>
      <exception cref="T:System.IndexOutOfRangeException">
        Trying to read a column that does not exist.
      </exception>
      <exception cref="T:System.InvalidCastException">
        <para>
          The returned type was not one of the types below:
        </para>
        <list type="bullet">
          <item><description>binary</description></item>
          <item><description>image</description></item>
          <item><description>varbinary</description></item>
          <item><description>udt</description></item>
        </list>
      </exception>
    </GetStream>
    <GetString>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column as a string.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a string.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetString>
    <GetTextReader>
      <param name="i">
        The column to be retrieved.
      </param>
      <summary>
        Retrieves Char, NChar, NText, NVarChar, text, varChar, and Variant data types as a <see cref="T:System.IO.TextReader" />.
      </summary>
      <returns>
        The returned object.
      </returns>
      <remarks>
        <para>
          <see cref="T:Microsoft.Data.SqlClient.SqlException" /> exceptions raised from <see cref="T:System.IO.TextReader" /> are thrown as <see cref="T:System.IO.IOException" /> exceptions; check the inner exception for the <see cref="T:Microsoft.Data.SqlClient.SqlException" />.
        </para>
        <para>
          Null values will be returned as an empty (zero bytes) <see cref="T:System.IO.TextReader" />. <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetChars(System.Int32,System.Int64,System.Char[],System.Int32,System.Int32)" /> will raise an <see cref="T:System.InvalidOperationException" /> exception when used on an object returned by <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetTextReader(System.Int32)" /> when <see cref="F:System.Data.CommandBehavior.SequentialAccess" /> is in effect.
        </para>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support">SqlClient Streaming Support</see>.
        </para>
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>The connection drops or is closed during the data retrieval.</description></item>
          <item><description>The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed during the data retrieval.</description></item>
          <item><description>There is no data ready to be read (for example, the first <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> hasn't been called, or returned false).</description></item>
          <item><description>Tried to read a previously-read column in sequential mode.</description></item>
          <item><description>There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.</description></item>
        </list>         
      </exception>
      <exception cref="T:System.IndexOutOfRangeException">
        Trying to read a column that does not exist.
      </exception>
      <exception cref="T:System.InvalidCastException">
        <para>The returned type was not one of the types below:</para>
        <list type="bullet">
          <item><description>char</description></item>
          <item><description>nchar</description></item>
          <item><description>ntext</description></item>
          <item><description>nvarchar</description></item>
          <item><description>text</description></item>
          <item><description>varchar</description></item>
        </list>
      </exception>
    </GetTextReader>
    <GetTimeSpan>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Retrieves the value of the specified column as a <see cref="T:System.TimeSpan" /> object.
      </summary>
      <returns>
        The value of the specified column.
      </returns>
      <remarks>
        <para>
          No conversions are performed; therefore, the data retrieved must already be a <see cref="T:System.TimeSpan" /> object.
        </para>
        <para>
          Call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" /> to check for null values before calling this method.
        </para>
      </remarks>
      <exception cref="T:System.InvalidCastException">
        The specified cast is not valid.
      </exception>
    </GetTimeSpan>
    <GetValue>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column in its native format.
      </summary>
      <returns>
        This method returns <see cref="T:System.DBNull" /> for null database columns.
      </returns>
      <remarks>
        <b>GetValue</b> returns data using the .NET Framework types.
      </remarks>
    </GetValue>
    <GetValues>
      <param name="values">
        An array of <see cref="T:System.Object" /> into which to copy the attribute columns.
      </param>
      <summary>
        Populates an array of objects with the column values of the current row.
      </summary>
      <returns>
        The number of instances of <see cref="T:System.Object" /> in the array.
      </returns>
      <remarks>
        <para>
          For most applications, this method provides an efficient means for retrieving all columns, instead of retrieving each column individually.
        </para>
        <para>
          You can pass an <see cref="T:System.Object" /> array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the <see cref="T:System.Object" /> array holds is copied to the array. You can also pass an <see cref="T:System.Object" /> array whose length is more than the number of columns contained in the resulting row.
        </para>
        <para>
          This method returns <see cref="T:System.DBNull" /> for null database columns.
        </para>
      </remarks>
      <example>
        <para>
          The following example demonstrates using a correctly sized  array  to read all values from the current row in the supplied <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />. In addition, the sample demonstrates using a fixed-sized array that could be either smaller or larger than the number of available columns.
        </para>
        <!-- DataTableReader_GetValues #2 -->
        <code language="c#">
          // using Microsoft.Data.SqlClient;
          private static void TestGetValues(SqlDataReader reader)
          {
              // Given a SqlDataReader, use the GetValues
              // method to retrieve a full row of data.
              // Test the GetValues method, passing in an array large
              // enough for all the columns.
              Object[] values = new Object[reader.FieldCount];
              int fieldCount = reader.GetValues(values);
      
              Console.WriteLine("reader.GetValues retrieved {0} columns.",
                  fieldCount);
              for (int i = 0; i &lt; fieldCount; i++)
              {
                  Console.WriteLine(values[i]);
              }
      
              Console.WriteLine();
      
              // Now repeat, using an array that may contain a different 
              // number of columns than the original data. This should work correctly,
              // whether the size of the array is larger or smaller than 
              // the number of columns.
      
              // Attempt to retrieve three columns of data.
              values = new Object[3];
              fieldCount = reader.GetValues(values);
              Console.WriteLine("reader.GetValues retrieved {0} columns.", fieldCount);
              for (int i = 0; i &lt; fieldCount; i++)
              {
                  Console.WriteLine(values[i]);
              }
          }
        </code>
      </example>
    </GetValues>
    <GetXmlReader>
      <param name="i">
        The value of the specified column.
      </param>
      <summary>
        Retrieves data of type XML as an <see cref="T:System.Xml.XmlReader" />.
      </summary>
      <returns>
        The returned object.
      </returns>
      <remarks>
        <para>
          The <see cref="T:System.Xml.XmlReader" /> object returned by <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetXmlReader(System.Int32)" /> does not support asynchronous operations. If you require asynchronous operations on an <see cref="T:System.Xml.XmlReader" />, cast the XML column to an NVARCHAR(MAX) on the server and use <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetTextReader(System.Int32)" /> with <see cref="M:System.Xml.XmlReader.Create(System.IO.TextReader)" />. <see cref="T:Microsoft.Data.SqlClient.SqlException" /> exceptions raised from <see cref="T:System.Xml.XmlReader" /> are thrown as <see cref="T:System.Xml.XmlException" /> exceptions; check the inner exception for the <see cref="T:Microsoft.Data.SqlClient.SqlException" />. <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetChars(System.Int32,System.Int64,System.Char[],System.Int32,System.Int32)" /> will raise an <see cref="T:System.InvalidOperationException" /> exception when used on an object returned by <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetXmlReader(System.Int32)" /> when <see cref="F:System.Data.CommandBehavior.SequentialAccess" /> is in effect.
        </para>
        <para>
          For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support">SqlClient Streaming Support</see>.
        </para>
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>The connection drops or is closed during the data retrieval.</description></item>
          <item><description>The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed during the data retrieval.</description></item>
          <item><description>There is no data ready to be read (for example, the first <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> hasn't been called, or returned false).</description></item>
          <item><description>Trying to read a previously read column in sequential mode.</description></item>
          <item><description>There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.</description></item>
        </list>         
      </exception>
      <exception cref="T:System.IndexOutOfRangeException">
        Trying to read a column that does not exist.
      </exception>
      <exception cref="T:System.InvalidCastException">
        The returned type was not xml.
      </exception>
    </GetXmlReader>
    <HasRows>
      <summary>
        Gets a value that indicates whether the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> contains one or more rows.
      </summary>
      <value><see langword="true" /> if the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> contains one or more rows; otherwise <see langword="false" />.
      </value>
    </HasRows>
    <IsClosed>
      <summary>
        Retrieves a Boolean value that indicates whether the specified <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> instance has been closed.
      </summary>
      <value>
        <see langword="true" /> if the specified <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> instance is closed; otherwise <see langword="false" />.
      </value>
      <remarks>
        It is not possible to read from a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> instance that is closed.
      </remarks>
    </IsClosed>
    <IsCommandBehavior>
      <param name="condition">
        A <see cref="T:System.Data.CommandBehavior" /> enumeration.
      </param>
      <summary>
        Determines whether the specified <see cref="T:System.Data.CommandBehavior" /> matches that of the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </summary>
      <returns>
        <see langword="true" /> if the specified <see cref="T:System.Data.CommandBehavior" /> is true, <see langword="false" /> otherwise.
      </returns>
      <remarks>
        This member supports the .NET Framework infrastructure and is not intended to be used directly from your code.
      </remarks>
    </IsCommandBehavior>
    <IsDBNull>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets a value that indicates whether the column contains non-existent or missing values.
      </summary>
      <returns>
        <see langword="true" /> if the specified column value is equivalent to <see cref="T:System.DBNull" /> ; otherwise <see langword="false" />.
      </returns>
      <remarks>
        Call this method to check for null column values before calling the typed get methods (for example, <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetByte(System.Int32)" />, <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.GetChar(System.Int32)" />, and so on) to avoid raising an error.
      </remarks>
      <example>
        <!-- SqlDataReader_IsDBNull -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;
          
          class Program
          {
              static void Main(string[] args)
              {
                  using (var connection = new SqlConnection(@"Data Source=(local);Initial Catalog=AdventureWorks2012;Integrated Security=SSPI"))
                  {
                      var command = new SqlCommand("SELECT p.FirstName, p.MiddleName, p.LastName FROM HumanResources.Employee AS e" +
                                              " JOIN Person.Person AS p ON e.BusinessEntityID = p.BusinessEntityID;", connection);
                      connection.Open();
                      var reader = command.ExecuteReader();
                      while (reader.Read())
                      {
                          Console.Write(reader.GetString(reader.GetOrdinal("FirstName")));
                          // display middle name only of not null
                          if (!reader.IsDBNull(reader.GetOrdinal("MiddleName")))
                          {
                              Console.Write(" {0}", reader.GetString(reader.GetOrdinal("MiddleName")));
                          }
                          Console.WriteLine(" {0}", reader.GetString(reader.GetOrdinal("LastName")));
                      }
                      connection.Close();
                  }
              }
          }
        </code>
      </example>
    </IsDBNull>
    <IsDBNullAsync>
      <param name="i">
        The zero-based column to be retrieved.
      </param>
      <param name="cancellationToken">
        The cancellation instruction, which propagates a notification that operations should be canceled. This does not guarantee the cancellation. A setting of <see langword="CancellationToken.None" /> makes this method equivalent to <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" />. The returned task must be marked as cancelled.
      </param>
      <summary>
        <para>
          An asynchronous version of <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.IsDBNull(System.Int32)" />, which gets a value that indicates whether the column contains non-existent or missing values.
        </para>
        <para>
          The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object.
        </para>
      </summary>
      <returns><see langword="true" /> if the specified column value is equivalent to <see langword="DBNull" /> otherwise <see langword="false" />.</returns>
      <remarks>
        For more information, see <see href="https://learn.microsoft.com/sql/connect/ado-net/sqlclient-streaming-support">SqlClient Streaming Support</see>.
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        <list type="bullet">
          <item><description>The connection drops or is closed during the data retrieval.</description></item>
          <item><description>The <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed during the data retrieval.</description></item>
          <item><description>There is no data ready to be read (for example, the first <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> hasn't been called, or returned false).</description></item>
          <item><description>Trying to read a previously read column in sequential mode.</description></item>
          <item><description>There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.</description></item>
        </list>         
      </exception>
      <exception cref="T:System.IndexOutOfRangeException">
        Trying to read a column that does not exist.
      </exception>
    </IsDBNullAsync>
    <ItemI>
      <param name="i">
        The zero-based column ordinal.
      </param>
      <summary>
        Gets the value of the specified column in its native format given the column ordinal.
      </summary>
      <value>
        The value of the specified column in its native format.
      </value>
      <exception cref="T:System.IndexOutOfRangeException">
        The index passed was outside the range of 0 through <see cref="P:System.Data.IDataRecord.FieldCount" />.
      </exception>
    </ItemI>
    <ItemName>
      <param name="name">
        The column name.
      </param>
      <summary>
        Gets the value of the specified column in its native format given the column name.
      </summary>
      <value>
        The value of the specified column in its native format.
      </value>
      <remarks>
        <para>
          A case-sensitive lookup is performed first. If it fails, a second case-insensitive search is made (a case-insensitive comparison is done using the database collation). Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter 'i' in "file".
        </para>
        <para>
          This method is kana-width insensitive.
        </para>
      </remarks>
      <exception cref="T:System.IndexOutOfRangeException">
        No column with the specified name was found.
      </exception>
    </ItemName>
    <NextResult>
      <summary>
        Advances the data reader to the next result, when reading the results of batch Transact-SQL statements.
      </summary>
      <returns><see langword="true" /> if there are more result sets; otherwise <see langword="false" />.</returns>
      <remarks>
        <para>
          Used to process multiple results, which can be generated by executing batch Transact-SQL statements.
        </para>
        <para>
          By default, the data reader is positioned on the first result.
        </para>
      </remarks>
    </NextResult>
    <NextResultAsync>
      <param name="cancellationToken">
        The cancellation instruction.
      </param>
      <summary>
        <para>
          An asynchronous version of <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.NextResult" />, which advances the data reader to the next result, when reading the results of batch Transact-SQL statements.
        </para>
        <para>
          The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object.
        </para>
      </summary>
      <returns>
        A task representing the asynchronous operation.
      </returns>
      <remarks>
        For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see <see href="https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming">Asynchronous Programming</see>.
      </remarks>
      <exception cref="T:System.InvalidOperationException">
        Calling <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.NextResultAsync(System.Threading.CancellationToken)" /> more than once for the same instance before task completion.
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        SQL Server returned an error while executing the command text.
      </exception>
    </NextResultAsync>
    <Read>
      <summary>
        Advances the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> to the next record.
      </summary>
      <returns><see langword="true" /> if there are more rows; otherwise <see langword="false" /></returns>
      <remarks>
        <para>
          The default position of the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is before the first record. Therefore, you must call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" /> to begin accessing any data.
        </para>
        <para>
          Only one <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> per associated <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> may be open at a time, and any attempt to open another will fail until the first one is closed. Similarly, while the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is being used, the associated <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> is busy serving it until you call <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Close" />.
        </para>
      </remarks>
      <example>
        <para>
          The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlConnection" />, a <see cref="T:Microsoft.Data.SqlClient.SqlCommand" />, and a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />. The example reads through the data, writing it out to the console window. The code then closes the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />. The <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> is closed automatically at the end of the <c>using</c> code block.
        </para>
        <!-- SqlDataReader_Read -->
        <code language="c#">
          using System;
          using System.Data;
          using Microsoft.Data.SqlClient;

          class Program
          {
              static void Main()
              {
                  string str = "Data Source=(local);Initial Catalog=Northwind;"
                             + "Integrated Security=SSPI";
                  ReadOrderData(str);
              }

              private static void ReadOrderData(string connectionString)
              {
                  string queryString = "SELECT OrderID, CustomerID FROM dbo.Orders;";

                  using (SqlConnection connection = new SqlConnection(connectionString))
                  {
                      SqlCommand command = new SqlCommand(queryString, connection);
                      connection.Open();

                      SqlDataReader reader = command.ExecuteReader();

                      // Call Read before accessing data.
                      while (reader.Read())
                      {
                          ReadSingleRow((IDataRecord)reader);
                      }

                      // Call Close when done reading.
                      reader.Close();
                  }
              }

              private static void ReadSingleRow(IDataRecord record)
              {
                  Console.WriteLine(String.Format("{0}, {1}", record[0], record[1]));
              }
          }
        </code>
      </example>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        SQL Server returned an error while executing the command text.
      </exception>
    </Read>
    <ReadAsync>
      <param name="cancellationToken">
        The cancellation instruction.
      </param>
      <summary>
        <para>
          An asynchronous version of <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.Read" />, which advances the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> to the next record.
        </para>
        <para>
          The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object.
        </para>
      </summary>
      <returns>
        A task representing the asynchronous operation.
      </returns>
      <remarks>
        <format type="text/markdown"><![CDATA[  
## Remarks  
If the `behavior` parameter of <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync%2A> is set to `Default`, <xref:Microsoft.Data.SqlClient.SqlDataReader.ReadAsync%2A> reads the entire row before returning the Task.  

For more information, including code samples, about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](https://learn.microsoft.com/sql/connect/ado-net/asynchronous-programming).  

> [!NOTE]
>  When reading large data (binary/text), it is recommended to use <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> for optimal performance.

]]></format>
        </remarks>
      <exception cref="T:System.InvalidOperationException">
        Calling <see cref="M:Microsoft.Data.SqlClient.SqlDataReader.ReadAsync(System.Threading.CancellationToken)" /> more than once for the same instance before task completion.
      </exception>
      <exception cref="T:Microsoft.Data.SqlClient.SqlException">
        SQL Server returned an error while executing the command text.
      </exception>
    </ReadAsync>
    <RecordsAffected>
      <summary>
        Gets the number of rows changed, inserted, or deleted by execution of the Transact-SQL statement.
      </summary>
      <value>
        The number of rows changed, inserted, or deleted; 0 if no rows were affected or the statement failed; and -1 for SELECT statements.
      </value>
      <remarks>
        The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of <c>RecordsAffected</c> will be two. <see cref="P:Microsoft.Data.SqlClient.SqlDataReader.IsClosed" /> and <see cref="P:Microsoft.Data.SqlClient.SqlDataReader.RecordsAffected" /> are the only properties that you can call after the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> is closed.
      </remarks>
    </RecordsAffected>
    <SensitivityClassification>
      <summary>
        Gets the <see cref="T:Microsoft.Data.SqlClient.DataClassification.SensitivityClassification" /> information with the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </summary>
      <value>
        The <see cref="T:Microsoft.Data.SqlClient.DataClassification.SensitivityClassification" /> associated with the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" />.
      </value>
    </SensitivityClassification>
    <System.Data.IDataRecord.GetData>
      <param name="i">
        A column ordinal.
      </param>
      <summary>
        Returns an <see cref="T:System.Data.IDataReader" /> for the specified column ordinal.
      </summary>
      <returns>
        The <see cref="T:System.Data.IDataReader" /> instance for the specified column ordinal.
      </returns>
      <remarks>
        This member is an explicit interface member implementation. It can be used only when the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> instance is cast to an <see cref="T:System.Data.IDataRecord" /> interface.
      </remarks>
    </System.Data.IDataRecord.GetData>
    <VisibleFieldCount>
      <summary>
        Gets the number of fields in the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> that are not hidden.
      </summary>
      <value>
        The number of fields that are not hidden.
      </value>
      <remarks>
        This value is used to determine how many fields in the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> are visible. For example, a SELECT on a partial primary key returns the remaining parts of the key as hidden fields. The hidden fields are always appended behind the visible fields.
      </remarks>
    </VisibleFieldCount>
  </members>
</docs>