1. 前言
StreamWriter 是 .NET 裡 System.IO 命名空間裡很重要的 class,專門讓你用 stream 寫文字資料到檔案超級方便。
為什麼不能直接用 FileStream?
FileStream 只會處理 byte。如果你想直接寫字串進去,你就要自己把文字轉成 byte,還要自己搞定編碼(你一定會後悔,然後回來用 StreamWriter)。
StreamWriter 幫你把這些麻煩事都搞定:你給它字串,它自動寫對的 byte 到檔案裡。
主要優點:
- 寫字串超簡單,不用自己轉 byte。
- 有方法可以一行一行寫文字。
- 可以控制 buffer 跟 encoding(我們等等會學怎麼用)。
最簡單的範例
using System.IO;
string path = "output.txt";
using (StreamWriter writer = new StreamWriter(path))
{
writer.WriteLine("哈囉,世界!");
writer.WriteLine("這是第二行。");
}
// 離開 using 大括號後 StreamWriter 一定會釋放檔案。
這裡發生了什麼?
- 打開一個檔案準備寫資料(如果檔案不存在會自動建立)。
- 每一行都會當作新的一行寫進檔案(用 WriteLine 方法)。
- using 區塊結束後,檔案會自動關閉,就算有錯誤也一樣。
如果你執行完這個程式去打開 output.txt,你會看到兩行文字,跟你預期的一樣。
重要小提醒
如果檔案已經存在,它會被整個覆寫!原本裡面的東西都會消失。所以要小心:不要把重要的論文或唯一的水電費收據放在這種檔案裡。
2. 寫資料到 stream
StreamWriter 主要方法
| 方法 | 說明 |
|---|---|
|
寫一個字串,不會換行 |
|
寫一個字串,會自動換行 |
|
強制把 buffer 資料寫進檔案(很少需要手動做) |
/ |
關閉 stream 並釋放資源(using 會自動做這件事) |
|
取得底層的 stream(例如 FileStream) |
Write() 方法
寫資料但不會換行。你後面寫的東西都會在同一行。
WriteLine() 方法
寫資料時會自動加上換行符號(Windows 是 \r\n,Unix 類系統是 \n)。
就像你每次寫完都按一下 Enter。
Write() vs WriteLine():差異示範
using (var writer = new StreamWriter("example.txt"))
{
writer.Write("第一個 ");
writer.Write("段落。 ");
writer.WriteLine("補上這行,Enter!");
writer.Write("第二個段落。");
}
現在 example.txt 內容大概會長這樣:
第一個 段落。 補上這行,Enter!
第二個段落。
3. 處理編碼
預設情況下,如果你沒特別設定 StreamWriter 的參數,它會用 UTF-8 有 BOM(Byte Order Mark)來寫檔案。
這樣其實很方便也很現代,但有時候你會需要指定編碼——比如要跟舊程式或外部資料相容。
怎麼指定編碼?
// 用 Windows-1251 編碼寫檔(舊系統的西里爾字母)
using (var writer = new StreamWriter("cyrillic.txt", false, System.Text.Encoding.GetEncoding("windows-1251")))
{
writer.WriteLine("哈囉,西里爾世界!");
}
重要提醒:
系統必須支援你指定的編碼。如果不確定,就用 UTF-8 吧。
4. 建構子的其他參數
來看看 StreamWriter 的內部參數:
public StreamWriter(
string path, // 檔案路徑
bool append = false, // 要不要加在檔案最後?
Encoding encoding = null, // 編碼
int bufferSize = 1024 // buffer 大小,單位 byte
)
- append — 如果是 false(預設),檔案會整個覆寫。如果是 true,新資料會加在最後面。
- encoding — 用哪種編碼。
- bufferSize — 內部 buffer 大小,寫大量資料時會比較快。
範例:追加資料到同一個檔案
// 檔案會一直加資料,不會覆蓋掉
using (var writer = new StreamWriter("log.txt", append: true))
{
writer.WriteLine(DateTime.Now + " -- 新事件");
}
5. 有用的小細節
追加跟覆寫時會發生什麼事
| 模式 | 會做什麼? | 檔案結果 |
|---|---|---|
| append: false | 整個覆寫檔案 | 舊資料會被清掉 |
| append: true | 新資料加在最後 | 舊資料會保留 |
小撇步: 追加模式(append: true)超適合拿來寫 log,這樣事件紀錄都不會被洗掉。
StreamWriter 處理大量資料
- StreamWriter 會先把資料放在 buffer,實際寫進檔案會慢一點點。等你關閉 stream(或呼叫 Flush())後,資料才會真的寫到硬碟。
- 用 WriteLine 一行一行寫資料超有效率。如果你要寫複雜格式(像 JSON、CSV 或 XML),建議用專門的 library,或自己小心處理特殊字元(像逗號或引號)。
怎麼正確結束寫入並釋放資源
正確做法: 一定要用 using!
這樣就算發生例外(比如硬碟爆了或檔案被別的程式鎖住),檔案也一定會被關閉。
flowchart TD
A[建立 StreamWriter] --> B[操作檔案]
B --> C{發生例外?}
C -- 是 --> D[會呼叫 Dispose]
C -- 否 --> D
D --> E[檔案一定會被關閉]
6. 實戰範例
假設我們課程裡有個小型書籍管理程式。來加個功能,把新書寫進檔案。
範例:把新書存到獨立檔案
using System;
using System.IO;
class Program
{
static void Main()
{
Console.WriteLine("請輸入書名:");
string bookTitle = Console.ReadLine();
Console.WriteLine("請輸入作者:");
string author = Console.ReadLine();
string path = "books.txt";
using (var writer = new StreamWriter(path, append: true))
{
writer.WriteLine($"{bookTitle};{author}");
// CSV 格式:每一行一筆書,用分號分隔
}
Console.WriteLine("書已經存到檔案囉!");
}
}
你可以試著連續加幾本書。books.txt 裡的資料會一直往下加,不會把舊的洗掉。這種方式很適合寫 log 或紀錄——比如你以後變成 Enterprise 工程師,要做審計系統時就會用到。
7. 怎麼避免寫檔常見錯誤
新手最常遇到這些問題:
檔案沒關閉,被其他程式鎖住。原因:忘記用 using。
寫了一堆資料但檔案是空的:忘記呼叫 Flush() 或沒關閉 stream(用 using 就會自動處理)。
不小心覆蓋檔案沒追加——忘了設 append: true。
編碼問題:檔案在記事本裡變亂碼——選錯編碼或其他程式不支援 UTF-8。
遇到 UnauthorizedAccessException 或 DirectoryNotFoundException:程式想存檔到沒權限或不存在的資料夾。記得檢查路徑跟權限。
錯誤 "file is used by another process":你開檔寫入但沒關,或同時有別的程式也在寫同一個檔案。
GO TO FULL VERSION