Read, edit and save report definitions
DocWright.Reporting.Rdl reads and writes SSRS and Power BI paginated report definitions (.rdl, .rdlc) across the 2005, 2008, 2010 and 2016 schemas. A load-and-save changes nothing you didn't change, which makes it a sound base for tools that edit reports.
dotnet add package DocWright.Reporting.Rdl
Load
This loads Microsoft's Invoice sample report:
using DocWright.Reporting;
using DocWright.Reporting.Rdl;
ReportDefinition definition;
using (FileStream input = File.OpenRead("Invoice.rdl"))
{
definition = new RdlReader().Read(input);
}
Console.WriteLine($"Schema: {definition.SchemaVersion}");
Console.WriteLine($"Datasets: {string.Join(", ", definition.DataSets.Select(d => d.AttributeValue("Name")))}");
Console.WriteLine($"Parameters: {string.Join(", ", definition.ReportParameters.Select(p => p.AttributeValue("Name")))}");
Output (this page's three steps)
Schema: Rdl2016
Datasets: SalesInvoiceDS, Company, Users, SalesInvoiceHeaderFooterDS, CompanyList
Parameters: Company
First textbox: Textbox5
Validation findings: 0
Edit and save
using DocWright.Reporting;
using DocWright.Reporting.Rdl;
// Typed properties for the common metadata; set null to remove an element.
definition.Description = "Sales invoice, revised for the 2026 brand";
definition.Author = "Finance systems";
// Anything else: find the element in the tree and change it.
RdlElement? firstTextbox = definition.Root.DescendantsAndSelf().FirstOrDefault(e => e.Name.Is("Textbox"));
Console.WriteLine($"First textbox: {firstTextbox?.AttributeValue("Name")}");
// Save. Everything DocWright doesn't model - designer data, extensions - is written back as it was.
using (FileStream output = File.Create("Invoice.revised.rdl"))
{
new RdlDefinitionWriter().Write(definition, output);
}
- The model is the element tree. Every element, attribute and namespace is kept, including Report Builder's private
rd:data and third-party extensions. Unknown content survives because it is still an element, not because some class remembered to copy it. - Sparseness is kept. A report that writes
<CanGrow>false</CanGrow>and one that omits it stay different, so saving never rewrites a customer's file. - Typed shortcuts read through to the tree:
SchemaVersion,Description,Author,Language,DataSources,DataSets,ReportParametersandNamedElements(). - New elements go where the schema says.
definition.SetValue(element, "ZIndex", "3")and the typed setters insert children in the schema's declared order, not at the end. Some RDL types require an order, and appending works only until it doesn't. - The schema version never changes on save. It is the root element's namespace.
Build in code
A definition doesn't have to come from a file. Create the root in the namespace of the schema you target and fill it:
using System.Text;
using DocWright.Reporting;
using DocWright.Reporting.Rdl;
// A new report: the root in the namespace of the schema you target.
var definition = new ReportDefinition(
new RdlElement(new RdlName(ReportNamespaces.ReportDefinition2016, "Report")));
definition.Description = "Built in code";
// An element in Report Builder's designer namespace, under its usual prefix.
definition.Root.Children.Add(new RdlElement(new RdlName(ReportNamespaces.ReportDesigner, "ReportUnitType"))
{
Prefix = "rd",
Value = "Inch",
});
// The writer declares the namespaces the names need; you add no xmlns yourself.
using var output = new MemoryStream();
new RdlDefinitionWriter(new RdlDefinitionWriteSettings { XmlDeclaration = false, ByteOrderMark = false })
.Write(definition, output);
Console.WriteLine(Encoding.UTF8.GetString(output.ToArray()));
Output
<Report xmlns="http://schemas.microsoft.com/sqlserver/reporting/2016/01/reportdefinition">
<Description>Built in code</Description>
<rd:ReportUnitType xmlns:rd="http://schemas.microsoft.com/SQLServer/reporting/reportdesigner">Inch</rd:ReportUnitType>
</Report>
The writer keeps every name it writes in scope. The default namespace is declared on the root, and a prefix is declared on the first element that uses it when nothing above declares it. A report you loaded already stores its declarations, so a load-and-save adds none. To have xmlns:rd once on the root, the way Report Builder writes it, add the declaration to definition.Root.Attributes yourself.
Validate
The RDL XML schema types sizes, colours and enumerations as plain strings, so passing it proves little. ReportValidator checks what matters:
using DocWright.Core.Diagnostics;
using DocWright.Reporting;
IReadOnlyList<ConversionDiagnostic> findings = ReportValidator.Validate(definition).ToList();
Console.WriteLine($"Validation findings: {findings.Count}");
foreach (ConversionDiagnostic finding in findings)
{
Console.WriteLine($"{finding.Code} at {finding.Location}: {finding.Message}");
}
It reports duplicate report-item names (expressions refer to items by name, so a duplicate is ambiguous), duplicate sibling names, references to datasets or data sources that don't exist, and a constant Reporting Services won't accept for its property (DXP9307) — bold for a font weight, which it compares exactly, or DashDot for a text box's border. Reporting Services refuses to render such a report. All seven Microsoft sample reports validate clean.
What a property accepts
Every element the schema declares also says what a property editor needs: the schema version it first appeared in, whether it can hold an expression, the kind of value it holds, and the values an enumeration accepts.
using DocWright.Reporting;
// What a property grid needs to edit a property: since when, expression or not, what kind, which values.
foreach (var (type, name) in new[] { ("StyleType", "FontWeight"), ("BorderType", "Style"), ("TablixType", "DataSetName"), ("StyleType", "FontSize") })
{
RdlSchemaChild child = RdlSchema.Type(type)!.Child(name)!;
Console.WriteLine($"{type}/{name}: since {child.FirstVersion}, expression {child.AcceptsExpression}, {child.ValueKind}"
+ (child.AllowedValues.Count > 0 ? ": " + string.Join(", ", child.AllowedValues) : ""));
}
// A border's DashDot is accepted under a chart, gauge panel or map only.
RdlSchemaChild border = RdlSchema.Type("BorderType")!.Child("Style")!;
Console.WriteLine("under a map: " + string.Join(", ", border.AllowedValuesUnder("Map")));
StyleType/FontWeight: since Rdl2005, expression True, Enumeration: Bold, Default, ExtraBold, ExtraLight, Heavy, Light, Medium, Normal, SemiBold, Thin
BorderType/Style: since Rdl2008, expression True, Enumeration: Dashed, Default, Dotted, Double, None, Solid
TablixType/DataSetName: since Rdl2008, expression False, Text
StyleType/FontSize: since Rdl2005, expression True, Size
under a map: Dashed, Default, Dotted, Double, None, Solid, DashDot, DashDotDot
The XML schema answers only the first question: it declares every property that can hold an expression as a plain string, so it says nothing about which strings are expressions and lists no values for them. The rest was measured against Microsoft's report engine, under every kind of report item. AllowedValues lists a value only where no kind of item refuses it; AllowedValuesUnder("Map") gives the list for one kind, which differs in one place — a border's DashDot works on charts, gauges and maps and breaks the report anywhere else.
Upgrade to a newer schema
Saving never changes a definition's schema version: a 2008 report saved as 2016 no longer opens on SSRS 2008. To move one to a later version, the way Report Builder offers to upgrade a 2005 report, call ReportDefinitionUpgrade.Upgrade:
using DocWright.Core.Diagnostics;
using DocWright.Reporting;
using DocWright.Reporting.Rdl;
ReportDefinition original;
using (FileStream input = File.OpenRead("Sales2005.rdl"))
{
original = new RdlReader().Read(input);
}
// A new definition in the 2016 schema; the original is not changed. A 2005 chart is kept and reported.
var diagnostics = new CollectingConversionDiagnostics();
ReportDefinition upgraded = ReportDefinitionUpgrade.Upgrade(original, ReportSchemaVersion.Rdl2016, diagnostics);
Console.WriteLine($"{original.SchemaVersion} -> {upgraded.SchemaVersion}");
Console.WriteLine(string.Join(", ", upgraded.Root.DescendantsAndSelf()
.Where(e => e.Name.LocalName is "Tablix" or "Group")
.Select(e => e.Name.LocalName + " " + e.AttributeValue("Name"))));
foreach (ConversionDiagnostic finding in diagnostics.Snapshot())
{
Console.WriteLine($"{finding.Code} {finding.Severity}: {finding.Message}");
}
using (FileStream output = File.Create("Sales2016.rdl"))
{
new RdlDefinitionWriter().Write(upgraded, output);
}
Rdl2005 -> Rdl2016
Tablix T, Group gRegion, Group T_Details_Group
DXP9308 Warning: The Chart 'Trend' was kept as it was and not upgraded: a 2005 Chart is not converted to the 2008 shape.
Downloads: Sales2005.rdl, Sales2016.rdl.
The rules are the ones Microsoft's own upgrader applies, measured on 50 probe reports:
- Every version: the namespace changes. From 2010 on, the body, width and page move into a report section. In 2016, the parameter pane gets its grid.
- From 2005:
- page properties move into
Page - text box values become paragraphs
- per-side borders become border elements
- tables, lists and matrices become tablixes, matrix subtotals included
- page properties move into
The result is valid against the target schema and renders the same in Microsoft's engine as Microsoft's own upgrade. The target defaults to 2016. A downgrade throws.
Warning
A 2005 chart or custom report item is not converted. It is kept in its 2005 shape and reported as DXP9308; nothing is dropped. Microsoft's own upgrader fails on a minimal 2005 chart, so there is no measured shape to convert it to. Rebuild the chart before saving: until then, the definition is not valid in the new schema.
Sizes
RDL sizes are strings like 2.5in or 1cm. RdlMeasure.Parse converts them to Twips and reports anything that isn't a size, such as 2,5pt, which a comma-decimal culture produces, rather than guessing. RdlMeasure.ToPoints(twips) writes one back.
Untrusted input
An .rdl is untrusted: XML with unlimited nesting and an expression language inside. The reader refuses DTDs, never resolves external entities, and limits nesting depth (256) and element count (2 million) by default. Tighten them with new RdlReader(new RdlReadSettings { Limits = … }).