FileField

A FileField is used to store and manage files that are uploaded by users. It extends the IFileField interface, which defines methods to handle file upload and storage.

File security

Please be aware that uploaded files are not monitored for malicious code or file format validity. Such checks should be performed by dedicated security applications.

Additional arguments

Each FileField is associated with an IFileStorage, which is provided as additional constructor argument. To add the field to a resource call:

FileField.Make(string label, string name, IFileStorage fileStorage).

The file storage defines how files are stored by the application.

FileStorage variants

There are currently two variants of IFileStorage available.

DatabaseFileStorage

A DatabaseFileStorage saves each file as a database record. Its respective field in the entity model must be of a compatible type such as a byte[].

Storing files in a database

A DatabaseFileStorage is best used for smaller file sizes, otherwise performance of the whole database may suffer. For larger files, we recommend you use local file storage instead.

LocalFileStorage

A LocalFileStorage saves each file to a local folder of your choice. The entity stores the file path, therefore the respective field type in the entity model is string.

INFO

Make sure that the application has all relevant permissions to access and modify files in the storage folder.

Example usage

We want to store manual documents for products in our demo application. We estimate that file sizes will remain relatively small. The product model class will store the manual file in a byte[]. Note, that we make the property nullable as some of the company's products might not have a manual, such as the camper vans.

public class Product
{
    [Key]
    public int Id { get; init; }
    public byte[]? Manual { get; set; }
}

The associated FileField can then be added to the product resource's fields. Please note how the field is initialized with a DatabaseFileStorage object.

public override IList<IResourceFieldBuilder> Fields()
{
    return 
    [
        FileField.Make(
                "Product Manual", 
                nameof(Product.Manual), 
                new DatabaseFileStorage()
            )
    ];
}

Additional configuration

There are several features exclusive to FileField, that can be configured after field initialization.

Storing filenames

Filenames are randomly generated during file upload. If you want to store the original filename alongside the file you need to specify a property in the entity model that references the filename as a string property. Here we make the filename property optional, as we might not want to upload a manual for every product.

public class Product
{
    [Key]
    public int Id { get; init; }
    public byte[]? Manual { get; set; }
    public string? ManualFilename {get; set;}
}

After setting up the database column, call StoreOriginalFilename(string columnName) after field initialization.

public override IList<IResourceFieldBuilder> Fields()
{
    return 
    [
        FileField.Make(
                "Product Manual", 
                nameof(Product.Manual), 
                new DatabaseFileStorage()
            )
            .StoreOriginalFilename(nameof(Product.ManualFilename)), 
    ];
}

Filename length

Different operating systems have different limits regarding filename length. To prevent any problems you may want to consider limiting the size of the filename property with a [MaxLength(int length)] attribute.

Storing file sizes

Storing the file size works similarly to storing the filename. Again, you need to create a property in the entity model to store the original file size in. File sizes are expressed in bytes as long values.

public class Product
{
    public int Id { get; init; }
    public byte[]? Manual { get; set; }
    public long ManualFileSize {get; set;}
}

After setting up the database column, call StoreOriginalFilesize(string columnName) after field initialization.

public override IList<IResourceFieldBuilder> Fields()
{
    return 
    [
        FileField.Make(
                "Product Manual", 
                nameof(Product.Manual), 
                new DatabaseFileStorage()
            )
            .StoreOriginalFilesize(nameof(Product.ManualFileSize)), 
    ];
}

Limiting file sizes

You can limit the allowed size of uploaded files by chaining MaxAllowedFileSize(long fileSize). The fileSize parameter represents the maximum size in bytes. If you want to limit the size in bigger units, such as megabytes, you can multiply by the appropriate factor.

For a limit in megabytes, you can input fileSize * 1024 * 1024.

The file upload is limited to 2 megabytes by default.

Allowed extensions

In many cases, you may want to restrict the types of files a user can upload. You can limit file extensions with AllowFileExtensions(string[] allowedExtensions).

For example, for our product manual we may only want to allow PDF files:

public override IList<IResourceFieldBuilder> Fields()
{
    return 
    [
        FileField.Make(
                "Product Manual", 
                nameof(Product.Manual), 
                new DatabaseFileStorage()
            )
            .AllowFileExtensions([".pdf"]), 
    ];
}

File type validation

This feature is for usability purposes only, we do not validate file associated MIME-types.

Field display

A FileField is displayed on Index and Details views with a 'Download' button for the file.

In the Update view you will also see a 'Delete' button to remove the file from the entity.

In Create and Update views a user will see a file input field. If you have configured a list of allowed file extensions, only relevant files can be selected in the user's file explorer.

Visibility

The default visibility values are as follows:

Resource View	Default
Index	visible
Create	visible
Update	visible
Details	visible

You can change the visibility of the field for each view. Please note, however, that fields should remain visible on Create pages if the field is required by the entity model and if no default value is set.