Report Designs
A Design defines the visual layout and rendering rules for an SSRS report. When the report framework has retrieved data through the data set, the design controls how that data appears on the rendered page — column layouts, groupings, headers, footers, charts, page breaks, and styling.
Every report contains one or more designs under its Designs collection. There are two types of design:
| Design Type | Artifact | Description |
|---|---|---|
| Auto Design | AxReportAutoDesign | A metadata-driven design generated automatically from data set field groups and data regions. The developer defines the data regions (tables, lists, matrices, charts) and the framework generates the SSRS RDL layout. This is the recommended approach for most reports. |
| Precision Design | AxReportPrecisionDesign | A free-form SSRS RDL layout created in the Visual Studio Report Designer. The developer has pixel-level control over element placement, sizing, and formatting. Use this for documents with strict layout requirements (e.g., pre-printed forms, cheques, regulatory documents). |
Both design types inherit from AxReportDesign, which provides the base Name and Tags properties.
Auto Design
An Auto Design (AxReportAutoDesign) is the recommended design type for most reports. Instead of hand-crafting the RDL layout, the developer defines data regions (tables, lists, matrices, charts) and configures their properties. The report framework generates the final SSRS RDL from this metadata at build time.
Key Properties
- Title — the title shown on the rendered report. If not set, inherits from the report-level title.
- LayoutTemplate — the layout template controlling page structure (headers, footers, margins).
- RenderParameters — whether report parameter values are shown in the report header.
- DisableRuntimeTransformation — disables the framework's automatic formatting adjustments at runtime.
- PageSize / Margin / InteractiveSize — control the physical page dimensions and margins.
Data Regions
Auto Designs contain a collection of data regions (AxReportDataRegion), each bound to a data set. Data regions are the core visual elements:
| Data Region Type | Artifact | Description |
|---|---|---|
| Table | AxReportTable | A tabular data region with column headers and repeating detail rows. The most common layout for transactional reports. Supports grouping, sorting, headers, and footers. |
| List | AxReportList | A list-based layout where each record is presented as a vertical or horizontal card. Useful for document-style reports (e.g., invoices where each line is a block of fields). |
| Matrix | AxReportMatrix | A cross-tab / pivot table with row and column groupings. Values at the intersection of row and column groups are aggregated. Used for summary reports and comparisons. |
| Chart | AxReportChart | A graphical data region rendering data as bar, column, line, pie, or doughnut charts. Supports 3D rendering, legend display, and chart-specific styling. |
All data region types inherit from AxReportDataRegion, which provides common properties like DataSet (which data set the region binds to), Title, DataNavigation, page break controls, visibility, filters, and a "no rows" message.
Table Data Region
Tables are the workhorse of SSRS reporting. They display data in a grid with:
- Groupings (
AxReportTableGrouping) — group rows by field values, creating subtotal sections. - Sorting (
AxReportSort) — order rows within and across groups. - Headers and Footers — optional header/footer rows that can be repeated on each page.
- StyleTemplate — a style template that controls the visual appearance (alternating row colours, header styles, etc.).
List Data Region
Lists display data as repeating blocks rather than rows. Each record gets its own block, with fields arranged either top-down or horizontally. Lists are ideal for:
- Document-style reports where each record has a distinct visual block.
- Reports with variable-height content per record.
- Nested layouts where a list contains child data regions.
Matrix Data Region
Matrices pivot data across two dimensions — rows and columns. They are used for:
- Cross-tab reports (e.g., sales by region × product).
- Summary reports with dynamic column headers.
- Variance analysis reports.
Matrix-specific properties include DrillDownNavigation (whether drill-down is available on row, column, or both groupings) and separate collections for RowGroupings and ColumnGroupings.
Chart Data Region
Charts render data graphically. The chart type is determined by the specific chart sub-object used (XY charts for bar/column/line, pie/doughnut charts for part-to-whole). Key properties include:
- DisplayLegend — whether to show the chart legend.
- RenderIn3D — whether to render as a 3D chart.
- Size — explicit chart dimensions.
- Series — chart data series groupings.
Precision Design
A Precision Design (AxReportPrecisionDesign) gives the developer full control over the RDL layout through the Visual Studio Report Designer (SSDT). The design is stored as raw RDL XML in the Text property.
When to use Precision Design:
- Documents with strict layout requirements (cheques, pre-printed forms, labels).
- Reports requiring pixel-precise element positioning.
- Complex layouts that cannot be expressed through Auto Design data regions.
- Reports with sub-reports, custom expressions, or advanced SSRS features.
Key Properties
- Text — the RDL markup for the design.
- DataNavigation — the navigation style (DocumentMap, DrillDown, or None).
- DisableRuntimeTransformation — disables framework formatting adjustments.
- EnableAutoDrillThroughStyling — automatic styling for drill-through links.
- StyleTemplate — the table style template applied to the design.
When working with Precision Designs, use the Visual Studio Report Designer (SSDT) to edit the RDL visually. The designer provides a WYSIWYG surface for placing text boxes, tables, images, and expressions. The resulting RDL is stored in the AOT and deployed with the report.
Drill-through Actions
Both Auto and Precision Designs can include drill-through actions that navigate the user from a report field to another report or URL. Drill-through actions are defined at the data region or item level:
AxReportDrillthroughAction— navigates to another SSRS report, passing parameters.AxReportURLDrillthroughAction— navigates to a URL (e.g., a D365 form via a URL-based menu item).
Each drill-through action specifies the target report and a collection of drill-through parameters (AxReportDrillthroughParameter) that pass context values from the current report to the target.
Filters
Data regions can include filters (AxReportFilter) that restrict the data displayed without modifying the underlying data set query. Filters are applied at the rendering stage after data retrieval.
Each filter specifies:
- Expression — the field or expression to evaluate.
- Operator — the comparison operator (Equals, NotEquals, In, GreaterThan, LessThan, Like, TopN, etc.).
- Value — the value to compare against.
Filters are useful when multiple data regions share the same data set but need to show different subsets of the data.
Embedded Images
Reports can include embedded images (AxReportEmbeddedImage) — binary images bundled with the report metadata. These are used for:
- Company logos on invoices and official documents.
- Watermarks (e.g., "DRAFT", "COPY").
- Static icons or decorative elements.
Embedded images are referenced from design expressions by name.
Properties
Design Base Properties
| Property | Display Name | Type | Description |
|---|---|---|---|
| Design (base)AxReportDesign | |||
| Name | Name | String | The name of the element. |
| Tags | Tags | String | Tags for this element separated by semicolon. |
| Auto DesignAxReportAutoDesign | |||
| Title | Title | String | Specifies the title of the design. If not overridden, the title specified at the report level is used. |
| TitleOverridden | Title Overridden | Boolean | Indicates whether the title is overridden. (read-only) |
| RenderParameters | Render Parameters | Boolean | Indicates whether parameters are displayed in the report header. |
| DisableRuntimeTransformation | Disable Runtime Transformation | Boolean | Indicates if runtime transformation should be disabled. |
| LayoutTemplate | Layout Template | String | The layout template controlling page structure (headers, footers, margins). |
| Precision DesignAxReportPrecisionDesign | |||
| Text | Text | String | The RDL markup for the precision design. |
| DataNavigation | Data Navigation | DataNavigation | The navigation style to use for the precision design. Values: DocumentMap (0), DrillDown (1), None (2). |
| DisableRuntimeTransformation | Disable Runtime Transformation | Boolean | Indicates if runtime transformation should be disabled. |
| EnableAutoDrillThroughStyling | Enable Auto Drill Through Styling | Boolean | Enable automatic styling for drill-through links. |
| StyleTemplate | Style Template | String | The table style template used for this design. |
Data Region Properties
| Property | Display Name | Type | Description |
|---|---|---|---|
| Common (all data regions)AxReportDataRegion | |||
| Name | Name | String | The name of the element. |
| Tags | Tags | String | Tags for this element separated by semicolon. |
| DataSet | Data Set | String | The dataset for the data region. |
| Title | Title | String | Specifies the title for this data region. |
| TitleOverridden | Title Overridden | Boolean | Indicates whether the title is overridden. (read-only) |
| DataNavigation | Data Navigation | DataNavigation | The navigation style to use for this data region. Values: DocumentMap (0), DrillDown (1), None (2). |
| PageBreakAtStart | Page Break At Start | Boolean | Indicates whether there should be a page break at the start of this data region. |
| PageBreakAtEnd | Page Break At End | Boolean | Indicates whether there should be a page break at the end of this data region. |
| NoRows | No Rows Message | String | Specifies the message to display if there is no data for this data region. |
| Visible | Visible | String | Indicates whether the data region should be visible. |
| TableAxReportTable | |||
| FieldCaptionRendering | Field Caption Rendering | FieldCaptionRendering | Indicates the field caption rendering style for this table. Values: Singlefile (0), Grouped (1). |
| FixedHeader | Fixed Header | Boolean | Indicates whether the header is fixed for this table. |
| RepeatHeaderOnEachPage | Repeat Header On Each Page | Boolean | Indicates whether the header should be repeated on each page for this table. |
| RepeatFooterOnEachPage | Repeat Footer On Each Page | Boolean | Indicates whether the footer should be repeated on each page for this table. |
| StyleTemplate | Style Template | String | The table style template used on the table. |
| ListAxReportList | |||
| FieldLayout | Field Layout | ListFieldLayout | Indicates the layout for the fields in the list. Values: TopDown (0), Horizontal (1). |
| FieldCaptionPlacement | Field Caption Placement | CaptionPlacement | Indicates the placement of the field captions in the list. Values: BesideField (0), AboveField (1). |
| Height | Height | String | Specifies the height of the list. |
| StyleTemplate | Style Template | String | The list style template used for the list. |
| MatrixAxReportMatrix | |||
| DrillDownNavigation | Drill Down Navigation | DrillDown | Specifies the drill down navigation behavior for the matrix. Values: None (0), RowAndColumnGroupings (1), RowGroupingsOnly (2), ColumnGroupingsOnly (3). |
| StyleTemplate | Style Template | String | The style template for the matrix. |
| ChartAxReportChart | |||
| DisplayLegend | Display Legend | LegendDisplay | Specifies whether the legend should be displayed in the chart. Values: Auto (0), Yes (1), No (2). |
| RenderIn3D | Render In 3D | Boolean | Indicates whether the chart should be rendered as a three dimensional chart. |
| Footer | Footer | String | The expression whose value is displayed in the footer of the chart. |
Filter Properties
| Property | Display Name | Type | Description |
|---|---|---|---|
| FilterAxReportFilter | |||
| Name | Name | String | The name of the element. |
| Tags | Tags | String | Tags for this element separated by semicolon. |
| Operator | Operator | FilterOperator | Specifies the operator to filter by. Values: Equals (0), NotEquals (1), In (2), GreaterThan (3), GreaterThanOrEquals (4), LessThan (5), LessThanOrEquals (6), Like (7), TopN (8), BottomN (9), TopPercent (10), BottomPercent (11). |
| Expression | Expression | String | The left expression of the filter. |
| Value | Value | String | The value of the filter. |
Embedded Image Properties
| Property | Display Name | Type | Description |
|---|---|---|---|
| Embedded ImageAxReportEmbeddedImage | |||
| Name | Name | String | The name of the element. |
| Tags | Tags | String | Tags for this element separated by semicolon. |
| MimeType | MIME Type | String | The MIME type of the embedded image (e.g., image/png, image/jpeg). |
| ImageData | Image Data | String | The base64-encoded image data. |