File uploads are one of those features that look simple on day one and become a reliability problem on day thirty. A developer adds IFormFile to a controller, it works in staging, and then production traffic hits and you're suddenly looking at memory spikes, timeouts, and files being silently truncated on high-load machines.
Choosing the right upload strategy isn't just a performance question — it's an architectural one. The trade-offs between buffered uploads, streaming, and cloud-direct approaches affect your memory footprint, server configuration, security posture, and the design of your entire request pipeline. If you want to go deeper with production-ready patterns, the complete implementation — including validation middleware, cloud upload wrappers, and virus-scan integration — is available on Patreon, alongside the annotated source code enterprise teams actually ship.
Understanding file uploads in isolation is useful, but seeing them wired into a complete production API — alongside rate limiting, global error handling, and output caching — is what makes the architecture click. That's exactly what Chapter 10 of the Zero to Production course covers, inside a full working codebase you can run immediately.
The Four Upload Strategies
ASP.NET Core supports four distinct approaches to handling incoming file data, each with different latency, memory, and scalability characteristics.
IFormFile (Buffered Model Binding) — The default. ASP.NET Core reads the entire multipart body, writes it to memory (under 64 KB) or a temp file on disk (over 64 KB), and then exposes it as an IFormFile object on the controller parameter. Simple to use, but the server must hold the entire file before your code runs a single line.
Buffered Manual Parsing — Explicitly reads the request body using MultipartReader but still reads chunks into memory or disk before processing. Useful when you need fine-grained control over section headers without taking the streaming trade-offs.
Streaming (Unbuffered) — Reads the multipart request body directly without buffering. Your handler processes bytes as they arrive, which means you can forward data to a database or storage service while the upload is still in progress. Lower memory footprint, but requires disabling request body buffering and cannot use model binding for form data alongside the file.
Cloud-Direct (Client-Side SAS / Pre-Signed URLs) — The client uploads directly to Azure Blob Storage, AWS S3, or similar using a short-lived pre-signed URL your API generates. The file never passes through your application server. Zero server memory cost, near-unlimited file size, and the storage provider handles throughput. The trade-off is that you lose in-transit validation — you must validate the file after it lands in storage, not while it's being received.
IFormFile is the right choice when all three of these are true:
Files are small — under 4 MB is the practical safe zone. Technically ASP.NET Core imposes a 28 MB default request body size limit (MaxRequestBodySize), but beyond 4 MB you begin to see meaningful memory pressure under concurrent load.
Concurrent upload volume is low. A form that handles a few submissions per minute is fine. An API endpoint that receives hundreds of concurrent large-file uploads will exhaust your Kestrel thread pool and temp disk space simultaneously.
Form data and the file travel together and need to be validated as a unit — e.g., a profile picture attached to a registration form where the user's details and the image are validated together before anything is saved.
Avoid IFormFile when:
File size exceeds 4 MB, especially on endpoints under production load
You're running in a containerised or serverless environment with limited ephemeral disk
You need to start processing (e.g., forwarding to object storage) before the entire file is received
The endpoint is a public-facing API that may receive adversarial requests with oversized bodies
When to Use Streaming
Streaming is the professional-grade default for APIs that accept file uploads as a primary feature. If your API exists primarily to ingest files — document processors, media platforms, data ingestion pipelines — streaming is not optional; it's the baseline.
With streaming, you disable ASP.NET Core's automatic request buffering using the [DisableRequestSizeLimit] attribute combined with [RequestFormLimits] configuration, and you read the multipart body manually via MultipartReader. Your handler begins forwarding to the storage layer before the upload is complete. Memory usage remains bounded regardless of file size or concurrency.
The cost is developer ergonomics. You cannot use [FromForm] model binding on the same action. Any metadata fields sent alongside the file must be parsed manually from the multipart sections. This is boilerplate that belongs in a shared base class or middleware — not duplicated across every upload endpoint.
Streaming is the right choice when:
Files routinely exceed 10 MB
The endpoint serves external clients (mobile apps, partner systems) over variable network conditions
You are running under strict memory constraints — Kubernetes pods with 512 MB limits, for example
You need to pipe the upload directly into an object storage write stream
When to Use Cloud-Direct Upload
Cloud-direct is architecturally the cleanest approach when your final destination is blob storage. You generate a pre-signed URL (Azure SAS token, AWS S3 pre-signed URL), return it to the client, and the client uploads directly. Your API receives only a completion event — either a callback or a polling request — once the upload finishes.
This approach eliminates the file-transit problem entirely. Your API server never touches the file bytes. Storage costs, bandwidth costs, and throughput are all handled by the storage provider. File sizes are limited only by the provider's limits, which are in the terabyte range.
The challenge is validation. You cannot inspect the file in transit. Post-upload validation requires a background trigger — an Azure Function, an event from S3, or a polling job — that runs virus scanning, content validation, and metadata extraction asynchronously. This adds latency between upload completion and the file being "ready" in your system. For workflows that require immediate feedback (e.g., a user uploads a profile photo and expects to see it immediately), you need a queued validation step and a loading state in the UI.
Cloud-direct is the right choice when:
Files are large (video, raw media, large data exports)
You're already using Azure Blob Storage, AWS S3, or Google Cloud Storage as your storage layer
Your team accepts asynchronous validation as a workflow pattern
Bandwidth cost is a concern — transferring gigabytes through your application server adds egress cost
Decision Matrix
| Scenario |
Recommended Strategy |
| Profile picture, avatar, thumbnail |
IFormFile |
| Form with attached document (PDF, <4 MB) |
IFormFile |
| Document management API, files 5–50 MB |
Streaming |
| Video upload, raw media, large exports |
Cloud-Direct |
| Data ingestion pipeline, files piped to DB |
Streaming |
| Mobile app with variable network conditions |
Streaming or Cloud-Direct |
| Multi-tenant SaaS with per-tenant storage |
Cloud-Direct |
| Internal tool, low traffic, simple form |
IFormFile |
How ASP.NET Core Handles File Limits
There are three distinct limits in the stack that affect uploads, and conflating them causes silent failures:
Kestrel's MaxRequestBodySize — Controls the maximum request body size at the server level. Default is 30 MB. Setting this to -1 disables the limit. This must be configured before the streaming/buffering decision is made, because Kestrel rejects oversized requests before your controller even runs.
IIS's maxAllowedContentLength — When hosted behind IIS, this is a separate limit that defaults to 30 MB. Both limits must be raised when accepting large uploads. Teams that raise only the Kestrel limit and host behind IIS see inexplicable 413s in production.
MultipartBodyLengthLimit — Controls the limit for individual multipart sections, not the total request body. This is what limits individual file size when using IFormFile. Default is 128 MB, but this limit is applied after the request is already buffered, so raising it without raising MaxRequestBodySize has no practical effect.
A mismatch between these three is the most common cause of upload bugs that only appear in production under IIS or reverse proxy configurations. See the ASP.NET Core Hosting Models guide for the full picture on how your hosting configuration interacts with request processing.
Security Considerations Every Upload Endpoint Needs
File upload endpoints are a persistent attack vector. The most common vulnerabilities are not complex — they're the basics that get skipped under delivery pressure.
File type validation must happen server-side. Trusting the Content-Type header or the file extension sent by the client is not validation. Read the file's magic bytes (the first few bytes of the binary content) and compare them against known signatures. Libraries like MimeDetective and FileSignatures do this for .NET.
Store uploads outside the web root. Files saved into wwwroot or any publicly accessible directory can be accessed directly via HTTP. Even if the filename is randomised, storing uploaded files in a path that ASP.NET Core serves statically bypasses every access control in your application.
Randomise filenames on save. Never use the client-provided filename. Always generate a new name server-side. The IFormFile.FileName property reflects what the client sent — it can contain path traversal sequences like ../../web.config.
Set a per-endpoint rate limit on upload endpoints. Unauthenticated or weakly authenticated upload endpoints are trivial to abuse. Use ASP.NET Core's rate limiting middleware with a named policy scoped to the upload endpoint — the Fixed Window vs Sliding Window vs Token Bucket guide covers the algorithm decision.
Virus scan asynchronously. Integrate a ClamAV scan or cloud-native scanning (Defender for Storage in Azure) into the post-upload flow. Do not block the upload on virus scanning — scan asynchronously and quarantine the file if a threat is detected.
Anti-Patterns That Cause Production Incidents
Saving the uploaded file to local disk on a stateless pod. Files saved to a container's local filesystem are lost on pod restart. In a horizontal-scaling environment, subsequent requests hit a different pod and the file is gone. Always write to shared storage.
Using IFormFile.OpenReadStream() multiple times in sequence. The stream is forward-only and not seekable. Reading it once for validation and then trying to read it again for saving will return an empty result on the second read. Copy the stream to a MemoryStream first if you need multiple reads — or, better, process in a single pass.
Ignoring the CancellationToken on upload endpoints. Clients disconnect mid-upload regularly on mobile networks. If your handler doesn't observe the cancellation token, you'll continue writing a partial file to storage after the client has already moved on, wasting I/O and storage space. Resource cleanup using IAsyncDisposable is especially important here — see the IDisposable vs IAsyncDisposable guide for the pattern.
Keeping uploads in memory "for now" on endpoints that will eventually be high-traffic. Teams regularly write IFormFile-based code during MVP development with the intention of optimising it later. Later rarely arrives. Design for the load you expect at month six, not the load you see on day one.
Deployment Considerations
When switching from buffered to streaming uploads, the order of middleware registration matters. UseRouting() must come before the upload endpoint is reached. DisableRequestSizeLimit must be applied before the request body is read — applying it in a filter that runs after model binding has no effect.
In load-balanced deployments, sticky sessions are not a solution to multi-part upload state problems. Use a resumable upload protocol (TUS protocol) or accept that uploads may need to restart on session loss. The TUS protocol has a .NET library (tusdotnet) that handles chunked, resumable uploads with pause/resume support.
For high-volume upload services, consider a dedicated upload service that handles only file ingestion, separated from your main API. This lets you scale upload capacity independently and apply different server-level limits without affecting your main API's configuration.
☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!
FAQ
What is the default maximum file upload size in ASP.NET Core? The default MaxRequestBodySize in Kestrel is approximately 30 MB (28.6 MB, or 30,000,000 bytes). The default MultipartBodyLengthLimit is 128 MB. Both must be configured to accept larger uploads, and if you're hosting behind IIS, you also need to raise maxAllowedContentLength in web.config.
Should I use IFormFile or streaming for files under 10 MB? For files under 4 MB on low-to-moderate traffic endpoints, IFormFile is perfectly appropriate and produces much simpler code. For files between 4 MB and 10 MB, the decision depends on concurrent upload volume. If your endpoint handles dozens of simultaneous uploads, streaming is the safer choice even in this size range.
How do I validate file type securely in ASP.NET Core? Do not trust the Content-Type header or file extension. Read the first several bytes of the file and compare them against known magic byte signatures for the allowed types. Libraries like MimeDetective and FileSignatures provide this for .NET with a curated signature database. Validate before writing the file to any storage layer.
Can I use both IFormFile and streaming in the same application? Yes. The upload strategy is per-endpoint. Low-risk, small-file endpoints (avatars, configuration files) can use IFormFile, while high-volume or large-file endpoints use streaming. There is no global setting that forces one approach across all endpoints — each action configures its own limits via attributes and middleware.
What is the difference between MaxRequestBodySize and MultipartBodyLengthLimit?MaxRequestBodySize is a Kestrel-level limit on the total HTTP request body size before any content is parsed. MultipartBodyLengthLimit is an ASP.NET Core model binding limit applied per multipart section. For a multipart upload with a single file, the effective limit is the lower of the two. Raising one without raising the other will not allow larger uploads.
How do cloud-direct uploads affect data validation and compliance? With cloud-direct uploads, data leaves the client and lands in storage without passing through your application's validation logic. For compliance-sensitive workloads (HIPAA, GDPR data subject files, PCI-adjacent uploads), you must validate content after it lands in storage using a triggered process. Azure Defender for Storage and AWS Macie provide automated policy enforcement at the storage layer.
What is the TUS protocol and when should I use it in .NET? TUS is an open protocol for resumable file uploads. It allows uploads to be paused and resumed without restarting from scratch, which is critical for large files on unreliable networks. The tusdotnet NuGet package implements TUS server-side in ASP.NET Core. Use it when your users regularly upload files over 100 MB or from mobile connections where session interruptions are common.
