minimal-api-file-upload

Implements secure file upload endpoints in ASP.NET Core minimal APIs.

Updated Jul 12, 2026
One-click install
npx skills add https://github.com/Patrick-Rex/DotNetTechSamples --skill minimal-api-file-upload-patrick-rex
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: minimal-api-file-upload
Source: https://github.com/Patrick-Rex/DotNetTechSamples/tree/main/.agents/plugins/dotnet-aspnetcore/skills/minimal-api-file-upload
Command: npx skills add https://github.com/Patrick-Rex/DotNetTechSamples --skill minimal-api-file-upload-patrick-rex

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building file upload endpoints in ASP.NET Core minimal APIs involves several non-obvious pitfalls: IFormFile binding rules, two separate size limits (Kestrel and FormOptions), automatic anti-forgery validation in .NET 8+, and security risks from trusting user-provided filenames or content types. This Skill provides correct, production-oriented patterns that avoid these common mistakes. ## Core Features & Use Cases - IFormFile Binding Patterns: Correctly bind single files, multiple files (IFormFileCollection), and mixed form fields using [FromForm] in minimal APIs. - Size Limit Configuration: Configure both Kestrel MaxRequestBodySize and FormOptions.MultipartBodyLengthLimit, plus per-endpoint overrides with RequestSizeLimit. - Security Validation: Validate uploads via magic bytes instead of trusting Content-Type or file extensions, and generate safe filenames to prevent path traversal attacks. - Large File Streaming: Use MultipartReader to stream very large files directly to disk without buffering. - Use Case: You are building a .NET 8+ API that accepts image uploads and keeps getting 400 errors or oversized request failures; this Skill walks you through anti-forgery opt-out, dual size limits, and content validation step by step. ## Quick Start Ask the AI to implement a secure file upload endpoint in an ASP.NET Core minimal API with size limits and content type validation.

Frequently Asked Questions about minimal-api-file-upload

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I handle file uploads in ASP.NET Core minimal APIs?

In .NET 8+ minimal APIs, IFormFile binds automatically from multipart/form-data when it is the only complex parameter. When mixing files with other form fields, apply [FromForm] to all form-bound parameters or group them into a single [FromForm] DTO.

How do I upload multiple files in a minimal API endpoint?

Use IFormFileCollection as the endpoint parameter, which binds automatically from multipart/form-data. You only need [FromForm] if you combine the collection with other form fields in the same endpoint.

Why does my file upload return 400 Bad Request in .NET 8?

In .NET 8+, UseAntiforgery() automatically validates anti-forgery tokens on all form-bound endpoints, including file uploads. For API-only endpoints, call .DisableAntiforgery(), which is safe for JWT or unauthenticated endpoints but not cookie-authenticated ones.

Why do large file uploads fail even after increasing Kestrel limits?

There are two separate limits: Kestrel MaxRequestBodySize (default 30MB) and FormOptions.MultipartBodyLengthLimit (default 128MB). You must configure both, or use [RequestSizeLimit] per endpoint, otherwise the upload fails at whichever limit is hit first.

When should I use MultipartReader instead of IFormFile?

Use MultipartReader for very large files where IFormFile's multipart parsing would buffer content in memory or spill to temp files. MultipartReader streams sections directly to storage in chunks, avoiding full-file buffering.

Is it safe to use IFormFile.FileName for the save path?

No, user-provided filenames can contain path traversal sequences like ../../../etc/passwd. Generate a safe filename with Guid.NewGuid() and derive the extension from validated content type or magic bytes instead of user input.