Click this symbol to show an illustration of the step embedded in the page; click the illustration to hide it again.
|Table of Contents|
What's in this document?
|What is xmlRSDocs?|
|A documenting method or kit for report metadata, using reports|
|An add-on to ReportDesigners [RS 2005 only, not needed for 2008]|
|A showpiece for various corners of the SQL Server and Visual Studio "universe"|
|An extensible mechanism for handling reporting metadata|
|Test Drive xmlRSDocs: xmlRSDocsHarness|
|Run the program|
|Document a single RDL/RDLC to docRDLxml file|
|Report on a single docRDL.xml file|
|Document many reports|
|Store your documentation to a SQL Database|
|Report on many reports' documents|
|Change what documentation is extracted|
|Change the documentation reports (Report1 and ReportMany)|
|Customize xmlRSDocsHarness's data repositories and behavior|
|Install SQL Server Compact Edition Runtime|
|Install a fresh copy of the SDF file|
|Add custom documentation while designing any RDL: RDLDocumenterDesigner in RS 2005, Custom Properties in RS 2008|
Deploy the custom control library for use at design-time
Add the custom control for use during Report Design sessions in Visual Studio
Add RDLDocumenterDesigner to a report design layout
Make RDLDocumenterDesigner's custom actions accessible
Use the RDLDocumenterDesigner-decorated report
Add custom documentation attributes to your report
Share decorated report with another report developer
Create RSdoc-specific properties
Create non-RSdoc-specific custom properties for documentation
Don't forget the global properties that the RDL provides natively!
Generally useful types of extra documentation
Walkthroughs for adding specialized documentation:
Change xmlRSDocs' "owned" prefix
Edit your custom documentation directly in any RDL
|Deploy RDLDocumenterDesigner-decorated reports to a Reporting Services server (RS 2005 Only): Options|
|Keep RDLDocumenterDesigner in report "invisibly"|
|Make RDLDocumenterDesigner visible in deployed reports|
|Remove RDLDocumenterDesigner before deployment|
|Turn any RDL or RDLC into RDLDoc.XML: Sample VBS script|
|Perform the process in a console (CMD) window|
|Use drag-and-drop with the VBS script|
|Learn more about using the same syntax in your own programs|
|Load RDLDoc.XML to any database, and analyze the results: Sample SQL scripts|
|Create a Microsoft SQL Server table suitable for holding the default docRDL-shaped rows|
|Load documentation data to a database with a SQL script|
|Use your database table with the xmlRSDocsHarness application|
|Smart-parse additional detail from the values in the table|
|Set up an automated production deployment: xmlRSDoc's SSIS package(s)|
|Set up the folder- and SSRS server-handling packages for debug-style use in Visual Studio|
|Run the packages in debug mode|
|Set package variables for optional features|
|Extend xmlRSDocs to new documentation schemas and new types of output|
|More to come!|
|What is xmlRSDocs?|
Learn about what xmlRSDocs is and does.
|A documenting method for report metadata, using reports||
xmlRSDocs "understands" SQL Server Reporting Services' XML report definition files. It extracts information from RDLs and RDLCs into a convenient XML data format, docRDL.xml, from which you can generate many different types of documentation.
docRDL.xml is designed to be easy to load into a table or a DataTable member of a DataSet. That means you can, using a very natural and familiar mechanism, use this data as a datasource for one or more RDL or RDLCs, to provide documentation about your reports.
|An add-on to ReportDesigner||
While the base information in an RDL or RDLC provides a great deal of useful metadata, sometimes you want to add comments or extra information about your report for users or other developers. For example, you may want to add descriptive information to a report that indicates the department or customer for whom it was prepared, or you might want to add an explanation of a complex expression you used for a particular textbox.
In RS 2005, a custom report item was required to do this fluently.
Report Designer and Report Builder v1 didn't allow access to custom
properties in the RDL during report design, and would blow away added schema
namespaces and custom elements if you tried to add them into the RDL by
other means. Even custom report items couldn't write to custom
properties of the RDL except on the global level.
RDLDocumenterDesigner is a design-time tool that gives you an opportunity to add custom information to your report as you work on it in the Report Designer. It appears as a custom report item in your layout, and can either appear in the report result or be invisible at runtime.
RDLDocumenterDesigner allows the following types of decoration to report metadata:
In Report Designer 2008+ and Report Builder v2+, you don't need
RDLDocumenterDesigner. You can still use xmlRSDocs-specialized syntax for adding
custom report documentation, directly in the design IDE, if you wish;
xmlRSDocs leverages the syntax, if found). You can mix and match this
syntax with other Custom Properties -- on both a global and individual
report control level -- however you want.
|A showpiece for various corners of the SQL Server and Visual Studio "universe"||
xmlRSDocs is supplied with a simple interactive harness that allows you to see how all its pieces work together. The xmlRSDocsHarness main form code illustrates some very important aspects of reporting, such as:
Beyond xmlRSDocsHarness, xmlRSDocs includes some simple scripts that show you how to extract docRDL.xml, load it to a database, and perform other maintenance tasks. You can use the scripts to learn how to adjust RDL xml manually, and shred XML to database columns, if you like.
But the basic idea of xmlRSDocs -- integrating RDL documentation with the full "universe" of SQL Server features, and also with the kind of documentation practices one uses in other .NET and Visual Studio development work -- also suggests a production-style mechanism you can use to process multiple reports to docRDL.xml, load them to a database, and even generate the documentation reports at the end if you wish. This mechanism consists of two SSIS packages, which can configured to your requirements. The first package documents the RDLs contained in a folder in your file system, similar to xmlRSDocsHarness. The second package documents all the RDLs published by an SSRS ReportServer instance.
The SSIS packages also provides working examples of some interesting Integration Services techniques, such as:
The docRDL.xml format can serve as an interim format, to be transformed into other XML outputs such as standard XML Comments files. This means additional tasks can be added into the SSIS package to invoke additional documentation producers such as Sandcastle, providing for unlimited types of output.
RDLDocumenterDesigner showcases a different kind of extensibility, leveraging the ability to add custom design-time elements into the Report Designer interface. It opens the door to a class of tools, using custom ReportItems that enhance the report design process without necessarily being significant to the reports' runtime output. While RDLDocumenterDesigner isn't needed for SSRS 2008, because we can handle custom documentation within the shipping Designer and Builder interfaces, this idea is still valid, and could be used for other purposes.
End-to-end, the whole process provides a really interesting array of different SQL Server and Visual Studio techniques, while remaining simple enough, within each element, to serve as an introduction to each technique.
|An extensible mechanism for handling reporting metadata||...||
Whether you use RDLDocumenterDesigner in RS 2005 or the native features in RS 2008, you are adding information to the RDL using Custom Properties, a feature of the RDL/RDLC format that is supported in Report Designer. xmlRSDocs recognizes CustomProperties that belong to its designer support tool and pulls them into the docRDL.xml like other report metadata. xmlRSDocs also reports on CustomProperties you may have added that don't belong to its special set.
But xmlRSDocs supports much more extensive custom documentation embedded in the XML, too. Whether you choose to use an external method of adding to the RDL or RDLC definition, whether by hand-editing the code file or in an external editor interface, the xmlRSDocs conceptually recognizes and extracts the following types of extensions, by default:
Note that, as shown in the example above, these extensions to the RDL require an extension namespace. While the RDLs and RDLCs so decorated remain valid for report processing, and while the Report Designer will load the reports, the current Report Designer removes extension content, so there's no point in adding this type of content if you are going to continue editing the report. This may change in future versions of Reporting Services design components. Meanwhile, using embedded XML in the supported (rdl namespace) Custom Properties may provide an alternative, depending on how you choose to extract the information.
Whether you work on a native-XML level or strictly through the native Designer and Builder, you can easily opt to support additional levels of verbosity, recognize additional namespaced content, extract different kinds of content than its default set, prepare its results for loading into tables with different columns, and so on. This is because xmlRSDocs's extraction mechanism is a fairly straightforward XSLT transformation, which it applies to your RDL and RDLC files to get its docRDL.xml output. If, for instance, by default xmlRSDocs does not document Chart attributes that you want to include in documentation, you can substitute an edited version of the XSLT that includes them.
|Test Drive xmlRSDocs: xmlRSDocsHarness|
xmlRSDocsHarness lets you quickly and easily extract documentation from standard RDL/RDLCs, so you can get a feel for how the system works.You can get documentation directly from a single RDL/RDLC, or extract and store documentation data from multiple reports and document the set.
|Run the program||
Run the xmlRSDocsHarness.exe executable file in the Deploy directory to invoke its winform interface.
|Document a single RDL/RDLC||
If the xmlRSDocsHarness.exe.config file is set to auto-load to a local SQL Server Compact Edition file (SDF) or SQL Server automatically, the data is also loaded to the specified database by this process. If it attempts to do so and fails, the fourth button in the dialog disables.
If you choose the same report definition file for extraction later, this process removes and replaces your previous entries in the database for this RDL/RDLC. It uses a fully-pathed filename as its key to identify each report and timestamps its entries for the report for your reference.
The xmlRSDocsTestHarness deployment folder points to an initially-empty copy of an SDF, in its db subfolder. There is another empty copy in a subfolder of the EditableResourceCopies folder. You can copy this over the one you've been filling, any time you want to restore it to its start-up state..
|Report on a single.docRDL.xml file||After you have created .docRDL.xml files, you can use them as the datasource for a documentation report at any time. Click the third button in the form to load any existing .docRDL.xml as a report.|
|Document many reports||You can document a whole folder of reports to docRDL.xml files at once,
using the second button in the xmlRSDocsHarness form. Each RDL gets its own
.docRDL.xml file. You receive feedback about how many RDLs were processed,
and about any RDLs that do not process correctly.
On reason why
some RDLs might not process correctly is that you have mixed 2005 and
2008/2010 reports in your folder. xmlRSDocsHarness can only process
one type at a time. If you have set the option to automatically load your
documentation to a database, all the RDLs documented in your DB show in a
new report in the xmlRSDocsHarness form. If you haven't set this
option, the last report documented shows in the report viewer.
|Report on many reports||
When you have loaded .docRDL data to a database, you can prepare a report on multiple RDL/RDLC report definitions at any time without re-reading the RDLs. Click the fourth button in the form to load multiple sets of .docRDL data that have been loaded to a database.
The xmlRSDocsHarness.exe.config file may be set to use a local SQL Server Compact Edition file (SDF), supplied with the deployment files, or it may be set to connect to your own SQL Server instance.
If connecting to the designated database fails, the third button in the dialog disables, and you see an error message indicating what has occurred.
|Change what documentation is extracted||
Because documentation is produced by applying an XSLT transformation to RDL and RDLC files, you can change the documentation by changing the XSLT file.
xmlRSDocsHarness and its default-supplied documenting reports expect to
load data in a standard DataSet format, with specific fields available.
Your XSLT file should produce this format to match the supplied reports (and the supplied SDF database that also stores the data).
|Change the documentation reports (Report1 and ReportMany)||
Because documentation is extracted as data-shaped XML files, you can produce many different types of documentation using these XML files (or their equivalent in a database) and creating standard Reporting Services reports.
|Customize xmlRSDocsHarness's data repositories and behavior||
xmlRSDocsHarness does not supply a means of creating the database, etc. While xmlRSDocsHarness provides a convenient interface for viewing documentation data; it is not intended to provide a production-worthy means to load and maintain documentation data, and has limited "understanding" of the schema you might wish to use.
You find more information about loading a database with docRDL data, below.
|Install SQL Server Compact Edition Runtime||
If your computer does not already have the SQL Server Compact Edition support libraries, locate the db\SQLServerCEDownloadInfo subfolder in the deployment set.
You will find links to information about SQL Server Compact Edition and downloading the (free) libraries required.
SQL Server CE requires minimal space and does not run as a service.
|Install a fresh copy of the SDF file||
|Add custom documentation while designing any RDL: RDLDocumenterDesigner in 2005, Custom Properties in RS 2008|
By default so far, you have extracted only standard RDL/RDLC elements for documentation.
While using TestHarness for xmlRSDocs 2005 you may have seen a small control at the bottom of the form. This is a reminder that xmlRSDocs for 2005 was supplied with a ReportDesigner-hosted control, which you could use to include custom remarks about reports, or individual report elements, during your design process. When you used this control, it placed information into the RDL or RDLC that became available for extraction and inclusion in your documentation, along with the default content.
In RS 2008, RDLDocumenterDesigner is no longer needed, but the idea of custom documentation -- how you use it once added, why you might want to use it, and what general types of custom documentation you might want -- are much the same.
Click here to expand/collapse the RDLDocumenterDesigner2005-specific material in this section.
|Deploy the custom control library for use at design-time in Report Designer 2005||
You may have to give yourself write permissions for the RSReportDesigner.config file that is edited in this task.
Also, the RSReportDesigner.config file may not have ReportItems or ReportItemDesigner entries under Extensions described below, or there may be other ReportItem elements listed under them.
If not, create these parent nodes for each ReportItem under the Extensions element, parallel to the Render, Data, and Designer nodes you see there.
|Add the 2005 custom control for use during Report Designer 2005 sessions in Visual Studio||
|Add RDLDocumenterDesigner to a Report Designer 2005 layout||
A third custom attribute, CustomPropertyNamePrefix, is used in the documenting process. Although user-editable, it does not affect display of the control. When you change the value of this property, whether interactively or by using Reset Defaults, RDLDocumenter asks you if you want to synchronize the documentation you have created to use this new value. It does not remove the documentation you have created.
|Make RDLDocumenterDesigners's custom actions accessible in the 2005 Report Designer||
You can always return RDLDocumenterDesigner to its default attributes using Reset Defaults from the right-click (context) menu, and you can access its Document action, RDLDocumenterDesigner's raison d'être, from the context menu, as well.
You also see these actions accessible at the bottom of the Properties window, in the illustration for the last step. If you prefer this method of accessing custom actions, and if you do not see them in your installation of Visual Studio, you need to turn on the Commands option for the Properties window pane that displays them. To do this, right-click anywhere in the Properties window and click the Commands option in the Properties window’s context menu .
|Use the 2005 RDLDocumenterDesigner-decorated report||
|Add custom documentation attributes to your report using RDLDocumenterDesigner in 2005||
Tip: Documentation items must have names unique in the layout, like other report elements. If your report has a textbox named "Customer" and you try to add the custom documentation element you see in the illustration, RDLDocumentDesigner will prevent you from doing it, with appropriate information. You may want to use a custom prefix for your documentation items, to avoid name collisions (for example: "docCustomer"). This is not required, but there are other reasons you might add custom prefixes to your documentation elements for extra intelligence in output. You see an example below.
|Share decorated report with another report developer who uses Report Designer 2005 -- or another developer who uses Report Designer 2008||
Other report developers can open this RDL or RDLC without issues if they have configured Visual Studio to use RDLDocumenterDesigner in 2005. If they have not, or if they use 2008, you need to remove the custom object before giving them the RDL.
You can retain the documentation information, however, by moving it as-is to become CustomProperty nodes of the Report node.
The standard XSLT treats these nodes the same way when they are under the Report node as when they are under an RDLDocumenter-type Custom Item node.
Follow these steps:
Why not just start with everything under Report? It would be nice but non-custom items don't allow CustomProperties nodes to be created in exactly the same way. You have to add them manually.
We may revisit this series of steps later, if this changes in the ReportDesigner, or at least make it possible for you to add a dummy CustomProperties node to Report manually and use it automatically, if available.
|2008 and 2010 users start with the first item below. 2005 users can use much of this material as well.|
|Create RSdoc-specific properties, globally and on individual object, in RS 2008+||In 2008+, documenting a report during a design session is as simple as
using one or more Custom Properties for your special content. In both
Report Designer and Report Builder you can do this by selecting an object in
the report layout (or the background of the report, for global
documentation), and using the Properties window. You willsee an item
labeled CustomProperties (it's in the Other section of the
Properties window, if you're using the "grouped" view of the window).
Press the ellipsis in Properties window to access the Custom Properties dialog you see in the screen shot. You can create as many Custom Properties as you want in this dialog.
xmlRSDocs "owns" a certain set of features that you can designate by using a special prefix in the Name of your Custom Properties. The default value of this prefix is RSdoc, but you can change it to anything you want (instructions below).
Right now, the only value for Custom Properties that has significant meaning to xmlRSDocs when prefixed by this special string is RSdoc.verbose. This Custom Property can be added to any Report object that requires documentation in greater depth than the basic level.
The meaning of RSdoc.verbose will obviously be different for different report layout controls. For textboxes, for example, the expression for the textbox is only included in documentationwhen you mark the textbox with a Custom Property with this special name, but the same meaning couldn't be applied sensibly to a line or rectangle.
It's important to realize that xmlRSDocs can pull out every detail -- the font name and style for every textbox -- from the RDL, but it doesn't make sense to consider this significant to every report. Not every textbox needs to be documented in any detail at all; many of them have expressions that are easily correlated to a field in the appropriate dataset (the fields are always brought into the documentation, and often a textbox's name as well as its expression tells you exactly what its derivation is). You might decide to mark a textbox as verbose if you needed to document a complex expression, to show dependency on several fields, a coded function, a .NET method, etc.
Right now, the existance of the RSdoc.verbose Custom Property name on an item is enough to invoke verbose documenting behavior. The Value can be empty, or any string you like. However, it's a good idea to include some consistent integer as each RSdoc.verbose Custom Property value. This will make it easier to extend the verbosity system to include different levels of verbosity, similar to what you would see in a logging API.
The xmlRSDocs default XSLT makes this easy to extend, since all verbose behavior is considered in one place and could easily be branched for each layout control type according to verbosity levels.
Although there is no xmlRSDocs-recognized meaning for other prefixed
values besides verbose, you might still choose to create other prefixed
Custom Properties of your own, for example RSdoc.remarks.
This might make it easy for you to query all documentation-related
properties for certain types of reporting, especially if you want to use
Custom Properties for other uses.
|Create non-RSdoc-specific custom properties for documentation in RS2008+||Of course, you can designate any Custom Properties' names you want (with
or without RSdoc prefix, or any other prefix you care to create). xmlRSDocs
will extract and store these values, along with the ones with its "owned"
prefix. It treats the "owned" prefix slightly differently in its
default behavior and data schema, essentially placing them in different
"documentation categories" when storing the documentation, but this might
not be important in your situation.
As an example, the second walkthrough below extracts Permissions notes for use in a specialized document, by searching the xmlRSDocs table.As you can see in that walkthrough, while this Custom Property name has no meaning to xmlRSDocs, t's still easy to query for it and isolate it.
Keep reading in this section for more information about what types of additional Custom Properties you might create, and why. While you can create anything you want, it's a good idea to build a consistent strategy for Custom Properties use, just as it is a good idea to structure any documentation in a consistent structure.
|Don't forget the global properties that the RDL provides natively!||
Before you start adding Custom Properties to serve specific purposes, don't forget that a few are provided natively, and are accessible from the native Designer and Builder surfaces. These, of course, are accessible to xmlRSDocs along with all other RDL attributes, so you don't have to duplicate them.
|Generally useful types of extra documentation||
The problem xmlRSDocs' use of Custom Properties solves is that the
natively-available descriptive or documenting properties are so limited.
xmlRSDocs follows the same strategy. We can easily indicate a set of tags recommended by xmlComments as a core set applicable to reports, such as:
In each case, we only need to create custom properties for information the RDL doesn't give us natively.
For example, we will already have access to the parameter value(s) and type in the RDL. A "param" Custom Property would add documentation on how the parameter is meant to be used, and why it exists.
When deciding where to place this information, we can first ask: is a Parameter object translated to an element in the RDL schema have a Custom Properties child element of its own? and, assuming it does, is this Custom Properties child element exposed in the Report Builder and Report Designer? In the case of the Parameter, the RDL 2008 XSD does not allow for Custom Properties directly. So, for a Parameter, a global Custom Property named param makes sense as a place to store this information.
The same rules that would apply to such tags or Custom Property names designed for a Parameter apply to Code. By contrast, physical objects in the layout, such as an image or even a line, have Custom Properties nodes, so should you choose to create special documentation for an image, you would create them directly for the image(s). Examples of tags you might use, for an image, might be :
indicates that a subset of its "recommended" tags are validated by the
compiler, xmlRSDocs has a limited idea of "validated" documentation.
In xmlRSDocs' case, the "validated" or parsed/compiled tags are the Custom
Properties for which it has specialized behavior. This is the idea
behind xmlRSDocs' special prefix for a subset of Custom Properties.
As one more consideration for how many, and what kind, of Custom Properties you need to create for documentation, consider how these properties will be used by the "documentation pipeline" you're going to apply to xmlRSDocs output.
One technique you can use, to limit the number of Custom Properties required, is to "pack" a single property with structured contents. Typically, you might do this by embedding XML in a single tag.
For example, you could have a single param Custom Property that contained within it a value that looked something like this:
Even though XML packing is a good choice for structured contents, again, consider the way you want to publish the documentation and what will work for these target formatting types. For example, you might be using SSRS RDLs to publish your documentation exclusively, rather than something that requires more extensive work for formatting (such as an integration into SandCastle or NDocs). In this case, you could decide to "pack" your documentation in embedded HTML. One of the walkthroughs below shows you how an SSRS report takes advantage of this strategy.
If you decide to "pack" complex structured content using embedded HTML, it's always best to follow a few rules to allow for future expansion of your publishing targets and pipelines:
Adding specialized documentation, such as images, to your xmlRSDocs data
The little RDLDocumenterPropertiesEditor dialog does not have extensive
capabilities in its current state, and the ability of a standard RDL CustomProperty
node to store complex information is limited as well. Even in this prototype
condition, however, it offers some room for extension features. You can
use the editor dialog to make some distinctions between various types
of custom items you might "attach" to a report for documentation purposes,
without making any code changes or enhancing the dialog.
In this example, we will add screenshots to our documentation of a report by using a naming convention; all custom items that start with IMG_ are understood to reference image files. The ReportMany.RDLC supplied with xmlRSDocsHarness.EXE respects this specific naming convention, and treats any such data rows differently from all others.
xmlRSDocs "understands" additional complexity, by using custom-namespaced additions to the RDL/RDLC, and it also supports the idea of "documentation categories" for other types of flexibility. However, you cannot add this information from within the ReportDesigner.
You can extend the next Walkthrough's idea of "packed" or structured content to add "documentation categories" to any Custom Property. If you are "packing" your structure using XML, simply create a <category> child element, or something similar, in your XML structure. If you are "packing" your documentation using HTML, as shown in the walkthrough, you can use classes on the HTML elements for this purpose.
You can later update the RDLCategory field you'll find in xmlRSDocs base table structure, or whatever column you like, by extracting this information.
"Packing" value into a Custom Properties with embedded structured content
In this example, we want to "pack" information into a "permissions" Custom Property so that the contents can contain a list of requirements to access an RDL.
We create a Custom Property with the Name we've decided on for this use, and simply type the list content into the Value for this Custom Property, as we normally would.
When we use xmlRSDocsHarness to extract documentation from this RDL, neither Report1 nor ReportMany "know" anything about our special property and usage, so the raw HTML appears as the Custom Properties' value in the xmlRSDocsHarness UI.
Of course, you could edit Report1 and ReportMany and select your edited samples for use in xmlRSDocsHarness, but they're just simple samples, and probably not the right presentation for your "permissions" report.
Instead, you create another report specificially for the purpose you have in mind. To extract the documentation details you want for this specialized "permissions" report, you use this query to drive your RDL dataset:
select * from [xmlRSDocs].[dbo].[RDLDocPrimary] where RDLLayoutType = 'CustomProperty' and RDLLayoutName like '%permission%'
To richly format the content of the appropriate textbox, you use the Placeholder attribute in Report Builder or Report Designer that tells the RDL a text item contains HTML markup.
The point of this (simplified) walkthrough is to show you "packed"
information within a single Custom Property, in action. Don't be
concerned because it shows as encoded in the RDL; you can use XML or HTML
tags and everything will work out well even though it might look strange in
the raw RDL.
|Change xmlRSDocs' "owned" prefix||
You can use RDLDocumenterDesigner's CustomPropertyNamePrefix to change this value,
if necessary, in 2005, and of course you do the same thing in 2008+
simply by designating a different, special prefix .for xmlRSDocs-specific
|Edit custom documentation directly in any RDL||
|Deploy RDLDocumenter-decorated reports to a Reporting Services server (SSRS 2005 only): Options|
What happens to an RDLDocumenter-decorated report when you deploy it? Here are your choices.
This section is relevant to 2005 users of RDL Documenter only.
|Keep RDLDocumenter in report "invisibly"||
As mentioned in an earlier section, you don't have to do anything to deploy reports with RDLDocumenter included. If a Reporting Services server does not have the control registered, it will ignore the control and render a blank rectangle.
If the control is registered on the server you can still choose to have it rendered for some reports and not others, using the ShowValue attribute.
|Make RDLDocumenter visible in deployed reports||
Registering the control on a Reporting Services server requires steps similar to registering it for design use.
|Remove RDLDocumenter before deployment||
You can remove RDLDocumenter as described in the section on sharing the decorated report definition document with other editors. Your documentation will be retained if you follow those instructions, either manually or using the supplied DeployRDLWithoutDocumenter.VBS script.
In some cases, you don't need to retain the documentation nodes any more, perhaps because you have already extracted a final version of the documentation to a database repository and archived the report definition. If so, you can simply remove the control without worrying about preserving the custom information.
Whether you choose to preserve or discard the custom documentation elements, removing the control will not affect anything else in your report and the report definition remains valid.
|Turn any RDL or RDLC into RDLDoc.XML: Sample VBS script|
As you learned by using xmlRSDocsHarness, you don't need to add custom documentation to a report to extract a standard set of documentation from the report. You can do this without using xmlRSDocsHarness' interface, by using the simple steps shown here on any report(s) you have handy. If you have added custom documentation, either by hand-editing the XML, by creating custom properties in the 2008 Report Designer and Builder, or by using the RDLDocumenterDesigner object in the 2005 Report Designer and Builder, of course these items are extracted too.
|Perform the process in a console (CMD) window||
At a command window, navigate to the 2008\AdditionalSamples directory and execute the transformRDL.vbs script. Without parameters it will indicate that you must provide at least one, and optionally two, fully-pathed filename arguments. The first argument is the RDL or RDLC that you wish to process to docRDL.xml, and the second is the XSLT transform to use.
If you do not pass the second argument, by default the script uses 2008\EditableResourceCopies\xmlRSDocsRS2008.xslt file.
If the script can find and process your nominated RDL or RDLC file, the matching docRDL.xml file is generated and saved to the directory holding the report.
The script is not very elaborate but, if it cannot process properly, you will see a raw scripting runtime error letting you know.
|Use drag-and-drop with the VBS script||
You can drag-and-drop an RDL or RDLC file onto the transformRDL.vbs file in Windows Explorer windows, for the same effect.
You can also drag-and-drop both an RDL/RDLC file and an XSLT file onto the script, as long as the name of the RDL/RDLC file will be sorted alphabetically before the name of the XSLT file you choose, to ensure the proper order of the arguments.
|Learn more about using the same syntax in your own programs||While transformRDL.vbs is a simple script showing the simplest and most version-independent COM syntax for applying an XSLT transform to an XML file, it also contains notes showing you additional, and more powerful syntax. If you plan to use XSLT in COM scripting, please take a look at the comments in this script for some recommendations.|
|Load RDLDoc.XML to any database, and analyze the results: Sample SQL scripts|
Just as you don't need xmlRSDocsHarness to extract documentation to docRDL.xml, you don't need xmlRSDocsHarness to move that regularly-shaped XML into a database. You can do it with the simple scripts discussed in this section.
Once you're got your docRDL data into a "real" database, the sky's the limit for the information you can pull out of it. This section introduces some SQL code useful in real-life SSRS analysis, also available in the sample code.
|Create a Microsoft SQL Server table suitable for holding the default docRDL-shaped rows||
Your AdditionalSamples directory contains a CreateDocTable.sql script to create a table with appropriate columns.
This script uses the same syntax that the production SSIS package, discussed below, uses if the table is not found in the database you nominate for docRDL loading.
You can execute the script in any database context that you want to use to hold this information. The database doesn't have to have any particular name. You may want to add it to a database you use for other metadata purposes, or consider it a temporary "holding" table from which you will extract and normalize your version of this data.
|Load documentation data to a database manually||
The xmlRSDocsHarness application can docRDL.xml directly to a SQL Server table, as explained in an earlier section; it auto-loads if you have chosen this configuration option.
However, you can take the docRDL.xml files you created (whether using the xmlRSDocsHarness.exe interface or the transformRDL.vbs script) and load them to your table by running a SQL procedure that "shreds" the xml files.
You'll find the SampleRDLDocXMLShredderProcedure.sql script file in your AdditionalSamples directory, along with the other script files. You should run the script to create a stored procedure with the name dbo.ShredRDLDoc in the same database as you created the table earlier.
The stored procedure takes a single argument, which is the fully-qualified name of a docRDL.xml file. When it runs, it creates a "transfer" table for use in consuming the XML if it doesn't find that table in the database. It then loads the XML file to this table and, from there, creates rows in the the RDLDocPrimary table you created in the last step.
You can easily see that you could call the procedure with different docRDL.XML filenames, in a loop, to load them all to your datbase table. While neither this stored procedure nor its style of XML-uploading is used in the SSIS production package, you can probably see that the package follows a similar path to handle a set of report definition files.
|Use your database table with the xmlRSDocsHarness application||
Once you have your docRDL data stored in a database, you can easily point xmlRSDocsHarness at this data for reporting. Set its configuration options (in the xmlRSDocsHarness.exe.config discussed earlier) as follows:
|Smart-parse additional detail from the values in the table|
While xmlRSDocsHarness is very convenient for quick RDL imports, and while its delivered RDLCs help you quickly evaluate your documentation strategy, it's hardly the be-all and end-all of what you can get out of xmlRSDocs data. Your 2008\AdditionalSamples includes a file named udf_xmlRSDocs_GetCommandTextEntityList.sql, which you can use to get a list of entities used in the CommandText values the RDL uses to load each of its Datasets. This is a table-valued function, returning one row for each entity it finds. It marks the entities "base" or "path", if the CommandText it parsed is a semantic model description, and "from" or "join" if the CommandText was a SQL SELECT statement. If the CommandText was a stored procedure, it marks the value as a "sproc".)
Calling the udf on your xmlRDLDocs data is as simple as the following SELECT statement, which is used in the accompanying RDL (xmlRSDocsEntityReport.rdl) to provide the final/formatted analysis result:
select distinct rdlFileName, rdlLayoutParentName, docServer, udf.* from RDLDocPrimary r cross apply dbo.udf_xmlRSDocs_GetCommandTextEntityList(r.ParseableValue) udf where r.RDLLayoutType = 'CommandText'
The production SSIS packages discussed in the next section use this sample RDL and UDF as a way of showing an end-to-end RDL documentation process. If you decide to turn on the option that the packages use to export its loaded xmlRSDocs results from a database to a PDF, you can use this RDL and deploy this UDF... or easily come up with your own versions.
Suppose, for example, you need to look at a list of datasets and fields being used in your RDLs. You don't really need a report to look at this; all you really need is an ad-hoc SQL query, such as this one:
select RDLFileName, RDLLayoutParentName, Value from RDLDocPrimary where RDLLayoutParentName like '%-Fields'
If you're dealing with semantic-model-sourced dataset, things might be slightly harder, but you can still "get at" the details of your RDL data sources with ad-hoc SQL queries, such as the following:
select Convert(xml,Value).query('//*:AttributeRef') from RDLDocPrimary where RDLLayoutType = 'CommandText' and Value like '%<!--%' -- you will see xml elements with embedded comments -- similar to the ones that the sample UDF parses for you -- in its semantic model-handling logic
|Set up an automated production deployment: xmlRSDoc's SSIS package(s)|
xmlRSDocsHarness's internal code, and the scripts discussed in the last two sections, prototype RDLDocumenter's production processing. This section discusses the customizable SSIS packages that put everything together, to automatically extract and load documentation from a set of reports into the database of your choice.
While the two packages are very similar in approach, they are both useful, because:
|Set up the package(s) for debug-style use in Visual Studio||
Open the xmlRSDocsProcessing2008.dtsx or the xmlRSDocsReportServerProcessing2008.dtsx package in the xmlRSDocsProcessing project, or add the DTSX package you choose to a SQL Server Integration Services project of your own. Setup for the two packages is similar; the instructions below work for both.
With the package open, navigate to the list of Variables. You'll find the package defines a number of package-scope values. These variables and some additional features of the package must be configured before you can run the package in your environment.
If you deploy the package to SQL Server later, you will re-set most of these values. But you may never need to deploy the package to run it; it's just fine to run it from Visual Studio. You still get complete results.
|Run the package in debug mode||
With the values in the last step properly configured, you should be able to run the package from the Visual Studio Debug menu. Depending on how you have set the variables, you should be able to confirm that the appropriate execution path(s) executed successfully.
If either package fails to load the data successfully to your SQL DB, and everything else runs properly, you may need to Run Visual Studio As Administrator in your environment.
If the ReportServer package does not successfully complete the first script task in the for-each loop container, named Download the RDL and check its schema - C#, you may have to reattach its SOAP proxy client class. Doubleclick the script task and choose to edit its script. You should see an included class in the script project, named Reference.cs.. If the class does not appear or the project cannot resolve the reference, you can re-add the class to this script project; it's included in your source. Look for it in the \xmlRSDocsSSISProcessing\Resources\GeneratedSSRSWebReference project; drill into the WebReferences folder. This generated proxy class is necessary because the script project doesn't hold on to a Web Reference if you try to add one directly.
|Set package variables for optional features||
The following table lists the various optional features you can configure by changing the value of package variables in xmlRSDocsProcessing.dtsx. Variables not shown here are used in processing; and their initial values as shown in the Properties window shouldn't be altered.
|Extend xmlRSDocs to new documentation schemas and new types of output|
The ExportRSResult output target introduced in the last section only hints at the vast number of things you can add to xmlRSDocs' default SSIS packages by adding new tasks and new types of output results into the SSIS package. You can also vastly improve the type and quality of documentation available from xmlRSDocs data by adding more metadata tables into your database, such as lookup tables that recognize documentation categories, order them intelligently, etc.
By extending other aspects of the xmlRSDocs feature set or -- more importantly -- the xmlRSDocs concept and motivating ideas, you can do much more.
|create new dialogs and/or change XSLT to allow more flexible categorization|
|Create Sandcastle and other output formats using a second XSLT in the pipeline|