File Attachments (Store Custom Files)
- 7 minutes to read
The eXpressApp Framework supplies the File Attachments module and special file data types for file manipulation (upload, download, open, and save files). This module contains Property Editors and Controllers for the file data type.
Supported Functionality
WinForms
- Attach a File
- When a user clicks the ellipsis button on the FileDataPropertyEditor, the OpenFileDialog dialog is invoked to select a file that should be attached.
- Save an Attached File to a Disk
- The FileDataPropertyEditor context menu contains the SaveTo Action. The FileAttachmentController‘s SaveFileData method handles this Action’s Execute event. You can override this method in the FileAttachmentController descendant to change the default logic.
- Open an Attached File
- The FileDataPropertyEditor context menu contains the Open Action. The FileAttachmentController‘s Open method handles this Action’s Execute event. You can override this method in the FileAttachmentController descendant to change the default logic.
- Detach a File
- The FileDataPropertyEditor context menu contains the ClearContent Action. This Action’s Execute event handler calls the property type’s Clear method to clear the file content. Override the IFileData.Clear method to implement your logic.
Blazor
FileDataPropertyEditor displays the property’s value as a link with the file name. A user can click the link to download the file. In the Detail View, the Select File and Clear buttons are shown. FileAttachmentController contains corresponding Actions. A user should save changes after a file upload to display a link instead of a plain text file name.
FileDataPropertyEditor shows the upload progress while a file is uploading. The default maximum file size is 4 MB.
FileAttachmentsBlazorModule splits the file into chunks to upload to the server.
Web Forms
FileDataPropertyEditor displays the FileDataEdit control, which shows 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
FileDataPropertyEditor shows the Change File and Clear buttons, which are ASPxButtons.
The Clear button clears a property value. For this purpose, the property type’s Clear method is called. You can override the IFileData.Clear method to implement your logic.
The Change File button makes ASPxUploadControl visible to allow users to upload a new file.
A user can click the HtmlAnchor control with the file name to download the file.
The default maximum file size is 4 MB.
File Attachments Module Components
The following table contains classes for different platforms:
Platform | Module Class |
---|---|
WinForms (.NET 5 and .NET Framework) | |
ASP.NET Core Blazor | FileAttachmentsBlazorModule |
ASP.NET Web Forms |
The File Attachments Module contains the following Property Editors to display file data properties in the UI:
- DevExpress.ExpressApp.FileAttachment.Win.FileDataPropertyEditor
- DevExpress.ExpressApp.FileAttachment.Blazor.FileDataPropertyEditor
- DevExpress.ExpressApp.FileAttachment.Web.FileDataPropertyEditor
Add File Attachments Module to an XAF Application
Follow the steps below to add the File Attachments Module to your application. If you added this Module when you created an XAF application, the Solution Wizard generates the code below automatically.
Add the corresponding NuGet package to the application project.
Platform
Project
NuGet Package
WinForms
MySolution.Win
DevExpress.ExpressApp.FileAttachment.Win
Blazor
MySolution.Blazor.Server
DevExpress.ExpressApp.FileAttachment.Blazor
Web Forms
MySolution.Web
DevExpress.ExpressApp.FileAttachment.Web
In the application constructor, add the File Attachments Module to the Modules collection:
WinForms
File: MySolution.Win\WinApplication.cs(.vb).using DevExpress.ExpressApp.FileAttachments.Win; // ... namespace MySolution.Win { public partial class MySolutionWinApplication : WinApplication { public MySolutionWinApplication() { // ... Modules.Add(new FileAttachmentsWindowsFormsModule()); } // ... } }
Blazor
File: MySolution.Blazor.Server\BlazorApplication.cs.using DevExpress.ExpressApp.FileAttachments.Blazor; // ... namespace MySolution.Blazor.Server { public partial class MySolutionBlazorApplication : BlazorApplication { public MySolutionBlazorApplication() { // ... Modules.Add(new FileAttachmentsBlazorModule()); } // ... } }
Web Forms
File: MySolution.Web\WebApplication.cs(.vb).
Tip
Alternatively, you can add the File Attachments Module to the ModuleBase.RequiredModuleTypes collection of the platform-specific Module. In .NET Framework applications, you can also use the Module or Application Designer to add the Module. For more information, see the following topic: Ways to Register a Module.
Define a File Data Object and Storage
The file data object is a business class that implements the IFileData interface. You can also use the built-in FileData class (XPO: the %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl\FileData.cs file, EFCore: the %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl.EF\FileData.cs file).
using DevExpress.Persistent.Base;
using DevExpress.Persistent.BaseImpl;
namespace MySolution.Module.BusinessObjects {
[FileAttachmentAttribute(nameof(File))]
public class MyFileAttachment : BaseObject {
// ...
private FileData file;
public FileData File {
get { return file; }
set { SetPropertyValue(nameof(File), ref file, value); }
}
}
public class FileData : BaseObject, IFileData {
// ...
}
}
Refer to the following help topic for more information on file data properties: File Attachment Properties.
XAF stores attached files in a database in a binary form. When you use the DevExpress.Persistent.BaseImpl.FileData
type, the gzip compression is applied to a file. The maximum file size is 2 GB.
Call the IFileData.LoadFromStream method to upload a file in code. To obtain the file, call the IFileData.SaveToStream method. The LoadFromStream
method does not require a full path to the file. This method accepts a file name as the first parameter.
Examples
Tip
The following example implements a business class with a file data property and a file collection property: How to: Implement File Data Properties.
Read Compressed Files in the FileData Database Table from External Non-XAF .NET Applications
XAF stores attached files in a database in a binary form. The maximum file size is 2 GB. The XPO DevExpress.Persistent.BaseImpl.FileData
type compresses files when it adds them to the database and decompresses the files when they are accessed in the database. The DevExpress.Persistent.Base.CompressionConverter
class (a custom XPO Value Converter class from the DevExpress.Persistent.BaseImpl.Xpo
assembly) applies GZIP compression to files. For more information on the GZIP compression algorithm, refer to the source code at %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl.Xpo\CompressionUtils.cs.
Use one of the following options to read compressed files in the FileData
database table from external non-XAF .NET apps:
If you can use XPO and
FileData
for data access, call the SaveToStream(Stream) method.If you cannot use XPO and
FileData
for data access, call theCompressionConverter.ConvertFromStorageType
method as shown below:using DevExpress.Data.Filtering; using DevExpress.Xpo; using SolutionName.Module.BusinessObjects; using System; using System.Data.SqlClient; using System.IO; using DevExpress.Persistent.Base; namespace SolutionName { class Program { static void Main(string[] args) { string cons = @"Integrated Security=SSPI;Pooling=false;Data Source=(localdb)\mssqllocaldb;Initial Catalog=XafDbWithFiles"; SqlConnection conn = new SqlConnection(cons); conn.Open(); SqlCommand sqlCmd = new SqlCommand("SELECT Content, FileName FROM FileData Where oid = 'B4C546BB-807D-4951-8443-50B800B6BE2D'", conn); using(SqlDataReader rdr = sqlCmd.ExecuteReader()) { while(rdr.Read()) { byte[] column1 =(byte[]) rdr["Content"]; var conv = new CompressionConverter(); byte[] decomp = (byte[]) conv.ConvertFromStorageType(column1); string column2 = rdr["FileName"].ToString(); using(var fs = new FileStream("c:\\test\\1ok_"+column2, FileMode.CreateNew)) { fs.Write(decomp, 0, decomp.Length); fs.Flush(); } } } conn.Close(); conn.Dispose(); } } }
If you do not want to reference the
DevExpress.Persistent.BaseImpl.Xpo
assembly, copy the source code of theCompressionConverter
class to your external non-XAF .NET project.If you do not need the default file compression, you can create a custom IFileData implementation and use it instead of the
DevExpress.Persistent.BaseImpl.FileData
type in your application. To do this, copy the source code of theFileData.cs
class. You can find it in the %PROGRAMFILES(x86)%\DevExpress 21.2\Components\Sources\DevExpress.Persistent\DevExpress.Persistent.BaseImpl.Xpo folder. In the copied code, remove the[ValueConverter(typeof(CompressionConverter))]
line from theContent
property and rename the class and namespaces.