File Attachments Module Overview

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. You can also use the ready-to-use FileData type that implements the IFileData interface.

  • FileAttachmentAttribute

    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.Base.Impl assemblies, respectively.

The FileAttachments module is designed individually for WinForms, ASP.NET and Mobile applications. So, it is represented by the FileAttachmentsWindowsFormsModule, FileAttachmentsAspNetModule and FileAttachmentsMobileModule module projects. These modules contain Property Editors and Controllers to work with the IFileData data type in WinForms, ASP.NET and Mobile applications, respectively.

To add the FileAttachments module to your application, use the Application Designer of the required application project.

Note

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 4 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, DevExpress.ExpressApp.FileAttachment.Web.FileDataPropertyEditor and DevExpress.ExpressApp.FileAttachments.Mobile.MobileFileDataPropertyEditor Property Editors are used to display your property in the default WinForms UI, Web Site UI and Mobile 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:

IFileDataWin

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.

    IFileDataWebViewMode

  • Edit Mode

    The Change File and Clear buttons are displayed using two ASPxButton controls.

    IFileDataWebEditMode

    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.

    FileDataEdit_FileDataPropertyEditor_Transparent

    The HtmlAnchor control is also displayed, so a user can download the current file in Edit mode.

The Mobile Property Editor for a FileData property supports only the file download.

MobileFileDataPropertyEditor

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:

FileTypeFilterAttribute

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.

See Also