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.

The effect you want to achieve is simple. Given that a user searched for the words highlighting and terms the following snippet of text:

…we found that highlighting query terms made it much easier for users…

Should be displayed like this:

…we found that highlighting query terms made it much easier for users…

A light touch for repeated use

Your first instinct might be to use a FlowDocument displayed within a RichTextBox or FlowDocumentViewer. FlowDocuments have a convenient API for applying formatting to words or phrases, but they are heavyweight objects. Since we’ll display many search results on the same screen, the repeated use of FlowDocuments and viewer/editor controls will increase memory use and be a drag on performance. It’s not a good idea to use them within the ItemsControl or ListBox item templates that present search results.

Fortunately, we can get term highlighting to work within a lightweight TextBlock control, if we use a few tricks. Our approach binds the text snippet to ContentControl using a converter that generates XAML objects.

The overview

First, let’s assume that your full-text search engine produces a string that contains delimiters to indicate where the highlights should begin and end. Lucene.Net, the content indexing engine we use for Infovark, has a Highlighter plugin that works this way.

In Lucene.Net, the default delimiters used are opening and closing <B></B> tags. We’ll need to change these default settings to use delimiters that won’t cause trouble for XML parsing. (Remember, your text snippet could contain HTML or characters invalid in an XML document, so you’ll need to escape its output. We don’t want our delimiters to get wiped away during the escape process!)

We decided to use the sequences |~S~| and |~E~| as these were highly unlikely to show up naturally in our snippets. Using our example from above, the highlighted snippet from Lucene.Net would look like this:

…we found that |~S~|highlighting|~E~| query |~S~|terms|~E~| made it much easier for users…

Now that we have our search result snippet formatted the way we want, we can build an IValueConverter that generates a TextBlock with internal Run elements. Here’s the full class.

Now I’ll explain what we’re doing in the Convert() method in detail.

Step by step

First, we check to make sure that we actually have a string object with some text. Then we take that string and run it through the System.Security.SecurityElement.Escape() routine, a handy method in the .NET Framework for replacing invalid XML characters with properly escaped ones.

Next, we replace the start delimiters with opening Run tags. Note that we set a style on this tag using a dynamic resource. This lets to apply whatever style we like to the highlighted words without having to mess with our converter logic. We also replace the end delimiters with a closing Run tag.

Then we wrap the snippet inside a TextBlock. I’ve set the TextWrapping property to Wrap so that our line of text doesn’t run off the edge of the screen in our UI. Note that I’ve also included the XAML namespace; this will become important later when we use the XamlReader.

Now we should have a well-formed XAML string. We feed this string into a StringReader, then an XmlReader, and finally a XamlReader. The XamlReader.Create() method instantiates the framework objects returned by our converter.

With our converter working properly, we can use it in the DataTemplates for our search results like this:

It’s quite a bit of work, but the end result is exactly what we want: a lightweight way of highlighting query terms in search results.

If you’ve got comments or suggestions about this approach, we’d love to hear them.

Related posts:

1. How to format the XAML Hyperlink NavigateUri
2. Getting XAML Hyperlink text to wrap

Well, in an effort to get the answer to stick inside my very tiny brain, I’m writing it up here on the Infovark Underground as well.

The problem in question had to do with text wrapping in XAML Hyperlinks. And here’s the answer I posted at the time.

And now here’s my more complete recap so that I hopefully never, ever forget it again.

Hyperlinks don’t work the way you expect

Getting Hyperlink text to wrap properly in WPF or Silverlight can be tricky. Depending on how you’ve structured your XAML, the technique you use for wrapping a Hyperlink can change a lot.

First, recall that you can’t use a Hyperlink element in a XAML file like an ordinary user control. It has to be embedded within a FlowDocument or a TextBlock. It typically looks something like this:

By default, the text of the hyperlink will appear on a single line.

A plain vanilla XAML Hyperlink

If the code above matches your situation, simply adding TextWrapping=”Wrap” to the TextBlock gives you the desired result.

This simple scenario wraps properly

But suppose you had this scenario:

You might be surprised to find that the the TextWrapping=”Wrap” attribute has no effect at all on the inner TextBlock. The text stretches out in a single line.

Adding an inner TextBlock prevents the text from wrapping

No worries, you think, I’ll just move the TextWrapping=”Wrap” bit to the inner TextBlock, like so.

This will wrap your text, all right. But it won’t wrap the underline for the hyperlink. Check it out:

The text of the XAML hyperlink wraps, but the underline does not

What’s going on here? Why does the first, simple scenario work, and everything else fail in odd ways?

The answer is that the text contents of the Hyperlink element get placed within a hidden Run element in the first case. This creation of an implied Run element happens frequently in the framework. It happens so often that most of the time you forget it’s doing it.

Sure enough, if you replace the inner TextBlock with a Run in our second scenario, you get a lovely text-wrapped link.

Here’s the markup:

And here’s our desired result:

Now everything works as expected

But it’s not so simple

Now I know what you’re thinking. You’re wondering what to do if you actually need that inner element to be TextBlock. What if you’re working with an older version of WPF or Silverlight, where the Run.Text property couldn’t be data-bound? Or what if you wanted to apply formatting to the text of the link, like bold or italics, neither of which are supported by Run?

Then it gets ugly. You’ll need something like the following code, which removes the underline from the Hyperlink element and reapplies it at the inner TextBlock.

This solution isn’t perfect; sometimes you’ll see the underline jiggle a bit as you resize your window. But it’s as close as we can get it for now.

A XAML Hyperlink with wrapped and formatted text

Who would have thought something as simple as a hyperlink with wrapped text could be so difficult?

Related posts:

1. How to format the XAML Hyperlink NavigateUri
2. Highlighting query terms in a WPF TextBlock

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

I jumped at the chance to have him look over our database design choices. You can find his analysis of our Contact email address tables. I’ll respond to his questions, and any questions raised by the community, in the comments to his posts.

Have a look, and join in the discussion!

Related posts:

1. Microformats Introduction

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

Domain-Driven Design by Eric Evans

I read Eric Evans’ Domain-Driven Design: Tackling Complexity in the Heart of Software nearly six months ago, but I wanted to take some time to mull over my response to it before posting a review.

Reading Domain-Driven Design can be a challenge. It’s taken me a while to sort through all the concepts in my head. It’s also taken me some time to chase down the references and articles related to the book. Eric Evans makes frequent references to design patterns and often cites other books in the software design canon. If you’re not familiar with these, you’ll find the book slow going. It’s definitely worth the effort, however, especially if you work with large codebases.

The key is large codebases. For simple software applications, a straightforward procedural approach to code works just fine. At larger scales, Object Oriented approaches to code work quite well. But neither procedural code nor OO principles give much guidance about large-scale software structures.

After your application grows beyond a dozen classes or so, you need to start thinking about the overall organization of your code. And once you start work on an application with different logical layers or physical tiers, or one that integrates with other software applications, you ought to give Domain-Driven Design a thorough read.

DDD defined

Software applications are tools that help people solve problems. The scope of the problem is called the problem domain, or simply the domain. The process of setting up your software to tackle the problem is called domain modeling. The domain model consists of the core concepts that help users of the software get the job done or the problem solved.

Domain-Driven Design recognizes that software applications have essential features needed to solve problems in the domain as well as supporting infrastructure. It places the core domain at the center of the design process and lets everything flow outward from that. It’s an approach sometimes called onion architecture, in contrast to the traditional “layer-cake” architecture diagrams you often see.

We write software to solve problems, so it makes sense that our software should model those problems as accurately as possible. It sounds so simple!

Sadly, in practice, it’s really hard to get right. Computers force us programmers to think about all sorts of things that have nothing at all to do with the problem we’re trying to solve:

• Resource management
• Data access and persistence
• Responding to user input
• Maintaining state
• Etc. etc. etc.

These things can easily overshadow the problem we’re trying to solve. For many applications, the amount of infrastructure code you’ll write will far exceed the amount of domain logic required to solve the problem. And if you’re not careful, this infrastructure code can spread throughout your application, making it very hard to identify the core concerns of your system.

Eric Evans’ book describes how to see the forest for the trees in large-scale applications.

Three key DDD concepts

One of the things Eric Evans said after he wrote the book was that he wished he’d put it in a different order. I agree! Here are the three most important concepts discussed in the book, from back to front.

Bounded Contexts are a way to separate concerns within a software application. While the core of your application might deal with video editing or insurance claims processing, you will have other parts of your application that deal with corollary concerns.

If your system interacts with another software application or uses a web service, you obviously have a different context. These third-party components likely have different ways to model the domain, and you’ll need to translate these to your model.

But sometimes it’s not clear when you’ve moved from one problem domain to another. For example, within an employee timekeeping application you might have two subsystems that consider timesheets from a cost accounting perspective and a billing perspective. Though they might look at the same underlying data, the logic of how they work is different.

It’s important to explicitly recognize these boundaries. These edges will help determine the structure of your application.

Domain Modeling helps you determine the essential features of your system. Your code should be the literal embodiment of these features. If it’s a paint application, we’d expect to see concepts like Canvas and Brush and Color. If it’s a airline scheduling application, we’d expect concepts like Seat and Booking and Destination.

Software is an abstract thing. We humans have a difficult time thinking about abstract concepts. The more concrete you can make your core domain concerns, the easier it is for you to reason about.

Ubiquitous Language is the idea that your software development team should be using, as much as possible, the language of your customer. They need to understand the domain as completely as the client does — otherwise they’ll have a hard time designing software to solve the problem!

This is essentially another argument in favor of using real, concrete concepts from the problem domain in your application model. When the junior developer says, “I get exceptions when I assign this SpecialNeedsPassenger to an ExitRowSeat”, the airline executive will have some inkling what is going on. And when the customer says to the lead developer, “Oh no, we always show accumulated vacation within the current pay period” the developer will have some idea of what needs to change in the code.

Specific techniques

Much of the book is an exploration of how these three principles can be used to design (or refactor) a software application so that it makes more sense. Eric Evans discusses several diagramming techniques that can be used to illustrate relationships and boundaries in the domain model. He also highlights several design patterns that are helpful as well.

You can get good advice on applying specific techniques from reading blogs and looking at programming Q&A sites like StackOverflow. But it’s worthwhile to explore Eric Evans’ take on these and to get a solid grip on the terminology used by the DDD community.

If you’re a C# developer in particular, it’s easy to get confused by DDD terms like “Value Object” and “Entity” which are also used within the Microsoft .NET Framework. They have special meaning to folks in the DDD crowd.

Conclusion

This is the single most important book I’ve read on large-scale software construction. But it’s a challenging read because you need to know quite a bit about design patterns and have had some experience working on large scale projects.

The book also suffers a bit from the way it’s organized. As Eric Evans mentions in the introduction, the most important parts of the book are Parts I and IV. It’s easy to get bogged down in all the detail in the middle.

But those issues shouldn’t stop you from reading the book or becoming familiar with the concepts of Domain-Driven Design. It’s quickly become an essential part of the software design canon. We keep it on our Infovark bookshelf among the other key technical books..

Software architects and software team leads will get the most benefit from the book, but if you’re a developer on a large enterprise software project or commercial product, you’ll find the Domain-Driven approach to software construction very useful in your work.

If you want to learn more, check out the Domain-Driven Design article on Wikipedia and the Domain-Driven Design Community. You can also listen to this short interview about Domain-Driven Design with Eric Evans on InfoQ.

But the best way to get started is to read the book itself.

Related posts:

1. Validation in Domain Driven Design
2. Domain Models in High Performance Systems
3. Review: Framework Design Guidelines

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