FileStream 類別
定義
重要
部分資訊涉及發行前產品,在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。
為檔案提供 Stream,同時支援同步與非同步讀取和寫入作業。
public ref class FileStream : System::IO::Stream
public class FileStream : System.IO.Stream
[System.Runtime.InteropServices.ComVisible(true)]
public class FileStream : System.IO.Stream
type FileStream = class
inherit Stream
[<System.Runtime.InteropServices.ComVisible(true)>]
type FileStream = class
inherit Stream
Public Class FileStream
Inherits Stream
- 繼承
- 繼承
- 衍生
- 屬性
範例
下列範例示範一些建 FileStream 構函式。
using namespace System;
using namespace System::IO;
using namespace System::Text;
void AddText( FileStream^ fs, String^ value )
{
array<Byte>^info = (gcnew UTF8Encoding( true ))->GetBytes( value );
fs->Write( info, 0, info->Length );
}
int main()
{
String^ path = "c:\\temp\\MyTest.txt";
// Delete the file if it exists.
if ( File::Exists( path ) )
{
File::Delete( path );
}
//Create the file.
{
FileStream^ fs = File::Create( path );
try
{
AddText( fs, "This is some text" );
AddText( fs, "This is some more text," );
AddText( fs, "\r\nand this is on a new line" );
AddText( fs, "\r\n\r\nThe following is a subset of characters:\r\n" );
for ( int i = 1; i < 120; i++ )
{
AddText( fs, Convert::ToChar( i ).ToString() );
//Split the output at every 10th character.
if ( Math::IEEERemainder( Convert::ToDouble( i ), 10 ) == 0 )
{
AddText( fs, "\r\n" );
}
}
}
finally
{
if ( fs )
delete (IDisposable^)fs;
}
}
//Open the stream and read it back.
{
FileStream^ fs = File::OpenRead( path );
try
{
array<Byte>^b = gcnew array<Byte>(1024);
UTF8Encoding^ temp = gcnew UTF8Encoding( true );
while ( fs->Read( b, 0, b->Length ) > 0 )
{
Console::WriteLine( temp->GetString( b ) );
}
}
finally
{
if ( fs )
delete (IDisposable^)fs;
}
}
}
using System;
using System.IO;
using System.Text;
class Test
{
public static void Main()
{
string path = @"c:\temp\MyTest.txt";
// Delete the file if it exists.
if (File.Exists(path))
{
File.Delete(path);
}
//Create the file.
using (FileStream fs = File.Create(path))
{
AddText(fs, "This is some text");
AddText(fs, "This is some more text,");
AddText(fs, "\r\nand this is on a new line");
AddText(fs, "\r\n\r\nThe following is a subset of characters:\r\n");
for (int i=1;i < 120;i++)
{
AddText(fs, Convert.ToChar(i).ToString());
}
}
//Open the stream and read it back.
using (FileStream fs = File.OpenRead(path))
{
byte[] b = new byte[1024];
UTF8Encoding temp = new UTF8Encoding(true);
int readLen;
while ((readLen = fs.Read(b,0,b.Length)) > 0)
{
Console.WriteLine(temp.GetString(b,0,readLen));
}
}
}
private static void AddText(FileStream fs, string value)
{
byte[] info = new UTF8Encoding(true).GetBytes(value);
fs.Write(info, 0, info.Length);
}
}
Imports System.IO
Imports System.Text
Public Class Test
Public Shared Sub Main()
Dim path As String = "c:\temp\MyTest.txt"
' Delete the file if it exists.
If File.Exists(path) Then
File.Delete(path)
End If
'Create the file.
Dim fs As FileStream = File.Create(path)
AddText(fs, "This is some text")
AddText(fs, "This is some more text,")
AddText(fs, Environment.NewLine & "and this is on a new line")
AddText(fs, Environment.NewLine & Environment.NewLine)
AddText(fs, "The following is a subset of characters:" & Environment.NewLine)
Dim i As Integer
For i = 1 To 120
AddText(fs, Convert.ToChar(i).ToString())
Next
fs.Close()
'Open the stream and read it back.
fs = File.OpenRead(path)
Dim b(1023) As Byte
Dim temp As UTF8Encoding = New UTF8Encoding(True)
Do While fs.Read(b, 0, b.Length) > 0
Console.WriteLine(temp.GetString(b))
Loop
fs.Close()
End Sub
Private Shared Sub AddText(ByVal fs As FileStream, ByVal value As String)
Dim info As Byte() = New UTF8Encoding(True).GetBytes(value)
fs.Write(info, 0, info.Length)
End Sub
End Class
下列範例示範如何以非同步方式寫入檔案。 此程式碼會在名為 UserInput 的 TextBlock 的 WPF 應用程式中執行,且按鈕會連結至名為 Button_Click 的 Click 事件處理常式。 檔案路徑必須變更為電腦上存在的檔案。
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)
{
UnicodeEncoding uniencoding = new UnicodeEncoding();
string filename = @"c:\Users\exampleuser\Documents\userinputlog.txt";
byte[] result = uniencoding.GetBytes(UserInput.Text);
using (FileStream SourceStream = File.Open(filename, FileMode.OpenOrCreate))
{
SourceStream.Seek(0, SeekOrigin.End);
await SourceStream.WriteAsync(result, 0, result.Length);
}
}
}
}
Imports System.IO
Imports System.Text
Class MainWindow
Private Async Sub Button_Click(sender As Object, e As RoutedEventArgs)
Dim uniencoding As UnicodeEncoding = New UnicodeEncoding()
Dim filename As String = "c:\Users\exampleuser\Documents\userinputlog.txt"
Dim result As Byte() = uniencoding.GetBytes(UserInput.Text)
Using SourceStream As FileStream = File.Open(filename, FileMode.OpenOrCreate)
SourceStream.Seek(0, SeekOrigin.End)
Await SourceStream.WriteAsync(result, 0, result.Length)
End Using
End Sub
End Class
備註
使用 類別 FileStream 來讀取、寫入、開啟和關閉檔案系統上的檔案,以及操作其他與檔案相關的作業系統控制碼,包括管道、標準輸入和標準輸出。 您可以使用 Read 、 Write 、 CopyTo 和 Flush 方法來執行同步作業,或 ReadAsync 、 WriteAsync 、 CopyToAsync 和 FlushAsync 方法來執行非同步作業。 使用非同步方法來執行耗用大量資源的檔案作業,而不會封鎖主執行緒。 此效能考慮在Windows 8.x 市集應用程式或傳統型應用程式中特別重要,其中耗時的串流作業可能會封鎖 UI 執行緒,並讓您的應用程式顯示為無法運作。 FileStream 緩衝區輸入和輸出,以提升效能。
重要
此型別代表 IDisposable 介面。 當您完成使用型別時,您應該直接或間接處置它。 若要直接處置型別,請呼叫其 try
/catch
區塊中的 Dispose 方法。 若要間接處置它,請使用語言建構函式,例如 using
(在 C# 中) 或 Using
(在 Visual Basic 中)。 如需詳細資訊,請參閱 IDisposable 介面文章中的<使用實作 IDisposable 的物件>一節。
屬性 IsAsync 會偵測檔案控制碼是否以非同步方式開啟。 當您使用具有 isAsync
、 useAsync
或 options
參數的建構函式建立 類別的 FileStream 實例時,可以指定這個值。 當 屬性為 true
時,資料流程會利用重迭的 I/O 以非同步方式執行檔案作業。 不過, IsAsync 屬性不需要 true
呼叫 ReadAsync 、 WriteAsync 或 CopyToAsync 方法。 IsAsync當 屬性是 false
且您呼叫非同步讀取和寫入作業時,UI 執行緒仍然不會遭到封鎖,但實際的 I/O 作業會以同步方式執行。
方法 Seek 支援隨機存取檔案。 Seek 允許將讀取/寫入位置移至檔案中的任何位置。 這是使用位元組位移參考點參數來完成。 位元組位移相對於搜尋參考點,可以是起點、目前位置或基礎檔案的結尾,如列舉的三個成員 SeekOrigin 所表示。
注意
磁片檔案一律支援隨機存取。 在建構時, CanSeek 屬性值會設定為 true
或 false
,視基礎檔案類型而定。 如果基礎檔案類型是FILE_TYPE_DISK,如 winbase.h 中所定義, CanSeek 屬性值為 true
。 否則, CanSeek 屬性值為 false
。
如果進程以鎖定的檔案部分終止,或關閉具有未完成鎖定的檔案,則行為是未定義的。
如需目錄作業和其他檔案作業,請參閱 File 、 Directory 和 Path 類別。 類別 File 是公用程式類別,其具有靜態方法,主要是根據檔案路徑建立 FileStream 物件。 類別 MemoryStream 會從位元組陣列建立資料流程,而且類似于 FileStream 類別。
如需一般檔案和目錄作業的清單,請參閱 一般 I/O 工作。
偵測串流位置變更
FileStream當物件在其控制碼上沒有獨佔保留時,另一個執行緒可以同時存取檔案控制代碼,並變更與檔案控制代碼相關聯的作業系統檔案指標位置。 在此情況下,物件中的 FileStream 快取位置和緩衝區中快取的資料可能會遭到入侵。 物件 FileStream 會定期對存取快取緩衝區的方法執行檢查,以確保作業系統的控制碼位置與 物件所使用的 FileStream 快取位置相同。
如果在呼叫 Read 方法時偵測到控制碼位置的非預期變更,.NET Framework會捨棄緩衝區的內容,然後再次從檔案讀取資料流程。 這可能會影響效能,視檔案大小和可能會影響檔案資料流程位置的任何其他進程而定。
如果在呼叫 Write 方法時偵測到控制碼位置的非預期變更,則會捨棄緩衝區的內容,並 IOException 擲回例外狀況。
FileStream當存取 屬性以公開控制碼或 FileStream 物件在其建構函式中提供 SafeFileHandle 屬性時 SafeFileHandle ,物件在其控制碼上不會有獨佔保留。
建構函式
屬性
CanRead |
取得值,表示目前資料流是否支援讀取。 |
CanSeek |
取得值,表示目前資料流是否支援搜尋。 |
CanTimeout |
取得值,該值判斷目前的資料流是否可以逾時。 (繼承來源 Stream) |
CanWrite |
取得值,表示目前資料流是否支援寫入。 |
Handle |
已過時。
已過時。
已過時。
已過時。
取得目前 |
IsAsync |
取得值,指出 |
Length |
取得資料流的位元組長度。 |
Name |
取得在 |
Position |
取得或設定這個資料流的目前位置。 |
ReadTimeout |
取得或設定值 (以毫秒為單位),該值決定資料流在逾時前將嘗試讀取多長時間。 (繼承來源 Stream) |
SafeFileHandle |
取得 SafeFileHandle 物件,這個物件代表目前的 FileStream 物件封裝之檔案的作業系統檔案控制代碼。 |
WriteTimeout |
取得或設定毫秒值,該值決定在逾時前資料流將嘗試寫入多長時間。 (繼承來源 Stream) |
方法
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) |
開始非同步的讀取作業。 請考慮改用 ReadAsync(Byte[], Int32, Int32, CancellationToken)。 |
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) |
開始非同步的讀取作業。 (請考慮用 ReadAsync(Byte[], Int32, Int32) 替代。) (繼承來源 Stream) |
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object) |
開始非同步的寫入作業。 請考慮改用 WriteAsync(Byte[], Int32, Int32, CancellationToken)。 |
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object) |
開始非同步的寫入作業。 (請考慮用 WriteAsync(Byte[], Int32, Int32) 替代。) (繼承來源 Stream) |
Close() |
關閉目前資料流和釋放與目前資料流相關聯的任何資源 (例如通訊端和檔案控制代碼)。 |
Close() |
關閉目前資料流和釋放與目前資料流相關聯的任何資源 (例如通訊端和檔案控制代碼)。 請確定正確地處置資料流,而非呼叫這個方法。 (繼承來源 Stream) |
CopyTo(Stream) |
從目前資料流讀取位元組,並將其寫入另一個資料流中。 這兩個數據流位置會依複製的位元組數目進階。 (繼承來源 Stream) |
CopyTo(Stream, Int32) |
使用指定的緩衝區大小,從目前資料流讀取所有位元組,並將其寫入另一個資料流中。 這兩個數據流位置會依複製的位元組數目進階。 (繼承來源 Stream) |
CopyToAsync(Stream) |
以非同步的方式從目前資料流讀取所有位元組,並將其寫入另一個資料流中。 這兩個數據流位置會依複製的位元組數目進階。 (繼承來源 Stream) |
CopyToAsync(Stream, CancellationToken) |
使用指定的取消權杖,以非同步的方式從目前資料流讀取位元組,並將其寫入另一個資料流。 這兩個數據流位置會依複製的位元組數目進階。 (繼承來源 Stream) |
CopyToAsync(Stream, Int32) |
使用指定的緩衝區大小,以非同步的方式從目前資料流讀取所有位元組,並將其寫入另一個資料流中。 這兩個數據流位置會依複製的位元組數目進階。 (繼承來源 Stream) |
CopyToAsync(Stream, Int32, CancellationToken) |
使用指定的緩衝區大小和取消語彙基元,以非同步方式從目前檔案資料流讀取位元組,並將其寫入另一個資料流。 |
CopyToAsync(Stream, Int32, CancellationToken) |
使用指定的緩衝區大小和取消語彙基元,以非同步的方式從目前資料流讀取位元組,並將其寫入另一個資料流。 這兩個數據流位置會依複製的位元組數目進階。 (繼承來源 Stream) |
CreateObjRef(Type) |
建立包含所有相關資訊的物件,這些資訊是產生用來與遠端物件通訊的所需 Proxy。 (繼承來源 MarshalByRefObject) |
CreateWaitHandle() |
已過時。
已過時。
已過時。
配置 WaitHandle 物件。 (繼承來源 Stream) |
Dispose() |
釋放 Stream 所使用的所有資源。 (繼承來源 Stream) |
Dispose(Boolean) |
釋放 FileStream 所使用的 Unmanaged 資源,並選擇性地釋放 Managed 資源。 |
DisposeAsync() |
以非同步方式釋放 FileStream 使用的不受控資源。 |
DisposeAsync() |
以非同步方式釋放 Stream 使用的不受控資源。 (繼承來源 Stream) |
EndRead(IAsyncResult) |
等候暫止的非同步讀取作業完成。 (請考慮用 ReadAsync(Byte[], Int32, Int32, CancellationToken) 替代。) |
EndRead(IAsyncResult) |
等候暫止的非同步讀取完成。 (請考慮用 ReadAsync(Byte[], Int32, Int32) 替代。) (繼承來源 Stream) |
EndWrite(IAsyncResult) |
結束非同步寫入作業並封鎖,直到 I/O 作業完成。 (請考慮用 WriteAsync(Byte[], Int32, Int32, CancellationToken) 替代。) |
EndWrite(IAsyncResult) |
結束非同步的寫入作業。 (請考慮用 WriteAsync(Byte[], Int32, Int32) 替代。) (繼承來源 Stream) |
Equals(Object) |
判斷指定的物件是否等於目前的物件。 (繼承來源 Object) |
Finalize() |
確認釋出資源,並在記憶體回收行程再利用 |
Flush() |
清除這個資料流的緩衝區,讓所有緩衝資料全部寫入檔案。 |
Flush(Boolean) |
清除此資料流的緩衝區,讓所有緩衝資料全部寫入檔案,同時也清除所有的中繼檔案緩衝區。 |
FlushAsync() |
以非同步的方式清除這個資料流的所有緩衝區,並造成所有緩衝資料都寫入基礎裝置。 (繼承來源 Stream) |
FlushAsync(CancellationToken) |
以非同步的方式清除這個資料流的所有緩衝區,造成所有緩衝資料都寫入基礎裝置,並且監視取消要求。 |
FlushAsync(CancellationToken) |
以非同步的方式清除這個資料流的所有緩衝區,造成所有緩衝資料都寫入基礎裝置,並且監視取消要求。 (繼承來源 Stream) |
GetAccessControl() |
取得 FileSecurity 物件,該物件會封裝目前 FileStream 物件所描述的檔案之存取控制清單 (ACL) 項目。 |
GetHashCode() |
做為預設雜湊函式。 (繼承來源 Object) |
GetLifetimeService() |
已過時。
擷取控制這個執行個體存留期 (Lifetime) 原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject) |
GetType() |
取得目前執行個體的 Type。 (繼承來源 Object) |
InitializeLifetimeService() |
已過時。
取得存留期服務物件,以控制這個執行個體的存留期原則。 (繼承來源 MarshalByRefObject) |
Lock(Int64, Int64) |
防止其他處理程序讀取或寫入 FileStream。 |
MemberwiseClone() |
建立目前 Object 的淺層複製。 (繼承來源 Object) |
MemberwiseClone(Boolean) |
建立目前 MarshalByRefObject 物件的淺層複本。 (繼承來源 MarshalByRefObject) |
ObjectInvariant() |
已過時。
提供 Contract 的支援。 (繼承來源 Stream) |
Read(Byte[], Int32, Int32) |
從資料流讀取位元組區塊,並將資料寫入指定緩衝區。 |
Read(Span<Byte>) |
從目前的檔案資料流讀取位元組序列,並依讀取的位元組數將檔案資料流中位置往前移。 |
Read(Span<Byte>) |
當在衍生類別中覆寫時,自目前資料流讀取一連串的位元組,並依所讀取的位元組數目進階資料流中的位置。 (繼承來源 Stream) |
ReadAsync(Byte[], Int32, Int32) |
以非同步的方式從目前的資料流讀取位元組序列,並依讀取的位元組數將資料流中的位置往前移。 (繼承來源 Stream) |
ReadAsync(Byte[], Int32, Int32, CancellationToken) |
以非同步方式從目前的檔案資料流讀取位元組序列、將其寫入位元組陣列 (從指定的位移開始)、依讀取的位元組數將檔案資料流中位置往前移,並監視取消要求。 |
ReadAsync(Byte[], Int32, Int32, CancellationToken) |
以非同步的方式從目前資料流讀取一連串的位元組、依所讀取的位元組數目進階資料流中的位置,以及監視取消要求。 (繼承來源 Stream) |
ReadAsync(Memory<Byte>, CancellationToken) |
以非同步方式從目前的檔案資料流讀取位元組序列、將其寫入記憶體區域、依讀取的位元組數將檔案資料流中位置往前移,並監視取消要求。 |
ReadAsync(Memory<Byte>, CancellationToken) |
以非同步的方式從目前資料流讀取一連串的位元組、依所讀取的位元組數目進階資料流中的位置,以及監視取消要求。 (繼承來源 Stream) |
ReadAtLeast(Span<Byte>, Int32, Boolean) |
至少會從目前的資料流程讀取位元組數目,並將資料流程中的位置前移為讀取的位元組數目。 (繼承來源 Stream) |
ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken) |
以非同步方式從目前資料流程讀取至少位元組數目、依讀取的位元組數目將資料流程中的位置往前移,並監視取消要求。 (繼承來源 Stream) |
ReadByte() |
從檔案讀取一個位元組,並將讀取位置前移一個位元組。 |
ReadExactly(Byte[], Int32, Int32) |
|
ReadExactly(Span<Byte>) |
從目前的資料流程讀取位元組,並將資料流程內的位置往前移,直到 |
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken) |
以非同步方式從目前資料流程讀取 |
ReadExactlyAsync(Memory<Byte>, CancellationToken) |
以非同步方式從目前的資料流程讀取位元組、將資料流程內的位置往前移,直到 |
Seek(Int64, SeekOrigin) |
設定這個資料流的目前位置為指定的數值。 |
SetAccessControl(FileSecurity) |
將 FileSecurity 物件所描述的存取控制清單 (ACL) 項目套用至目前 FileStream 物件所描述的檔案。 |
SetLength(Int64) |
設定這個資料流長度為指定的數值。 |
ToString() |
傳回代表目前物件的字串。 (繼承來源 Object) |
Unlock(Int64, Int64) |
允許其他處理序存取先前鎖定之檔案的全部或一部分。 |
Write(Byte[], Int32, Int32) |
將位元組區塊寫入檔案資料流中。 |
Write(ReadOnlySpan<Byte>) |
將位元組序列從唯讀範圍寫入目前的檔案資料流,並依寫入的位元組數將此檔案資料流中目前位置往前移。 |
Write(ReadOnlySpan<Byte>) |
在衍生類別中覆寫時,將一連串的位元組寫入目前的資料流,並且由這個資料流中目前的位置前移寫入的位元組數目。 (繼承來源 Stream) |
WriteAsync(Byte[], Int32, Int32) |
以非同步的方式將位元組序列寫入至目前的資料流,並依寫入的位元組數將資料流中目前的位置往前移。 (繼承來源 Stream) |
WriteAsync(Byte[], Int32, Int32, CancellationToken) |
以非同步的方式將一連串的位元組寫入目前的資料流,由這個資料流中目前的位置前移寫入的位元組數目,並且監視取消要求。 |
WriteAsync(Byte[], Int32, Int32, CancellationToken) |
以非同步的方式將一連串的位元組寫入目前的資料流,由這個資料流中目前的位置前移寫入的位元組數目,並且監視取消要求。 (繼承來源 Stream) |
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken) |
以非同步方式將位元組序列從記憶體區域寫入目前的檔案資料流、依寫入的位元組數將此檔案資料流中目前位置往前移,並監視取消要求。 |
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken) |
以非同步的方式將一連串的位元組寫入目前的資料流,由這個資料流中目前的位置前移寫入的位元組數目,並且監視取消要求。 (繼承來源 Stream) |
WriteByte(Byte) |
寫入一個位元組到檔案資料流中的目前位置。 |
明確介面實作
IDisposable.Dispose() |
釋放 Stream 所使用的所有資源。 (繼承來源 Stream) |
擴充方法
GetAccessControl(FileStream) |
傳回檔案的安全性資訊。 |
SetAccessControl(FileStream, FileSecurity) |
變更現有檔案的安全性屬性。 |
AsInputStream(Stream) |
將適用於 Windows 市集應用程式的 .NET 中的受控資料流轉換成 Windows 執行階段中的輸入資料流。 |
AsOutputStream(Stream) |
將適用於 Windows 市集應用程式的 .NET 中的受控資料流轉換成 Windows 執行階段中的輸出資料流。 |
AsRandomAccessStream(Stream) |
將指定的資料流轉換為隨機存取資料流。 |
ConfigureAwait(IAsyncDisposable, Boolean) |
設定如何執行從非同步可處置項目傳回的工作 await。 |