Stream.ReadAsync 方法

定義

以非同步的方式從目前的資料流讀取位元組序列,並依讀取的位元組數將資料流中的位置往前移。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)

以非同步的方式從目前資料流讀取一連串的位元組、依所讀取的位元組數目進階資料流中的位置,以及監視取消要求。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.

public:
 virtual System::Threading::Tasks::Task<int> ^ ReadAsync(cli::array <System::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>

參數

buffer
Byte[]

寫入資料的緩衝區。The buffer to write the data into.

offset
Int32

開始於此處自資料流寫入資料的 buffer 中的位元組位移。The byte offset in buffer at which to begin writing data from the stream.

count
Int32

要讀取的最大位元組數。The maximum number of bytes to read.

cancellationToken
CancellationToken

用來監視是否有取消要求的語彙基元。The token to monitor for cancellation requests. 預設值為 NoneThe default value is None.

傳回

表示非同步讀取作業的工作。A task that represents the asynchronous read operation. TResult 參數的值會包含讀取至緩衝區的位元組總數。The value of the TResult parameter contains the total number of bytes read into the buffer. 如果目前可供使用的位元組數目少於所要求的數目,結果值可能會小於所要求的位元組數目,或者如果已經到達資料流末端,則可能為 0 (零)。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) if the end of the stream has been reached.

屬性

例外狀況

buffernullbuffer is null.

offsetcount 為負。offset or count is negative.

offsetcount 的總和大於緩衝區長度。The sum of offset and count is larger than the buffer length.

資料流不支援讀取。The stream does not support reading.

資料流已經處置。The stream has been disposed.

之前的讀取作業目前正在使用資料流。The stream is currently in use by a previous read operation.

備註

ReadAsync方法可讓您執行耗用大量資源的 i/o 作業, 而不會封鎖主執行緒。The ReadAsync method enables you to perform resource-intensive I/O operations without blocking the main thread. 這項效能考量對於 Windows 8.x 市集Windows 8.x Store 應用程式或 桌面desktop 應用程式而言特別重要,尤其是針對耗時的資料流作業可能會阻礙 UI 執行緒,使應用程式看起來像是停止運作的情況。This performance consideration is particularly important in a Windows 8.x 市集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. 非同步方法會與 Visual Basic 和async C#中的和await關鍵字搭配使用。The async methods are used in conjunction with the async and await keywords in Visual Basic and C#.

CanRead使用屬性來判斷目前的實例是否支援讀取。Use the CanRead property to determine whether the current instance supports reading.

如果作業在完成前取消, 則傳回的工作會包含Canceled Status屬性的值。If the operation is canceled before it completes, the returned task contains the Canceled value for the Status property.

如需範例,請參閱ReadAsync(Byte[], Int32, Int32)多載。For an example, see the ReadAsync(Byte[], Int32, Int32) overload.

另請參閱

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.

public virtual System.Threading.Tasks.ValueTask<int> ReadAsync (Memory<byte> buffer, System.Threading.CancellationToken cancellationToken = null);
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>

參數

buffer
Memory<Byte>

要寫入資料的記憶體區域。The region of memory to write the data into.

cancellationToken
CancellationToken

用來監視是否有取消要求的語彙基元。The token to monitor for cancellation requests. 預設值為 NoneThe default value is None.

傳回

表示非同步讀取作業的工作。A task that represents the asynchronous read operation. Result 屬性值包含讀入緩衝區的位元組總數。The value of its Result property contains the total number of bytes read into the buffer. 如果目前無法取得足夠的位元組,則結果值可能小於緩衝區所配置的位元組數,如果已經到達資料流末端,則為 0 (零)。The result value can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or it can be 0 (zero) if the end of the stream has been reached.

備註

ReadAsync方法可讓您執行耗用大量資源的 i/o 作業, 而不會封鎖主執行緒。The ReadAsync method enables you to perform resource-intensive I/O operations without blocking the main thread. 這項效能考量對於 Windows 8.x 市集Windows 8.x Store 應用程式或 桌面desktop 應用程式而言特別重要,尤其是針對耗時的資料流作業可能會阻礙 UI 執行緒,使應用程式看起來像是停止運作的情況。This performance consideration is particularly important in a Windows 8.x 市集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. 非同步方法會與 Visual Basic 和async C#中的和await關鍵字搭配使用。The async methods are used in conjunction with the async and await keywords in Visual Basic and C#.

CanRead使用屬性來判斷目前的實例是否支援讀取。Use the CanRead property to determine whether the current instance supports reading.

如果作業在完成前取消, 則傳回的工作會包含TaskStatus.Canceled Status屬性的值。If the operation is canceled before it completes, the returned task contains the TaskStatus.Canceled value for the Status property.

如需範例,請參閱ReadAsync(Byte[], Int32, Int32)多載。For an example, see the ReadAsync(Byte[], Int32, Int32) overload.

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.

public:
 System::Threading::Tasks::Task<int> ^ ReadAsync(cli::array <System::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>
Public Function ReadAsync (buffer As Byte(), offset As Integer, count As Integer) As Task(Of Integer)

參數

buffer
Byte[]

寫入資料的緩衝區。The buffer to write the data into.

offset
Int32

開始於此處自資料流寫入資料的 buffer 中的位元組位移。The byte offset in buffer at which to begin writing data from the stream.

count
Int32

要讀取的最大位元組數。The maximum number of bytes to read.

傳回

表示非同步讀取作業的工作。A task that represents the asynchronous read operation. TResult 參數的值會包含讀取至緩衝區的位元組總數。The value of the TResult parameter contains the total number of bytes read into the buffer. 如果目前可供使用的位元組數目少於所要求的數目,結果值可能會小於所要求的位元組數目,或者如果已經到達資料流末端,則可能為 0 (零)。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) if the end of the stream has been reached.

屬性

例外狀況

buffernullbuffer is null.

offsetcount 為負。offset or count is negative.

offsetcount 的總和大於緩衝區長度。The sum of offset and count is larger than the buffer length.

資料流不支援讀取。The stream does not support reading.

資料流已經處置。The stream has been disposed.

之前的讀取作業目前正在使用資料流。The stream is currently in use by a previous read operation.

範例

下列範例顯示如何以非同步方式讀取檔案。The following example shows how to read from a file asynchronously. 此範例會使用FileStream衍生Stream自類別的類別。The example uses the FileStream class, which derives from the Stream 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.IO
Imports System.Text

Class 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 Sub
End Class

備註

ReadAsync方法可讓您執行耗用大量資源的 i/o 作業, 而不會封鎖主執行緒。The ReadAsync method enables you to perform resource-intensive I/O operations without blocking the main thread. 這項效能考量對於 Windows 8.x 市集Windows 8.x Store 應用程式或 桌面desktop 應用程式而言特別重要,尤其是針對耗時的資料流作業可能會阻礙 UI 執行緒,使應用程式看起來像是停止運作的情況。This performance consideration is particularly important in a Windows 8.x 市集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. 非同步方法會與 Visual Basic 和async C#中的和await關鍵字搭配使用。The async methods are used in conjunction with the async and await keywords in Visual Basic and C#.

CanRead使用屬性來判斷目前的實例是否支援讀取。Use the CanRead property to determine whether the current instance supports reading.

適用於