WriteableFileProviders.AzureBlob 2027.1.1

WriteableFileProviders.AzureBlob

An Azure Blob Storage container as an IWriteableFileProvider, on Azure.Storage.Blobs 12. Part of WriteableFileProviders.

Install

dotnet add package WriteableFileProviders.AzureBlob

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.AzureBlob;

await using var files = new WriteableAzureBlobFileProvider(new AzureBlobFileProviderOptions
{
    AccountName = "contoso",
    AccountKey = configuration["Storage:Key"],
    ContainerName = "files",
    RootDirectoryPath = "tenants/acme",
});

await files.UpdateFileAsync("reports/2026.csv", stream, new UpdateFileOptions { ContentType = "text/csv" });
var url = await files.GetSignedUrlAsync("reports/2026.csv", new SignedUrlOptions { Validity = TimeSpan.FromMinutes(15) });

From configuration (services.AddWriteableFileProvider(section)):

{ "Files": { "Type": "WriteableAzureBlobFileProvider", "AccountName": "contoso", "AccountKey": "...", "ContainerName": "files" } }

Or pass a BlobContainerClient you build (managed identity, retries, Aspire). The provider never disposes it, and reads only RootDirectoryPath and CreateContainerIfMissing from the options:

var container = new BlobContainerClient(new Uri("https://contoso.blob.core.windows.net/files"), new DefaultAzureCredential());
await using var files = new WriteableAzureBlobFileProvider(new AzureBlobFileProviderOptions(), container);

Configuration

Authentication

• Shared key (AccountName, AccountKey). Signed URLs are service SAS.
• Microsoft Entra ID (UseDefaultAzureCredential, or your client with a TokenCredential). Give the identity a data role on the container, such as Storage Blob Data Contributor. Signed URLs are user delegation SAS, which also need generateUserDelegationKey at the account scope (Storage Blob Delegator grants it).
• A SAS URL or anonymous client. Everything the SAS allows works; signed URLs throw NotSupportedException.

What's different

• Files are block blobs. A write commits its blocks in one request, so readers never see half a file, and IfMatch and IfNotExists are atomic.
• Two writers at once: if another commit lands while yours stages, a write up to 8 MiB is staged again (5 attempts in all). A larger one throws IOException and stores nothing; a conditional one, PreconditionFailedException.
• Appends add blocks only to an unchanged file, retrying up to 5 times, then throw PreconditionFailedException.
• Append blobs written by 2026 stay readable. The first write turns one into a block blob through a temp blob in .wfp-tmp/ (hidden from listings); after that, a 2026 provider can't append to it. Upgrade all writers together.
• Moves and copies run on the server. A move deletes the source only if it is unchanged; otherwise it removes the copy. A copy still pending after 10 minutes is aborted with IOException.
• Snapshots are kept. Deleting or moving a blob that has snapshots throws IOException and leaves it as it was.
• Signed URLs are SAS for read, create and write, up to 7 days. A 7-day user delegation SAS needs AllowShorterValidity, as its key lives just under 7 days. Upload URLs can't carry a content type; the gateway's can.
• Limits: a write from a stream that can't seek is at most 50,000 blocks of 8 MiB (about 390 GiB). Page blobs are read-only. Watch throws NotSupportedException.

Learn more

• The guide: reading and writing, signed URLs, errors, providers compared.
• Moving from 2026.