WriteableFileProviders.Physical 2027.0.0

WriteableFileProviders.Physical

A folder on the local disk as an IWriteableFileProvider, with atomic writes and change notifications. Part of WriteableFileProviders.

Install

dotnet add package WriteableFileProviders.Physical

Needs .NET 10, and is native AOT compatible. Keep every WriteableFileProviders package in an app on the same major version.

Use

using WriteableFileProviders;
using WriteableFileProviders.Physical;

await using var files = new WriteablePhysicalFileProvider("/srv/files");

await files.UpdateFileAsync("reports/2026.csv", stream);                // creates reports/ if missing
await files.UpdateFileAsync("app.log", line, UpdateFileOptions.Append);
await using var slice = await files.ReadRangeAsync("big.bin", 1_000_000, 4096);
var changed = files.Watch("reports/*.csv");

From configuration, with WriteableFileProviderSerializer.FromConfiguration(section) or services.AddWriteableFileProvider(section):

{ "Files": { "Type": "WriteablePhysicalFileProvider", "RootDirectoryPath": "/srv/files" } }

Configuration

Authentication

None. The provider reads and writes with the permissions of the process.

What's different

• Writes are atomic. An overwrite, an append, a copy or a local stream's commit writes .wfp-<guid>.tmp next to the target, then renames it over the target. Listings hide these files; a crash can leave one, which you can delete.
• An append copies the whole file, so frequent appends to a large file (a log) are expensive.
• A write puts a new file at the path. Other hard links keep the old content, and a symbolic link at the path becomes a file. On Windows the file takes the folder's permissions; on Linux and macOS, the old file's mode bits. ACLs and extended attributes are not kept.
• IfMatch is not atomic. It is checked just before the rename. ETags come from the last-write time and length.
• On Windows, a write to a file that is open for reading fails (UnauthorizedAccessException or IOException), and the file keeps its content. Linux and macOS let the write go ahead.
• Case is ignored on Windows and macOS, and matters elsewhere. : is refused in names everywhere. On Windows, so are names Windows can't hold or would read as another name: report.txt., a?b, CON, con.txt. Listings leave out such names, and on Linux and macOS, names holding : or \.
• Symbolic links and junctions inside the root are followed, wherever they point. A recursive listing lists a linked folder but doesn't walk into it.
• No content types. UpdateFileOptions.ContentType is ignored; ContentType is null.
• Watch works like ASP.NET Core's PhysicalFileProvider: a glob relative to the root. Hidden and dot-prefixed files aren't watched. Where file system events don't arrive (some network and container mounts), set DOTNET_USE_POLLING_FILE_WATCHER=1.
• No native signed URLs. GetSignedUrlAsync throws NotSupportedException. For download and upload links, use the gateway in WriteableFileProviders.AspNetCore.

Learn more

• Getting started: local files first, then download links through the gateway.
• The guide: reading and writing, paths and listings, errors, providers compared.
• Moving from 2026.