Fundamentals of Themelia - HTTP Route Debugging
Thursday, July 24, 2008
This documentation has been updated for Themelia Framework 2.0 Beta 4.
One of the most important aspects of development is unfortunately debugging. We shouldn't have to do it. Stuff should just work. However, as it stands, we all type stupid stuff. Computers are deterministic and if there's a problem somewhere in an application, you don't blame the computer, you blame the programmer, network administrator, or, preferably, the project manager. So, we need to be able to debug our work and Themelia HTTP routing is no exception.
When working with Themelia, we will register many processors and various handlers. However, what happens when we have a typo? As it stands, in Themelia, nothing happens. The last thing anyone needs is your web site to shutdown just because someone forgot that a particular HTTP handler was moved from the Commerce to the Commerce.Web assembly. Therefore, you never have to worry about your web site shutting down because of a faulty component. If Themelia did throw exceptions on faulty exceptions the situation would be analogous to a process leaking its fault resources (i.e. memory) into another process. No thanks.
Now, while it's great that your web site won't explode, without errors, there can be no true debugging. In other words, how in the world can we figure out what's wrong with our routing? To make matters worst, if you are building a complex Themelia web component, the error could be a single letter missing in any of a dozen of places. So goes all development.
Because of this, we may use Themelia's information reporting capabilities to aide in HTTP routing debugging. Now, while complete coverage of Themelia's reporting capabilities is far beyond the scope of this entry, we will make use of it for routing debugging. Thus, for now, we do need to have a very tiny introduction to what's entailed in Themelia reporting.
Themelia's reporting model is not in the Themelia.Web assembly, but rather in the Themelia assembly thus making it non-web specific and ready for use in WPF, WCF, console, and web applications alike. As such, there's also a different configuration section for it: themelia.system, which is registered in your app.config or web.config as such:
<configSections> <section name="themelia.system" type="Themelia.Configuration.SystemSection, Themelia" /> </configSections>
The actual configuration area looks like this:
<themelia.system> <appInfo name="My Web Site" /> <reporting> </reporting> </themelia.system>
Themelia reporting, though a large topic, can be boiled down the one simple concept: the reporter. A reporter is simply a combination of a report creator, a formatter, and a sender. Report creators create, formatters format, and senders send. Thus ends the mini-explanation of Themelia reporting!
To enable HTTP route debugging, you simply need to register a reporter with the name WebRouteDebug. For the time being, use the following settings:
<themelia.system> <appInfo name="My Web Site" /> <reporting> <reporters> <add name="WebRouteDebug" creator="Map" sender="EventLog" formatter="Wiki" /> </reporters> </reporting> </themelia.system>
These settings mean to use the map report creator and save the report in Wiki format in the Event Log. You could easily replace EventLog with a another sender and Wiki with another formatter, but the regardless of what you set as the report creator, Themelia web routing will force the map report creator. But, this isn't a lesson on reporting, so that's a discussion for a different time.
Once this is simple reporter is activated, Themelia's HTTP routing engine will automatically start logging all exceptions thrown within it's boundaries. The errors will be cataloged together, passed through the map report creator, formatted to the Wiki (yes, as in Wikipedia formatting; it's cooler than plain text) and saved to the Themelia event log. That's seriously all there is to it. To disable that particular report, just comment out the XML line or set enable to "false"; it's true by default.
One final thing one reporting that should be said is that reporting is not strictly a debugging mechanism. There is no excessive cost for running it (and you could use the individual parts of reporting as well; I use Themelia report creators and formatters all over the place outside of reporting). So, you could theoretically leave it on at all times, but since it deals mostly with setup, you really only need to have HTTP route debugging enabled while you are debugging the configuration. It kind of seems meaningless to leave it in this context.
