xmlRSDocs Deployment and Use

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.

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.

This section covers a design time tool that you can add into Report Designer 2005, which writes to the RDL for you using a specialized syntax that overcame these problems.

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:

• Global custom attributes. By default, the Report Properties dialog in the Report Designer provides a way to add an Author and Description to each report, but RDLDocumenterDesigner allows you to add other global attributes (such as Customer and Department).
• Comments for individual report items. You can pick individual items from a list by their unique layout control names, and add free-form comments.
• General indication of extra significance to individual report items. Similar to logging APIs, xmlRSDocs has an idea of "verbosity" built-in, meaning that you indicate that some report items are of more interest, and deserve more detail in the extraction process, than others. At present, xmlRSDocs exposes only a rudimentary understanding of what extra content you might want, and RDLDocumenterDesigner supports only one level of verbosity, which you can set "on" for any items of special interest. However, xmlRSDocs's mechanism for recognition and expressing verbosity is easily extended.

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.

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:

• dynamic data binding and report-switching with a ReportViewer control
• use of XML as a datasource for a report
• using embedded versus external reports with the control (xmlRSDocsHarness uses both, so you can switch between its internal test report set and your own edited copies).
• transparent use of different types of data connections -- including, in xmlRSDocsHarness' case, configuring and connecting to using both SQL Server Compact Edition and other SQL Server editions as well as XML.

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:

• XML column to database mappings as part of a dataflow
• dynamic use of a file collection task
• Invoking Reporting Services using URL Access for export, within the SSIS context.
• Invoking Reporting Services using SOAP within the SSIS context.

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.

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:

• an XML syntax derived from XML Comments, commonly used to provide class documentation in .NET Framework code and used by documentation generators such as NDoc and Sandcastle .
  You can think of the base information that xmlRSDocs pulls out of report definitions as the equivalent of the reflection-based code that NDoc and Sandcastle can create from class definitions. Using XML Comments, developers provide additional custom comments to generated class information. RDLDocumenterDesigner provides a simple way to do this, but XML Comment syntax is much richer. For instance you might want an extension comment that looks similar to an XML method header, like this:

  <RSdoc:example>

  <remarks>may be as much as 100 chars</remarks>

  <code>this is a sample output value</code>

  </RSdoc:example>

• a companion syntax to XML Comments, specific to xmlRSDocs, which allows you to designate a type of documentation instruction as applicable to all children of a specific report element, or all siblings of a specific report element. For example, in a table that used many dynamic color expressions to indicate data classifications, you could use an expression like this to indicate that you wanted to include these expressions in your xmlRSDocs extractions, even though for most items the Color property is not considered significant enough to document:

  <RSdoc:Sibling>

  <Label>Color Expression</Label>

  <Item>Color</Item>

  </RSdoc:Sibling>

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.

Run the xmlRSDocsHarness.exe executable file in the Deploy directory to invoke its winform interface.

1. Click the top button in the xmlRSDocsHarness interface.
2. Browse and select an RDL or RDLC file
3. Documentation is extracted to a .docRDL.xml file in the same directory.
4. After creating the .docRDL.xml file, xmlRSDocsHarness loads the file as a dataset serving as the data source for a report, which appears in the lower half of the xmlRSDocsHarness form.
5. Resize the form and explore the default data that has been extracted and is available to you.

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.

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.

Because documentation is produced by applying an XSLT transformation to RDL and RDLC files, you can change the documentation by changing the XSLT file.

1. Click the fifth button to browse for a different XSLT transformation to use.
2. You can try out the samples you find in the EditableResourceCopies folder. These XSLTs are copies of the embedded XSLTs (one for the 2005 RDL schema, one for the 2008 RDL schema which can also be used on 2010 schema RDLs) resources in xmlRSDocsHarness. You can examine and edit these files to change which RDL elements are extracted, what level of detail is included, what documentation categories are used for various types of elements, etc.
3. When you choose a file, it is loaded for the next RDL/RDLC extraction you select. If you cancel from the dialog, the default (embedded resource) XSLT is loaded.  As delivered, this is the 2008 RDL schema-handling XLST; however, you can use an EXE config option to determine whether the 2005 or 2008 version is loaded as the default XSLT.
   Note that you can, and should, use the 2008 XSLT if you have 2005 reports that have been up-converted to the 2010 schema reference. If your older reports include 2005 RDLDocumenterDesigner notations, these notations will be correctl interpreted by the 2008 XSLT.

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.

1. Click the sixth button to browse for different reports.
2. You can try out the load process by using the samples you find in the EditableResources sub-folder. These are copies of the default, embedded RDLC resources that xmlRSDocsHarness uses. They produce the same results as the embedded RDLCs unless you alter them.
   The report names Report1.RDLC and ReportMany.RDLC are required, and they must be in the same folder.
   In the EditableResources folder, along with the RDLC files, you find the definition files for DataSet1 and DataSetMany, which support the two reports supplied. They are the same structure except that DataSetMany includes two additional columns, RDLFileName and DocDate, which are loaded to the database along with the contents of the documentation extracted from the single RDL/RDLC files, to support documenting multiple reports.
3. When you choose a file, it is loaded for the next RDL/RDLC extraction you select. If you cancel from the dialog, the currently-loaded reports (whether embedded or external) remain loaded.
4. Try a simple alteration to these editable copies, such as a change of background color for some element, if you want to test which version is really being loaded in xmlRSDocsHarness.
   You may need to toggle between Report1-ReportMany, or close the application and re-open, to see any difference. xmlRSDocsHarness tries not to re-load reports unnecessarily, so if you don't change the report folder location it may not "notice" the change right away.

1. Close the xmlRSDocsHarness form.
2. Open the xmlRSDocsHarness.exe.config file in your favorite XML editor (or Notepad!).
3. There are five user-settable values:

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.

1. The EditableResourceCopies\xmlRSDocsHarness-Specific\dbCESamples folder contains a copy of the deployment set's xmlRSdocs.SDF file in the SQL CE 3.5 version, plus another one in the earlier SDF format that xmlRSDocs' TestHarness 2005 originally supported. Copy the SDF file to a different location, or replace the deployment set's xmlRSdocs.SDF file if you do not need to keep its contents.
2. Edit the xmlRSDocsHarness.exe.config to match the SDF file you want to use.

1. Locate your Visual Studio installation files (for example, C:\Program Files\Microsoft Visual Studio 8).
2. Copy the Spacefold.RDLDesigner.dll into the Common7/IDE/PrivateAssemblies folder of your Visual Studio installation.
3. Edit the RSReportDesigner.config file you find in the same location to include the following node as a child of the /Configuration/Extensions/ReportItems element (remove the comment tags from what you cut and paste from here):
   
   <!-- <ReportItem Name="RDLDocumenter" Type="Spacefold.RS.Extensibility.RDLDocumenterRenderer,Spacefold.RDLDesigner"/> -->
   
4. Edit the RSReportDesigner.config file to include the following node as a child of the /Configuration/Extensions/ReportItemDesigner element:
   
   <!-- <ReportItem Name="RDLDocumenter" Type= "Spacefold.RS.Extensibility.RDLDocumenterDesigner,Spacefold.RDLDesigner"/> -->

1. Open an RDL or RDLC for edit in Visual Studio.
2. Right-click on the ReportItems group in the Toolbox -- or, if you prefer, create a new group and right-click on its header.
3. Select the Choose Items... option in the context menu.
4. Browse to the PrivateAssemblies location in which you copied Spacefold.RDLDesigner.dll and choose that file in the nested dialog.
5. The two controls you added to the config file (RDLDocumenter and RDLDocumenterDesigner) should appear in the list. Both checkboxes are usually clicked "on", and both are selected/highlighted in the list. You can chose to accept this default, or you can un-select RDLDocumenter; ensure that RDLDocumenterDesigner is selected and checked.
6. Press OK in the dialog to return to the report design layout.
7. The RDLDocumenterDesigner control appears in the Toolbox. (RDLDocumenter does not appear even if it was selected in the dialog.)

1. Drag an instance of the RDLDocumenterDesigner component to your layout. Size it as desired.
   
   You only need one instance of the the control in the layout. You can place it anywhere in the Body section; Custom Report Items are not allowed in the Page Header or Footer. It doesn't seem to work when placed directly inside a List element in the current version, although it can be in a Table or Matrix (which may be inside a List).
   
   Since there is little reason to want to render repeated instances of the control, it's best placed outside any data region, in an "empty" area of the Body layout.
2. Since you can render the control at runtime if you wish, a few standard appearance and style elements are editable: font color, background color, and font size. (Font size does not change in the designer layout, but your edits to this property show in Preview.)
3. You see a custom attribute, DisplayName, which you can use to change the text displayed by the control. Alternatively, you can use the custom attribute ShowValue, which you can toggle to change whether RDLDocumenter renders at all. In the illustration, RDLDocumenter's appearance has been customized.
4. You see a custom action, Reset Defaults on the context menu and at the bottom of the Properties window, which you can use to restore the control to its default appearance.

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 .

1. You can preview with the custom control in place at this point; it should appear (or not, if ShowValue is False) as expected.
2. You can also deploy the report to a server, as-is. Because the server does not have the control registered for use, a default blank rectangle renders for this control.
   Tip: you can size the control very small and leave it in place for deployment. You can also deploy the control to a server, if you wish. More information below.

1. Choose the Document custom action from the context menu or Properties Window entry for the custom control.
2. A RDLDocumenterPropertiesEditor dialog appears, listing the various elements of the report. You can select the checkbox of individual items for verbose documentation. This has the effect of adding extra data rows with detailed information about the marked items, if your XSLT contains appropriate instructions.
3. When an item is selected, the Edit Selected Item... button enables. You can add custom information about any report element. You can also add custom-global documentation elements, such as the name of the customer who requested the report.

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.

Follow these steps:

1. Save a copy of the original file, in case you want to revert later in this process.
2. View code (XML) for the RDLC or RDL, in any XML Editor.
3. Look for a CustomProperties node for your Report's root node. It probably doesn't have one.
4. Locate the CustomProperties node for your RDLDocumenter object. If the Report root node already has a CustomProperties node, select and copy the documentation child nodes you wish to preserve. If the Report root node doesn't have a CustomProperties node yet, just select and copy the whole CustomProperties node.
5. If the Report root node already has a CustomProperties node, paste these nodes into it. If the Report root node does not yet have a CustomProperties node, paste its new CustomProperties node anywhere directly under Report. (It doesn't matter whether it's first, last, or in the middle, as long as it is a direct child of Report.)
6. Save your changes, and view the report in Layout mode again. It should open properly. If it does not open properly, revert to the copy you saved, and try again.
   
   
   A VBS Script, DeployRDLWithoutDocumenter.VBS, is included in the Additional Samples directory. You can use it to perform the steps above. You should still manually remove the RDLDocumenter instance, or instances, in the Report Designer from the adjusted report.
   
7. Select and remove the rdlDocumenter custom control from your layout, and save the report.
8. To test, re-extract documentation from this report in xmlRSDocsHarness. It will behave the same way as before, and the two supplied reports will give you the same results.

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.

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.

The problem xmlRSDocs' use of Custom Properties solves is that the natively-available descriptive or documenting properties are so limited. 
Which ones do you need to add, on both a global and an individual object level, will depend on your practices and your organization. xmlRSDocs doesn't restrict this or require any particular set.  It simply suggests that xmlComments is a good place to start looking, since this would make your RDL documentations coordinate well with your practices for documenting other Visual Studio types of code.
Suppose you don't use, or don't like, xmlComments.  All you really need to do is create a set of Custom Property tags that are parallel to your other documentation efforts, however you do it.  Since xmlRSDocs simply puts them all into a database or a datatable-shaped XML file for you, you're free to query and organize the results however you wish.
You'll notice that the xmlComments doesn't specify all the possible documentation tags that are acceptable, either.  It has a set of "recommended tags", and, within that set, it marks some as tags for which the compiler will verify syntax. 

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:

• param
• code
• remarks
• seealso
• permission

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 :

• copyright-status
• version

Just as xmlComments 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.

In both cases, xmlComments and xmlRSDocs are telling you about tags or names that are expected to have some sort of specialized meaning and contents, and that will be used accordingly; all other tags' or names' contents are simply passed along verbatim in the documentation chain, so you can do whatever you want with them.

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:

<param>
<usage>This parameter contains multiple values available for selection only if the user is an administrator.  Otherwise, the dropdown has only a single value appropriate to the user. </usage>
<modified>LSN 1/1/2011</modified>
<remarks>The selection code here should be used as a template for future reports with similar requirements. </remarks>
</param>

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:

1. Always ensure that your HTML is also well-formed XML so a parser can deal with it properly later.  Even custom code in a SQL function will have an easier time parsing the HTML values if it was wellformed. (There is an example of such code supplied as a UDF with xmlRSDocs; it parses entity names out of a semantic model definition.)
2. Whenever feasible, use some consistent classes or id attributes on your various HTML elements, so that the parse can deal with the content intelligently (parsing and classifying its meaning) later.

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.

The same principles apply to making distinctions between Custom Properties in 2008+.  If you keep a consistent strategy for how you use Custom Properties, how you prefix property names, etc, you can ensure that one or more specialized behaviors are triggered by one or more documentation attributes at runtime.

Walkthrough 1

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.

1. While designing a report layout, open the RDLDocumenterPropertiesEditor dialog, if you're working in 2005.  In 2008+, just create one or more Custom Properties on the global/Report level for this exercise.
2. Add a custom item for each screenshot you want for the report, with a name that starts with IMG_. The value for each such property should represent the image you want to include. As you see in the image here, you can use a UNC (with http:// or file:// locations). If you extend the default RDLDoc default database schema and store images in a database column, you can use other types of expressions here.
3. Save your report and re-run xmlRSDocsHarness.EXE. When you re-extract docRDL.xml from this report, Report1.RDLC treats your new custom items like any other documentation item, because it does not "understand" that the IMG_ prefix makes them special. However, ReportMany.RDLC loads these properties into images, and places them before other documentation rows for this report.
4. The image in this section shows a composite view of this walkthrough. In the background, you see the report being worked on, with the special custom properties for the report screenshots being assigned in the RDLDocumenterDesigner dialog. In the foreground, you see the resulting ReportMany.RDLC display in xmlRSDocsHarness, with an embedded image in its contents.

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. 

As recommended in an earlier section, unless you know that all your documentation targets are going to "understand" HTML markup, you probably should use XML, rather than an HTML concept such as a list, to structure your "packed" content.  You can always create some sql syntax, and XSLT, or even just a code function within the "permissions" report, in this case, that parses the xml and extrudes HTML formatting when you need it.

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 behavior.

In 2008, be sure to change this value consistently across all the objects and global properties for which you have designed RSdoc-specific instructions. The 2005 RDLDocumenterDesigner control ask you to confirm and then change all of "its" prefixed properties to the value you chose. But it won't know about any additional CustomProperty nodes you've added to other objects. Change the Name values for any such CustomProperty nodes you have moved to other locations in the layout, to match, the value you have used in CustomPropertyNamePrefix if you want the RDLDocumenterDesigner control to take care of them again later.

To "connect" with your new prefix, the standard XSLT also needs to know your preference for the CustomPropertyNamePrefix, to know what custom properties "count" as documentation. Tell the standard XSLT about what you've used, by changing a value you see at the top of the XSLT file, in the parameter section. Change RSdoc. in the select attribute, as shown below, to what you have used. Be sure to finish the prefix with a full stop (".") character, as shown here, and also to preserve the single quote characters surrounding your prefix and marking this parameter as a string value:

<xsl:param name="RSDocCustomPropertyNamePrefix" 
        select="'RSdoc.'"/>

1. View Code for the RDL or RDLC file, in any XML editor.
2. If you are working in 2005, find the documentation attributes you added included in the RDLDocumenterDesigner control's CustomProperties set along with its standard attributes, such as DisplayName. You can edit them, or remove them, here. If the report layout is open, and if you save your changes to the XML, the report layout reloads and your changes are immediately available in the RDLDocumenterPropertiesEditor dialog.
   If you are working in 2008+, the same instructions and reload behavior apply, except that you will find your documentation attributes visible on the Report level and/or on individual report elements, as standard Custom Properties.
3. If you're using RDLDocumenterDesigner in 2005, observe that the documentation properties are prefixed with the value you see in the CustomPropertyNamePrefix attribute. This distinguishes them from other attributes that the control has, since this custom item's CustomProperties collection has to do both jobs.
   This prefix is also used in 2008+, or in 2005 if you choose to move these CustomProperty nodes to other, standard RDL nodes, to retain your documentation while removing the control from the report design. The standard XSLT looks for this prefix in CustomProperty names for any RDL node, and distinguishes other possible Custom work using Custom Properties, so that it can apply its special behavior to known xmlRSDocs instructions.

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.

Registering the control on a Reporting Services server requires steps similar to registering it for design use.

1. Copy the Spacefold.RDLDesigner.dll to the bin folder under your ReportServer instance; for example C:\Program Files\Microsoft SQL Server\MSSQL.3\Reporting Services\ReportServer\bin.
2. In the directory above, in this example C:\Program Files\Microsoft SQL Server\MSSQL.3\Reporting Services\ReportServer\, edit two configuration files, as follows (as before, omit the comment tags from what you copy and paste from here):
   • rsreportserver.config requires the same rendering instructions as you gave to the Designer configuration file. In its Extensions/ReportItems node which (as before, you can add if it does not exist), you must include the same ReportItem as you gave the Designer:
     <!-- <ReportItem Name="RDLDocumenter" Type= "Spacefold.RS.Extensibility.RDLDocumenterRenderer,Spacefold.RDLDesigner"/> -->
   • rssrvpolicy.config needs to be told that this new extension is safe. Add the following IMembershipCondition node to a CodeGroup that grants permissions to the zone in which you determine that this code should be accessible, adjusting the filepath in the Url attribute value you see here as appropriate:
     <!-- within in a CodeGroup node that looks like this: <CodeGroup class="UnionCodeGroup" version="1" Name="MyCodeGroup" Description="Code group for my tools" PermissionSetName="FullTrust"> --> <!-- <IMembershipCondition class="UrlMembershipCondition" version="1" Url="C:\Program Files\Microsoft SQL Server\MSSQL.3\Reporting Services\ReportServer\bin\Spacefold.RDLDesigner.dll"/> -->

    

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.

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.

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.

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.

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.

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:

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
  
  

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.

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.

1. First, establish the correct values for folder and server resources used in processing.
   

   ResourceDir	Point to the directory holding the XSLT transforms used to extract rdlDoc.xml, the T-SQL script that describes the structure of the matching data table, and a sample of the output XML with its matching XSD, required to set up one of the SSIS tasks. Example: C:\WORK\xmlRSdocs\Resources\
   InputDir (FileServer) or OutputDir (ReportServer)	For the File Server package, point to the directory holding the RDL and/or RDLC files to be processed. If you choose to save the doc.XML files to disk, they will be placed in this location too. For the Report Server package, point to the directory in which you want to export the doc.XML files, if you choose to save them to disk, and/or the export file, if you choose to "publish" a report result at the end of the package. Example: C:\WORK\MyReports\ For the File Server package, your InputDir location should hold only 2008-schema RDLs for this run, because the File Server package supports a single XsltValue configuration value. When you work in the File Server context, xmlRSDocs can make the simplifying assumption that you have control over what's contained in your input location, and you can do separate runs (with separate InputDir values matched to varied XsltValue files) for RDLs that conform to the different schemas. While the package won't fail at the transformation step if you have mixed namespaces in your RDL/RDLCs, only one namespace will actually produce any docXML content and inserts into your DB -- because the XSLT will only be able to handle one of the two possible namespaces. The Report Server package does not have this restriction. In the Report Server context, xmlRSDocs assumes you do not have control over what's contained in your source (InputSSRSURL) location. For each report in the report catalog, the package script "peeks" at the RDL namespaces and adjusts the current XSLT value to suit. It doesn't process any RDLs that do not correspond to one of the namespaces it recognizes. Currently it recognizes three schemas: 2005 2008 2010 The 2010 schema, which belongs to RS 2008 R2 (at this writing), is not completely supported, in that some of the newer R2 elements are not recognized and dealt with explicitly yet. However, most of the basic information available in a 2010 RDL will be correctly documented.
   InputSSRSURL (ReportServer only)	The SSRS server supplying a Report Catalog to process. This value should be the correct endpoint for the SOAP service on the server. If StoreDocToTable is True, this value is stored to the SSRSID Column (by default this column is named DocServer), so that documentation content for RDLs on different servers can be analyzed separately. Example: http://myserver:80/ReportServer/ReportService2005.asmx

   
   
2. Next, establish the correct value for two Boolean values for types of output you choose to receive on your first run. You can get both types of output (and additional types, later) from the same run:
   

   SaveDocFile	If True, your docRDL.xml files are saved to disk in the input directory, just as xmlRSDocsHarness.exe saved them. The SSIS package doesn't need to have the files on disk, if you're using a database, but the external files have additional uses, as you'll see later.
   StoreDocToTable	If True, your documentation rows are inserted in a SQL table.

   
   
3. Next, configure the data flow task labelled Insert Rows from Dox XML to SQL Table, which you'll see at the bottom right side of the processing loop that forms the main part of the control flow for the package. (Perform this step even if you have set StoreDocToTable to False and you don't intend to use the right-side processing branch that stores docRDL.XML to a SQL table, so that the package compiles properly. If you don't do it correctly, you will probably have to fix several things using the Advanced Editor dialog later!)
   • Move to the data flow tab for the package.
   • Right-click on the XML Source task and choose to Edit, or navigate to the Properties window with this task selected..
   • Set the XSD location value to match the location of the Resources folder for your disk.
     
     
     
4. If you have set StoreDocToTable to True, and if you're going to use a separate/new database for your xmlRSDocs data, create the database on the SSRS server of your choice.
5. If you have set StoreDocToTable to True, configure the xmlRSDocs.RDLDoc SQL connection in the Connection Managers pane. Edit the values, using either the Properties window or the Connection Manager dialog, to match what you need to connect to the database server that holds your designated database.
   
   
6. If you are using the ReportServer package, you need to configure a second SQL connection, SSRS.ReportServer. Point this one to the ReportServer DB for the SSRS instance you want to document. Remember that it may not be on the same server as the URL for the SSRS instance! This connection is used to supply a catalog list of the reports to document. The server's SOAP methods are called in a loop, for each report found in the catalog by an initial query to this db.

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.

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.

• Used for all output types

• Used when SaveDocFile is True

• Used when StoreDocToTable is True

  These values allow you to change the "shape" of the stored documentation information. They are all String type.

• Used when ExportRSResult is True

  The ExportRSResult Boolean-type variable provides an automatic export path to generate Reporting Services output from your RDLDoc database table and "publish" the results to a file on disk. The additional task used to accomplish this (after the file-processing control loop) is only available when StoreDocToTable is also True.
  
  While the variables below, all of String type, have default values, they won't do you much good unless you create and deploy an appropriate report to Reporting Services.