Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]UI Construction
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Collapse]Extra Modules
   [Expand]Audit Trail Module Overview
    Business Class Library Customization Module
    Chart Module
    Clone Object Module
   [Expand]Conditional Appearance Module Overview
   [Expand]Dashboards Module
    File Attachments Module Overview
    HTML Property Editor Module
   [Expand]Notifications Module
    KPI Module
   [Expand]Maps Module
   [Expand]Pivot Chart Module
    Pivot Grid Module
   [Expand]Reports V2 Module
   [Expand]Reports Module (Obsolete)
   [Expand]Scheduler Module
    Script Recorder Module
   [Expand]State Machine Module
   [Expand]TreeList Editors Module
   [Expand]Validation Module
    View Variants Module
   [Expand]Workflow Module
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
[Expand]End-User Documentation

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.

Expanded 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.

Expanded 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:

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.

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

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.

Expanded 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.

Expanded 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.

Expanded 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.

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.

Expanded See Also

How would you rate this topic?​​​​​​​