Export to MailMessage

  • 6 minutes to read

This document describes how to export a report document to an email message.

A document can only be exported to an email message at run time. An MailMessage instance contains the report document exported to HTML and optimized to be sent by email. You can then use .NET Framework mail features to send the generated message to recipients.

To export a report document to an email message in code, use one of the following approaches:

  • Export a Report

    Call an XtraReport.ExportToMail overloaded method to export a report. To export a report asynchronously in a separate task, call an XtraReport.ExportToMailAsync overloaded method instead. To specify export options, create a MailMessageExportOptions class instance and pass this instance to the invoked method, or use XtraReport's ExportOptions.MailMessage property.

    using System;
    using DevExpress.XtraPrinting;
    using DevExpress.XtraReports.UI;
    // ...
    XtraReport report = new XtraReport() {
        Name = "HelloWorld",
        Bands = {
            new DetailBand(){
                Controls={
                    new XRLabel(){
                        Text="Hello World!"
                    }
                }
            }
        }
    };
    // mailMessageExportFile specifies the exported file's name and path. The user's Downloads folder is used as the default path.
    string mailMessageExportFile = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile) + @"\Downloads\" + report.Name + ".mailMessage";
    // Specify export options to export the report.
    // Uncomment the lines below to specify export options in an MailMessageExportOptions class instance.
    // MailMessageExportOptions MailMessageExportOptions = new MailMessageExportOptions();
    // MailMessageExportOptions.ExportMode = MailMessageExportMode.SingleFile;
    // report.ExportToMail(mailMessageExportFile, MailMessageExportOptions);
    
    // Comment the lines below if you specified export options in an MailMessageExportOptions class instance above.
    report.ExportOptions.MailMessage.ExportMode = MailMessageExportMode.SingleFile;
    report.ExportToMail(mailMessageExportFile);
    
  • Export a Document

    Call a PrintingSystem.ExportToMail overloaded method to export a document. To specify export options, create a MailMessageExportOptions class instance and pass this instance to the invoked method, or use PrintingSystem's ExportOptions.MailMessage property.

    using System;
    using DevExpress.XtraPrinting;
    using DevExpress.XtraReports.UI;
    // ...
    XtraReport report = new XtraReport() {
        Name = "HelloWorld",
        Bands = {
            new DetailBand(){
                Controls={
                    new XRLabel(){
                        Text="Hello World!"
                    }
                }
            }
        }
    };
    // Create a document from the report.
    report.CreateDocument();
    // mailMessageExportFile specifies the exported file's name and path. The user's Downloads folder is used as the default path.
    string mailMessageExportFile = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile) + @"\Downloads\" + report.Name + ".mailMessage";
    // Specify export options and export the document.
    // Uncomment the lines below to specify export options in an MailMessageExportOptions class instance.
    // MailMessageExportOptions MailMessageExportOptions = new MailMessageExportOptions();
    // MailMessageExportOptions.ExportMode = MailMessageExportMode.SingleFile;
    // report.PrintingSystem.ExportToMail(mailMessageExportFile, MailMessageExportOptions);
    
    // Comment the lines below if you specified export options in an MailMessageExportOptions class instance above.
    report.PrintingSystem.ExportOptions.MailMessage.ExportMode = MailMessageExportMode.SingleFile;
    report.PrintingSystem.ExportToMail(mailMessageExportFile);
    

Export Options

The options that can be specified for a document exported to an email message are stored in the MailMessageExportOptions class. Use the report's ExportOptions.MailMessage property to access these options. The MailMessageExportOptions class extends the HtmlExportOptionsBase class and gives access to a set of options common to all HTML-based export formats.

The HtmlExportOptionsBase.ExportMode property determines how a document is exported to HTML. For instance, it may be exported to a single file (with a single page header at the start and a single page footer at the end), or it may be exported page-by-page to a single file or different files.

The HtmlExportOptionsBase.TableLayout property specifies whether to use the table layout in the exported document's HTML markup. The table layout is recommended, as it uses a more compact and efficient markup.

The HtmlExportOptionsBase.ExportWatermarks property specifies whether to maintain the report's text and image watermarks in the HTML markup. The following image illustrates this option in the HTML Export Options dialog:

html-export-options-watermarks

Overlapped Controls

To ensure that report controls are exported to XLS correctly, they should not intersect. Otherwise, the file layout can be corrupted.

Overlapped controls are highlighted in reports. Users can move the mouse pointer over these controls to see what needs to be fixed.

ShowExportWarnings

Use a report's HasExportWarningControls collection to check if there are controls that have export warnings.
Disable a report's DesignerOptions.ShowExportWarnings property to remove highlights on overlapped controls.

To export a report that contains overlapped controls, use the non-table layout.

Document Navigation

Document navigation uses scripts. To use HTML link-based navigation instead, enable the HtmlExportOptionsBase.UseHRefHyperlinks property. When users view such a document in a client web browser, script security messages are not displayed. Ensure that the controls' Text properties are specfiied - otherwise links contain empty text and users cannot click them.

Limitations

If a report uses a CachedReportSource, changes made in Preview are not included in the exported report.

Code Example

This example demonstrates how to export a report to an email message and use the .NET Framework mail features to send the generated message to recipients.

using DevExpress.XtraReports.UI;
using System.Collections.Generic;
using System.Net.Mail;
using System.Windows.Forms;
// ...

private void sendButton_Click(object sender, EventArgs e) {
    XtraReport report = new XtraReport1();

    using (SmtpClient client = new SmtpClient("mail.smtpclient.test", 25)) {
        using (MailMessage message = report.ExportToMail("sender@test.test",
        "reciever1@test.test, reciever2@test.test, reciever3@test.test", "Subject")) {
            client.Credentials = new System.Net.NetworkCredential("username", "password");
            client.EnableSsl = true;
            client.Send(message);
        }
    }
}