File Attachments Module
- 7 minutes to read
File manipulation is needed in almost every business application. For example, an application can have an Employee business object with File and Portfolio properties. These properties should support operations such as file attachment, saving, opening and downloading. The eXpressApp Framework supplies special data types, and the FileAttachments module to process them. The FileAttachments module provides Property Editors and Controllers to perform these operations with special file data types. This topic details the potential provided by these data types, together with the module, to extend applications with file manipulations. To see an example of how to implement a business class that has a file data property or a file collection property, refer to the How to: Implement File Data Properties topic.
Overview
The eXpressApp Framework‘s Business Class Library supplies a special interface and attribute to work with files:
IFileData interface
Implement this interface to develop the data type that enables an end-user to attach a file to a business object. To see an example, refer to the FileData class sources at %PROGRAMFILES(x86)%\DevExpress 20.2\Components\%PROGRAMFILES(x86)%\DevExpress 20.2\.NET Core Desktop Libraries\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl\FileData.cs, or to the following articles: How to: Store file attachments in the file system instead of the database | How to: Store file attachments in Dropbox instead of the database(video). You can also use the ready-to-use FileData type that implements the IFileData interface.
-
This attribute specifies the property which returns an IFileData type value. Use this attribute to develop the data type that enables an end-user to attach file collections to a business object. You can also use the ready-to-use FileAttachmentBase type that applies the FileAttachment attribute.
The interface, attribute and ready-to-use data types mentioned above are contained in the DevExpress.Persistent.Base and DevExpress.Persistent.BaseImpl assemblies, respectively.
The FileAttachments module is designed individually for WinForms, ASP.NET, and Blazor applications. So, it is represented by the FileAttachmentsWindowsFormsModule, FileAttachmentsAspNetModule and FileAttachmentsBlazorModule modules. These modules contain Property Editors and Controllers to work with the IFileData data type in WinForms, ASP.NET and Blazor applications, respectively.
To add the FileAttachments module to your application, use the Application Designer of the required application project.
Note
You can add modules to your application when you create a new XAF solution using the Solution Wizard. To do this, select modules in the Choose Extra Modules step.
- To add an extra module in code, add it to the XafApplication.Modules or ModuleBase.RequiredModuleTypes list (adding a reference to the module assembly is insufficient).
Attached files are stored in the database in binary representation. When using the FileData type, gzip compression is applied and the maximum file size is 2 gigabytes. Information about the file name is also stored. Alternatively, you can implement a file system storage as it is demonstrated in the How to: Store file attachments in the file system instead of the database Code Central example.
Tip
To save the file stored within the current FileData object to the specified stream, use the IFileData.SaveToStream method.
IFileData Type Properties and Methods
If you add an IFileData type property to your business class, the DevExpress.ExpressApp.FileAttachment.Win.FileDataPropertyEditor and DevExpress.ExpressApp.FileAttachment.Web.FileDataPropertyEditor Property Editors are used to display your property in the default WinForms and ASP.NET WebForms UI, respectively.
The WinForms Property Editor for a FileData property provides the following features for end-users:
Attach a File
When an end-user clicks the ellipsis button on the FileDataPropertyEditor, the OpenFileDialog dialog is invoked, which allows the addition of the required file.
Save an Attached File to Disk
An end-user can invoke the context menu for the FileDataPropertyEditor. This menu contains the SaveTo Action. This Action’s Execute event is handled by the FileAttachmentController‘s SaveFileData method. So, you can override this method in the FileAttachmentController descendant, to perform specific code when executing this Action.
Open an Attached File
An end-user can invoke the context menu for the FileDataPropertyEditor. This menu contains the Open Action. This Action’s Execute event is handled by the FileAttachmentController‘s Open method. So, you can override this method in the FileAttachmentController descendant to perform specific code when executing this action.
Detach a File
An end-user can invoke the context menu for the FileDataPropertyEditor. This menu contains the ClearContent Action. This Action’s Execute event handler calls the property type’s Clear method, to clear the file content. Implement the IFileData interface, or override the FileData class to define the Clear method in your own way.
The following image demonstrates the FileDataPropertyEditor in a WinForms application:
The Web property editor for the FileData property displays the FileDataEdit control, which displays a different set of controls in View mode and Edit modes:
View Mode
Displays the HtmlAnchor control which allows users to download the current file.
Edit Mode
The Change File and Clear buttons are displayed using two ASPxButton controls.
The Clear button allows end-users to clear a property value. For this purpose, the property type’s Clear method is called. You can implement the IFileData interface or override the FileData class to define the Clear method in your own way.
A click on the Change File button makes ASPxUploadControl visible, which allows end-users to upload a new file.
The HtmlAnchor control is also displayed, so a user can download the current file in Edit mode.
You can attach and get files in code. The LoadFromStream and SaveToStream methods are used for this purpose. Note that the LoadFromStream method does not require a full path to the file, it takes just a file name as the first parameter.
Refer to the File Attachment Properties section in our documentation to learn more about file attachment properties creation.
File Type Filters in the Open Dialog
In XAF WinForms applications, you can specify the file type filters that must appear in the Open dialog’s “Files of type” box:
The required file type filters can be specified in code by applying the FileTypeFilterAttribute attribute, or by modifying the Application Model. For detailed information, refer to the FileTypeFilterAttribute class description.
File Attachments Module Specifics in WinForms Applications
The WinForms FileAttachments module allows you to customize the approach used to open and save the attached files.
CustomOpenFileWithDefaultProgram
By default, to open an attached file, the module saves it to the operating system’s temporary folder, and then passes the saved file to the operating system to open. Then, the operating system searches for a default program and starts it. The module does not delete the saved file, because it cannot determine when a file becomes unnecessary. So, the end-user is responsible for the temporary folder’s content.
You can implement custom behavior. To do this, handle the FileAttachmentsWindowsFormsModule.CustomOpenFileWithDefaultProgram event. To cancel the default behavior, set the handler’s Handled parameter to true. To access the module, use the XafApplication.Modules property of your WinApplication class instance in a custom Controller.
CustomSaveFiles
By default, to save an attached file, the SaveFile dialog is invoked. An end-user saves the file to the required folder (by default, MyDocuments is offered).
You can implement a custom behavior. To do this, handle the FileAttachmentsWindowsFormsModule.CustomSaveFiles event. To cancel the default behavior, set the handler’s Handled parameter to true. To access the module, use the XafApplication.Modules property of your WinApplication class instance in a custom Controller.
File Attachments Module Specifics in ASP.NET Web Applications
The default file upload size supported by ASP.NET is 4 MB. This limit is used to prevent denial of service attacks caused by users posting large files to the server. You can change the limit by specifying the httpRuntime element’s maxRequestLength attribute in the Web.config file. The following code snippet illustrates this.
<configuration>
<system.web>
<httpRuntime maxRequestLength="16384" />
</system.web>
</configuration>
Note however, that it is not recommended to set it to more than 10-20 megabytes. For additional information, refer to the httpRuntime Element (ASP.NET Settings Schema) MSDN article.
See the property editors described here in the Property Editors section of the Feature Center Demo, which is installed with XAF, or refer to the Feature Center Demo online to see these editors in action.