FileStream 類別

定義

命名空間:

System.IO

組件:

System.Runtime.dll

來源:

FileStream.cs

為檔案提供 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 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);
    }
}

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

備註

如需此 API 的詳細資訊，請參閱 FileStream的補充 API 備註。

建構函式

FileStream(IntPtr, FileAccess)	已淘汰. 使用指定的讀取/寫入許可權，初始化指定之檔句柄之 FileStream 類別的新實例。
FileStream(IntPtr, FileAccess, Boolean)	已淘汰. 使用指定的讀取/寫入許可權和 FileStream 實例擁有權，初始化指定之檔句柄 FileStream 類別的新實例。
FileStream(IntPtr, FileAccess, Boolean, Int32)	已淘汰. 使用指定的讀取/寫入許可權、FileStream 實例擁有權和緩衝區大小，初始化指定之檔句柄 FileStream 類別的新實例。
FileStream(IntPtr, FileAccess, Boolean, Int32, Boolean)	已淘汰. 使用指定的讀取/寫入許可權、FileStream 實例擁有權、緩衝區大小和同步或異步狀態，初始化指定之檔句柄 FileStream 類別的新實例。
FileStream(SafeFileHandle, FileAccess)	使用指定的讀取/寫入許可權，初始化指定之檔句柄之 FileStream 類別的新實例。
FileStream(SafeFileHandle, FileAccess, Int32)	使用指定的讀取/寫入許可權和緩衝區大小，初始化指定之檔句柄 FileStream 類別的新實例。
FileStream(SafeFileHandle, FileAccess, Int32, Boolean)	使用指定的讀取/寫入許可權、緩衝區大小和同步或異步狀態，初始化指定之檔句柄 FileStream 類別的新實例。
FileStream(String, FileMode)	使用指定的路徑和建立模式，初始化 FileStream 類別的新實例。
FileStream(String, FileMode, FileAccess)	使用指定的路徑、建立模式和讀取/寫入許可權，初始化 FileStream 類別的新實例。
FileStream(String, FileMode, FileAccess, FileShare)	使用指定的路徑、建立模式、讀取/寫入許可權和共用許可權，初始化 FileStream 類別的新實例。
FileStream(String, FileMode, FileAccess, FileShare, Int32)	使用指定的路徑、建立模式、讀取/寫入和共享許可權，以及緩衝區大小，初始化 FileStream 類別的新實例。
FileStream(String, FileMode, FileAccess, FileShare, Int32, Boolean)	使用指定的路徑、建立模式、讀取/寫入和共用許可權、緩衝區大小和同步或異步狀態，初始化 FileStream 類別的新實例。
FileStream(String, FileMode, FileAccess, FileShare, Int32, FileOptions)	使用指定的路徑、建立模式、讀取/寫入和共用許可權，初始化 FileStream 類別的新實例，其他 FileStreams 可以具有相同的檔案、緩衝區大小和其他檔案選項的存取權。
FileStream(String, FileStreamOptions)	使用指定的路徑、建立模式、讀取/寫入和共用許可權、緩衝區大小、其他檔案選項、預先配置大小，以及其他 FileStreams 可以具有相同檔案的存取權，初始化 FileStream 類別的新實例。

屬性

CanRead	取得值，這個值表示目前數據流是否支援讀取。
CanSeek	取得值，這個值表示目前數據流是否支持搜尋。
CanTimeout	取得值，這個值會判斷目前的數據流是否可以逾時。 (繼承來源 Stream)
CanWrite	取得值，這個值表示目前數據流是否支援寫入。
Handle	已淘汰. 取得目前 FileStream 物件封裝之檔案的操作系統檔句柄。
IsAsync	取得值，這個值表示 FileStream 是以異步或同步方式開啟。
Length	取得數據流的位元組長度。
Name	取得在 FileStream中開啟之檔案的絕對路徑。
Position	取得或設定這個數據流的目前位置。
ReadTimeout	取得或設定值，以毫秒為單位，決定數據流在逾時之前嘗試讀取的時間長度。 (繼承來源 Stream)
SafeFileHandle	取得 SafeFileHandle 物件，代表目前 FileStream 物件封裝之檔案的操作系統檔句柄。
WriteTimeout	取得或設定值，以毫秒為單位，決定數據流在逾時之前嘗試寫入的時間長度。 (繼承來源 Stream)

方法

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)	從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyTo(Stream, Int32)	從目前的數據流讀取位元組，並使用指定的緩衝區大小將它們寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream)	以異步方式從目前的數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream, CancellationToken)	使用指定的取消標記，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream, Int32)	使用指定的緩衝區大小，以異步方式從目前數據流讀取位元組，並將其寫入另一個數據流。 這兩個數據流位置都會依複製的位元元組數目進階。 (繼承來源 Stream)
CopyToAsync(Stream, Int32, CancellationToken)	使用指定的緩衝區大小和取消標記，以異步方式從目前的檔案數據流讀取位元組，並將其寫入另一個數據流。
CreateObjRef(Type)	建立物件，其中包含產生用來與遠端物件通訊之 Proxy 所需的所有相關信息。 (繼承來源 MarshalByRefObject)
CreateWaitHandle()	已淘汰. 配置 WaitHandle 物件。 (繼承來源 Stream)
Dispose()	釋放 Stream所使用的所有資源。 (繼承來源 Stream)
Dispose(Boolean)	釋放 FileStream 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。
DisposeAsync()	以異步方式釋放 FileStream所使用的 Unmanaged 資源。
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)	以異步方式從目前數據流讀取位元組序列，並依讀取的位元元組數目將數據流中的位置往前移。 (繼承來源 Stream)
ReadAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式從目前的檔案數據流讀取位元組序列，並將其寫入位元組陣列，從指定的位移開始，依讀取的位元組數目將檔案數據流中的位置往前移，並監視取消要求。
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)	以異步方式將位元組序列寫入目前數據流，並依寫入的位元元組數目，將這個數據流中的目前位置往前移。 (繼承來源 Stream)
WriteAsync(Byte[], Int32, Int32, CancellationToken)	以異步方式將位元組序列寫入至目前的數據流、依寫入的位元組數目將這個數據流中的目前位置往前移，並監視取消要求。
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	以異步方式將位元組序列從記憶體區域寫入至目前的檔案數據流、依寫入的位元組數目將這個檔案數據流中的目前位置往前移，並監視取消要求。
WriteByte(Byte)	將位元組寫入檔案數據流中的目前位置。

擴充方法

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

另請參閱

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