I mentioned that I’ve been working on a SQL Server Reporting Services utility… I’ve now posted the docs for this tool as a Spacefold article. They’re not done, but they’re copiously illustrated and give a good idea of what it is and does.

So what is it, anyway?

• XMLRSDocs is an idea: documentation for reports should be done the same way, as much as possible, and with the same facility, as developers have when creating documentation for class libraries and other application components.

I started with XML Comments as a model:

You ought to be able to extract some standard documentation into a usable XML schema, from any RDL or RDLC, and you ought to be able to use XML to decorate any RDL or RDLC with custom documentation elements, to be extracted at the same time if they are present.  It would be pretty easy to put the extraction process into a standard post-build step for reports, similar to how XML Comments are extracted when you build your class libraries.

Then I added to this idea, in a way that ought to be applicable to class libraries, so other people are probably doing it:

The extracted XML documentation should be easy to insert into a SQL database, so you could Do More Stuff to it.

Then I added a bit more, in a way particularly nice for reports:

Once you have your Reporting Services documentation data in database form… you should be able to get your documentation out as Reporting Services reports, as a base output format. (Duh, right?)

• RDLDocumenter is an implementation of the idea: it’s a lot of SQL Server and .NET technologies, used together, to make this possible.

You can use RDLDocumenterDesigner, the ReportDesigner add-on part of RDLDocumenter, to add notes to your report and its elements while you’re working on it.  That seemed to be the make-or-break requirement to allow folks to document reports with ease. It wouldn’t do to have them run the RDL or RDLC through a separate process, like a form or a wizard in which you could see the various elements of the RDL exposed and have a chance to add notes to them.  Such a form interface would allow a more elaborate UI, but it wasn’t a fluent way of working. Besides, discovering more about this process was a significant motivation for working on RDLDocumenter in the first place.  As explained in my earlier post, I was trying to show how certain tasks were pretty standard when writing the design-time and run-time components of a reporting tool, no matter what the toolset.

But it turns out that, at least in the current state of the art, there are also some critical limitations in creating a ReportDesigner add-on that are worth discussing, too (and I hope to do that soon).  Plus, a design-time tool for a single report just wasn’t clarifying the end-to-end documentation process that one would want.  Suppose you created some sort of processing hook that would run when the report was saved or closed in the Designer; how did this material get put together with documentation for other reports? And so on.

I ended up creating an external form as a prototype for and demonstration of the end-to-end process, and an SSIS package for a demonstration of using it in a production mode.  The various tasks in the process are also broken out as simple VBS scripts you could chain together or incorporate in some other form of processing, if you like.

While creating these external pieces, I faced a bunch of interesting challenges related to RS reporting in general. I’m hoping that the code in these pieces will serve as illustration of a whole bunch of FAQs one sees on RS forums: how do you switch between report definitions in a ReportViewer control? how do you bind datasources to a report dynamically for a ReportViewer.LocalReport? what kind of code is good for downloading a report  from a Reporting Services instance, without user interface? and so on.

We’ll see how it goes…