Strumienie#
Strumienie w C# są abstrakcją dla operacji wejścia/wyjścia (I/O). Strumień reprezentuje sekwencję bajtów, którą można czytać lub zapisywać. Źródłem danych może być pamięć, pliki, łącza, czy połączenie sieciowe. Niezależnie od tego, co to jest, strumienie pozwalają pracować z danymi w jednolity sposób.
Możliwości strumienia#
Strumienie pozwalają na trzy podstawowe operacje: odczyt (Read), zapis (Write) i pozycjonowanie (Seek). Można sprawdzić, czy strumień wspiera te operacje za pomocą właściwości Can*:
using Stream stream = new FileStream("lorem.txt", FileMode.Open);
Console.WriteLine($"Can read: {stream.CanRead}");
Console.WriteLine($"Can write: {stream.CanWrite}");
Console.WriteLine($"Can Seek: {stream.CanSeek}");Praca ze strumieniem#
Strumienie dostarczają metody podobne w swoim działaniu do tych z API POSIXa. Główną różnicą jest sposób obsługi błędów. Zamiast zwracać kody błędów (i ustawiać errno), metody związane ze strumieniami w C# zgłaszają wyjątki — najczęściej IOException i klasy pochodne (np. FileNotFoundException), ale też inne, np. UnauthorizedAccessException (brak uprawnień) lub NotSupportedException (operacja nieobsługiwana przez dany strumień).
Praca z “surowym strumieniem” jest zazwyczaj niewygodna/niewskazana, lepiej to robić przez adaptery strumieni lub korzystając z fasady pliku.
Większość operacji na strumieniach ma swoje odpowiedniki asynchroniczne (nieblokujące), np.
Read-ReadAsync. Na tym etapie przemilczymy ich istnienie.
Odczyt#
Metoda int Read(byte[] buffer, int offset, int count) ma analogiczne parametry do funkcji read z POSIX API. Podobnie, zwraca liczbę przeczytanych bajtów, która może się różnić od liczby bajtów, które chcielibyśmy przeczytać. Koniec strumienia jest sygnalizowany przez zwrócenie wartości 0.
using Stream stream = new FileStream("lorem.txt", FileMode.Open);
byte[] buffer = new byte[256];
int read;
while ((read = stream.Read(buffer, 0, buffer.Length)) > 0)
{
Console.WriteLine($"Read {read} bytes");
}Można też przeczytać pojedynczy bajt ze strumienia metodą
ReadByte, ale nie jest to zbyt efektywne.
Ponieważ Read może zwrócić mniej bajtów, niż żądaliśmy, odczyt bloku o znanym rozmiarze wymaga pętli. Od .NET 7 strumienie udostępniają do tego metody pomocnicze:
using Stream stream = new FileStream("lorem.txt", FileMode.Open);
byte[] header = new byte[16];
stream.ReadExactly(header); // reads exactly 16 bytes, or throws EndOfStreamException
byte[] buffer = new byte[256];
int read = stream.ReadAtLeast(buffer, minimumBytes: 64); // reads at least 64 (at most 256) bytesZapis#
Podobnie metoda void Write(byte[] buffer, int offset, int count) ma analogiczne parametry do funkcji write z POSIX API.
using Stream stream = new FileStream("lorem.txt", FileMode.Create);
byte[] buffer = new byte[256];
for (int i = byte.MinValue; i <= byte.MaxValue; i++)
{
buffer[i - byte.MinValue] = (byte)i;
}
stream.Write(buffer, 0, buffer.Length);Można też zapisać pojedynczy bajt do strumienia metodą
WriteByte, ale nie jest to zbyt efektywne.
Pozycjonowanie#
Niektóre strumienie wspierają operację zmiany pozycji. Zazwyczaj są to strumienie, których źródłem są pliki i pamięć. Strumienie sieciowe i łącza nie będą wspierały tej operacji.
using Stream stream = new FileStream("lorem.txt", FileMode.Open);
stream.Position = 0;
stream.Position = stream.Length;
stream.Seek(offset: 10, SeekOrigin.Begin);
stream.Seek(offset: -10, SeekOrigin.End);
stream.Seek(offset: -10, SeekOrigin.Current);Jeżeli potrzebujemy jedynie czytać lub pisać pod wskazanym przesunięciem (jak funkcje POSIX
pread/pwrite), możemy użyć statycznej klasyRandomAccess(.NET 6). Operuje ona na uchwycie pliku i nie korzysta z bieżącej pozycji (ani jej nie zmienia), więc może być bezpiecznie używana przez wiele wątków jednocześnie:using var handle = File.OpenHandle("lorem.txt", FileMode.Open); byte[] buffer = new byte[16]; int read = RandomAccess.Read(handle, buffer, fileOffset: 100); long length = RandomAccess.GetLength(handle);
Opróżnianie i zamykanie strumieni#
Dane, które wpisujemy do strumienia, zazwyczaj nie są od razu zapisywane do miejsca docelowego (plik, sieć itp.). Operacje I/O są często buforowane, czy to przez system operacyjny, czy inny mechanizm. Aby wymusić zapis buforów strumienia, używamy na nim metody Flush. Flush przekazuje dane zbuforowane przez obiekt strumienia do systemu operacyjnego, ale nie gwarantuje, że system fizycznie zapisał je na dysk. Do tego FileStream udostępnia przeciążenie Flush(flushToDisk: true) (odpowiednik fsync). Zamknięcie strumienia powoduje jego automatyczne opróżnienie. Strumień zamykamy metodą Dispose lub Close. Obie te metody są równoważne i robią to samo.
Najlepiej jest używać instrukcji using — powoduje ona, że na końcu bloku zasoby z nią związane są automatycznie zwalniane poprzez wywołanie metody Dispose. Dzięki temu unikamy błędów związanych z niezamkniętymi zasobami.
using Stream stream = new FileStream("lorem.txt", FileMode.Open);
byte[] buffer = new byte[256];
int read;
while ((read = stream.Read(buffer, 0, buffer.Length)) > 0)
{
Console.WriteLine($"Read {read} bytes");
}Jest zamieniane przez kompilator na:
Stream stream = new FileStream("lorem.txt", FileMode.Open);
try
{
byte[] buffer = new byte[256];
int read;
while ((read = stream.Read(buffer, 0, buffer.Length)) > 0)
{
Console.WriteLine($"Read {read} bytes");
}
}
finally
{
stream?.Dispose();
}Strumienie plików#
Klasa FileStream reprezentuje strumień danych, którego źródłem jest plik. Plik można otworzyć na wiele sposobów, FileStream dostarcza wiele konstruktorów z wieloma opcjami.
// FileStream constructors:
public FileStream(string path, FileMode mode);
public FileStream(string path, FileMode mode, FileAccess access);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share, int bufferSize);
public FileStream(string path, FileMode mode, FileAccess access, FileShare share, int bufferSize, FileOptions options);
// and more...Poza konstruktorami FileStream, klasa File również dostarcza statyczne metody do otwierania plików:
// Using constructor:
FileStream fs1 = new FileStream("file1.txt", FileMode.OpenOrCreate, FileAccess.ReadWrite);
// File façade methods:
FileStream fs2 = File.Create("file2.txt");
FileStream fs3 = File.OpenRead("file3.txt");
FileStream fs4 = File.OpenWrite("file4.txt"); // FileMode.OpenOrCreate - does not truncate an existing file!
FileStream fs5 = File.Open("file5.txt", FileMode.OpenOrCreate, FileAccess.ReadWrite);Enum FileMode określa, jak plik ma być otwarty. Poniższa tabela opisuje dostępne możliwości:
| Wartość | Działanie, gdy plik istnieje | Działanie, gdy plik nie istnieje |
|---|---|---|
CreateNew | Rzuca IOException | Tworzy nowy plik |
Create | Nadpisuje (usuwa zawartość) | Tworzy nowy plik |
Open | Otwiera plik | Rzuca FileNotFoundException |
OpenOrCreate | Otwiera plik | Tworzy nowy plik |
Truncate | Nadpisuje (usuwa zawartość) | Rzuca FileNotFoundException |
Append | Otwiera plik i ustawia kursor na końcu | Tworzy nowy plik |
flowchart TD
A{Does file<br>exist?} -->|Yes| B{Truncate?}
A -->|No| C[FileMode.CreateNew]
B -->|Yes| D[FileMode.Truncate]
B -->|No| E[FileMode.Open]
A -->|Don't know/<br>Don't care| F{What to do<br>if it exists?}
F --->|Truncate| G[FileMode.Create]
F -->|Leave it be| H[FileMode.OpenOrCreate]
F -->|Append| I{Access}
I -->|Read/Write| H
I -->|Write| J[FileMode.Append]Enum FileAccess decyduje o tym, jak możemy korzystać ze strumienia, i przyjmuje jedną z wartości: Read, Write, ReadWrite.
Fasada#
Klasa File udostępnia fasadę, czyli uproszczony interfejs, który dostarcza metody czytające lub zapisujące cały plik w jednym prostym wywołaniu, ukrywając wszystkie szczegóły techniczne związane z operacjami na plikach.
ReadAllTextiWriteAllText:string content = File.ReadAllText("lorem.txt"); File.WriteAllText("lorem.txt.bak", content);ReadAllLinesiWriteAllLines:string[] lines = File.ReadAllLines("lorem.txt"); File.WriteAllLines("lorem.txt.bak", lines);ReadAllBytesiWriteAllBytes:byte[] bytes = File.ReadAllBytes("lorem.bin"); File.WriteAllBytes("lorem.bin.bak", bytes);AppendAllText:const string logFile = "log.txt"; for (int i = 0; i < 100; i++) { File.AppendAllText(logFile, $"[Info] This is a log entry no. {i}{Environment.NewLine}"); }ReadLinesiAppendAllLines:IEnumerable<string> lines = File.ReadLines("lorem.txt"); int errors = lines .Where(line => line.Contains("Error")) .Count();IEnumerable<string> lines = File.ReadLines("lorem.txt"); File.AppendAllLines("lorem.txt.bak", lines);
Metody
ReadAll*wczytują jednorazowo całą zawartość pliku do pamięci. Nie należy ich używać, jeżeli wiadomo, że plik jest duży. Dużo lepiej dla dużych plików sprawdzi się metodaReadLines, która leniwie, na bieżąco doczytuje kolejne linie w postaci sekwencji stringów.
Dekoratory strumieni#
Wzorzec Dekorator pozwala na dynamiczne dodawanie nowej funkcjonalności do obiektu bez zmiany jego klasy. Robi się to poprzez opakowanie oryginalnego obiektu w nowy obiekt-dekorator, który posiada ten sam interfejs. Dekorator deleguje oryginalne zadania do opakowanego obiektu, a dodatkowo wykonuje swoje własne operacje.
classDiagram
direction BT
class Stream {
<<abstract>>
+Read(byte[] buffer, int offset, int count)
+Write(byte[] buffer, int offset, int count)
+Seek(long offset, SeekOrigin origin)
+Flush()
}
class BufferedStream {
stream: Stream
+BufferedStream(stream: Stream)
+Read(...) // Adds buffering logic
+Write(...) // Adds buffering logic
}
class GZipStream {
stream: Stream
+GZipStream(stream: Stream, mode: CompressionMode)
+Read(...) // Adds decompression logic
+Write(...) // Adds compression logic
}
BufferedStream --|> Stream : inherits from
GZipStream --|> Stream : inherits fromBufferedStream#
BufferedStream dodaje buforowanie do strumienia. Opakowuje on inny strumień (np. FileStream) i utrzymuje w pamięci bufor (np. 4KB). Gdy spróbujemy odczytać z niego mniejszą liczbę bajtów, BufferedStream w rzeczywistości odczyta naraz z pliku 4KB i zapisze je do wewnętrznego bufora, z którego będziemy czytać, dopóki bufor się nie wyczerpie. Analogicznie byłoby z zapisem. Czytanie z i zapis do pamięci RAM jest dużo szybsze niż operacje na plikach na dysku, a buforowanie pozwala na minimalizację liczby kosztownych operacji I/O.
FileStreamma już własny wewnętrzny bufor (domyślnie 4 KB, rozmiar można ustawić parametrem konstruktorabufferSize), więc opakowywanie go wBufferedStreamniewiele daje, chyba że potrzebujemy większego bufora.BufferedStreamjest najbardziej przydatny dla strumieni bez własnego buforowania, np.NetworkStream.
// Write 100K bytes to a file:
File.WriteAllBytes("file.bin", new byte [100_000]);
using Stream fs = File.OpenRead("file.bin");
// Add 20k bytes buffering
using Stream bs = new BufferedStream(fs, 20_000);
bs.ReadByte();
Console.WriteLine(fs.Position); // 20000Kompresja#
Biblioteka standardowa dostarcza kompresujące dekoratory strumieni DeflateStream, ZLibStream (.NET 6), GZipStream i BrotliStream. Pierwsze trzy korzystają z tego samego algorytmu Deflate i różnią się jedynie formatem nagłówka i stopki (surowy Deflate, zlib, gzip); BrotliStream używa algorytmu Brotli. Gdy opakowujemy strumień w np. GZipStream i zapisujemy do niego dane, GZipStream najpierw kompresuje te dane, zanim przekaże je dalej do opakowanego strumienia. Podczas odczytów proces jest odwrotny: GZipStream czyta skompresowane dane z opakowanego strumienia i dekompresuje je, zanim je zwróci.
Kompresja
using Stream fsIn = File.OpenRead("file.txt"); using Stream fsOut = File.Create("file.txt.gz"); using Stream cs = new GZipStream(fsOut, CompressionMode.Compress); byte[] buffer = new byte[4096]; int read; while ((read = fsIn.Read(buffer, 0, buffer.Length)) > 0) { cs.Write(buffer, 0, read); }Dekompresja
using Stream fsIn = File.OpenRead("file.txt.gz"); using Stream ds = new GZipStream(fsIn, CompressionMode.Decompress); using Stream fsOut = File.Create("file.txt"); byte[] buffer = new byte[4096]; int read; while ((read = ds.Read(buffer, 0, buffer.Length)) > 0) { fsOut.Write(buffer, 0, read); }
Łączenie dekoratorów#
Ponieważ dekoratory same są strumieniami, możemy łączyć je w łańcuchy.
using Stream fs = new FileStream("dane.bin.gz", FileMode.Create);
using Stream bs = new BufferedStream(fs);
using Stream cs = new GZipStream(bs, CompressionMode.Compress);
byte[] data = new byte[1000];
cs.Write(data, 0, data.Length);W powyższym przykładzie dane, które zapisujemy, przechodzą przez następującą drogę:
data -> GZipStream (compression) -> BufferedStream (buffering) -> FileStream (disk write).Zwolnienie dekoratora (lub adaptera) zwalnia także opakowany przez niego strumień, więc wystarczy zwolnić najbardziej zewnętrzny obiekt łańcucha. Jeżeli opakowany strumień ma pozostać otwarty, należy przekazać do konstruktora leaveOpen: true. Warto też pamiętać, że strumienie kompresujące zapisują resztę skompresowanych danych (a w przypadku gzip także stopkę) dopiero przy zwolnieniu:
using MemoryStream ms = new MemoryStream();
using (GZipStream gz = new GZipStream(ms, CompressionMode.Compress, leaveOpen: true))
{
gz.Write(new byte[1000]);
} // Disposing gz writes the rest of the compressed data, but ms stays open
Console.WriteLine($"Compressed size: {ms.Length} bytes"); // Compressed size: 29 bytesAdaptery strumieni#
Największą przewagą nad API POSIX są adaptery strumieni. Dla strumieni mamy adaptery, które przystosowują strumienie do pracy z tekstem StreamReader i StreamWriter, i adaptery do pracy z danymi binarnymi BinaryReader i BinaryWriter. Adaptery również opakowują strumień, ale w odróżnieniu od dekoratorów nie są same w sobie strumieniami. Zazwyczaj przy pracy ze strumieniami na końcu łańcucha dekoratorów ląduje adapter.
Adaptery tekstu#
Adaptery tekstu dodają do strumienia możliwość odczytu i zapisu znaków, napisów i całych linii tekstu. Pozwalają na operacje takie jak string? ReadLine(), string? ReadToEnd(), void WriteLine(string str), void Write(string str).
StreamReaderusing FileStream fs = File.OpenRead("lorem.txt"); using StreamReader sr = new StreamReader(fs); while (sr.ReadLine() is { } line) { Console.WriteLine(line); }StreamWriterusing FileStream fs = File.Create("fizzbuzz.txt"); using StreamWriter sw = new StreamWriter(fs); for (int i = 1; i <= 100; i++) { sw.Write($"{i} : "); if (i % 3 == 0 && i % 5 == 0) sw.WriteLine("FizzBuzz"); else if (i % 3 == 0) sw.WriteLine("Fizz"); else if (i % 5 == 0) sw.WriteLine("Buzz"); else sw.WriteLine(i); }
Adaptery tekstu zamieniają znaki na bajty (i z powrotem) przy użyciu kodowania (System.Text.Encoding). Domyślnie StreamWriter oraz metody File.WriteAll* używają UTF-8 bez BOM (byte order mark). StreamReader rozpoznaje kodowanie po BOM, jeżeli dane się od niego zaczynają; w przeciwnym razie używa podanego kodowania (domyślnie UTF-8). Kodowanie można jawnie przekazać do konstruktorów oraz do metod fasady File:
File.WriteAllText("a.txt", "zażółć"); // UTF-8 without BOM: 10 bytes
File.WriteAllText("b.txt", "zażółć", Encoding.UTF8); // UTF-8 with BOM (EF BB BF): 13 bytes
File.WriteAllText("c.txt", "zażółć", Encoding.Unicode); // UTF-16 LE with BOM (FF FE): 14 bytes
using StreamReader sr = new StreamReader("c.txt"); // detects UTF-16 from the BOM
Console.WriteLine(sr.ReadToEnd()); // zażółćAdaptery binarne#
Z kolei adapterów binarnych używamy, gdy pracujemy z danymi binarnymi. Adaptery te pozwalają na serializację i deserializację typów podstawowych na bajty. Pozwalają na operacje takie jak int ReadInt32(), void Write(int value), double ReadDouble(), void Write(double value), string ReadString().
BinaryWriterusing FileStream fs = File.Create("player.bin"); using BinaryWriter bw = new BinaryWriter(fs); Player player = new Player("Bob", 100, 2500, 10, new Vector2(48.5f, 32.5f)); bw.Write(player.Name); bw.Write(player.Health); bw.Write(player.Experience); bw.Write(player.Money); bw.Write(player.Position.X); bw.Write(player.Position.Y);public record Player(string Name, int Health, long Experience, long Money, Vector2 Position);BinaryReaderusing FileStream fs = File.OpenRead("player.bin"); using BinaryReader br = new BinaryReader(fs); string name = br.ReadString(); int health = br.ReadInt32(); long experience = br.ReadInt64(); long money = br.ReadInt64(); float posX = br.ReadSingle(); float posY = br.ReadSingle(); Player player = new Player(name, health, experience, money, new Vector2(posX, posY)); Console.WriteLine(player);
BinaryWriteriBinaryReaderzawsze używają kolejności bajtów little-endian, niezależnie od platformy.stringjest zapisywany jako jego długość (liczba całkowita w kodowaniu 7-bitowym), a po niej bajty UTF-8 — dzięki temuReadStringwie, ile bajtów ma przeczytać. Do odczytu i zapisu danych w innym formacie (np. big-endian w protokołach sieciowych) służy klasaBinaryPrimitivesz przestrzeni nazwSystem.Buffers.Binary:Span<byte> bytes = stackalloc byte[4]; BinaryPrimitives.WriteInt32BigEndian(bytes, 100); // 00 00 00 64 int value = BinaryPrimitives.ReadInt32BigEndian(bytes);