Stream.ReadAsync Method

Definition

Namespace:: System.IO

Assemblies:: netstandard.dll, System.Runtime.dll

Assembly:: System.Runtime.dll

Assembly:: netstandard.dll

Assemblies:: mscorlib.dll, System.IO.dll

Assembly:: System.IO.dll

Assembly:: mscorlib.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Overloads

Name	Description
ReadAsync(Memory<Byte>, CancellationToken)	Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.
ReadAsync(Byte[], Int32, Int32)	Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
ReadAsync(Byte[], Int32, Int32, CancellationToken)	Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

ReadAsync(Memory<Byte>, CancellationToken)

Source:: Stream.cs

Source:: Stream.cs

Source:: Stream.cs

Source:: Stream.cs

Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

public virtual System.Threading.Tasks.ValueTask<int> ReadAsync(Memory<byte> buffer, System.Threading.CancellationToken cancellationToken = default);

abstract member ReadAsync : Memory<byte> * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask<int>override this.ReadAsync : Memory<byte> * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask<int>

Public Overridable Function ReadAsync (buffer As Memory(Of Byte), Optional cancellationToken As CancellationToken = Nothing) As ValueTask(Of Integer)

Parameters

buffer: Memory<Byte>

The region of memory to write the data into.

cancellationToken: CancellationToken

The token to monitor for cancellation requests. The default value isNone.

Returns

ValueTask<Int32>

A task that represents the asynchronous read operation. The value of itsResult property contains the total number of bytes read into the buffer. The result value can be less than the length of the buffer if that many bytes are not currently available, or it can be 0 (zero) if the length of the buffer is 0 or if the end of the stream has been reached.

Exceptions

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

Remarks

TheReadAsync method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with theasync andawait keywords in Visual Basic and C#.

Use theCanRead property to determine whether the current instance supports reading.

If the operation is canceled before it completes, the returned task contains theTaskStatus.Canceled value for theStatus property.

For an example, see theReadAsync(Byte[], Int32, Int32) overload.

Applies to

ReadAsync(Byte[], Int32, Int32)

Source:: Stream.cs

Source:: Stream.cs

Source:: Stream.cs

Source:: Stream.cs

Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

public: System::Threading::Tasks::Task<int> ^ ReadAsync(cli::array <System::Byte> ^ buffer, int offset, int count);

public System.Threading.Tasks.Task<int> ReadAsync(byte[] buffer, int offset, int count);

[System.Runtime.InteropServices.ComVisible(false)]public System.Threading.Tasks.Task<int> ReadAsync(byte[] buffer, int offset, int count);

member this.ReadAsync : byte[] * int * int -> System.Threading.Tasks.Task<int>

[<System.Runtime.InteropServices.ComVisible(false)>]member this.ReadAsync : byte[] * int * int -> System.Threading.Tasks.Task<int>

Public Function ReadAsync (buffer As Byte(), offset As Integer, count As Integer) As Task(Of Integer)

Parameters

buffer: Byte[]

The buffer to write the data into.

offset: Int32

The byte offset inbuffer at which to begin writing data from the stream.

count: Int32

The maximum number of bytes to read.

Returns

Task<Int32>

A task that represents the asynchronous read operation. The value of theTResult parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) ifcount is 0 or if the end of the stream has been reached.

Attributes: ComVisibleAttribute

Exceptions

ArgumentNullException

buffer isnull.

ArgumentOutOfRangeException

offset orcount is negative.

ArgumentException

The sum ofoffset andcount is larger than the buffer length.

NotSupportedException

The stream does not support reading.

ObjectDisposedException

The stream has been disposed.

InvalidOperationException

The stream is currently in use by a previous read operation.

Examples

The following example shows how to read from a file asynchronously. The example uses theFileStream class, which derives from theStream class.

using System;using System.Text;using System.Threading.Tasks;using System.Windows;using System.Windows.Controls;using System.IO;namespace WpfApplication1{    public partial class MainWindow : Window    {        public MainWindow()        {            InitializeComponent();        }        private async void Button_Click(object sender, RoutedEventArgs e)        {            string filename = @"c:\Temp\userinputlog.txt";            byte[] result;            using (FileStream SourceStream = File.Open(filename, FileMode.Open))            {                result = new byte[SourceStream.Length];                await SourceStream.ReadAsync(result, 0, (int)SourceStream.Length);            }            UserInput.Text = System.Text.Encoding.ASCII.GetString(result);        }    }}

Imports System.IOImports System.TextClass MainWindow    Private Async Sub Button_Click(sender As Object, e As RoutedEventArgs)        Dim filename As String = "c:\Temp\userinputlog.txt"        Dim result As Byte()        Using SourceStream As FileStream = File.Open(filename, FileMode.Open)            result = New Byte(SourceStream.Length - 1) {}            Await SourceStream.ReadAsync(result, 0, CType(SourceStream.Length, Integer))        End Using        UserInput.Text = System.Text.Encoding.ASCII.GetString(result)    End SubEnd Class

Remarks

Use theCanRead property to determine whether the current instance supports reading.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such asArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown byRead(Byte[], Int32, Int32).

Applies to

ReadAsync(Byte[], Int32, Int32, CancellationToken)

Source:: Stream.cs

Source:: Stream.cs

Source:: Stream.cs

Source:: Stream.cs

Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.

public: virtual System::Threading::Tasks::Task<int> ^ ReadAsync(cli::array <System::Byte> ^ buffer, int offset, int count, System::Threading::CancellationToken cancellationToken);

public virtual System.Threading.Tasks.Task<int> ReadAsync(byte[] buffer, int offset, int count, System.Threading.CancellationToken cancellationToken);

[System.Runtime.InteropServices.ComVisible(false)]public virtual System.Threading.Tasks.Task<int> ReadAsync(byte[] buffer, int offset, int count, System.Threading.CancellationToken cancellationToken);

abstract member ReadAsync : byte[] * int * int * System.Threading.CancellationToken -> System.Threading.Tasks.Task<int>override this.ReadAsync : byte[] * int * int * System.Threading.CancellationToken -> System.Threading.Tasks.Task<int>

[<System.Runtime.InteropServices.ComVisible(false)>]abstract member ReadAsync : byte[] * int * int * System.Threading.CancellationToken -> System.Threading.Tasks.Task<int>override this.ReadAsync : byte[] * int * int * System.Threading.CancellationToken -> System.Threading.Tasks.Task<int>

Public Overridable Function ReadAsync (buffer As Byte(), offset As Integer, count As Integer, cancellationToken As CancellationToken) As Task(Of Integer)