Back to Devexpress

Printing and Exporting in WPF

dashboard-119902-wpf-viewer-manage-exporting-capabilities.md

latest23.9 KB
Original Source

Printing and Exporting in WPF

  • Apr 29, 2025
  • 11 minutes to read

The WPF Viewer allows you to print or export an entire dashboard and individual items. You can also use an API to customize printing/exporting settings or implement non-visual export. For more information about basic printing/exporting capabilities, refer to Printing and Exporting - Common Concept.

To print or export the entire dashboard, click the Export To button in the dashboard title area and choose the format.

The following options are available:

The button invokes a Print Preview dialog that allows you to specify print options and print the dashboard:

Export to PDF

Invokes a dialog that allows users to export a dashboard to a PDF file.

Specify the options in this dialog and click Export to export the dashboard. To reset changes to the default values, click the Reset button.

The following options are available:

Page LayoutSpecifies the page orientation used to export a dashboard. You can select between Portrait, Landscape, and Auto. Note that in the Auto mode, page orientation is selected automatically depending on the horizontal and vertical sizes of a dashboard.SizeSpecifies the standard paper size (for instance, Letter or A4).Show TitleSpecifies whether to apply the dashboard title to the exported document title.TitleSpecifies the title of the exported document.Scale ModeSpecifies the scaling mode when exporting a dashboard. This option is in effect when Page Layout is set to a value other than Auto.Scale FactorSpecifies the dashboard’s scale factor (in fractions of 1). This option is in effect if Scale Mode is set to Use Scale Factor.Auto Fit Page CountSpecifies the number of horizontal/vertical pages that span the total width/height of a dashboard. This option is in effect if Scale Mode is set to Auto Fit to Page Width.Include FiltersAllows you to include master filter values to the exported document.Include Parameters Allows you to include parameter values to the exported document.PositionSpecifies the position of the master filter and parameter values in the exported document. You can select either Below or Separate Page.

Export to Image

Invokes a dialog that allows users to export a dashboard to an image in the specified format.

Specify the options in this dialog and click Export to export the dashboard. To reset changes to the default values, click the Reset button.

The following options are available:

Image FormatSpecifies the image format in which the dashboard is exported. The following formats are available: PNG, JPEG, SVG, and GIF.Show TitleSpecifies whether to use the dashboard’s title as the exported document’s title.TitleSpecifies the title of the exported document.Resolution (dpi)Specifies the resolution (in dpi) used to export a dashboard.Include FiltersAllows you to include master filter values in the exported document.Include ParametersAllows you to include parameter values in the exported document.

Export to Excel

Invokes a dialog that allows users to export a dashboard’s data to the Excel file.

Specify the options in this dialog and click Export to export the dashboard. To reset changes to the default values, click the Reset button.

The following options are available:

Excel FormatSpecifies the Excel workbook format in which the dashboard’s data is exported. You can select either XLSX or XLS. Export to CSV is not supported for the entire dashboard, tab, or group.Include | FiltersAllows you to include master filter values to the exported document.Include | ParametersAllows you to include parameter values to the exported document.PositionSpecifies the position of the master filter and parameter values in the exported document. You can select either Below or Separate Sheet.

To print or export a dashboard item, click the Export To button in its caption and choose the format.

Export to PDFInvokes a dialog that allows users to export a dashboard to a PDF file with specific options.Export to ImageInvokes a dialog that allows users to export a dashboard to an image in the specified format.Export to ExcelInvokes a dialog that allows users to export a dashboard item’s data to the Excel workbook or CSV file.

For more information about printing/exporting specifics of different dashboard items, refer to the Printing and Exporting topic for dashboard items.

The DashboardControl control exposes an API that allows you to customize the default export options, export dashboard and dashboard items, and so on.

Export Dashboard

ExportToPdfExports a dashboard to the specified stream in PDF format using the specified PDF-specific options.ExportToImageExports a dashboard to the specified stream in Image format using the specified image-specific options.ExportToExcelExports dashboard data to the specified stream in Excel format.

Export Dashboard Items

ExportDashboardItemToPdfExports the dashboard item to the specified stream in PDF format using the specified PDF-specific options.ExportDashboardItemToImageExports the dashboard item to the specified stream in Image format using the specified image options.ExportDashboardItemToExcelExports the dashboard item to the specified stream in Excel format using specified export options.

Specify Export Options

PdfExportOptionsProvides access to options related to exporting a dashboard/dashboard item to PDF format.ImageExportOptionsProvides access to options related to exporting a dashboard/dashboard item to an image.ExcelExportOptionsProvides access to options related to exporting a dashboard item to Excel format.

Configure Print Preview

PrintPreviewOptionsProvides access to options that the Print Preview window uses to print a dashboard/dashboard item.ShowPrintPreview()Invokes the Print Preview, which shows the print preview of the dashboard.ShowDashboardItemPrintPreview(String)Invokes the Print Preview, which shows the print preview of the dashboard item.

Non-Visual Export

You can use the non-visual DashboardExporter component to implement server-side export of a dashboard or dashboard items without referencing dashboard UI controls ( DashboardDesigner, DashboardViewer, ASPxDashboard, and so on) or DashboardConfigurator.

To integrate the DashboardExporter into a service, register the DevExpress NuGet feed as a package source and install the DevExpress.Dashboard.Core package. See the DashboardExporter class description for details.

Example: Export Dashboards in a Console Application

The following example shows how to use the DashboardExporter component in a console application to export Dashboards in PDF format.

View Example

cs
using System;
using System.IO;
using DevExpress.DashboardCommon;

namespace DashboardExporterApp {
    class Program {
        static void Main(string[] args) {
            if(args.Length < 1 || !Directory.Exists(args[0])) {
                Console.WriteLine("Path to the dashboard and output folders are required");
                return;
            }
            string[] dashboards = Directory.GetFiles(args[0], "*.xml");
            string outputFolder = args[1];
            DashboardExporter exporter = new DashboardExporter();
            exporter.ConnectionError += Exporter_ConnectionError;
            exporter.DataLoadingError += Exporter_DataLoadingError;
            exporter.DashboardItemDataLoadingError += Exporter_DashboardItemDataLoadingError;
            foreach(string dashboard in dashboards) {
                string outputFile = Path.Combine(outputFolder, 
                    $"{Path.GetFileNameWithoutExtension(dashboard)}.pdf");
                using FileStream stream = new FileStream(outputFile, FileMode.OpenOrCreate);
                try {
                    exporter.ExportToPdf(dashboard, stream);
                }
                catch(Exception e) {
                    Console.WriteLine($"Unable to export {dashboard}.");
                    Console.WriteLine(e.Message);
                    continue;
                }
            }
            Console.WriteLine("Done!");
        }
        static void Exporter_ConnectionError(object sender,
            DashboardExporterConnectionErrorEventArgs e) {
            Console.WriteLine(
                $"The following error occurs in {e.DataSourceName}: {e.Exception.Message}");
        }
        static void Exporter_DataLoadingError(object sender, 
            DataLoadingErrorEventArgs e) {
            foreach(DataLoadingError error in e.Errors)
                Console.WriteLine(
                    $"The following error occurs in {error.DataSourceName}: {error.Error}");
        }
        static void Exporter_DashboardItemDataLoadingError(object sender, 
            DashboardItemDataLoadingErrorEventArgs e) {
            foreach(DashboardItemDataLoadingError error in e.Errors)
                Console.WriteLine(
                    $"The following error occurs in {error.DashboardItemName}: {error.Error}");
        }
    }
}
vb
Imports System
Imports System.IO
Imports DevExpress.DashboardCommon

Namespace DashboardExporterApp
    Friend Class Program
        Shared Sub Main(ByVal args() As String)
            If args.Length < 1 OrElse Not Directory.Exists(args(0)) Then
                Console.WriteLine("Path to the dashboard and output folders are required")
                Return
            End If
            Dim dashboards() As String = Directory.GetFiles(args(0), "*.xml")
            Dim outputFolder As String = args(1)
            Dim exporter As New DevExpress.DashboardCommon.DashboardExporter()
            AddHandler exporter.ConnectionError, AddressOf Exporter_ConnectionError
            AddHandler exporter.DataLoadingError, AddressOf Exporter_DataLoadingError
            AddHandler exporter.DashboardItemDataLoadingError, AddressOf Exporter_DashboardItemDataLoadingError
            For Each dashboard As String In dashboards
                Dim outputFile As String = Path.Combine(outputFolder, $"{Path.GetFileNameWithoutExtension(dashboard)}.pdf")
                Using stream = New FileStream(outputFile, FileMode.OpenOrCreate)
                    Try
                        exporter.ExportToPdf(dashboard, stream)
                    Catch e As Exception
                        Console.WriteLine($"Unable to export {dashboard}.")
                        Console.WriteLine(e.Message)
                        Continue For
                    End Try
                End Using
            Next dashboard
            Console.WriteLine("Done!")
        End Sub
        Private Shared Sub Exporter_ConnectionError(ByVal sender As Object, ByVal e As DashboardExporterConnectionErrorEventArgs)
            Console.WriteLine($"The following error occurs in {e.DataSourceName}: {e.Exception.Message}")
        End Sub
        Private Shared Sub Exporter_DataLoadingError(ByVal sender As Object, ByVal e As DataLoadingErrorEventArgs)
            For Each [error] As DataLoadingError In e.Errors
                Console.WriteLine($"The following error occurs in {[error].DataSourceName}: {[error].Error}")
            Next [error]
        End Sub
        Private Shared Sub Exporter_DashboardItemDataLoadingError(ByVal sender As Object, ByVal e As DashboardItemDataLoadingErrorEventArgs)
            For Each [error] As DashboardItemDataLoadingError In e.Errors
                Console.WriteLine($"The following error occurs in {[error].DashboardItemName}: {[error].Error}")
            Next [error]
        End Sub
    End Class
End Namespace

Example: How to Use MailKit to Send a Dashboard as a Document in PDF

This example demonstrates how to email a dashboard with the MailKit email client library. To email a document to a specific address, run the application, enter the SMTP host, port, SMTP credentials, and click Send.

View Example

Example: How to Email a Dashboard that Displays Different Data Depending on the Addressee

The following example shows how to use the DashboardExporter component in a console application to email a dashboard that displays different data depending on the addressee. The MailKit email client library is used in this example.

View Example

Custom Export

The Dashboard Control raises the DashboardControl.CustomExport event before saving the exported document to the PDF and Image formats. Use this event to obtain the printable control(s) and customize the exported document.

The following table illustrates dashboard items and their corresponding printable XRControls:

Dashboard ItemXRControl
ChartDashboardItemXRChart
ScatterChartDashboardItemXRChart
PieDashboardItemXRChart
PivotDashboardItemXRPivotGrid
RangeFilterDashboardItem (When CustomExportBaseEventArgs.ExportMode is SingleItem)XRChart
GaugeDashboardItemXRGaugeDashboardItem
TextBoxDashboardItemXRTextBox

CustomizeExportDocument is raised after CustomExport and allows you to customize the stream containing the resulting document (such as PDF, Image or Excel).

Handle the BeforeExportDocument event to hide specific dashboard items when printing or exporting the entire dashboard.

The following example shows how to customize dashboard items in the exported document when you handle the DashboardDesigner.CustomExport / DashboardViewer.CustomExport / DashboardControl.CustomExport events. You can use the CustomExportEventArgs.GetPrintableControls method to obtain the printable controls.

csharp
using DevExpress.DashboardCommon;
using DevExpress.DashboardExport;
using DevExpress.DashboardWin;
using DevExpress.XtraCharts;
using DevExpress.XtraGauges.Core.Drawing;
using DevExpress.XtraGauges.Win.Base;
using DevExpress.XtraGauges.Win.Gauges.Circular;
using DevExpress.XtraReports.UI;

private void DashboardControl_CustomExport(object sender, CustomExportEventArgs e) {
    foreach(var printControl in e.GetPrintableControls()) {
        if(printControl.Value is XRGaugeDashboardItem) {
            var gaugeItemName = printControl.Key;
            DashboardControl control = (DashboardControl)sender;
            var gaugeDashboardItem = control.Dashboard.Items[gaugeItemName] as GaugeDashboardItem;
            foreach(var dashGaugeElement in gaugeDashboardItem.Gauges) {
                foreach(var gaugePanel in 
                    e.GetGaugeContext(gaugeItemName).GetPrintableGauges(dashGaugeElement).Cast<XRDashboardGauge>()) {
                    if(gaugePanel != null) {
                        gaugePanel.MainSeriesLabel.ForeColor = Color.Red;
                    }
                }
            }
        }

        if(printControl.Value is XRChart) {
            var chartItemName = printControl.Key;
            DashboardControl control = (DashboardControl)sender;
            var chartDashboardItem = control.Dashboard.Items[chartItemName] as ChartDashboardItem;
            foreach(var pane in chartDashboardItem.Panes) {
                if(pane.Series.Count > 0) {
                    foreach(var dashSeries in pane.Series) {
                        if(dashSeries != null) {
                            var controlSeries = e.GetChartContext(chartItemName).GetControlSeries(dashSeries);
                            if(controlSeries != null) {
                                foreach(var ser in controlSeries) {
                                    LineSeriesView view = ser.View as LineSeriesView;
                                    if(view != null) {
                                        view.LineStyle.DashStyle = DashStyle.DashDot;
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
vb
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardExport
Imports DevExpress.DashboardWin
Imports DevExpress.XtraCharts
Imports DevExpress.XtraGauges.Core.Drawing
Imports DevExpress.XtraGauges.Win.Base
Imports DevExpress.XtraGauges.Win.Gauges.Circular
Imports DevExpress.XtraReports.UI

Private Sub DashboardControl_CustomExport(ByVal sender As Object, ByVal e As CustomExportEventArgs)
    For Each printControl In e.GetPrintableControls()
        If TypeOf printControl.Value Is XRDashboardPanel Then
            Dim gaugeItemName = printControl.Key
            Dim designer As DashboardDesigner = CType(sender, DashboardDesigner)
            Dim gaugeDashboardItem = TryCast(designer.Dashboard.Items(gaugeItemName), GaugeDashboardItem)
            For Each dashGaugeElement In gaugeDashboardItem.Gauges
                For Each gaugePanel In e.GetGaugeContext(gaugeItemName).GetPrintableGauges(dashGaugeElement).Cast(Of XRDashboardGaugePanel)()
                    If gaugePanel IsNot Nothing Then
                        gaugePanel.MainSeriesLabel.ForeColor = Color.Red
                    End If
                Next gaugePanel
            Next dashGaugeElement
        End If

        If TypeOf printControl.Value Is XRChart Then
            Dim chartItemName = printControl.Key

            Dim designer As DashboardDesigner = CType(sender, DashboardDesigner)
            Dim chartDashboardItem = TryCast(designer.Dashboard.Items(chartItemName), ChartDashboardItem)

            For Each pane In chartDashboardItem.Panes
                If pane.Series.Count > 0 Then
                    For Each dashSeries In pane.Series
                        If dashSeries IsNot Nothing Then
                            Dim controlSeries = e.GetChartContext(chartItemName).GetControlSeries(dashSeries)
                            If controlSeries IsNot Nothing Then
                                For Each ser In controlSeries
                                    Dim view As LineSeriesView = TryCast(ser.View, LineSeriesView)
                                    If view IsNot Nothing Then
                                        view.LineStyle.DashStyle = DashStyle.DashDot
                                    End If
                                Next ser
                            End If
                        End If
                    Next dashSeries
                End If
            Next pane
        End If
    Next printControl
End Sub

Post-Process Excel and PDF Files

You can post-process resulting Excel and PDF files with the help of dedicated DevExpress libraries (collectively known as DevExpress Office File API ):

  • PDF Document API helps you edit, merge, split, password-protect, and digitally sign PDF files.
  • Spreadsheet Document API helps you manage worksheets, cells, values and formulas, graphics, charts, pivot tables, and other objects.

PDF Document API and Spreadsheet Document API work in applications that target a variety of platforms (Windows Forms, WPF, ASP.NET Web Forms, ASP.NET MVC, ASP.NET Core, Blazor, MAUI) and operating systems (Windows, Linux, macOS).

Office File API is included into the DevExpress Universal Subscription - the same subscription that includes DevExpress Dashboard.