Stream 類別

定義

命名空間:

System.IO

組件:

System.Runtime.dll

來源:

Stream.cs

提供位元組序列的泛型檢視。 這是抽象類。

public ref class Stream abstract : MarshalByRefObject, IAsyncDisposable, IDisposable

public abstract class Stream : MarshalByRefObject, IAsyncDisposable, IDisposable

type Stream = class
    inherit MarshalByRefObject
    interface IAsyncDisposable
    interface IDisposable

Public MustInherit Class Stream
Inherits MarshalByRefObject
Implements IAsyncDisposable, IDisposable

繼承

Object

MarshalByRefObject

Stream

衍生

Microsoft.JScript.COMCharStream

System.Data.OracleClient.OracleBFile

System.Data.OracleClient.OracleLob

System.Data.SqlTypes.SqlFileStream

System.IO.BufferedStream

System.IO.Compression.BrotliStream

System.IO.Compression.DeflateStream

System.IO.Compression.GZipStream

System.IO.Compression.ZLibStream

System.IO.FileStream

System.IO.MemoryStream

System.IO.Pipes.PipeStream

System.IO.UnmanagedMemoryStream

System.Net.Quic.QuicStream

System.Net.Security.AuthenticatedStream

System.Net.Sockets.NetworkStream

System.Printing.PrintQueueStream

System.Security.Cryptography.CryptoStream

實作

IDisposable IAsyncDisposable

範例

下列範例示範如何使用兩個 FileStream 物件，以異步方式將檔案從一個目錄複製到另一個目錄。 FileStream 類別衍生自 Stream 類別。 請注意，Button 控件的 Click 事件處理程式會標示為 async 修飾詞，因為它會呼叫異步方法。

using System;
using System.Threading.Tasks;
using System.Windows;
using System.IO;

namespace WpfApplication
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }

        private async void Button_Click(object sender, RoutedEventArgs e)
        {
            string StartDirectory = @"c:\Users\exampleuser\start";
            string EndDirectory = @"c:\Users\exampleuser\end";

            foreach (string filename in Directory.EnumerateFiles(StartDirectory))
            {
                using (FileStream SourceStream = File.Open(filename, FileMode.Open))
                {
                    using (FileStream DestinationStream = File.Create(EndDirectory + filename.Substring(filename.LastIndexOf('\\'))))
                    {
                        await SourceStream.CopyToAsync(DestinationStream);
                    }
                }
            }
        }
    }
}

Imports System.IO

Class MainWindow

    Private Async Sub Button_Click(sender As Object, e As RoutedEventArgs)
        Dim StartDirectory As String = "c:\Users\exampleuser\start"
        Dim EndDirectory As String = "c:\Users\exampleuser\end"

        For Each filename As String In Directory.EnumerateFiles(StartDirectory)
            Using SourceStream As FileStream = File.Open(filename, FileMode.Open)
                Using DestinationStream As FileStream = File.Create(EndDirectory + filename.Substring(filename.LastIndexOf("\"c)))
                    Await SourceStream.CopyToAsync(DestinationStream)
                End Using

            End Using
        Next
    End Sub

End Class

備註

Stream 是所有數據流的抽象基類。 數據流是位元組序列的抽象概念，例如檔案、輸入/輸出裝置、進程間通訊管道或 TCP/IP 套接字。 Stream 類別及其衍生類別提供這些不同類型的輸入和輸出的泛型檢視，並將程式設計人員與操作系統和基礎裝置的特定詳細數據隔離。

串流牽涉到三個基本作業：

• 您可以從數據流讀取。 讀取是將數據從數據流傳輸到數據結構，例如位元組陣列。

• 您可以寫入資料流。 寫入是將數據從數據結構傳輸到數據流。

• 串流可以支持搜尋。 搜尋是指查詢和修改數據流中目前的位置。 搜尋功能取決於數據流擁有的備份儲存區類型。 例如，網路數據流沒有目前位置的統一概念，因此通常不支持搜尋。

繼承自 Stream 的一些較常用資料流是 FileStream，MemoryStream。

視基礎數據源或存放庫而定，數據流可能只支援其中一些功能。 您可以使用 Stream 類別的 CanRead、CanWrite和 CanSeek 屬性來查詢資料流的功能。

Read 和 Write 方法會以各種格式讀取和寫入數據。 對於支援搜尋的數據流，請使用 Seek 和 SetLength 方法和 Position 和 Length 屬性來查詢和修改數據流目前的位置和長度。

此類型會實作 IDisposable 介面。 當您完成使用類型時，應該直接或間接處置它。 若要直接處置類型，請在 try/catch 區塊中呼叫其 Dispose 方法。 若要間接處置它，請使用語言建構，例如 using （C#） 或 Using （在 Visual Basic 中）。 如需詳細資訊，請參閱 介面主題中的<使用實作 IDisposable 的物件>一節。

處置 Stream 物件會排清任何緩衝的數據，並基本上為您呼叫 Flush 方法。 Dispose 也會釋放操作系統資源，例如檔句柄、網路連線或用於任何內部緩衝的記憶體。 BufferedStream 類別提供將緩衝數據流包裝到另一個數據流的功能，以改善讀取和寫入效能。

從 .NET Framework 4.5 開始，Stream 類別包含異步方法，以簡化異步操作。 異步方法在其名稱中包含 Async，例如 ReadAsync、WriteAsync、CopyToAsync和 FlushAsync。 這些方法可讓您執行耗用大量資源的 I/O 作業，而不會封鎖主要線程。 在 Windows 8.x 市集應用程式或傳統型應用程式中，此效能考慮特別重要，其中耗時的串流作業可能會封鎖 UI 線程，並讓應用程式看起來好像無法運作。 異步方法會與 Visual Basic 和 C# 中的 async 和 await 關鍵詞搭配使用。

在 Windows 8.x 市集應用程式中使用時，Stream 包含兩個擴充方法：AsInputStream 和 AsOutputStream。 這些方法會將 Stream 物件轉換成 Windows 執行時間中的數據流。 您也可以使用 AsStreamForRead 和 AsStreamForWrite 方法，將 Windows 執行時間中的數據流轉換成 Stream 物件。 如需詳細資訊，請參閱 如何：在 .NET Framework 數據流與 Windows 運行時間數據流之間轉換

某些數據流實作會執行基礎數據的本機緩衝，以改善效能。 針對這類數據流，您可以使用 Flush 或 FlushAsync 方法來清除任何內部緩衝區，並確保所有數據都已寫入基礎數據源或存放庫。

如果您需要沒有備份存放區的數據流（也稱為位貯體），請使用 [Null] 字段來擷取專為此目的設計的數據流實例。

給實施者的注意事項

當您實作 Stream的衍生類別時，您必須提供 Read(Byte[], Int32, Int32) 和 Write(Byte[], Int32, Int32) 方法的實作。 異步方法 ReadAsync(Byte[], Int32, Int32)、WriteAsync(Byte[], Int32, Int32)和 CopyToAsync(Stream) 在其實作中使用同步方法 Read(Byte[], Int32, Int32) 和 Write(Byte[], Int32, Int32)。 因此，您的 Read(Byte[], Int32, Int32) 和 Write(Byte[], Int32, Int32) 實作會正確搭配異步方法運作。 ReadByte() 和 WriteByte(Byte) 的預設實作會建立新的單一元素位元組陣列，然後呼叫 Read(Byte[], Int32, Int32) 和 Write(Byte[], Int32, Int32)的實作。 當您衍生自 Stream時，建議您覆寫這些方法來存取內部緩衝區，如果您有這些方法，以大幅提升效能。 您也必須提供 CanRead、CanSeek、CanWrite、Flush()、Length、Position、Seek(Int64, SeekOrigin)和 SetLength(Int64)的實作。

請勿覆寫 Close() 方法，而是將所有 Stream 清除邏輯放在 Dispose(Boolean) 方法中。 如需詳細資訊，請參閱 實作 Dispose 方法。

建構函式

Stream()

初始化 Stream 類別的新實例。

欄位

Null	沒有備份存放區的 Stream。

屬性

CanRead	在衍生類別中覆寫時，取得值，指出目前數據流是否支援讀取。
CanSeek	在衍生類別中覆寫時，取得值，指出目前數據流是否支持搜尋。
CanTimeout	取得值，這個值會判斷目前的數據流是否可以逾時。
CanWrite	在衍生類別中覆寫時，取得值，指出目前數據流是否支援寫入。
Length	在衍生類別中覆寫時，取得數據流的位元組長度。
Position	在衍生類別中覆寫時，取得或設定目前數據流中的位置。
ReadTimeout	取得或設定值，以毫秒為單位，決定數據流在逾時之前嘗試讀取的時間長度。
WriteTimeout	取得或設定值，以毫秒為單位，決定數據流在逾時之前嘗試寫入的時間長度。

方法

BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步讀取作業。 （請考慮改用 ReadAsync(Byte[], Int32, Int32)。
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步寫入作業。 （請考慮改用 WriteAsync(Byte[], Int32, Int32)。
Close()	關閉目前的數據流，並釋放與目前數據流相關聯的任何資源（例如套接字和檔句柄）。 請確定已正確處置數據流，而不是呼叫此方法。
CopyTo(Stream)	從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyTo(Stream, Int32)	從目前的數據流讀取位元組，並使用指定的緩衝區大小將它們寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream)	以異步方式從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream, CancellationToken)	使用指定的取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream, Int32)	使用指定的緩衝區大小，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream, Int32, CancellationToken)	使用指定的緩衝區大小和取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CreateObjRef(Type)	建立物件，其中包含產生用來與遠端物件通訊之 Proxy 所需的所有相關信息。 (繼承來源 MarshalByRefObject)
CreateWaitHandle()	已淘汰. 配置 WaitHandle 物件。
Dispose()	釋放 Stream所使用的所有資源。
Dispose(Boolean)	釋放 Stream 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。
DisposeAsync()	以異步方式釋放 Stream所使用的 Unmanaged 資源。
EndRead(IAsyncResult)	等候暫止的異步讀取完成。 （請考慮改用 ReadAsync(Byte[], Int32, Int32)。
EndWrite(IAsyncResult)	結束異步寫入作業。 （請考慮改用 WriteAsync(Byte[], Int32, Int32)。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Flush()	在衍生類別中覆寫時，清除此數據流的所有緩衝區，並導致任何緩衝的數據寫入基礎裝置。
FlushAsync()	以異步方式清除此數據流的所有緩衝區，並導致任何緩衝的數據寫入基礎裝置。
FlushAsync(CancellationToken)	以異步方式清除此數據流的所有緩衝區、導致任何緩衝的數據寫入基礎裝置，並監視取消要求。
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetLifetimeService()	已淘汰. 擷取控制這個實例存留期原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
InitializeLifetimeService()	已淘汰. 取得存留期服務物件，以控制這個實例的存留期原則。 (繼承來源 MarshalByRefObject)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
MemberwiseClone(Boolean)	建立目前 MarshalByRefObject 對象的淺層複本。 (繼承來源 MarshalByRefObject)
ObjectInvariant()	已淘汰. 提供 Contract的支援。
Read(Byte[], Int32, Int32)	在衍生類別中覆寫時，從目前數據流讀取位元組序列，並將數據流中的位置依讀取的位元組數目往前移。
Read(Span<Byte>)	在衍生類別中覆寫時，從目前數據流讀取位元組序列，並將數據流中的位置依讀取的位元組數目往前移。
ReadAsync(Byte[], Int32, Int32)	以異步方式從目前數據流讀取位元組序列，並依讀取的位元元組數目將數據流中的位置往前移。
ReadAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式從目前數據流讀取位元組序列、依讀取的位元元組數目將數據流中的位置往前移，並監視取消要求。
ReadAsync(Memory<Byte>, CancellationToken)	以異步方式從目前數據流讀取位元組序列、依讀取的位元元組數目將數據流中的位置往前移，並監視取消要求。
ReadAtLeast(Span<Byte>, Int32, Boolean)	從目前數據流讀取至少一個字節數目，並將數據流中的位置依讀取的位元組數目往前移。
ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken)	以異步方式從目前數據流讀取至少一個字節數目、依讀取的位元組數目將數據流中的位置往前移，並監視取消要求。
ReadByte()	從數據流讀取位元組，並在數據流結尾處將數據流中的位置往前移一個字節，或在數據流結尾傳回 -1。
ReadExactly(Byte[], Int32, Int32)	從目前數據流讀取 count 位元組數，並將位置往前移。
ReadExactly(Span<Byte>)	從目前的數據流讀取位元組，並將位置往前移，直到填入 buffer 為止。
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式從目前數據流讀取 count 位元組數目、推進數據流中的位置，以及監視取消要求。
ReadExactlyAsync(Memory<Byte>, CancellationToken)	以異步方式從目前數據流讀取位元組、將數據流中的位置往前移，直到填入 buffer，並監視取消要求。
Seek(Int64, SeekOrigin)	在衍生類別中覆寫時，設定目前數據流中的位置。
SetLength(Int64)	在衍生類別中覆寫時，設定目前數據流的長度。
Synchronized(Stream)	在指定的 Stream 物件周圍建立安全線程的包裝函式。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)
ValidateBufferArguments(Byte[], Int32, Int32)	驗證提供給在 Stream上讀取和寫入方法的自變數。
ValidateCopyToArguments(Stream, Int32)	驗證提供給 CopyTo(Stream, Int32) 或 CopyToAsync(Stream, Int32, CancellationToken) 方法的自變數。
Write(Byte[], Int32, Int32)	在衍生類別中覆寫時，將位元組序列寫入目前數據流，並依寫入的位元組數目將這個數據流中的目前位置往前移。
Write(ReadOnlySpan<Byte>)	在衍生類別中覆寫時，將位元組序列寫入目前數據流，並依寫入的位元組數目將這個數據流中的目前位置往前移。
WriteAsync(Byte[], Int32, Int32)	以異步方式將位元組序列寫入目前數據流，並依寫入的位元元組數目，將這個數據流中的目前位置往前移。
WriteAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式將位元組序列寫入至目前的數據流、依寫入的位元組數目將這個數據流中的目前位置往前移，並監視取消要求。
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	以異步方式將位元組序列寫入至目前的數據流、依寫入的位元組數目將這個數據流中的目前位置往前移，並監視取消要求。
WriteByte(Byte)	將位元組寫入數據流中的目前位置，並將數據流中的位置往前移一個字節。

擴充方法

CopyToAsync(Stream, PipeWriter, CancellationToken)	使用取消標記，以異步方式從 Stream 讀取位元組，並將其寫入指定的 PipeWriter。
ConfigureAwait(IAsyncDisposable, Boolean)	設定如何執行從異步可處置專案傳回的工作等候。

另請參閱

• FileStream
• MemoryStream
• BufferedStream
• 檔案和串流 I/O
• 如何：在 .NET Framework 數據流與 Windows 運行時間數據流之間轉換