|
|
these are early adopter draft docs
an early deployement set of files is available from our download page |
these notes require javascript
in your browser |
click these symbols to expand and collapse
doc sections below: 
hover over this symbol 
to see an illustration briefly; click the symbol to show an illustration of the step embedded in the page (for printing purposes or close viewing); click the illustration to hide it again. |
| A documenting tool for report metadata, using reports |
 |
RDLDocumenter "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.
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, RDLDocumenter 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, RDLDocumenter has 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, RDLDocumenter's mechanism for recognition
and expressing verbosity is easily extended.
|
| A showpiece for various corners of the SQL Server and Visual Studio
"universe" |
 |
RDLDocumenter has a simple interactive TestHarness that allows you
to see how all its pieces work together. The TestHarness 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 (TestHarness
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 TestHarness' case, configuring and connecting to using both SQL Server
Compact Edition and other SQL Server editions as well as XML.
Beyond TestHarness, RDLDocumenter supplies 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 RDLDocumenter also has 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 an SSIS package, which can configured to your requirements.
The SIS package 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.
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.
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 |
... |
When you use RDLDocumenterDesigner, you are adding information to the
RDL using Custom Properties, a feature of the RDL/RDLC format that is
well supported in Report Designer. RDLDocumenter recognizes CustomProperties
that belong to its designer support tool and pulls them into the docRDL.xml
like other report metadata.
But RDLDocumenter supports much more extensive custom documentation embedded
in the XML, too. If 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, RDLDocumentation 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 RDLDocumenter 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 RDLDocumenter, 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 RDLDocumenter 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>
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.
You can easily change RDLDocumenter 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 RDLDocumenter'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, RDLDocumenter does not document Chart attributes that you
want to include in documentation, you can substitute an edited version
of the XSLT that includes them. |
| To: |
|
Do this: |
| Run the program |
 |
Run the TestHarness.exe executable file in the Deploy
directory to invoke its winform interface.
 |
| Document a single RDL/RDLC |
 |
- Click the top button in the TestHarness interface.
- Browse and select an RDL or RDLC file
- Documentation is extracted to a .docRDL.xml file in the same directory.
- After creating the .docRDL.xml file, TestHarness loads the file as
a dataset serving as the data source for a report, which appears in
the lower half of the TestHarness form.
- Resize the form and explore the default data that has been extracted
and is available to you.
If the TestHarness.exe.config file is set to auto-load to
a local SQL Server Compact Edition file (SDF), the data is also loaded
to the the SDF file by this process. If it attempts to do so and fails,
the third 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 SDF 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 Samples folder includes an empty copy of the SDF. You can copy this
over the one you've been filling any time you want to restore it to its
start-up state.
|
| Load a.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 second button in the form to load any existing .docRDL.xml as
a report. |
| Document many reports |
 |
When you have loaded .docRDL data to a database, you can prepare a
report on multiple RDL/RDLC report definitions. Click the third button
in the form to load multiple sets of .docRDL data that have been loaded
to a database.
The TestHarness.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.
- Click the fourth button to browse for a different XSLT transformation
to use.
- You can try out the sample you find in the EditableResources sub-folder.
This is a copy of the embedded XSLT resource that TestHarness uses.
You can examine and edit this file to change which RDL elements are
extracted, what level of detail is included, what documentation categories
are used for various types of elements, etc.
- 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.
TestHarness and its default-supplied documenting reports expect to
load data in a standard DataSet format, with specific fields available.
You can examine any docRDL.xml file to see what this format looks like.
You'll also find this structure documented in the CreateDocTable.sql
script you'll find in the Samples directory.
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.
- Click the fifth button to browse for different reports.
- 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 TestHarness 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.
- 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.
- 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 TestHarness.
You may need to toggle between Report1-ReportMany, or close the application
and re-open, to see any difference. TestHarness 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.
 |
| Customize TestHarness's data repositories |
 |
- Close the TestHarness form.
- Open the TestHarness.exe.config file in your favorite XML editor (or
Notepad!).
- There are four user-settable values:
| DatabaseIsCompact |
Determines whether TestHarness loads from a Compact
Edition SDF file or from an instance of SQL Server (in other editions)
available to you. |
| AutoLoadCompactDatabase |
Determines whether the top button in the TestHarness
form automatically attempts to load the extracted docRDL.xml data
into your SDF. Ignored when DatabaseIsCompact is
False. |
| RDLDocCompactDatabase |
The location of the SDF you wish to use. Ignored
when DatabaseIsCompact is False. |
| RDLDocPrimaryDatabase |
The connection string for an alternative SQL Server
repository. Ignored when DatabaseIsCompact is True. |
TestHarness does not supply a means of loading the docRDL.xml to alternative
SQL Server repositories, creating the database, etc. When DatabaseIsCompact
is False, the database is only accessed to read data for documenting
multiple reports. This capability exists because TestHarness 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 SQLServerCompactRuntimeInstallInfo
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 |
|
- The Samples folder contains a copy of the deployment
set's xmlRSdocs.SDF file. Copy this file to a different location, or
replace the deployment set's xmlRSdocs.SDF file if you do not need to
keep its contents.
- Edit the TestHarness.exe.config to match the SDF
file you want to use.
|
| To: |
|
Do this: |
| Deploy the custom control library for use at design-time |
 |
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.
- Locate your Visual Studio installation files (for example,
C:\Program Files\Microsoft Visual Studio 8).
- Copy the Spacefold.RDLDesigner.dll into the Common7/IDE/PrivateAssemblies
folder of your Visual Studio installation.
- 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):
- Edit the RSReportDesigner.config file to include
the following node as a child of the /Configuration/Extensions/ReportItemDesigner
element:
|
| Add the custom control for use during Report Design
sessions in Visual Studio |
 |
- Open an RDL or RDLC for edit in Visual Studio.
- Right-click on the ReportItems group in the Toolbox
-- or, if you prefer, create a new group and right-click on its header.
- Select the Choose Items... option in the context
menu.
- Browse to the PrivateAssemblies location in which
you copied Spacefold.RDLDesigner.dll and choose that
file in the nested dialog.
- 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.
- Press OK in the dialog to return to the report design layout.
- The RDLDocumenterDesigner control appears in the Toolbox. (RDLDocumenter
does not appear even if it was selected in the dialog.)

|
| Add RDLDocumenter to a report design layout |
 |
- 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.
- 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.)
- 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.
- 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.
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 RDLDocumenter's custom actions accessible |
 |
You can always return RDLDocumenter to its default attributes using
Reset Defaults from the right-click (context) menu, and
you can access its Document action, RDLDocumenter'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 RDLDocumenter-decorated report |
 |
- You can preview with the custom control in place at this point; it
should appear (or not, if ShowValue is False) as expected.
- 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.
 |
| Add custom documentation attributes to your report |
 |
- Choose the Document custom action from the context
menu or Properties Window entry for the custom control.
- 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.
- 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.
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.
|
| Edit your custom documentation directly in the RDL |
 |
- View Code for the RDL or RDLC file, in any XML editor.
- You find the documentation attributes you added included in the RDLDocumenter
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.
- 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.
It is also used 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 it.
You can use the CustomPropertyNamePrefix to change this value,
if necessary.The 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.
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.'"/>
 |
| Add specialized documentation, such as images |
 |
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.
Walkthrough
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 TestHarness.EXE respects this naming convention, and treats any such
data rows differently from all others.
- While designing a report layout, open he RDLDocumenterPropertiesEditor
dialog.
- 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.
- Save your report and re-run TestHarness.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.
- 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 TestHarness, with an
embedded image in its contents.
RDLDocumenter "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.
 |
| Share decorated report with another report developer |
|
Other report developers can open this RDL or RDLC without issues if
they have configured Visual Studio to use RDLDocumenter. If they have
not, 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:
- Save a copy of the original file, in case you want to revert later
in this process.
- View code (XML) for the RDLC or RDL, in any XML Editor.
- Look for a CustomProperties node for your Report's
root node. It probably doesn't have one.
- 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.
- 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.)
- 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 Samples directory. You can use it to perform the
steps above. You must still manually remove the RDLDocumenter instance,
or instances, in the Report Designer from the adjusted report.
- Select and remove the rdlDocumenter custom control from your layout,
and save the report.
- Re-extract documentation from this report in TestHarness. It will
behave the same way as before, and the two supplied reports will give
you the same results.
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.
|
| 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.
- 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.
- 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:
- 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:
|
| 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. |
| To: |
|
Do this: |
| Perform the process in a console (CMD) window |
 |
At a command window, navigate to the Samples 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 Deploy\EditableResources\xmlRSDocs.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 and, if it cannot process
properly, you will see a 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, please take a look at the
comments in this script for some recommendations. |
| To: |
|
Do this: |
| Create a Microsoft SQL Server table suitable for holding
the default docRDL-shaped rows |
 |
Your samples 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 TestHarness application does not load docRDL.xml directly to a
SQL Server table, as explained in an earlier section; it only auto-loads
if you have chosen its local Compact database for storage.
However, you can take the docRDL.xml files you created (whether using
the TestHarness.exe interface or the transformRDL.vbs
script) and load them to your table by running a SQL procedure.
You'll find the SampleRDLDocXMLShredderProcedure.sql
script file in your Samples directory, along with the
other script files. Edit the USE [..] statement at the top of the file
to point to the database in which you created your RDLDocPrimary table
in the last step. You can run the script to create a stored procedure
with the name dbo.ShredRDLDoc in the same database.
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 TestHarness application |
|
Once you have your docRDL data stored in a database, you can easily
point TestHarness at this data for reporting. Set its configuration options
(in the TestHarness.exe.config discussed earlier) as follows:
| DatabaseIsCompact |
False |
| AutoLoadCompactDatabase |
(ignored) |
| RDLDocCompactDatabase |
(ignored) |
| RDLDocPrimaryDatabase |
Use a connection string and authentication info appropriate to your
server and database. |
|
| To: |
|
Do this: |
| Set up the package for debug-style
use in Visual Studio |
|
Open the xmlRSDocsProcessing.dtsx in the xmlRSDocsProcessing
project, or add it to a SQL Server Integration Services project
of your own. 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.
- First, establish the correct values for two directories used in processing.
Each String value below should end in a backslash.
| ResourceDir |
Point to the directory holding the XSLT transform 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 |
Point to the directory holding the RDL and/or RDLC files to
be processed.
Example: C:\WORK\MyReports\ |
- 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 TestHarness.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. |
- 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.

- Finally, if you have set StoreDocToTable to True,
configure the 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 your database server.
|
| 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.
|
| 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.
- Used for all output types
| XsltValue |
The name of the XSLT file to be used to extract DataSet-shaped
XML from RDL/RDLC files. Must be placed
in the ResourceDir location. You
can change this file if you want to change the nature of the documentation
that is extracted and/or you wish to change the columns in the resulting
DataSet, to correspond to changes you make in your SQL table respository.
Default value: xmlRSdocs.xslt |
- Used when SaveDocFile is True
| OutputDocExt |
Determines the extension added to the name of each RDL/RDLC file
.
Default value: docRDL.xml |
| SQLCreateDocTable |
The name of the T-SQL script to run to create the documentation
table on-the-fly in your database if it does not exist. While this
is not often necessary, having the script documents the current
structure of your table, so it's nice to keep it up-to-date even
if you use other means to adjust the table structure. This file
must be placed in the ResourceDir
location to be used.
Default value: CreateDocTable.sql |
| SQLFileIDColumnName |
As the package consumes each RDL/RDLC set of rows, it adds an
identifying value, the fully-qualified name of each RDL/RDLC file,
to the set of rows. This activity occurs in the Add CodeModule
Info data flow step.
Default value: RDLFileName |
| SQLTableName |
While the Connection Manager associated with this package provides
the database context in which it operates, this variable provides
the name of the table to update within the database.
Default value: RDLDocPrimary |
| OutputValue |
This variable is used during processing to hold the extracted
XML documents, which are consumed during the XML Source
data flow step using the XML data
from variable data access method. While the value of this variable
is dynamically determined throughout processing, it's a good idea
to have its initial value representative of the actual DataSet structure
you plan to use. SSIS may choose to validate this value against
the schema you have provided to the data flow as it checks column
mappings, etc.
Default value: <sample XML>, matching the Resources\SampleData.xml
file contents |
- 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. Just think of the defaults as examples.
| ExportRSType |
The type of export file to be created and placed on disk.
Default value: PDF |
| ExportRSFilename |
The name of the file to be published on disk. You can include
a full path, or just a filename. In the latter case, your file is
published to your package's InputDir location.
Default value: RDLDocumenter.pdf |
| ExportRSURL |
The Reporting Services URL at which the script should access
your report, using URL Access.
Default value: http://localhost/reportserver?/xmlRSDocSampleReports/RSDocsSample |
| ExportRSParams |
Any parameter information you want appended to the URL along
with the standard rs:* arguments for export.
Because of the XML storage mechanism of various stages in the "life"
of a DTSX, you cannot include an ampersand (&)
character directly in this string to reference multiple parameters
for your querystring. The supplied script take the fairly simple-minded
approach of replacing any caret (^) characters
it finds in the string with ampersands at the appropriate moment.
You can easily alter the script to take a different approach.
Default value: RDLDocInfo=MyTestServer^test=something |
|
| To: |
|
Do this: |
| .. |
|
.. |
| create new dialogs and/or change XSLT to allow more
flexible categorization |
|
|
| normalize database |
|
|
| Create Sandcastle and other output formats using a second
XSLT in the pipeline |
|
|
| |
|
|
|