Stream 類別

參考

定義

命名空間:: System.IO

組件:: System.IO.dll

組件:: System.Runtime.dll

組件:: mscorlib.dll

組件:: netstandard.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

提供位元組順序的一般觀點。這是 abstract 類別。

public ref class Stream abstract : IDisposable

public ref class Stream abstract : MarshalByRefObject, IAsyncDisposable, IDisposable

public ref class Stream abstract : MarshalByRefObject, IDisposable

public abstract class Stream : IDisposable

public abstract class Stream : MarshalByRefObject, IAsyncDisposable, IDisposable

public abstract class Stream : MarshalByRefObject, IDisposable

[System.Serializable]
public abstract class Stream : MarshalByRefObject, IDisposable

[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public abstract class Stream : MarshalByRefObject, IDisposable

type Stream = class
    interface IDisposable

type Stream = class
    inherit MarshalByRefObject
    interface IAsyncDisposable
    interface IDisposable

type Stream = class
    inherit MarshalByRefObject
    interface IDisposable

[<System.Serializable>]
type Stream = class
    inherit MarshalByRefObject
    interface IDisposable

[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type Stream = class
    inherit MarshalByRefObject
    interface IDisposable

Public MustInherit Class Stream
Implements IDisposable

Public MustInherit Class Stream
Inherits MarshalByRefObject
Implements IAsyncDisposable, IDisposable

Public MustInherit Class Stream
Inherits MarshalByRefObject
Implements IDisposable

繼承: Object
Stream

繼承: Object

MarshalByRefObject
Stream

衍生: Microsoft.JScript.COMCharStream

System.Data.OracleClient.OracleBFile

System.Data.OracleClient.OracleLob

System.Data.SqlTypes.SqlFileStream

System.IO.BufferedStream

更多…

屬性: SerializableAttribute ComVisibleAttribute

實作: 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 、 CanWrite 和 CanSeek 屬性，查詢資料流程中是否有其功能。

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

此型別代表 IDisposable 介面。當您完成使用型別時，您應該直接或間接處置它。若要直接處置型別，請呼叫其 try/catch 區塊中的 Dispose 方法。若要間接處置它，請使用語言建構函式，例如 using (在 C# 中) 或 Using (在 Visual Basic 中)。如需詳細資訊，請參閱 IDisposable 介面文章中的＜使用實作 IDisposable 的物件＞一節。

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

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

在 Windows 8.x Store 應用程式中使用時， Stream 包含兩個擴充方法： AsInputStream 和 AsOutputStream 。這些方法會將物件轉換成 Stream Windows 執行階段中的資料流程。您也可以使用 AsStreamForRead 和 AsStreamForWrite 方法，將Windows 執行階段 Stream 中的資料流程轉換成物件。如需詳細資訊，請參閱How to： Convert between .NET Framework Streams and Windows 執行階段 Streams

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

如果您需要沒有支援存放區的資料流程 (也稱為位貯體) ，請使用 Null 欄位來擷取專為此目的設計的資料流程實例。

給實施者的注意事項

當您實作的 Stream 衍生類別時，您必須提供和 Write(Byte[], Int32, Int32) 方法的 Read(Byte[], Int32, Int32) 實作。非同步方法 ReadAsync(Byte[], Int32, Int32) 、 WriteAsync(Byte[], Int32, Int32) 和 CopyToAsync(Stream) 會在其實作中使用同步方法 Read(Byte[], Int32, Int32) 。 Write(Byte[], Int32, Int32) 因此，和 Write(Byte[], Int32, Int32) 的 Read(Byte[], Int32, Int32) 實作會正確搭配非同步方法運作。和的預設實作 ReadByte() ，並 WriteByte(Byte) 建立新的單一元素位元組陣列，然後呼叫和 Write(Byte[], Int32, Int32) 的 Read(Byte[], Int32, Int32) 實作。當您衍生自 Stream 時，建議您覆寫這些方法，以存取內部緩衝區，如果您有的話，以大幅提升效能。您也必須提供、 CanSeek 、 CanWrite 、 Flush() 、 Length 、 Position 、 Seek(Int64, SeekOrigin) 和的 CanRead 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 使用的不受控資源。
EndRead(IAsyncResult)	等候暫止的非同步讀取完成。 (請考慮用 ReadAsync(Byte[], Int32, Int32) 替代。)
EndWrite(IAsyncResult)	結束非同步的寫入作業。 (請考慮用 WriteAsync(Byte[], Int32, Int32) 替代。)
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Flush()	當在衍生類別中覆寫時，會清除這個資料流的所有緩衝區，並造成所有緩衝資料都寫入基礎裝置。
FlushAsync()	以非同步的方式清除這個資料流的所有緩衝區，並造成所有緩衝資料都寫入基礎裝置。
FlushAsync(CancellationToken)	以非同步的方式清除這個資料流的所有緩衝區，造成所有緩衝資料都寫入基礎裝置，並且監視取消要求。
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetLifetimeService()	已過時。擷取控制這個執行個體存留期 (Lifetime) 原則的目前存留期服務物件。 (繼承來源 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)	驗證提供給或 CopyToAsync(Stream, Int32, CancellationToken) 方法的 CopyTo(Stream, Int32) 引數。
Write(Byte[], Int32, Int32)	在衍生類別中覆寫時，將一連串的位元組寫入目前的資料流，並且由這個資料流中目前的位置前移寫入的位元組數目。
Write(ReadOnlySpan<Byte>)	在衍生類別中覆寫時，將一連串的位元組寫入目前的資料流，並且由這個資料流中目前的位置前移寫入的位元組數目。
WriteAsync(Byte[], Int32, Int32)	以非同步的方式將位元組序列寫入至目前的資料流，並依寫入的位元組數將資料流中目前的位置往前移。
WriteAsync(Byte[], Int32, Int32, CancellationToken)	以非同步的方式將一連串的位元組寫入目前的資料流，由這個資料流中目前的位置前移寫入的位元組數目，並且監視取消要求。
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	以非同步的方式將一連串的位元組寫入目前的資料流，由這個資料流中目前的位置前移寫入的位元組數目，並且監視取消要求。
WriteByte(Byte)	寫入一個位元組至資料流的目前位置，並將資料流位置推進一個位元組。

明確介面實作

IDisposable.Dispose()

釋放 Stream 所使用的所有資源。

擴充方法

AsInputStream(Stream)	將適用於 Windows 市集應用程式的 .NET 中的受控資料流轉換成 Windows 執行階段中的輸入資料流。
AsOutputStream(Stream)	將適用於 Windows 市集應用程式的 .NET 中的受控資料流轉換成 Windows 執行階段中的輸出資料流。
AsRandomAccessStream(Stream)	將指定的資料流轉換為隨機存取資料流。
ConfigureAwait(IAsyncDisposable, Boolean)	設定如何執行從非同步可處置項目傳回的工作 await。

適用於

Stream 類別

定義

範例

備註

給實施者的注意事項

建構函式

欄位

屬性

方法

明確介面實作

擴充方法

適用於

另請參閱

其他資源