1. The FileStream class: working in chunks
You can think of FileStream like a water pipe directly connected to your file on disk. Through this pipe, you can control the flow of data: send bytes to the file (write) or get bytes from the file (read). Unlike higher-level methods that just "give you a glass of water," FileStream gives you direct access to the "faucet," letting you control the flow of water (bytes) as needed.
FileStream works at the byte level. That means it doesn't care if it's text or an image; for it, everything is just a sequence of bytes. If you're working with text files through FileStream, you'll need to convert strings to bytes yourself (using an encoding like UTF-8) when writing, and back again when reading.
When exactly do you need FileStream?
- Working with really big files: When a file is so huge that you can't or shouldn't load it all into RAM (like gigabyte-sized logs or video files). FileStream lets you read or write data in chunks, which is way more memory-efficient.
- Binary data: If you're dealing with files that aren't just plain text (images, audio, video, serialized objects, database files), FileStream is your go-to tool, since it gives you direct access to the bytes.
- Detailed control over access modes: Need to open a file for reading *and* writing at the same time? Or open it so other programs can't access it? Or maybe you want several processes to read the file at once? FileStream gives you full control over these modes.
- Async operations: In modern high-performance apps (like web servers), it's super important that file operations don't block the main thread. FileStream supports async methods (ReadAsync, WriteAsync), so your app stays responsive.
- Partial read/write or random access: If you need to read data from a specific spot in a file (like from the 500th byte) or write data in the middle of a file, FileStream lets you control the file pointer position.
Classic newbie mistake: Using FileStream for super simple stuff, like writing a single line of text to a small file. In those cases, it's overkill. FileStream is a tool for specific and more complex scenarios.
2. Creating and opening a FileStream
To start working with a file through FileStream, you need to create an instance of it. You do this with a constructor that takes several important parameters, which define how you want to interact with the file.
using System;
using System.IO; // Required for FileStream
using System.Text; // For working with encodings (converting strings to bytes and back)
Example of basic reading of a text file using FileStream:
First, let's create a file so we have something to read.
// Let's create a simple text file for demonstration
string path = "example_filestream.txt";
// Open the stream for reading.
FileStream fs = new FileStream(path, FileMode.Open, FileAccess.Read);
// Create a buffer (byte array) to temporarily store the read data.
byte[] buffer = new byte[fs.Length];
// Read bytes from the stream into the buffer.
int bytesRead = fs.Read(buffer, 0, buffer.Length);
// Convert the read bytes back into a string using the right encoding (like UTF-8).
string content = Encoding.UTF8.GetString(buffer, 0, bytesRead);
Console.WriteLine("Read from file via FileStream: " + content);
fs.Close(); //close the stream
Main parameters
- FileMode: how exactly to open the file (
Open,Create,AppendOpenOrCreateetc.) - FileAccess: what to do with the file (
Read,Write,ReadWrite) - FileShare: can other processes use this file at the same time (usually not needed for simple stuff)
Classic mistake: If you forget to close FileStream, the file might get "locked" — you won't be able to delete or reopen it later!
3. FileStream constructor parameters
The FileStream constructor lets you fine-tune exactly how you want to open the file. Here are its main parameters:
new FileStream(
string path, // Path to the file (absolute or relative)
FileMode mode, // How to open the file (create, open, overwrite, etc.)
FileAccess access, // What access is allowed (read only, write only, read+write)
FileShare share // How other processes can access the file while it's open (optional)
);
Let's break down the values for the FileMode and FileAccess enums:
FileMode (File open mode):
Defines how the OS should handle the file when opening it.
FileMode.Open: Opens an existing file. If the file at the given path isn't found, a FileNotFoundException is thrown.FileMode.Create: Creates a new file. If a file with that name already exists, it will be completely overwritten (its contents will be deleted).
FileAccess (File access rights):
Defines what operations your program is allowed to do with the open file.
FileAccess.Read: File is open for reading only. You can't write to it.FileAccess.Write: File is open for writing only. You can't read from it.FileAccess.ReadWrite: File is open for both reading and writing. This is the most flexible, but also potentially more complex mode, since you have to manage the stream position yourself.
FileShare (Sharing mode):
Defines how other processes can open the same file while it's open in your program. Super important for avoiding file locks.
FileShare.Read: Other processes can read the file while it's open in your FileStream, but can't write to it.FileShare.Write: Other processes can write to the file while it's open in your FileStream, but can't read it.FileShare.ReadWrite: Other processes can read and write to the file. This is the most liberal mode, but can lead to conflicts if multiple programs modify the file at the same time.
More about these modes in the next lecture.
4. Reading and writing data with FileStream
When working with FileStream, you're dealing with bytes. That means for text data, you need to convert between strings and byte arrays using encoding classes (like System.Text.Encoding.UTF8).
Writing data to a file with FileStream
When writing, you convert your data (like a string) to a byte array, then write those bytes to the stream.
string outputPath = "user_data.txt";
string userName = "Ivan Petrov";
// Convert the string to a byte array using UTF-8 encoding
byte[] userNameBytes = Encoding.UTF8.GetBytes(userName);
// Open FileStream for writing.
FileStream fsWrite = new FileStream(outputPath, FileMode.Create, FileAccess.Write);
// Write the byte array to the stream.
fsWrite.Write(userNameBytes, 0, userNameBytes.Length);
Console.WriteLine($"Name '{userName}' successfully written to file '{outputPath}'.");
fsWrite.Close(); //close the stream
Reading data from a file with FileStream
When reading, you read bytes from the stream into a buffer, then convert those bytes back into the format you want (like a string).
string inputPath = "user_data.txt";
// Open FileStream for reading
FileStream fsRead = new FileStream(inputPath, FileMode.Open, FileAccess.Read);
// Create a buffer the size of the file to read all bytes.
byte[] buffer = new byte[fsRead.Length];
// Read bytes from the stream into the buffer.
int bytesRead = fsRead.Read(buffer, 0, buffer.Length);
// Convert the read bytes to a string.
string loadedUserName = Encoding.UTF8.GetString(buffer, 0, bytesRead);
Console.WriteLine($"Name from file (via FileStream): {loadedUserName}");
fsRead.Close(); //close the stream
5. Working with big files
The main advantage of FileStream over File.ReadAll... methods is the ability to read and write a file in chunks, which is super important for working with big files that don't fit into RAM all at once.
Reading big files in chunks
When you read a file in chunks, you use a buffer (byte array) of fixed size and read data into it until you reach the end of the file.
string bigFilePath = "bigfile.bin"; //big file
int bufferSize = 4096; // Buffer size, for example, 4 KB
byte[] buffer = new byte[bufferSize]; // Create buffer
int bytesRead; // Number of bytes actually read
long totalBytesRead = 0; // Total bytes read
// open the stream
FileStream fs = new FileStream(bigFilePath, FileMode.Open, FileAccess.Read);
int chunkNumber = 1;
// Loop continues while fs.Read() returns a positive number of bytes
while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) > 0)
{
totalBytesRead += bytesRead;
Console.WriteLine($"Chunk {chunkNumber++}: read {bytesRead} bytes. Total: {totalBytesRead} bytes.");
// !!! Here you process the read "chunks" of data !!!
}
fs.Close(); //close the stream
Important note: The fs.Read(buffer, offset, count) method doesn't guarantee it'll fill the whole buffer. It returns the number of bytes actually read, which can be less than count (especially at the end of the file). Always use the returned bytesRead value to process data correctly.
Writing big data in chunks
Just like reading, you can write large amounts of data to a file in chunks.
string bigOutputPath = "big_output.txt";
string longText = new string('A', 1_000_000); // String of a million 'A's
byte[] longTextBytes = Encoding.UTF8.GetBytes(longText);
int writeBufferSize = 1024; // Write 1 KB at a time
// FileMode.Create: create the file
FileStream fsWrite = new FileStream(bigOutputPath, FileMode.Create, FileAccess.Write);
for (int i = 0; i < longTextBytes.Length; i += writeBufferSize)
{
// Figure out how many bytes are left to write in this iteration
int bytesToWrite = Math.Min(writeBufferSize, longTextBytes.Length - i);
// Write a chunk of data from longTextBytes, starting at offset 'i'
fsWrite.Write(longTextBytes, i, bytesToWrite);
Console.WriteLine($"Wrote {bytesToWrite} bytes");
}
fsWrite.Close(); //close the stream
6. Sneaky pitfalls and classic mistakes
Even with a powerful tool like FileStream, there are some gotchas you should watch out for:
Buffering and Flush(): Like we mentioned, data can stay in the memory buffer and not actually hit the disk. If you don't use using and don't call Close()/Dispose(), and just end the program, your data might get lost. Always call Flush() (or rely on using/Close()) to make sure your data is written.
Exception handling: IO errors (like IOException when trying to write to a full disk, UnauthorizedAccessException because of lack of permissions, FileNotFoundException when trying to open a non-existent file in Open mode) — these are totally normal. Always wrap your FileStream operations in try-catch blocks.
Encodings: When working with text data via FileStream (which works with bytes), you're fully responsible for picking the right encoding (Encoding.UTF8, Encoding.ASCII, Encoding.Unicode, etc.) when converting strings to bytes and back. Pick the wrong encoding and you'll get "gibberish."
Managing position: If you use Seek(), be careful with the offset and origin parameters so you don't move past the end of the file or to a weird spot.
File locks (FileShare): If you open a file with FileShare.None, other processes won't be able to access it. This can be a problem if another program (or even another thread in your program) tries to use the same file. Always pick the most appropriate FileShare mode.
GO TO FULL VERSION