Stream 類別

定義

命名空間:

System.IO

組件:

netstandard.dll, 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.Extensions.AI.HostedFileDownloadStream

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.Compression.ZstandardStream

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.Net.WebSockets.WebSocketStream

System.Printing.PrintQueueStream

System.Security.Cryptography.CryptoStream

實作

IDisposable IAsyncDisposable

範例

以下範例示範如何利用兩個 FileStream 物件非同步地將檔案從一個目錄複製到另一個目錄。 類別 FileStream 衍生自 Stream 類別。 請注意， Click 控件的 Button 事件處理程式會以 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和 。

視基礎數據源或存放庫而定，數據流可能只支援其中一些功能。 你可以利用CanRead類別的 Stream 、 、 CanWriteCanSeek 和 屬性來查詢串流的能力。

Read與Write方法以多種格式讀寫資料。 對於支援尋址的串流，請使用 Seek and SetLength 方法和 and PositionLength 屬性來查詢並修改串流目前的位置與長度。

此類型會實作 IDisposable 介面。 當您完成使用類型時，應該直接或間接處置它。 若要直接處置類型，請在 Disposetry/ 區塊中呼叫其 catch 方法。 若要間接處置它，請使用語言建構，例如 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 線程，並讓應用程式看起來好像無法運作。 非同步方法與 async 和 await 關鍵字搭配使用 Visual Basic 和 C# 中。

當用於 Windows 8.x 商店應用程式時，包含 Stream 兩種擴充方法： AsInputStream 和 AsOutputStream。 這些方法將物件轉換 Stream 成 Windows 執行時的串流。 你也可以在 AsStreamForRead Windows 執行時使用和AsStreamForWrite方法，將串流轉換成Stream物件。 欲了解更多資訊，請參閱 《如何：在 .NET Framework 串流與 Windows 執行環境串流間轉換

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

如果你需要一個沒有後備儲存的串流（也稱為位元桶），可以使用欄位 Null 來擷取專為此目的設計的串流實例。

給實施者的注意事項

當你實作導Stream出類別時，必須提供 和 Write(Byte[], Int32, Int32) 方法的實作Read(Byte[], Int32, Int32)。 非同步方法ReadAsync(Byte[], Int32, Int32)、、、CopyToAsync(Stream)並使用同步方法Read(Byte[], Int32, Int32)及其Write(Byte[], Int32, Int32)實作。 WriteAsync(Byte[], Int32, Int32) 因此，你的 和 Read(Byte[], Int32, Int32)Write(Byte[], Int32, Int32) 實作會與非同步方法正常運作。 預設的 和 實作ReadByte()WriteByte(Byte)建立一個新的單元素位元組陣列，然後呼叫你的實作 Read(Byte[], Int32, Int32)Write(Byte[], Int32, Int32)和 。 當你從 推導出 Stream時，我們建議你覆寫這些方法來存取你的內部緩衝區（如果有的話），以大幅提升效能。 你還必須提供 、 CanSeek、 Seek(Int64, SeekOrigin)CanWriteSetLength(Int64)Flush()PositionLength的實作。CanRead

不要覆寫方法， Close() 而是把所有 Stream 清理邏輯都放進方法裡 Dispose(Boolean) 。 欲了解更多資訊，請參閱 「實施處置方法」。

建構函式

名稱	Description
Stream()	初始化 Stream 類別的新執行個體。

欄位

名稱	Description
Null	Stream A，沒有後備商店。

屬性

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

方法

名稱	Description
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步讀取作業。 （考慮改用 ReadAsync(Byte[], Int32, Int32) 。）
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步寫入作業。 （考慮改用 WriteAsync(Byte[], Int32, Int32) 。）
Close()	關閉目前的數據流，並釋放與目前數據流相關聯的任何資源（例如套接字和檔句柄）。 請確定已正確處置數據流，而不是呼叫此方法。
CopyTo(Stream, Int32)	從目前的數據流讀取位元組，並使用指定的緩衝區大小將它們寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyTo(Stream)	從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream, CancellationToken)	使用指定的取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream, Int32, CancellationToken)	使用指定的緩衝區大小和取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream, Int32)	使用指定的緩衝區大小，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CopyToAsync(Stream)	以異步方式從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。
CreateWaitHandle()	已淘汰. 分配一個 WaitHandle 物件。
Dispose()	釋放所有由 Stream.
Dispose(Boolean)	釋放 未管理的資源， Stream 並可選擇性地釋放受管理資源。
DisposeAsync()	非同步釋放 Stream.
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, CancellationToken)	以異步方式從目前數據流讀取位元組序列、依讀取的位元元組數目將數據流中的位置往前移，並監視取消要求。
ReadAsync(Byte[], Int32, Int32)	以異步方式從目前數據流讀取位元組序列，並依讀取的位元元組數目將數據流中的位置往前移。
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) OR CopyToAsync(Stream, Int32, CancellationToken) 方法的參數。
Write(Byte[], Int32, Int32)	在衍生類別中覆寫時，將位元組序列寫入目前數據流，並依寫入的位元組數目將這個數據流中的目前位置往前移。
Write(ReadOnlySpan<Byte>)	在衍生類別中覆寫時，將位元組序列寫入目前數據流，並依寫入的位元組數目將這個數據流中的目前位置往前移。
WriteAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式將位元組序列寫入至目前的數據流、依寫入的位元組數目將這個數據流中的目前位置往前移，並監視取消要求。
WriteAsync(Byte[], Int32, Int32)	以異步方式將位元組序列寫入目前數據流，並依寫入的位元元組數目，將這個數據流中的目前位置往前移。
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	以異步方式將位元組序列寫入至目前的數據流、依寫入的位元組數目將這個數據流中的目前位置往前移，並監視取消要求。
WriteByte(Byte)	將位元組寫入數據流中的目前位置，並將數據流中的位置往前移一個字節。

擴充方法

名稱	Description
ConfigureAwait(IAsyncDisposable, Boolean)	設定如何執行從異步可處置專案傳回的工作等候。
CopyToAsync(Stream, PipeWriter, CancellationToken)	非同步讀取 的 Stream 位元組並使用消去標記寫入指定的 PipeWriter。

另請參閱

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