Stream 類別
定義
重要
部分資訊涉及發行前產品,在發行之前可能會有大幅修改。 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
- 繼承
-
Stream
- 繼承
- 衍生
- 屬性
- 實作
範例
下列範例示範如何使用兩 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。
視基礎數據源或存放庫而定,數據流可能只支援其中一些功能。 您可以使用 類別的 CanReadStream 、 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 Store 應用程式或傳統型應用程式而言特別重要,尤其是針對耗時的資料流作業可能會阻礙 UI 執行緒,使應用程式看起來像是停止運作的情況。 異步方法會與 Visual Basic 和 C# 中的 和 await
關鍵詞搭配async
使用。
在 Windows 8.x Store 應用程式中使用時,Stream包含兩種擴充方法:AsInputStream和 AsOutputStream。 這些方法會將 對象轉換成 Stream Windows 執行階段 中的數據流。 您也可以使用 AsStreamForRead 和 AsStreamForWrite 方法,將 Windows 執行階段 Stream 中的數據流轉換成 物件。 如需詳細資訊,請參閱如何:在 .NET Framework 數據流與 Windows 執行階段 數據流之間轉換
某些數據流實作會執行基礎數據的本機緩衝,以改善效能。 針對這類數據流,您可以使用 Flush 或 FlushAsync 方法來清除任何內部緩衝區,並確保所有數據都已寫入基礎數據源或存放庫。
如果您需要沒有備份存放區的數據流 (也稱為位值區) ,請使用 Null 欄位來擷取專為此用途設計的數據流實例。
給實施者的注意事項
當您實作 的Stream衍生類別時,您必須提供 和 Write(Byte[], Int32, Int32) 方法的Read(Byte[], Int32, Int32)實作。 異步方法、 與您會使用同步方法與 Read(Byte[], Int32, Int32)Write(Byte[], Int32, Int32)CopyToAsync(Stream)WriteAsync(Byte[], Int32, Int32)ReadAsync(Byte[], Int32, Int32) 因此,和的Read(Byte[], Int32, Int32)Write(Byte[], Int32, Int32)實作會使用異步方法正確運作。 和 WriteByte(Byte) 的默認實作ReadByte()會建立新的單一元素位元組陣列,然後呼叫 和Write(Byte[], Int32, Int32)的實作Read(Byte[], Int32, Int32)。 當您衍生自 Stream時,建議您覆寫這些方法來存取內部緩衝區,如果您有內部緩衝區,以大幅提升效能。 您也必須提供、CanSeek、CanWrite、Flush()、Length、Position、 Seek(Int64, SeekOrigin)和 的SetLength(Int64)實作CanRead。
請改為不要覆寫 Close() 方法,將所有清除邏輯放在 Stream 方法中 Dispose(Boolean) 。 如需詳細資訊,請參閱 實作 Dispose 方法。
建構函式
Stream() |
初始化 Stream 類別的新執行個體。 |
欄位
Null |
沒有底層存放區的 |
屬性
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) |
|
ReadExactly(Span<Byte>) |
從目前的數據流讀取位元組,並將該位置往前移,直到 |
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken) |
以異步方式從目前數據流讀取 |
ReadExactlyAsync(Memory<Byte>, CancellationToken) |
以異步方式從目前的數據流讀取位元組、將數據流內的位置往前移,直到 |
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 所使用的所有資源。 |
擴充方法
CopyToAsync(Stream, PipeWriter, CancellationToken) |
使用取消語彙基元,以非同步的方式從 Stream 讀取位元組,並將其寫入指定的 PipeWriter。 |
AsInputStream(Stream) |
將適用於 Windows 市集應用程式的 .NET 中的受控資料流轉換成 Windows 執行階段中的輸入資料流。 |
AsOutputStream(Stream) |
將適用於 Windows 市集應用程式的 .NET 中的受控資料流轉換成 Windows 執行階段中的輸出資料流。 |
AsRandomAccessStream(Stream) |
將指定的資料流轉換為隨機存取資料流。 |
ConfigureAwait(IAsyncDisposable, Boolean) |
設定如何執行從非同步可處置項目傳回的工作 await。 |
適用於
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應