Brownfield Application Development in .NET

I was surprised to read that Brownfield has been out for a full year now, and figured it was high time to post my review of it. (I’d been meaning to post a review of the book for several months, but it’s been on loan to several different people. I didn’t get it back into my possession until a few weeks ago, which should tell you something about its quality right away.)

Brownfield is about the tools and techniques required to get an existing .NET application under control. Sadly, most of us developers have encountered development projects that were rushed, cobbled together, barely functional messes. This book is about reworking the application and its surrounding environment so that development work can continue on a sustainable footing.

The book is divided into two parts: the ecosystem and the code. The ecosystem describes all the necessary components to support modern software development:

• Source control
• Continuous integration
• Automated testing
• Code analysis and metrics
• Defect tracking

This was the most valuable part of the book. You’ll see these topics covered elsewhere, but they’re often scattered across vendor sites, developer forms, and programmer blogs. Having all these best practices gathered in one place is worth the price of the book alone. It makes a great checklist to use to evaluate the status of your current development projects as well as any future work you undertake.

I’ve also found it helpful to get Java developers or development teams up to speed on the .NET suite of tools and practices. It’s saved me a lot of time translating the “we used to do it like this in Java…” conversations into their .NET equivalents.

The second part of the book concerns coding practices that can help sort out a legacy codebase. I found this much less useful than the first section. While Brownfield provides a useful summary, much of this is material that is covered in depth elsewhere. The whirlwind tour of coding practices includes:

• OO principles
• Layers and tiers
• Taming dependencies
• User interface patterns
• Data access patterns
• Managing external dependencies
• Keeping up momentum

The final chapter in the list is the only one that touches on the project management aspects of getting an unruly development effort under control. Though it too is a topic that has been covered elsewhere, I was very glad to see that it was included in the book. I’ve found that a slapdash approach to application development reflects as much upon poor management practices as it does on a lack of programmer skills — if not more.

In conclusion

If you’re inheriting an old .NET application and don’t know quite where to begin, Brownfield Application Development in .NET is an excellent guide to tools and practices that can help get you started.

Related posts:

1. Review: Framework Design Guidelines
2. Review: Working Effectively with Legacy Code
3. Review: The Pragmatic Programmer

We’d been using modal dialogs in our startup routine for several purposes. We’d display an error message if certain application prerequisites hadn’t been met. We might inform the user that the system was performing an upgrade. Or, most important, we might show our trial/evaluation dialog. This last message tells the user how many days were remaining in the evaluation period, and provides a way for the user to visit our website and buy a copy. (Critical functionality for us!)

All of these messages had been working properly in our integration tests. And then one day they stopped working.

Splish splash

After looking through our check-in logs and hunting around online, we discovered that the problem had to do with the WPF Splash Screen mechanism. We’d followed the instructions in How To Add a Splash Screen to a WPF Application and added a static image to our project to display to the user while the application was loading.

But apparently, this has a nasty side effect of clobbering any modal dialogs that you show before your first non-modal window. A few other folks have noted the same problem. It’s been submitted twice on Microsoft Connect as a bug:

• WPF splash screen closes MessageBox
• WPF splash screen dismisses dialog box

But it’s not clear whether Microsoft’s going to address the issue. The cause of the problem is that a modal dialog without an explicit parent window set will automatically attach itself to an active non-modal window. It’s a nifty behavior in most cases, but if a modal dialog attaches itself to a splash screen, and the splash screen is dismissed — well, so is your dialog!

All washed up

So, what are our options? One is to avoid Visual Studio’s built-in splash screen feature entirely and create our own splash screen. This thread in the MSDN forums describes how that can be done.

That seemed like too much work for us, which left us with three possible workarounds:

1. Use a hidden window. Create a tiny, non-modal window to act as a parent for your MessageBox or modal dialog.
2. Create non-modal message windows. Change your startup mode to explicit shutdown and use a non-modal window to display your message.
3. Call MessageBox twice. Apparently, the problem only affects the first modal dialog shown. So you could simply call your modal dialog twice, if you didn’t mind the flash of the first one opening and closing.

I don’t recommend that last technique — though it does work — so I’m not going to provide a link to it.

Drying off

I found several custom implementations of splash screens on CodePlex, but at this stage, so close to our 2.0 release, I didn’t want to add any code to our project that I didn’t thoroughly understand.

Since our software licensing code come from a third party, we couldn’t easily modify all of the windows shown during start-up to be non-modal.

So ultimately we decided to use the hidden window workaround. It seemed the quickest way to get the behavior we wanted. It feels a bit dirty, but I can’t justify rolling my own splash screen implementation just to display a static “Loading…” image.

I’d really like to see Microsoft fix this one. If you think so too, vote for the issue here. Thanks!

No related posts.

Sadly, the Hyperlink element’s NavigateUri property makes this extremely difficult. Since the NavigateUri property’s target type is a Uri, not a string, you can’t use the convenient StringFormat syntax to create dynamic URLs. I started a StackOverflow question to discuss how to use StringFormat with the NavigateUri property. The best approach for now appears to be to write an IValueConverter that will create the Uri from a string.

This works if you only need to apply a single value. But what if you need to supply multiple values to generate a querystring with several parameters?

A post from Paul Stovell pointed me in the right direction: prior to the introduction of special StringFormat syntax in .NET 3.5 SP1, you needed to use multibinding to manipulate strings. We can use this older method to generate the Uri we need for the Hyperlink.

First, create a converter that implements IMultiValueConverter.

Remember to add the converter application resources in your App.xaml file, so you can reference it throughout your application.

Then you can use it wherever you need to dynamically create a URI within your WPF or Silverlight application.

Whew. That’s a lot of extra work just to generate a URL for a hyperlink!

Notice that I had to escape the ampersand in the format string supplied in the ConverterParameter. Since XAML is based on XML, not HTML, you must escape the ampersand within attribute values. This catches me every time.

Generating dynamic URLs is such a basic operation for building navigation-style WPF or Silverlight applications, I’m surprised the folks at Microsoft didn’t create a helper syntax to handle this cleanly.

Related posts:

1. Getting XAML Hyperlink text to wrap
2. Highlighting query terms in a WPF TextBlock
3. Using WCF to return HTML

In two previous posts, I talked about the misuse of dependency injection and the problems with the service locator pattern. I should include factories among the list of dangerous patterns too.

These patterns get overused in many .NET frameworks and toolkits. Some of that stems from a desire to avoid complex configuration. Some of it comes from the natural envy programmers in stuffy statically typed languages feel regarding their freewheeling counterparts using dynamically typed languages.

(Wikipedia has a good article exploring the differences in type checking in computer language type systems, if you’re curious about the different paradigms. But I digress.)

On reflection

System.Reflection two main uses, as Marc Gravell points out in his answer regarding what problems Reflection solves on StackOverflow:

1. Investigating type information
2. Metaprogramming

These two capabilities allow you to shoehorn dynamic or late-binding features into C# applications. In other words, it’s a clever hack.

Want to enable Ruby-style convention over configuration in your C# framework? Use reflection! Want to reach into private or internal methods for unit testing? Use reflection! Want to add some duck typing goodness to your statically typed language? Use reflection!

But on further reflection

The System.Reflection API has some big drawbacks. The performance penalty incurred by reflection is well known. Less well known is that the Reflection API is really difficult to use, especially when inspecting and creating constructor method parameters. So most framework developers skip the hard bits.

This means that most of these frameworks will insist on your using constructors without parameters in your classes. (Sometimes people call parameter-less constructors “default constructors” though it isn’t the same thing.)

But if you can’t use parameters in the constructors of your objects, you’re doing object-oriented programming with one hand tied behind your back.

For example, it’s difficult to achieve object immutability without using a constructor. You’ll also have a hard time enforcing business rules without constructors. And if you’re a fan of dependency injection, you’ll have to implement it via Init() methods or property setters, both of which can cause significant headaches.

So if you work with a framework or API that makes heavy use of reflection, and thus restricts the sort of constructors you use, prepare yourself for significant pain.

Related posts:

1. Avoiding the “new”
2. The Service Locator pattern is the new global variable
3. Creating Dummy Targets for Configuration Objects

As I was wrestling with yet another third-party software component that made heavy use of an inversion-of-control (IoC) container, I realized that service locators are the new global variable.

Global variables are a code smell and should be used sparingly.

This means that you should use a service locator only as a last resort, not as the default way of wiring bits of your application together.

And if you’re using an IoC container, make sure that you are using it to inject dependencies through your object constructors, rather than calling its static Resolve() methods from within your classes.

Related posts:

1. Reflecting on reflection in .NET
2. Avoiding the “new”
3. The Curse of the Singleton

But that was before I started taking a look at several open source frameworks for WPF. Now I’m feeling ranty too!

Dependency Injection is an important principle of software design, but it can be abused. My biggest concern with overusing inversion-of-control (IoC) containers is that it makes learning a framework ten times harder than it needs to be.

First, you can’t tell precisely when an object gets created. Sure, it’s nice that your framework provides control over the lifetime of objects, but this should be an optional feature for advanced scenarios. Not every solution requires lazy loading. Sometimes a simple “new” will do.

Second, by placing all the wiring and object discovery in the container or service locator, you hide important information about how the framework components fit together. Yes, the global object factory knows what classes go with what types, but you don’t. That information is hidden among all the framework plumbing.

For similar reasons, Microsoft cautions against using factory methods in place of constructors in its Framework Design Guidelines:

Prefer constructors to factories, because they are generally more usable, consistent, and convenient than specialized construction mechanisms.

I think that goes double for dependency injection and IoC containers. Eliminating constructors makes for less readable code. I can’t tell what classes other classes depend on to do their jobs.

My errors should get thrown from my code

Sure, IoC containers are great when everything gets wired together automagically. But when an error occurs, I want it to be thrown from my code, as close to the source of the error as possible. (Like Jeff Atwood, I assume it’s always my fault.)

Instead, frameworks that overuse dependency injection throw most of these setup, configuration, and instantiation from its internal IoC container, usually with some horribly generic error message.

Then it’s up to me to find which dependency failed to resolve, which constructor failed to bind, or which concrete implementation didn’t get registered. And in order to do that, I have to go spelunking in the framework code — which I don’t know well — rather than the code I was trying to write, which I know quite well.

Frameworks that rely on dependency injection and IoC containers practically require you to have the framework source available and for you to become an expert in its mysterious inner workings. If I need to step through the framework code or use reflector on it, the framework has failed me.

This is exactly what Uncle Bob was decrying in his article. I don’t want to become an expert in the XYZ framework for ABC. I just want to get my stuff done.

Related posts:

1. Reflecting on reflection in .NET
2. The Service Locator pattern is the new global variable
3. One-Way Serialization

One of the first four features on preview is a new Long Path wrapper class, which will hopefully make some of the awkward hacks we’ve used in the past obsolete. Hooray!

The code is available for download, and they have documentation and samples as well.

I plan on giving the new Long Path class a thorough test drive.

Related posts:

1. 256 Character Filenames Should be Enough for Anybody
2. Creating Dummy Targets for Configuration Objects

Spark template file icons

First, I made a couple registry files to give Spark templates a spiffy icon.

Visual Studio gets its icons from the same registry setting used in Windows Explorer. So all we need to do is register the file extension and associate it with a default icon.

I found a free-for-noncommercial-use “S”-shaped lightning bolt icon and used the instructions in this StackOverflow question to create the necessary registry entries.

Add an icon for Spark templates in Visual Studio 2008

You can download the SparkFile.zip package I created from Codeplex. Place the .ico file in C:\Program Files\Spark, and run the two .reg files, and you’ll have a nifty spark icon inside Visual Studio.

(All the usual caveats apply regarding modifying your registry.)

Visual Studio template

Next, I created an item template to use in the Visual Studio Add New Item menu, using this guide to creating item templates.

You can download my SparkVSTemplate.zip package from Codeplex as well. Place the SparkVSTemplate.zip file in My Documents\Visual Studio 2008\Templates\ItemTemplates\Visual C#\Web and you’ll be able to create a basic template from the VS menu. You don’t need to unzip it.

HTML syntax highlighting

Finally, I wanted to apply the standard syntax highlighting used for HTML pages.

In Visual Studio 2008, go to Tools | Options, then choose Text Editor, then associate files ending in .spark with the HTML editor.

Set up Spark View Engine templates to use the HTML Editor in Visual Studio 2008

This will set all the colors properly. Unfortunately, it will also flag any Spark-specific attributes or elements as HTML validation errors. I figure this is a small price to pay for proper syntax highlighting.

What’s missing?

I’d really like to get intellisense working for Spark. Though I tried the Visual Studio Integration Package, it won’t work right outside of VS Web projects. Syntax highlighting seems like the best I can do for the moment.

If you’ve got other tips and tricks for using Spark inside Visual Studio, I’d love to hear them.

Related posts:

1. Using Spark View Engine with C# WebServer
2. Visual Studio 2008 and the CopyLocal setting
3. Visual Studio 2008 and its CopyLocal setting

After posting messages to the Spark project and C# WebServer project forums, I decided there was enough interest to make sharing my integration code worthwhile.

You can find it at: http://code.google.com/p/sparkserver/

If you’d like to participate in the project, please let me know. Comments, suggestions, and especially fixes are always welcome!

Related posts:

1. Using Spark View Engine with C# WebServer
2. Support the JQuery Project
3. Looking for an IIS Alternative

Since we’re not using Microsoft IIS, we wanted to avoid a dependency on System.Web, which has the popular but flawed HttpUtility.HtmlEncode() method.

In my research, I discovered Rick Strahl’s post about Html and Uri String Encoding without System.Web. He points out the problems and inconsistencies in the mainstream encoding methods available in the .NET framework, and ultimately decided to roll his own encoding method.

But in this StackOverflow question on HTML Encoding in C#, several folks suggested using Microsoft’s anti-cross-site scripting library, AntiXSS.

After spending some time working with the library, it seems like just the thing to solve the problem of web encoding.

The AntiXSS Library includes helpful methods for encoding HTML, URLs, JavaScript, and XML. It’s based on a secure whitelist model, so anything not allowed in the specifications is prohibited.

Microsoft has made the source of AntiXSS 3.1 available on Codeplex (http://antixss.codeplex.com/), but you can also get the official release of AntiXSS direct from Microsoft. It includes a sample application and thorough documentation.

It’s exactly the solution I was looking for.

Related posts:

1. Using WCF to return HTML
2. JQuery Turns 3
3. How to format the XAML Hyperlink NavigateUri