Uploads

StreamFilesAsync reads a multipart body one section at a time. Files are handed to a callback as they arrive and never held, so the memory an upload costs does not grow with its size — a request larger than available memory is fine, provided the callback streams rather than collects.

The shape

using ApricotFramework.AspNetCore.Extensions.ModelBinding;
using ApricotFramework.AspNetCore.Extensions.Uploads;

[HttpPost("upload")]
[DisableFormValueModelBinding]
public async Task<IActionResult> Upload(CancellationToken cancellationToken)
{
    var fields = await this.Request.StreamFilesAsync(
        file => blobStore.WriteAsync(file.FileName, file.OpenReadStream(), cancellationToken),
        cancellationToken);

    return this.Ok(new { Title = fields["title"].ToString() });
}

The callback runs once per file section. The return value is the request's non-file fields, in the order they were declared, as an ordinary IFormCollection.

How large a file can be

This library sets no ceiling on a file. It leaves MultipartReader.BodyLengthLimit unset, and each file is handed over as a stream, so nothing here has to hold one.

The limit you will actually hit is the server's. Kestrel caps a request body at 30 MB (30000000 bytes) by default, and rejects anything larger with 413 Payload Too Large before your callback runs.

builder.WebHost.ConfigureKestrel(options =>
{
    options.Limits.MaxRequestBodySize = 2048L * 1024 * 1024;   // 2 GB, or null for no limit
});

With the cap raised, 1 GB through a single request completes in about a second and process memory does not move — measured, not assumed. What matters is the callback: streaming it onward costs nothing, while CopyToAsync into a MemoryStream reintroduces the whole file.

FormOptions.MultipartBodyLengthLimit, the 128 MB cap you may have met elsewhere, does not apply. It belongs to ReadFormAsync, which this bypasses entirely.

The other limits worth knowing, none of which is about file size:

Two rules about the file stream

A file is only readable for the duration of its callback. The next section cannot be reached until this one has been consumed, so a reference kept past the callback points at a stream that has already moved on.

Reading the next section drains whatever the callback left, so ignoring a file, or reading only part of it, is safe — the sections after it are still found correctly.

Length is not available

IFormFile.Length reports MultipartFile.UnknownLength, which is -1.

Fields

Non-file sections are collected rather than streamed, so unlike files they are bounded — see the table above for the values.

A section header limit of 16 KB is also what bounds field names, since a name arrives inside Content-Disposition. A section declaring no name at all is skipped rather than filed under an empty key.

Character encoding comes from each section's own charset, falling back to UTF-8 when it declares none or declares something unparseable.

Binding the fields to a model

using System.Globalization;

var values = fields.ToValueProvider(CultureInfo.InvariantCulture);

ToValueProvider presents the collected fields as an MVC IValueProvider, which is what TryUpdateModelAsync consumes.

Errors

An empty or already-consumed body reports the likely cause by name, because reading it as an empty upload — which this library used to do — hides a wiring mistake behind a successful response.

Behaviour worth knowing

Verified against bodies produced by curl, not by this library:

• A file name containing quotes and semicolons is preserved verbatim; it cannot break out of the header it arrived in.
• A body containing what looks like its own boundary is read as data, not as a section break.
• A zero-byte file is a file, and the callback runs for it.
• Non-ASCII file names and content survive unchanged.