C# web service methods file upload and download

ASP.NET Core supports uploading one or more files using buffered model binding for smaller files and unbuffered streaming for larger files.

View or download sample code (how to download)

Security considerations

Use caution when providing users with the ability to upload files to a server. Attackers may attempt to:

• Execute denial of service attacks.
• Upload viruses or malware.
• Compromise networks and servers in other ways.

Security steps that reduce the likelihood of a successful attack are:

• Upload files to a dedicated file upload area, preferably to a non-system drive. A dedicated location makes it easier to impose security restrictions on uploaded files. Disable execute permissions on the file upload location.†
• Do not persist uploaded files in the same directory tree as the app.†
• Use a safe file name determined by the app. Don't use a file name provided by the user or the untrusted file name of the uploaded file.† HTML encode the untrusted file name when displaying it. For example, logging the file name or displaying in UI (Razor automatically HTML encodes output).
• Allow only approved file extensions for the app's design specification.†
• Verify that client-side checks are performed on the server.† Client-side checks are easy to circumvent.
• Check the size of an uploaded file. Set a maximum size limit to prevent large uploads.†
• When files shouldn't be overwritten by an uploaded file with the same name, check the file name against the database or physical storage before uploading the file.
• Run a virus/malware scanner on uploaded content before the file is stored.

†The sample app demonstrates an approach that meets the criteria.

For more information on implementing security measures, including examples from the sample app, see the Validation section.

Storage scenarios

Common storage options for files include:

• Database

  • For small file uploads, a database is often faster than physical storage (file system or network share) options.
  • A database is often more convenient than physical storage options because retrieval of a database record for user data can concurrently supply the file content (for example, an avatar image).
  • A database is potentially less expensive than using a data storage service.

• Physical storage (file system or network share)

  • For large file uploads:
    • Database limits may restrict the size of the upload.
    • Physical storage is often less economical than storage in a database.
  • Physical storage is potentially less expensive than using a data storage service.
  • The app's process must have read and write permissions to the storage location. Never grant execute permission.

• Data storage service (for example, Azure Blob Storage)

  • Services usually offer improved scalability and resiliency over on-premises solutions that are usually subject to single points of failure.
  • Services are potentially lower cost in large storage infrastructure scenarios.

  For more information, see Quickstart: Use .NET to create a blob in object storage.

File upload scenarios

Two general approaches for uploading files are buffering and streaming.

Buffering

The entire file is read into an IFormFile, which is a C# representation of the file used to process or save the file.

The resources (disk, memory) used by file uploads depend on the number and size of concurrent file uploads. If an app attempts to buffer too many uploads, the site crashes when it runs out of memory or disk space. If the size or frequency of file uploads is exhausting app resources, use streaming.

Buffering small files is covered in the following sections of this topic:

Streaming

The file is received from a multipart request and directly processed or saved by the app. Streaming doesn't improve performance significantly. Streaming reduces the demands for memory or disk space when uploading files.

Streaming large files is covered in the Upload large files with streaming section.

Upload small files with buffered model binding to physical storage

To upload small files, use a multipart form or construct a POST request using JavaScript.

The following example demonstrates the use of a Razor Pages form to upload a single file (Pages/BufferedSingleFileUploadPhysical.cshtml in the sample app):

The following example is analogous to the prior example except that:

• JavaScript's (Fetch API) is used to submit the form's data.
• There's no validation.

To perform the form POST in JavaScript for clients that don't support the Fetch API, use one of the following approaches:

• Use a Fetch Polyfill (for example, window.fetch polyfill (github/fetch)).

• Use . For example:

In order to support file uploads, HTML forms must specify an encoding type () of .

For a input element to support uploading multiple files provide the attribute on the element:

The individual files uploaded to the server can be accessed through Model Binding using IFormFile. The sample app demonstrates multiple buffered file uploads for database and physical storage scenarios.

When uploading files using model binding and IFormFile, the action method can accept:

The following example:

• Loops through one or more uploaded files.
• Uses Path.GetTempFileName to return a full path for a file, including the file name.
• Saves the files to the local file system using a file name generated by the app.
• Returns the total number and size of files uploaded.

Use to generate a file name without a path. In the following example, the path is obtained from configuration:

The path passed to the FileStreammust include the file name. If the file name isn't provided, an UnauthorizedAccessException is thrown at runtime.

Files uploaded using the IFormFile technique are buffered in memory or on disk on the server before processing. Inside the action method, the IFormFile contents are accessible as a Stream. In addition to the local file system, files can be saved to a network share or to a file storage service, such as Azure Blob storage.

For another example that loops over multiple files for upload and uses safe file names, see Pages/BufferedMultipleFileUploadPhysical.cshtml.cs in the sample app.

Upload small files with buffered model binding to a database

To store binary file data in a database using Entity Framework, define a Byte array property on the entity:

Specify a page model property for the class that includes an IFormFile:

The is used in the Razor Pages form:

When the form is POSTed to the server, copy the IFormFile to a stream and save it as a byte array in the database. In the following example, stores the app's database context:

The preceding example is similar to a scenario demonstrated in the sample app:

• Pages/BufferedSingleFileUploadDb.cshtml
• Pages/BufferedSingleFileUploadDb.cshtml.cs

Upload large files with streaming

The following example demonstrates how to use JavaScript to stream a file to a controller action. The file's antiforgery token is generated using a custom filter attribute and passed to the client HTTP headers instead of in the request body. Because the action method processes the uploaded data directly, form model binding is disabled by another custom filter. Within the action, the form's contents are read using a , which reads each individual , processing the file or storing the contents as appropriate. After the multipart sections are read, the action performs its own model binding.

The initial page response loads the form and saves an antiforgery token in a cookie (via the attribute). The attribute uses ASP.NET Core's built-in antiforgery support to set a cookie with a request token:

The is used to disable model binding:

In the sample app, and are applied as filters to the page application models of and in using Razor Pages conventions:

Since model binding doesn't read the form, parameters that are bound from the form don't bind (query, route, and header continue to work). The action method works directly with the property. A is used to read each section. Key/value data is stored in a . After the multipart sections are read, the contents of the are used to bind the form data to a model type.

The complete method for streaming to a database with EF Core:

(Utilities/MultipartRequestHelper.cs):

The complete method for streaming to a physical location: