FileStream 類別

定義

命名空間:

System.IO

組件:

netstandard.dll, System.Runtime.dll

來源:

FileStream.cs

提供檔案 的 A Stream ，支援同步與非同步讀寫操作。

public ref class FileStream : System::IO::Stream

public class FileStream : System.IO.Stream

type FileStream = class
    inherit Stream

Public Class FileStream
Inherits Stream

繼承

Object

MarshalByRefObject

Stream

FileStream

衍生

System.IO.IsolatedStorage.IsolatedStorageFileStream

範例

以下範例展示了部分 FileStream 構造子。

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);
    }
}

open System
open System.IO
open System.Text

let addText (fs:FileStream) (value: string) =
    let info = UTF8Encoding(true).GetBytes value
    fs.Write(info, 0, info.Length);

let path = @"c:\temp\MyTest.txt"

// Delete the file if it exists.
if File.Exists path then
    File.Delete path

//Create the file.
do
    use 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 i = 1 to 119 do
        Convert.ToChar i
        |> string
        |> addText fs
    
do
    //Open the stream and read it back.
    use fs = File.OpenRead path
    let b = Array.zeroCreate 1024
    let temp = UTF8Encoding true
    let mutable readLen = fs.Read(b,0,b.Length);
    while readLen> 0 do
        printfn $"{temp.GetString(b,0,readLen)}"
        readLen <- fs.Read(b,0,b.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

以下範例展示了如何非同步寫入檔案。 這段程式碼運行在一個WPF應用程式中，該應用程式有一個名為 UserInput 的 TextBlock 和一個連接到名為 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 方法來執行異步作。 使用異步方法來執行資源密集的檔案作業，而不封鎖主要線程。 這種效能考量在桌面應用程式中尤其重要，因為耗時的串流操作可能會阻塞 UI 執行緒，讓應用程式看起來像是無法運作。 FileStream 對輸入和輸出進行緩衝，以提升效能。

Important

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

屬性 IsAsync 會偵測檔案句柄是否以異步方式開啟。 當您使用具有FileStream、 isAsync或 useAsync 參數的建構函式來建立 類別的options實例時，您可以指定此值。 當 屬性為 true時，數據流會利用重疊的 I/O 以異步方式執行檔案作業。 不過， IsAsync 屬性不一定是 true 呼叫 ReadAsync、 WriteAsync或 CopyToAsync 方法。 IsAsync當 屬性是 false 且您呼叫異步讀取和寫入作業時，UI 線程仍不會遭到封鎖，但實際的 I/O 作業會同步執行。

Seek方法支援隨機存取檔案。 Seek 允許將讀取/寫入位置移至檔案中的任何位置。 可以使用位元組偏移參考點參數來完成此操作。 位元組偏移量是相對於搜尋參考點的，它可以是基礎檔案的開頭、目前位置或結尾，由SeekOrigin列舉的三個成員表示。

Note

磁碟檔案一律支援隨機存取。 在建構時， 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 會捨棄緩衝區的內容，並再次從檔案讀取數據流。 這可能會影響效能，視檔案大小以及可能影響檔案數據流位置的任何其他進程而定。

如果在呼叫 Write 方法時偵測到句柄位置的意外變更，則會捨棄緩衝區的內容，並拋出 IOException 例外狀況。

當存取FileStream屬性以公開SafeFileHandle物件的句柄，或在建構函式中賦予FileStream物件SafeFileHandle屬性時，該物件的句柄將不會被獨佔保留。

建構函式

名稱	Description
FileStream(IntPtr, FileAccess, Boolean, Int32, Boolean)	已淘汰. 初始化指定檔案句柄的新實例 FileStream ，並具備指定的讀寫權限、 FileStream 實例擁有權、緩衝區大小，以及同步或非同步狀態。
FileStream(IntPtr, FileAccess, Boolean, Int32)	已淘汰. 初始化指定檔案柄的新實例 FileStream ，並依照指定的讀寫權限、 FileStream 實例所有權及緩衝區大小。
FileStream(IntPtr, FileAccess, Boolean)	已淘汰. 初始化指定檔案柄的新實例 FileStream ，並擁有指定的讀寫權限與 FileStream 實例所有權。
FileStream(IntPtr, FileAccess)	已淘汰. 初始化該類別的新實例 FileStream ，以指定的檔案柄，並取得指定的讀寫權限。
FileStream(SafeFileHandle, FileAccess, Int32, Boolean)	初始化指定檔案帳柄的新實例 FileStream ，並以指定的讀寫權限、緩衝區大小及同步或非同步狀態。
FileStream(SafeFileHandle, FileAccess, Int32)	初始化指定檔案柄的新類別實例 FileStream ，並依照指定的讀寫權限及緩衝區大小。
FileStream(SafeFileHandle, FileAccess)	初始化該類別的新實例 FileStream ，以指定的檔案柄，並取得指定的讀寫權限。
FileStream(String, FileMode, FileAccess, FileShare, Int32, Boolean)	初始化類別的新實例 FileStream ，包含指定的路徑、建立模式、讀寫與共享權限、緩衝區大小，以及同步或非同步狀態。
FileStream(String, FileMode, FileAccess, FileShare, Int32, FileOptions)	初始化類別的新實例 FileStream ，包含指定的路徑、建立模式、讀寫與共享權限、其他 FileStream 對同一檔案的存取權限、緩衝區大小及額外檔案選項。
FileStream(String, FileMode, FileAccess, FileShare, Int32)	初始化類別的新實例 FileStream ，包含指定的路徑、建立模式、讀寫與共享權限，以及緩衝區大小。
FileStream(String, FileMode, FileAccess, FileShare)	初始化一個新實例 FileStream ，包含指定的路徑、建立模式、讀寫權限及共享權限。
FileStream(String, FileMode, FileAccess)	以指定的路徑、建立模式及讀寫權限初始化該類別的新實例 FileStream 。
FileStream(String, FileMode)	初始化一個以指定路徑與建立模式的新類別實例 FileStream 。
FileStream(String, FileStreamOptions)	初始化一個新的類別實例 FileStream ，包含指定的路徑、建立模式、讀寫與分享權限、緩衝區大小、額外檔案選項、預配置大小，以及其他檔案流對同一檔案的存取權限。

屬性

名稱	Description
CanRead	會得到一個值，表示目前串流是否支援讀取。
CanSeek	會得到一個值，表示目前串流是否支援尋道。
CanTimeout	取得值，這個值會判斷目前的數據流是否可以逾時。 (繼承來源 Stream)
CanWrite	會得到一個值，表示目前串流是否支援寫入。
Handle	已淘汰. 取得目前 FileStream 物件所封裝檔案的作業系統檔案柄。
IsAsync	會得到一個值，表示是 FileStream 非同步還是同步開啟。
Length	取得數據流的位元組長度。
Name	取得檔案在 FileStream.
Position	取得或設定該串流的當前位置。
ReadTimeout	會取得或設定一個以毫秒為單位的值，決定串流在逾時前嘗試讀取的時間長短。 (繼承來源 Stream)
SafeFileHandle	取得 SafeFileHandle 一個物件，代表該 FileStream 物件所封裝的檔案作業系統的檔案柄。
WriteTimeout	取得或設定一個毫秒級的值，決定串流在逾時前嘗試寫入的時間長短。 (繼承來源 Stream)

方法

名稱	Description
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步讀取作業。 請考慮改用 ReadAsync(Byte[], Int32, Int32, CancellationToken)。
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	開始異步寫入作業。 請考慮改用 WriteAsync(Byte[], Int32, Int32, CancellationToken)。
Close()	關閉目前串流並釋放與目前串流相關的資源（如套接字和檔案柄）。 與其呼叫此方法，不如確保溪流已被妥善處理。 (繼承來源 Stream)
CopyTo(Stream, Int32)	從目前串流讀取位元組，並依指定緩衝區大小寫入另一串流。 兩個串流的位置依複製的位元組數前進。
CopyTo(Stream)	從目前串流讀取位元組，然後寫入另一條串流。 兩個串流的位置依複製的位元組數前進。 (繼承來源 Stream)
CopyToAsync(Stream, CancellationToken)	使用指定的取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 兩個串流的位置依複製的位元組數前進。 (繼承來源 Stream)
CopyToAsync(Stream, Int32, CancellationToken)	使用指定的緩衝區大小和取消標記，以異步方式從目前的檔案數據流讀取位元組，並將其寫入另一個數據流。
CopyToAsync(Stream, Int32)	非同步讀取目前串流的位元組，並以指定的緩衝區大小寫入另一串流。 兩個串流的位置依複製的位元組數前進。 (繼承來源 Stream)
CopyToAsync(Stream)	非同步地從目前串流讀取位元組，然後寫入另一條串流。 兩個串流的位置依複製的位元組數前進。 (繼承來源 Stream)
CreateWaitHandle()	已淘汰. 分配一個 WaitHandle 物件。 (繼承來源 Stream)
Dispose()	釋放 Stream所使用的所有資源。 (繼承來源 Stream)
Dispose(Boolean)	釋放 未管理的資源， FileStream 並可選擇性地釋放受管理資源。
DisposeAsync()	非同步釋放 FileStream.
EndRead(IAsyncResult)	等待即將完成的非同步讀取操作。 （考慮改用 ReadAsync(Byte[], Int32, Int32, CancellationToken) 。）
EndWrite(IAsyncResult)	結束非同步寫入操作並阻塞直到 I/O 操作完成。 （考慮改用 WriteAsync(Byte[], Int32, Int32, CancellationToken) 。）
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Finalize()	確保當垃圾回收器 FileStream回收時，資源被釋放並執行其他清理作業。
Flush()	清除此數據流的緩衝區，並導致任何緩衝的數據寫入檔案。
Flush(Boolean)	清除此數據流的緩衝區，並導致任何緩衝的數據寫入檔案，並清除所有中繼檔案緩衝區。
FlushAsync()	非同步清除此串流的所有緩衝區，並使任何緩衝資料寫入底層裝置。 (繼承來源 Stream)
FlushAsync(CancellationToken)	非同步清除此串流的所有緩衝區，將任何緩衝資料寫入檔案，並監控取消請求。
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetLifetimeService()	已淘汰. 擷取控制這個實例存留期原則的目前存留期服務物件。 (繼承來源 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>)	從目前檔案串流讀取一串位元組，並依讀取位元組數推進檔案流中的位置。
ReadAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式從目前的檔案數據流讀取位元組序列，並將其寫入位元組陣列，從指定的位移開始，依讀取的位元組數目將檔案數據流中的位置往前移，並監視取消要求。
ReadAsync(Byte[], Int32, Int32)	非同步讀取當前串流的位元組序列，並依讀取位元組數推進串流中的位置。 (繼承來源 Stream)
ReadAsync(Memory<Byte>, CancellationToken)	非同步讀取目前檔案串流中的一串位元組並將其寫入記憶體區域，依讀取位元組數推進檔案串流中的位置，並監控取消請求。
ReadAtLeast(Span<Byte>, Int32, Boolean)	從目前數據流讀取至少一個字節數目，並將數據流中的位置依讀取的位元組數目往前移。 (繼承來源 Stream)
ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken)	以異步方式從目前數據流讀取至少一個字節數目、依讀取的位元組數目將數據流中的位置往前移，並監視取消要求。 (繼承來源 Stream)
ReadByte()	從檔案讀取一個位元組，並將讀取位置往前推進一個位元組。
ReadExactly(Byte[], Int32, Int32)	從目前串流讀取 count 位元組數，並推進串流中的位置。 (繼承來源 Stream)
ReadExactly(Span<Byte>)	從目前串流讀取位元組，並推進串流中的位置直到填 buffer 滿。 (繼承來源 Stream)
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)	非同步讀取 count 當前串流的位元組數量，推進串流中的位置，並監控取消請求。 (繼承來源 Stream)
ReadExactlyAsync(Memory<Byte>, CancellationToken)	非同步讀取目前串流的位元組，推進串流中的位置直到填 buffer 滿，並監控取消請求。 (繼承來源 Stream)
Seek(Int64, SeekOrigin)	將此串流的當前位置設定為給定值。
SetLength(Int64)	將此串流的長度設定為給定值。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)
Unlock(Int64, Int64)	允許其他進程存取先前鎖定之檔案的所有或部分。
Write(Byte[], Int32, Int32)	將一個位元組區塊寫入檔案串流。
Write(ReadOnlySpan<Byte>)	從唯讀區間寫入一串位元組到目前的檔案串流，並依照寫入的位元組數將該檔案串流中的當前位置往前推進。
WriteAsync(Byte[], Int32, Int32, CancellationToken)	非同步地將一串位元組寫入目前串流，依照寫入位元組數將該串流中的當前位置前進，並監控取消請求。
WriteAsync(Byte[], Int32, Int32)	非同步地將一串位元組寫入目前串流，並依照寫入的位元組數將該串流中的當前位置往前推進。 (繼承來源 Stream)
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	非同步地從記憶體區域寫入一串位元組到目前的檔案串流，依照寫入的位元組數將該檔案串流中的當前位置往前推進，並監控取消請求。
WriteByte(Byte)	會將一個位元組寫入檔案串流的當前位置。

擴充方法

名稱	Description
ConfigureAwait(IAsyncDisposable, Boolean)	設定如何執行從異步可處置專案傳回的工作等候。
CopyToAsync(Stream, PipeWriter, CancellationToken)	非同步讀取 的 Stream 位元組並使用消去標記寫入指定的 PipeWriter。
GetAccessControl(FileStream)	傳回檔案的安全性資訊。
SetAccessControl(FileStream, FileSecurity)	變更現有檔案的安全性屬性。

另請參閱

• File
• FileAccess
• FileMode
• FileShare
• 檔案和數據流 I/O
• 如何：從檔案讀取文字
• 如何：將文字寫入檔案
• 如何：讀取和寫入新建立的數據檔