Files, storage and streams
System.Storage describes provider-bound paths, files and directories. System.IO supplies asynchronous byte streams, text readers and writers. Await their Task results; storage lookup/open operations remain immediate. See setup for toolchain requirements.
Resolve a directory and work with files
The Storage POC resolves a directory through FileSystem, writes a file, reads UTF-8 through StreamReader, seeks and reads again, and lists files and directories. Its source and expected output are available with the guide.
async func Main() -> Task<()> {
let provider: StorageProvider = FileSystem("storage-demo")
match provider.GetDirectory(Parse("/")) {
Ok(let directory) => await Explore(directory)
Failure(let error) => Panic(error.ToString())
}
return ()
}
StorageProvider resolves paths through GetItem, GetFile and GetDirectory. StorageItem is a closed interface hierarchy with File and Directory branches. FileSystem supplies host-backed implementations; the memory provider sample uses the same interfaces with in-memory contents. Name and Path describe represented state without an implicit lookup. File opens byte streams; Directory resolves children.
Paths and lookup
Path.Parse validates logical slash-based syntax and preserves accepted spelling. Equality and hashing use that spelling, not filesystem identity, case folding or Unicode normalization. Providers decide how a valid Path resolves. Other APIs can accept text without requiring callers to adopt Path universally.
Directory.FileAt describes an address; GetFile explicitly checks it. A successful lookup cannot guarantee that a later open succeeds. Relative paths resolve within a directory; absolute paths belong to provider-level lookup. The directory string overload accepts one child name. GetItems produces a bounded synchronous snapshot.
Path API · Storage items · Provider contract · Lookup
Byte and text I/O
FileInputStream and FileOutputStream provide bounded reads and writes, exclusive creation and explicit close. InputStream and OutputStream express separate capabilities; optional seekability is separate. MemoryStream provides in-memory byte storage. Callers retain buffers until settlement. Reads may be short; successful writes cover the requested range.
StreamReader decodes strict UTF-8; StreamWriter awaits complete encoded writes. ReadToEnd decodes chunks incrementally and reports malformed input before EOF when detected. It still returns one accumulated String; errors return no partial text. See the reader contract. Callers await flushing and close explicitly. FileText supplies bounded whole-file text helpers. Console exposes the same text and byte interfaces through standard streams.
Streams and ownership · Console
Selected text encodings
StreamReader and StreamWriter accept an Encoding, with
UTF-8 as the default. Encodings.Ascii selects strict ASCII. Both adapters retain
the leaveOpen option. Lines are recognized after decoding; unsupported ASCII output
fails before writing. StreamWriter uses bounded encoder output and
provides Finish to observe final conversion bytes/errors. Flush handles the stream;
Close releases ownership. Await Finish and Flush explicitly when required before
Close. See selected encoding contracts.
Behavior and limits
Compared with .NET Stream capability flags, separate interfaces express readable, writable and seekable operations at the cost of more contracts and adapters. Storage paths describe provider addresses rather than universal native file identity.
Calls block; async and incremental enumeration are not implemented. Writes are not transactional or guaranteed atomic, and a failure after opening may leave partial output. Flush does not promise durable storage. Memory and host providers can have different bounds and supported operations. Match named storage/stream error cases. EntryKind is a non-flags enum with File = 1 and Directory = 2; zero is unnamed.
The File Transformer is an application experiment using its own bounded JSON parser. The separate public JSON API supports DOM and flat object mapping; it does not change that sample's contract.
Physical file watching (development)
System.IO.FileSystemWatcher watches a physical directory and delivers callbacks
on the invocation completion queue. It supports filename filters, recursive watching,
creation/change/deletion/rename notifications, errors and explicit disposal.
System.Storage retains its provider-based File/Directory model.
Use watcher.Subscribe(callback) to receive FileSystemNotification. Match its
Created, Changed, Deleted, Renamed and RescanRequired cases; rename payloads always
contain old and new paths. Dispose the returned registration to release the callback.
The configuration watcher sample subscribes to changes and debounces calls to JsonConfigurationProvider.TryLoad. Failed reads preserve previous settings; notifications can be duplicated or lost, so consumers must also handle errors by re-reading current state.
Windows and macOS are the release priorities. macOS is the local qualification target; Windows execution and broader platform coverage remain tracked gates. See API, deployment and limitations.
Possible directions
A file catalog can guide richer metadata queries, freshness rules and enumeration. Async stream ownership and provider-neutral information need concrete use cases. Windows/Unix path normalization and broader attributes remain open design work.
Reference and feedback
Report a small program, toolchain revision, expected behavior and observed output. See how to contribute.
Default arguments (development)
Cancellation-aware operations now use cancellationToken: CancellationToken = default
in place of redundant forwarding overloads. Omitting it uses a non-cancellable token;
passing an explicit token keeps the existing cancellation behavior. Rebuild binary
consumers against matching libraries. See parameter defaults and migration.