Chris Falter

How to Reuse Code Without Creating an Implicit API

Chris Falter — Sun, 29 Mar 2009 19:44:23 GMT

I work for an ISV, and we have to be very cautious about the code that we declare with public scope. If it's public, a customer can treat it as an API, which might not always be a good idea if the code is really just doing some internal task in a way that could easily change as we improve our software. In other words, not all that is public should be an API.

So what do you do if you need to share code across assembly boundaries? Recently I was writing some unit tests for a class, and the tests needed access to a class method in order to imitate (and test) its behavior. Of course this method was private--of course!--so it appeared that I had to choose between 2 very unpalatable options:

Give the method public scope, which would make it visible to all our customers' implementations. Essentially, this option would make the method part of our API. Not happening.
Copy the 20 lines of code from the method, paste it into my new class, and supplicate the dark spirits of bad software design to supernaturally prevent the method from ever being modified. But how could I perform the ritual without an eye of newt and toe of frog?*

But appearances can be deceiving. It turns out that the InternalsVisibleToAttribute, introduced by Microsoft in .NET 2.0, solves the problem quite neatly. Using this attribute, you can designate one or more friend assemblies that will be allowed access to classes, methods and properties in the target assembly that have friend scope, while all other code--including customer code--is denied access.

Using the attribute is a piece of cake:

Mark any classes/methods/properties that need to be visible to other assemblies with "Friend" scope.
Import the System.Runtime.CompilerServices namespace into your assembly's AssemblyInfo.vb file.

Imports System.Runtime.InteropServices
In AssemblyInfo.vb, mark the assembly with the InternalsVisibleToAttribute for each friend assembly that should have access to the friend scope.

<Assembly: InternalsVisibleTo("MySystem.Assembly1")>
<Assembly: InternalsVisibleTo("MySystem.Assembly2")>

If you are working in C#, you will make your changes in the AssemblyInfo.cs file for the assembly that contains the code to be re-used, and you will use "using" instead of "Imports."

So I could have my cake (re-use of existing code) and shield it from inappropriate eyes at the same time. While this technique is obviously useful for writing tests, it can be applied anywhere that code needs to be shared between your system's assemblies without exposing it customers as part of an API.

* Not to mention the wool of bat and tongue of dog.

Turbotax Customer Service to the Rescue

Chris Falter — Sun, 29 Mar 2009 19:21:10 GMT

I've got to give the Turbotax customer service organization credit: they responded quickly to my inquiry, and figured out a way to solve the problem. Yeah, the user interface design was stinky, but plan B worked out, so my faith in Turbotax is restored.

Lesson: a good customer service organization is essential if you want to keep your customers in spite of the occasional and inevitable screw-up.

Bad Software Design: Turbotax Web Edition

Chris Falter — Sun, 22 Mar 2009 20:44:12 GMT

After I completed my federal taxes, Turbotax insisted on checking for errors before allowing me to file for the refund Uncle Sam owes me. No problem there, I want my software to catch any possible errors. The supposed errors that Turbotax wanted me to correct, however, were so completely misguided that I have to nominate the 2009 Turbotax Web Edition for the Software Hall of Shame.

First, Turbotax insisted that I had to file a 1099-INT for my bank savings account because I had filed one last year. And it would not allow me to state that I did not receive a form; I had to provide some dollars and cents before Turbotax would let me file my 1040. Wait a second, though; my bank didn't send me a 1099-INT this year because my account earned so little interest! (It's a pathetic little savings account, really.) So Turbotax was refusing to let me file until I provided data that do not even exist.

Let's talk about software design for a minute. How on God's green earth does Turbotax know that I must have overlooked a form, just because I filed it in a previous year? Is it not possible that I might have even closed the pathetic little savings account before 2008 even began? It just so happened that I could visit my bank's web site and sum up the few pennies in interest paid on the account in 2008, so I was able to feed Turbotax's demand for data and pass on to the next hurdle. Not that I was happy about what had happened.

The second design flaw was so bad that I may not even be able to file my taxes (with Turbotax, anyway). Several years ago I worked briefly as a consultant, so I filed a Schedule C that included the analysis of vehicle mileage and expenses for business vs. personal use. In the subsequent years, I have not worked as a consultant, and I have never again filed a Schedule C. So guess what supposed error Turbotax insisted that I had to correct? That's right, Turbotax is refusing to allow me to file my taxes until I file a Schedule C that includes business and personal use of my vehicle.

I had not claimed any income from consulting for 2008.

I no longer own the vehicle that I supposedly have to file the mileage reports for.

But Turbotax will not allow me to indicate that I do not need to file the form. It's their way on Schedule C, or the highway.

So I'm about to contact Turbotax support. If it's anywhere close to the quality of the actual software design, I will no doubt have to write off the hours I spent working with their web software, hit the highway, and find a better tax software provider. But maybe not; maybe their support is world-class and will save the day. I'll report on the results as they become available.

Simplicity vs. Performance

Chris Falter — Thu, 05 Feb 2009 11:33:03 GMT

A colleague and I had a recent discussion about two versions of a trigger. One was simple, containing a single query. The other performed 14% better, but was a lot more complex--double the lines of code, and a branch that had to be evaluated. My colleague advocated for checking in the more complex version right from the start, while I advocated for starting with simplicity. What do you think? Post a comment!

Here's how our discussion went:

COLLEAGUE:

Is your first example more than 14% more maintainable than the second example? If not (which is my opinion, since there's really only one line, the "select inserted.NAME +..." line, that would change over time; the rest is boilerplate code), I think I'd go with the second for the performance increase.

ME:

My experience has been that it's a lot more expensive for an organization to maintain complex code than it is to tweak performance. Additional complexity tends to work like Adam Smith's invisible hand--except that this invisible hand works for evil, rather than for good. It makes staff spend more time trying to figure out how to fix bugs and add new functionality than they would with simpler code. It makes the software organization slower to respond to customer requests and changing market conditions.

The problem is that this complexity tax that the organization has to keep paying cycle after cycle is truly invisible because it is hard to quantify (unlike a small bump in performance). But ask any developer whether s/he has had to spend significant extra time in development or troubleshooting because the code base was complex (i.e., whether s/he has had to pay the code complexity tax), and invariably the answer is yes, a thousand times yes.

Granted, a single trigger that improves performance by 14% itself will not cause all that hardship. It's the cumulative effect of millions of lines of code that are a little too complex that make the development process harder and more expensive than it has to be/should be.

I guess the other way of pitching this philosophy is that if you tend to choose slightly better performance over simpler code, when it comes time to optimize the system you're asking the question: which of these millions of lines of code could be simplified at only a small performance cost? And we don't have the tools to answer that question very well. OTOH, if we tend to choose simpler code over slightly better performance, then optimization means we're asking: where are the bottlenecks where we can get a big performance boost at a small cost in code complexity? And we have a variety of profiling tools that help us answer that question very well.

COLLEAGUE:

I think you're letting a general philosophy get in the way of optimizing the one example you've shown. A 14% improvement in performance is more than enough reason to have branching code that's only slightly less maintainable than the non-branching code. I just can't imagine a scenario where a maintenance programmer sits down to fix a bug in this trigger and is so completely confounded by its complexity that fixing it would bring down the entire organization as you have suggested.

ME:

Actually, the maintainability difference is quite dramatic. You're buying the slightly better performance at a cost of doubling the lines of code and doubling the cyclomatic complexity.

Granted, this loss of maintainability occurs over a tiny portion of the code base. On the other hand, the performance gain, measured as a percentage of total transactions against the database, is essentially imperceptible as well. I.e., it's not as if a 14% perf gain in one of the most lightly used triggers among tens of thousands will amount to more than a sneeze.

What I'm saying is that the best strategy to optimize performance is to start with a good, simple code base, find the biggest bottlenecks in a realistic load test, and optimize just those code sections. Usually, the vast majority of perf gains emerge from a small number of trade-offs against simplicity.

The opposite approach (always choosing performance over simplicity during initial development) results in getting to market more slowly (which has a cost), and--through the accretion of thousands of small complexities--a gnarly code base that is expensive and time-consuming to maintain. The cumulative effect of small decisions makes a big difference.

If you look at this scenario in the small--one decision about one trigger--I can understand why you might choose performance over simplicity. Now multiply that bias for perf over simplicity across dozens of developers writing code every day, and you end up with an entire system that is twice as expensive and time-consuming to maintain. And the system would have lower quality to boot, since when you multiply lines of code and cyclomatic complexity, quality is pretty much lost at an exponential rate. Such a loss of quality is surely expensive to an organization over the long-term.

That's why I advocate choosing simplicity as a matter of initial development. Then as a QA process, look for the performance optimizations that will yield the biggest gains, and implement just those. The 80/20 rule will apply: you'll get 80% of the performance gains, while giving up only 20% of the simplicity.

The problem of trying to go in the reverse direction is that we don't have very good tools for identifying which code simplifications can be purchased at the lowest performance expense. So you just give up, and end up bearing all the expenses of a code base which is twice as big and twice as complex. And those expenses are far, far greater than the expense of system performance that is a few percent slower.

How To Search Encrypted Text in SQL Server 2005/2008

Chris Falter — Mon, 06 Oct 2008 05:14:56 GMT

Recently I was discussing SQL Server encryption with some friends who have been using it to encrypt short strings such as Social Security numbers at their shop. I commented, "Just try searching those Social Security Numbers," they shared my lamentation, and we moved on to other subjects. Later that evening, though, I thought there must be a way to search those wretched encrypted blocks--somehow--and worked out the solution you are about to read.

The Problem

The difficulty lies in the fact that you cannot compare varbinaries in a predicate. Combine this with the fact that encrypted text is stored as a varbinary, and the result is that you cannot search the varbinary encrypted text, even if you run the search term through the encryption algorithm before performing the comparison.

To illustrate, suppose you have a Person table that stores a name and a Social Security Number (SSN) encrypted with a certificate, defined like this:

CREATE TABLE [dbo].[Person](
[Id] [int] IDENTITY(1,1) NOT NULL,
[SSN] [varbinary](128) NULL,
[Name] [varchar](50) NULL,
CONSTRAINT [PK_Person] PRIMARY KEY CLUSTERED
(
[Id] ASC
)ON [PRIMARY]
)ON [PRIMARY]

It would be nice if you could just encrypt the search text and build a predicate that compares the term and the encrypted column, like this:

declare @encryptedSSN varbinary(128);
set @encryptedSSN = ENCRYPTBYCERT(CERT_ID('certKey'), @ssn);
select name, CONVERT(char(9),DECRYPTBYCERT(CERT_ID('certKey'), SSN) as SSN
from dbo.Person
where ssn = @encryptedSSN;

As I mentioned previously, though, this approach simply does not work.

Of course, you could make the predicate succeed by setting the datatype of the encrypted text column to char(128), and then converting the encryption products (stored SSNs plus the search term) from varbinary to char(128) before using them. However, indexing a column that large, and performing comparisons with it, would consume a lot of disk and processing resources.

The Solution

Instead of converting the large encrypted block into char(128) data, you can work with the hash of the SSN instead. If you calculate the hash using the SHA1 algorithm, the hash will require only 20 bytes of storage, so the burden on disk and processing resources will drop significantly. And since the SHA1 algorithm is considered to be very secure, you will not add any significant security risk to your solution. From start to finish, here's how the approach will work:

1. Include a char(20) column in your table to hold the hash of the SSN. The new table definition will look like this:

CREATE TABLE [dbo].[Person](
[Id] [int] IDENTITY(1,1) NOT NULL,
[SSN] [varbinary](128) NULL,
[Name] [varchar](50) NULL,
[Hash] [char](20) NULL,
CONSTRAINT [PK_Person] PRIMARY KEY CLUSTERED
(
[Id] ASC
)ON [PRIMARY]
)ON [PRIMARY]

You should also index the Hash column to improve the performance of searches by SSN, of course.

2. Whenever you insert a record, store the hash of the SSN along with the encrypted bytes. Your insert stored procedure should use the built-in HASHBYTES function, like this:

CREATE PROCEDURE [dbo].[usp_Insert_Person]
@ssn char(9),
@name varchar(50)
AS
BEGIN
insert into dbo.Person(SSN, Name,Hash)
values(ENCRYPTBYCERT(CERT_ID('certKey'), @ssn), @name, convert(char(20), HASHBYTES('SHA1', @ssn)))
END

3. When you search by SSN, compare the search term hash to the stored hash in your predicate:

CREATE PROCEDURE usp_Search_Person_BySsn
@ssn char(9)
AS
BEGIN
--SET NOCOUNT ON added to prevent extra result sets from
--interfering with SELECT statements.
SET NOCOUNT ON;

declare @hash char(20);
set @hash = convert(char(20), HASHBYTES('SHA1', @ssn));
select convert(char(9), DECRYPTBYCERT(cert_id('certkey'), ssn)) as SSN, name
from dbo.Person
where Hash= @hash;
END

Conclusion

This approach has worked well for me in my experimentation, and I recommend it to you if you need to search on an encrypted field. You should note, however, that the approach does have a limitation: you cannot search on an arbitrary substring of the encrypted text. In other words, a "begins with" or "contains" search is not possible. As long as you can live with this limitation, you should be able to employ this approach for your own encrypted data.

As always, I invite you, my reader, to leave a comment if you have found this useful or if you can think of an improvement.

Five Steps to Evaluate Technology Options

Chris Falter — Tue, 05 Aug 2008 17:33:13 GMT

Recently a project leadership team I was assisting had the difficult task of selecting between implementation technologies for a distributed architecture. We had brainstormed a list of candidates, and after some investigation were able to enumerate their strengths and weaknesses well enough. But then the decision-making process started to come unhinged as we thrashed about, weighing the various options. How do you narrow the field to a winner, anyway?

When I was able to frame the process in terms of the five steps you are about to read, though, the path to a confident decision became clear. While I am not suggesting that this is the evaluation methodology to end all evaluation methodologies, it certainly helped us.

Step 1: Reduce the Candidate List via Head-to-Head Comparisons. You will make your job easier if you can quickly knock out some of the contenders. Among the options we were considering for synchronizing data were

using SQL Server replication, and
writing our own application to read database records marked with an update flag, update records in a partner node with the data, and then remove the flags.

Ultimately, we realized that the application we were thinking of writing would be remarkably similar in structure and purpose to SQL Server's merge replication. Since we had no intention of re-inventing the wheel, we removed the idea of writing such an application from our candidate list.

Step 2: Build an Analysis Table. Since the goal is to learn how the technology options will influence the development of your system, the next step is to build a table that will compare the options according to how well they implement potential system features. Start by lining up the remaining technology options on the x-axis, and system features on the y-axis. The level of difficulty in implementing a feature, using a technology option, will be the data at the intersection of an option and a feature. Here is a sample of how an analysis grid might look for a distributed architecture:

Feature	Option 1	Option 2	Option 3
Workflow: Overnight Batch	Simple	Simple	Relatively Easy
Workflow: Straight-Through (Central Only)	Difficult	Very Difficult	Moderately Difficult
Workflow: Straight-Through (All Nodes)	Very Difficult	Impossible	Difficult
Data Replication: Near Real-time	Very Difficult	Moderately Difficult	Moderately Difficult
Data Replication: Every Hour	Moderately Difficult	Impossible	Relatively Easy
Post-failure Data Re-sync: overnight	Simple	Relatively Easy	Relatively Easy
Post-failure Data Re-sync: immediate	Moderately Difficult	Relatively Easy	Impossible

In this example we see that straight-through workflow processing at the central node will be difficult using option 1, very difficult using option 2, and moderately difficult using option 3. The ease of implementation (for all the feature/option pairs) ranges from simple to impossible, with four intermediate values (relatively easy, moderately difficult, difficult, and very difficult). Given the murkiness of IT crystal balls, there is probably no point in attempting a finer-grained analysis of the difficulty level.

Step 3. Assign Scores. In order to compare the various combinations of features and options, you need to assign a score to every combination. If you assign a score for a level of difficulty, you can quantify the comparison. The Cohn scale, a pseudo-Fibonacci series in which each score is about 50% greater than its predecessor, is a good choice. Many shops are already using the Cohn scale to estimate user stories in agile methodologies, so the familiarity can help. If you convert a level of difficulty into a score on the Cohn scale, you are assuming that it is about 50% more difficult than the next lower level, as you can see below:

Description	Points
Simple	1
Relatively Easy	2
Moderately Difficult	3
Difficult	5
Very Difficult	8
Impossible	10,000
Converting Descriptions Into Points (Cohn Scale)

"Impossible" is converted to an extremely high number in order to allow a numeric comparison.

After assigning the scores, the example table looks like this:

Feature	Option 1	Option 2	Option 3
Workflow: Overnight Batch	1	1	2
Workflow: Straight-Through (Central Only)	5	8	3
Workflow: Straight-Through (All Nodes)	8	10000	5
Data Replication: Near Real-time	8	3	3
Data Replication: Every Hour	3	10000	2
Post-failure Data Re-sync: overnight	1	2	2
Post-failure Data Re-sync: immediate	3	2	10000

Step 4. Discuss Features and Effort with Your Customer. Of course your customer will want to understand the choices they have. Using the analysis table from step 3, you could tell your customer that if they desperately desire straight-through workflow processing on all nodes in the distributed system, near real-time data replication, and immediate re-synchronization of data after a failure in the link between distributed nodes, the only technology available is option 1, which will "cost" 19 points. You could then point out that if it is acceptable to wait until overnight to re-synchronize data after a communications link failure, you could implement option 3 at a cost of 10 points--about half the effort.

What if my customer wants an estimate in terms of actual resources (person-days)? Your customer certainly has the right to get a ball-park estimate of the costs, of course. Since it is impractical to work up an estimate for each combination of features and options, you could perform an estimate for the lowest scoring combination instead, which will then become the basis for a conversion factor between points and effort. In the example, the lowest scoring combination is overnight batch workflow, hourly data replication, and overnight re-synchronization of nodes after a communication failure, using option 1 (5 points). If you estimate this combination as requiring 10 person-weeks of effort, then the conversion factor is 2 person-weeks per point. As a result, you can estimate that the desperately desired combination (costing 19 points) will require 38 person-weeks. Obviously, your project plan should not rely on this ball-park estimate; it is only precise enough to help the project team make an informed technology choice.

Step 5. Choose the Lowest Scoring Option for the Desired Feature Set. In most projects, the biggest cost factor (and biggest risk) is the use of human resources, so the option which requires the least effort should usually win. However, if there is a near tie between first and second place, you might want to weigh other factors such as licensing costs and vendor support in order to make your choice.

What methodology have you used for choosing between technology options? Have you used an analysis table like this? Leave a comment!

Health Monitoring in ASP.NET

Chris Falter — Fri, 06 Jun 2008 18:03:56 GMT

While I was busy customizing Microsoft's Exception Management Application Block to classify and log all exceptions thrown in our web and Windows apps, and writing instrumentation code that published timing events via System.Diagnostics.Trace, Microsoft was busy writing ASP.NET Health Monitoring. Microsoft has more resources, so their product is a little more advanced and customizable. Here's what it provides:

An event model: There are event classes for web request failures, for authentication failures, for errors, for SQL errors, for heartbeats, and so forth. You can subclass the WebBaseEvent in order to define your own custom events, as well.
A provider model: Health monitoring can publish events with 4 built-in providers (email notification, SQL Server, WMI, and event log). The WMI provider is especially interesting, but you will have to write your own application to manage and report WMI events, according to Microsoft.
A customization model: You can edit web.config in order to map events to providers and to configure providers (for example, to specify a connection string for the SQL Server provider).

Since we have already customized so much infrastructure, especially by writing a bug portal that makes use of the customized Exception Management block, we will probably not be migrating to the ASP.NET Health Monitor any time soon. However, for those of you who have been whistling in the dark with respect to the health of your web applications and services, get busy! I highly recommend Scott Allen's post as a starting place for your efforts.

How To Create a Windows Form Singleton

Chris Falter — Fri, 06 Jun 2008 14:31:25 GMT

Recently a friend asked me how you might create a Windows Forms application that only allows a single instance per computer. A print driver might make use of this functionality, for example, to launch a print job management dialog whenever a document prints. Never having needed this sort of functionality before, my initial answer wasn't very helpful. But being both curious and disinclined to back down from a technical challenge, I just had to figure this one out.

As I was looking for an inter-process synchronization mechanism, I came across the Semaphore and Mutex in the System.Threading namespace. A semaphore can be used to manage a pooled resource (memory buffer, thread pool, connection pool, etc.) by tracking the number of available resources. You instantiate a semaphore with an invariant maximum corresponding to the quantity of pooled resource entities (e.g., the number of database connections). Whenever a thread wants to use the resource, it calls .WaitOne() on the appropriate semaphore and blocks until the semaphore count is greater than zero. If the count is positive when the call is made, the thread will not need to block at all.

When a thread enters a semaphore, the semaphore decrements its count by one. The calling thread is responsible for calling the semaphore's .Release() method when it has completed using the resource. This allows the semaphore to increment its count--and as a result, gives another thread access to the pooled resource. You must call Release() inside of a finally block as soon as feasible in your codepath; my testing shows that the CLR will not release an unreleased semaphore when the semaphore reference goes out of scope, or even when the thread of execution terminates.

What we need, then, is a semaphore that has a maximum count of one (since we want only one instance of our application to be running) and will increment its count no matter how the thread that entered it terminates. Happily, this would be a pretty good one-sentence description of the Mutex class. The thread that calls WaitOne on a mutex ("mutual exclusion") gains ownership when it enters the mutex. It can release the mutex at any time by calling the ReleaseMutex method, but should it fail to do so (whether by logic error or run-time failure) before it terminates, the CLR will release the mutex on its behalf. As a result, the mutex should prove more reliable for our purposes.

Here is the singleton code in a nutshell:

using System;

using System.Windows.Forms;

using System.Threading;

namespace MutexTest

{

    static class Program

    {

        [STAThread]

        static void Main()

        {

            Application.EnableVisualStyles();

            Application.SetCompatibleTextRenderingDefault(false);

            // make sure no other instances of this app are running

            bool mutexIsAvailable = false;

            Mutex m = null;

            try

            {

                m = new Mutex(true, "MutexTest.Singleton");

                mutexIsAvailable = m.WaitOne(1, false); // wait only 1 ms

            }

            catch (AbandonedMutexException)

            {

                // don't worry about the abandonment; 

                // the mutex only guards app instantiation

                mutexIsAvailable = true;

            }

            if (mutexIsAvailable)

            {

                try

                {

                    Application.Run(new Form1());

                }

                finally

                {

                    m.ReleaseMutex();

                }

            }

        }

    }

}

One of three things can happen when the Main() thread calls m.WaitOne(1, false):

If the mutex is unowned (or becomes unowned within one millisecond), mutexIsAvailable is true and the thread enters/owns the mutex.
If the mutex remains owned by another instance of the Windows Form app for the one millisecond duration, mutexIsAvailable is false.
If the mutex is available because another instance abandoned it without releasing it, the method throws an AbandonedMutexException. In this case, the thread owns the mutex and may safely launch the application instance, so it sets mutexIsAvailable true.

If the Main thread owns the mutex, it runs the application, using a try/finally block in order to guarantee a call to ReleaseMutex. While strictly speaking it is not necessary to call ReleaseMutex (the CLR will do so on the thread's behalf when it terminates), I have written the code this way in order to maintain a best practice. In some other situation, the thread that enters the mutex might continue performing more work (or enter a suspended state) after finishing its use of the resource and might not call ReleaseMutex, so it's a good idea to write the code in this fashion.

What do you think? Is this code helpful? Do you have any suggestions for improvement? Leave a comment!

.NET Entity Framework: Is It Ready for Web Prime-Time?

Chris Falter — Tue, 27 May 2008 14:50:29 GMT

Our shop has been looking for a way to simplify the interaction between our domain layer and data layer. The data layer uses typed datasets for all its operations. When it retrieves data, it populates a dataset; when it stores data, it checks the DataRowState of all rows in the dataset, and calls the appropriate stored procedure to insert, update, or delete the data. The domain layer then uses dataset elements as the in-memory backing store for properties and collections. A collection typically uses a DataTable, for example, and a collection member would use a DataRow in the DataTable.

This arrangement has some advantages:

Between requests, domain objects can cache their state in session by caching a dataset.
DataRowState can inform the logic about which CRUD operation to perform on a DataRow. Unmodified data can also be skipped over, yielding improved efficiency.
We have considerable freedom in designing domain classes. We can make a property read-only, for example, if it corresponds to an immutable database field, such as an identity column.

This arrangement also has a big disadvantage, however. We end up with lots of properties that look like this:

public string Phone

{

    get { return dr.PHONE; }

    set { dr.PHONE = value; }

}

This property's one and only use is to map a domain attribute (an entity's phone number) to a particular field in a DataRow (dr). Our domain layer has hundreds of these pass-through properties, which are a very verbose and not especially readable way of mapping between the domain and data layers. So we've been looking for a better way to handle this mapping.

Along comes the .NET Entity Framework (EF), which provides a tool that creates a domain-to-data map in XML format. Our first reaction was: this is just what the doctor ordered! And supported by Microsoft, to boot.

On closer examination, though, the EF toolset has some growing up to do before we could consider using it in our web applications. It can generate only public get/set accessors in the entity domain model (EDM) classes, for example. You cannot make a property read-only, or internal/protected/private, or virtual. You cannot map a non-generated property to a database field. And programming in a straitjacket was not what we had in mind for a new approach.

Second, EDM classes generated by EF do not have any supported way to cache their state. A Microsoftie is working on a tool ("Perseus") that can serialize the state of an entity using an EntityBag<T> instance, but it seems somewhat incomplete (and definitely not supported) at the moment. Since our web apps do cache domain entity state, adopting the EF right now would entail an important risk.

What alternatives exist? We can license DevForce EF, which is built on top of the EF and seems to offer pretty much everything that it lacks. Or we can try NHibernate, an open-source .NET port of the Hibernate tool which is quite popular in the Java development world.

Or maybe we can just wait for the EF to mature. Microsoft has big plans for the EF, and intends to make REST-oriented web services, Reporting Services, workflows, etc. EDM-aware. So an EF investment today can yield important dividends in the future.

Even though I cannot render a definitive answer, I hope that this discussion will help readers make an informed discussion about their ORM choices in the .NET world. What do you think? Leave a comment with your insights or questions!

BOOK REVIEW: Don't Make Me Think, 2d Ed. by Steve Krug

Chris Falter — Tue, 13 May 2008 20:31:39 GMT

You've mastered web forms and controls. You've prototyped a Silverlight 2.0 application. AJAX? You're all over it. But have you really learned how to design a good web page or web site?

Steve Krug's "Common Sense Approach to Web Usability" provides surprising and sometimes counterintuitive principles that every good website must follow. Krug preaches the importance of removing clutter in order to make the purpose and functionality of a site (or page) clear--and happily, he practices what he preaches in this remarkably lucid book. Here are some of Krug's key insights:

Don't make users think! Your job is to make sure users do not have to puzzle over a site's purpose, or how to use it. Krug offers the search functionality at Amazon.com as a great example of this principle in action. A user does not have to decide what type of search she wants (by author, by title, by ISBN, etc.); instead, she can just enter whatever text interests her, and Amazon offers a list of matches, ranked by relevance.
Users don't behave the way you think they do. You've been poring over your site--reading everything ten times or more--so you tend to think that users will do the same. But they don't. Instead, the users...
- "don't read pages, they scan them." (In fact you only decided to read this review after you scanned the intro and decided it would be worth your while.)
- "don't figure out how things work, they muddle through."
Design pages for scanning. Since users are going to treat your site like a billboard going by at 70mph (rather than a textbook that they carefully work through), you should learn to design great billboards!
- Create a clear visual hierarchy. Highlight the important stuff, and indicate relationship by grouping.
- Use conventions. If your site design conforms to what users generally expect, they can more easily understand it at a glance.
- Break pages into clearly defined areas.
- Make what's clickable obvious. Use arrows or underlines to indicate that text is clickable, for example.
- Minimize noise. Prefer clarity to pizzazz.
Give users simple\mindless choices. It's okay to make a user traverse 4 or 5 links to get to his desired destination as long as each choice along the way is clear.
"Omit needless words." "Get rid of half the words on each page, then get rid of half of what's left" is Krug's Third Law of Usability. More words just make the site look more daunting, which can discourage the user in a hurry. Krug's Third Law has 2 corollaries:
- Happy talk must die. "We're so glad you're at our site! We think you'll like your experience here..." Oops, you just lost your user, who's too busy to keep reading.
- Instructions must die. Users almost never read them anyway (remember, they don't figure out, they muddle through). So keep instructions brief and simple.

Krug then discusses some details about 2 features every site must have: navigation and a home page. Krug recommends that the sections and subsections of a site be indicated with a clear set of links or tabs on the home page, and that the navigation remain available no matter where the user goes. (This answers the questions: what can I do on this site? and Where can I go from here?) Each page should have a visible name, and the site should a breadcrumb trail with arrows between the levels in order to allow a user to know where he's at in the site's hierarchy. (These answer the questions: where am I at now? and How do I get back to where I was before?).

Krug's discussion of the home page acknowledges that the forces conspiring against simplicity are enormous in any ambitious site, because there are so many organizational interests competing for the valuable home page real estate. Krug provides some useful tips for managing the problems, though, by suggesting how to use logos, taglines, and home page navigation.

Next Krug addresses the often religious arguments that site development teams often endure (pulldowns or menus? Flash animation or simple text?) with this simple advice: forget the arguments and start testing! Simple usability testing will reveal the key problems with a site, and often they have nothing to do with what the development team has been arguing about. Krug believes that frequent tests are more important than comprehensive (often expensive tests), and he offers advice on how to do testing on a tight budget (use 3 or 4 subjects; use an inexpensive screen recorder like Camtasia; try to get all the project stakeholders to observe). He concludes with an extremely useful script of an interaction between a test subject and a test guide.

Those who have already read the first edition will be pleased to know that Krug has included some very helpful new material in the second edition. Is your site accessible to sight-impaired users? If not, Krug offers a top 5 list of tips for making sites accessible, along with a pointer on how to use Cascading Style Sheets to make your site more accessible. Not to mention that CSS makes your site a lot easier to manage.... And what do you do when your boss (or the customer) wants you to do something that violates every known law of web usability? Just compose an email that borrows liberally from one of Krug's friendly "here's how it should be done" missives!

Krug sprinkles his book with examples of sites that work well (and a few that don't) to illustrate his ideas. He often offers a few "How does (or does not) this page implement the principles we've been discussing?" tests, with his own answers on the following pages. I found these examples to be enormously helpful. And Krug offers a wonderful set of additional resources for those who want to pursue the subject further, both within the text and in a notated bibliography at the end.

Because I am a long-time web user and web developer, I thought I understood just about everything I needed to know about usability to design a good site. Then I read this book, and learned a ton. If you work on web sites in any way (whether as designer, developer, or tester), the few hours you spend on Steve Krug's little gem will pay rich dividends.

How To: Encrypt and Manage Documents with SQL Server 2005

Chris Falter — Thu, 08 May 2008 21:13:56 GMT

When one of our departments decided to store sensitive reports, the architecture I first considered was storing them, unencrypted, in our imaging system. The imaging system cannot manage encrypted documents, but its security capabilities allow it to to deny unauthorized users access to the reports. This ability to restrict access seemed to meet our security requirements.

Then I started asking questions about data backups. Offsite backups can be a major security vulnerability, as we have recently learned. The names, addresses, social insurance numbers, and (in many cases) bank account details of almost half of England ended up who-knows-where last year because database backups disappeared in the postal system. And our company, like any responsible organization, backs up our data and stores it offsite. So leaving the sensitive data unencrypted was not acceptable.

Fortunately, SQL Server 2005 comes with native encryption capabilities that are simple to use. In the absence of an affordable imaging system with built-in encryption capabilities, here's the approach I hammered out:

Create a table in a SQL Server 2005 database to store the encrypted documents.
Create a symmetric key in the same database. To facilitate recovery from database failures, store the instructions for re-creating the key in a safe, remote location.
Create stored procedures that use the key to encrypt/decrypt documents that are stored in the table.
Create a service account under which the service that stores the report will run.
Create a (presumably internal) website for displaying the reports.
- Use the same service account for the site's app pool identity.
- Restrict access to authorized groups via Windows authentication.
- Require secure http so that a network trace cannot intercept decrypted documents on their way to the browser.
On SQL Server, deny permissions for the stored procedures and table to anyone other than the service account. The security context of the backup job must also be granted the db_backupoperator role on the database, of course.
Implement network encryption between SQL Server and any services that insert or select sensitive documents, using IPSec or SQL Server Network Encryption.

Below is a diagram of the system that allows authorized users to view sensitive documents.

There is scant MSDN documentation for accomplishing the first 3 steps, but the rest are well understood in the world of Microsoft development. The remainder of this article will therefore focus on creating and managing the tables, keys, and stored procedures.

Step #1: Create a Table to Store the Encrypted Documents

Several considerations drive the design of the table:

The column that stores a block of encrypted data must have the datatype of varbinary(8000) because the result of an encryption operation is always a varbinary(8000).
Unless you are dealing with very small documents, 8000 bytes will not hold an entire document. Therefore a single document will require multiple records, which will be associated with one another by a common unique identifier. A foreign key to the business entity associated with the document would be a good candidate. In our system, the encrypted document is associated with an "Order," so the identifier is an OrderId.
In order to thwart brute force decryption attacks, you should "salt" the encryption with a unique integer for each report. Unless your sensitive documents are very large, the foreign key (OrderId) will serve the purpose nicely.

Here's the table definition that emerges from these considerations:

CREATE TABLE [dbo].[EncryptedReport](
   [OrderId] [int] NOT NULL,
   [BlockNum] [int] NOT NULL,
   [Block] [varbinary](8000) NULL,
CONSTRAINT [PK_EncryptedReport] PRIMARY KEY CLUSTERED
(
   [OrderId] ASC,
   [BlockNum] ASC
)
) ON [PRIMARY]

Step #2: Create a Symmetric Key

To encrypt data in SQL Server 2005, you may use a certificate or a symmetric key. A certificate provides somewhat stronger protection than a symmetric key, so it is the encryption method of choice for a small amount of data (such as a Social Security Number). However, its far greater demand for server resources makes it impractical for large amounts of text or other data. Therefore, if you are encrypting a sensitive document, you should create a symmetric key and encrypt it with a certificate. At run-time, SQL Server will use the certificate to decrypt the key, then use the key to encrypt or decrypt the document.

Before SQL Server can encrypt or decrypt a sensitive document for you, it must traverse a chain of encrypted secrets:

A certificate available only to the SQL Server process identity encrypts SQL Server's Service Master Key.
The Service Master Key encrypts the Database Master Key.
The Database Master key encrypts a certificate ("certDocEncryption" in this example).
The certificate encrypts a symmetric key ("keyReportEncryption" in this example).
(Finally!) the symmetric key encrypts your sensitive documents.

SQL Server stores all of these secrets for you, except for the process identity's certificate (which is stored in the Windows certificate store). Consequently, you do not need to worry about making a "secret" available to your run-time environment by, for example, storing it in a configuration file. Database backups will not include the process identity's certificate (which the operating system maintains for you), so the only way the bad guy that steals your backup can decrypt your sensitive documents is by a brute force attack.

This design does place certain responsibilities on your IT organization:

You must be very careful about using this design with a virtual server. While creating an image of an entire virtual server (Windows OS, SQL Server, and data) facilitates quick disaster recovery, it can also facilitate the theft of sensitive documents, since the virtual server image will have everything (from Windows certificate down to the symmetric key) that a hacker needs to read the data.
To recover data in the event of a server failure, you must be able to re-create the symmetric key. While it is impossible to back up a symmetric key, you can always create an identical key on any instance of SQL Server 2005 by issuing the "CREATE SYMMETRIC KEY" statement with the same algorithm, key source, and identity value. Consequently, you must store the statement used to create your symmetric key in a secure location, such as a safe deposit box at a local bank. And although this statement is quite obvious, I'll say it anyway: don't store the statement with your data backups!

Step #3: Create Stored Procedures

Encrypting a sensitive document is a four-step process:

Open the symmetric key.
Break the document into blocks that, when encrypted, will consume less than 8000 bytes. When I applied Microsoft's published formula to my encryption key process, I concluded that 7876 bytes was the maximum size of unencrypted data that I could safely fit into a varbinary(8000).
Encrypt each block.
Insert each encrypted block into the table.

Here's the definition of the stored procedure that does the trick:

CREATE PROCEDURE [dbo].[usp_StoreReportWithEncryption] 

    @OrderId int, 

    @ReportText varchar(max) = ''

AS

BEGIN

    declare @idx int

    declare @textLength int

    declare @blockSize int

    declare @blockNum int

    declare @block varbinary(8000)

    declare @keyGuid uniqueidentifier

    Open Symmetric Key keyReportEncryption

        decryption by certificate certDocEncryption

    set @keyGuid = Key_GUID('keyReportEncryption')

    set @blockSize = 7876

    set @blockNum = 1

    set @idx = 1

    set @textLength = datalength(@ReportText)

    BEGIN

        WHILE @idx < @textLength

        BEGIN

            set @block = EncryptByKey(@keyGuid, SUBSTRING(@ReportText, @idx, @blockSize), 1, Convert(varbinary, @OrderId))

            insert into dbo.EncryptedReport(OrderId, BlockNum, Block)

                values(@OrderId, @blockNum, @block)

            set @idx = @idx + @blockSize

            set @blockNum = @blockNum + 1

        END

    END

END

To decrypt the document, you must:

Open the symmetric key, then
Reassemble the document by
- Decrypting each block, and
- Concatenating the results.

Here's the definition of the stored procedure that will fetch the document associated with a particular OrderId:

CREATE PROCEDURE [dbo].[usp_FetchEncryptedReport] 

    @OrderId int = 0

AS

BEGIN

    -- SET NOCOUNT ON added to prevent extra result sets from

    -- interfering with SELECT statements.

    SET NOCOUNT ON;

    Declare @numBlocks int

    Declare @rowIdx int

    Declare @text varchar(max)

    Declare @block varbinary(8000)

    Open Symmetric Key keyReportEncryption

        decryption by certificate certDocEncryption

    set @rowIdx = 1

    set @text = ''

    set @numBlocks = (select IsNull(max(blocknum), 0) from dbo.EncryptedReport where OrderId = @OrderId)

    BEGIN

     WHILE @rowIdx <= @numBlocks

        BEGIN

            set @block = (Select Block from dbo.EncryptedReport where OrderId = @OrderId and BlockNum = @rowIdx)

            set @text = @text + Convert(varchar(max), DecryptByKey(@block, 1, Convert(varbinary,@OrderId)))

            set @rowIdx = @rowIdx + 1

        END

    END

    Select @text

END

Finishing Your Security Infrastructure

There is no such thing as a perfectly secure architecture that provides a 100% guarantee against the theft or compromise of your sensitive documents. An authorized user can give up his network credentials to a social engineering attack; an unpatched or badly configured database server might allow a hacker to gain administrator access to it; a trusted network administrator can steal data outright. What SQL Server 2005 does very well is protecting data "at rest"--i.e., sensitive documents stored in your database. By following the first 3 steps in this article, you should be able to get a solution up and running quickly. Just remember: make sure you implement other forms of network security (including the last 4 steps mentioned in the introduction) to make your entire infrastructure for handling sensitive documents resilient against theft and hacking.

If you have suggestions or questions, please leave a comment! Thanks for reading; I trust you have learned something useful from this article.

Want to Write Great Business Software? Create a Great Domain Model!

Chris Falter — Tue, 25 Mar 2008 14:01:28 GMT

When you are coding in a hurry, it is very tempting to write business logic in the first place that comes to mind, such as a button click handler. However, for all but the simplest systems, such a practice leads very quickly to a chaotic system whose business logic is scattered like the ash from an erupting volcano. So let's take a step back and see how you can develop an application more intelligently.

"Divide and Conquer"

“Divide and Conquer” is a useful metaphor for organizing the effort of developing a complex system. A software architect can assign major system responsibilities to various components or layers (which I will refer to as a “part”). As long as the responsibilities of a part are understood, a developer can develop the part in such a way as to satisfy those responsibilities. And as long as the parts integrate well, a useful system can emerge.

“Divide and Conquer” has many advantages:

A team can work in a coordinated fashion on several parts of the system simultaneously, without stepping on each other’s toes.
Assigning a limited set of related responsibilities to a system part simplifies its design.
Modifying a system is easier when the part that is responsible for the functionality that must be changed can be identified.
Ultimately, the complexity of the system decreases as its various responsibilities, and the strategies for handling them, become clear. Unnecessary complexity is what can make “the last 10%” of a project go into deep cost and time overruns, as quality issues and poor design make their effects known.

“Divide and Conquer” is the driving force behind creating logical layers of a user interface, an application layer, a data layer, and a domain model in an enterprise software application.

While the advantages of separating UI, application, and data logic into their own layers are well understood and frequently practiced, the point behind creating a domain model is not as widely grasped. A domain model defines the business entities represented by a system, the activities associated with them, the relationships between them, and the rules and constraints that govern them. These are clearly very important aspects of the system, even though (from the end user’s perspective) they are not as visible as the user interface, application flow, or database. I will illustrate the importance of a domain model by examining how insurance endorsements work in the homeowners point-of-sale system that my team has developed.

Example of a Complex Business Domain

Let’s start by examining the data model for endorsements:

An endorsement can be associated with either an application (future policy) or with a risk (such as a dwelling or a vehicle). Therefore the Endorsement table has 2 foreign keys: one that relates an endorsement to an application (via the Quotenumber) and the other that relates it to a risk (via the RiskId).
Endorsements come in a bewildering variety. Some endorsements have no related data; some have one or more limits; some have one or more attributes, few of which are common between endorsements. Clearly it is unwise to attempt to create a single table with identified columns for each of the possible limits or attributes that an endorsement may possess. In addition, any attempt to create a unique table for each endorsement’s associated attributes is going to result in a very large number of tables—along with the responsibility of defining a new table each time a new endorsement type is created. Therefore, the design we chose was to create 2 dependent tables for Endorsement: an EndorsementLimit table and an EndorsementDescription table. Each table has 3 fields: an EndorsementId (foreign key back to the associated endorsement), a “type” field that allows the system to distinguish between all the related descriptions (or limits) of an endorsement, and the associated data field (a numerical limit or a varchar description). Note that segmentation and history are irrelevant to a point-of-sale system, so the schema is not designed with that capability.
Some endorsements are concerned with parties to an insurance application other than the applicant, such as an additional interest or an additional insured. Since these additional entities reside in a different table (the OtherParty table), we use a join table (EndorsementParty) to manage the association between Endorsement and OtherParty.

This portion of the database schema is represented graphically below:

So if we have a data model, why do we need a domain model? Why can’t some UI code simply write its data directly to the tables? Clearly this one way of designing a system—you can, after all, do anything with software (provided you have sufficient time and resources).

Let us consider, though, the knowledge about the business domain that the point-of-sale application must manage with regard to endorsements:

The relationship of endorsement attributes to an endorsement. A homeowners “HO 05 28” (golf cart) endorsement has several related attributes: a limit (cart value), a make, a model, a serial number, and an indicator of whether collision coverage is included. Each one of these attributes is stored in its own record in the EndorsementLimit or EndorsementDesc table. The DescType field distinguishes the four EndorsementDesc records from one another; however, the system must somehow keep track of which DescType is used for which attribute.
Differences between the format of stored data and how it is used. In a database system that does not have a built-in boolean type (such as the DB2 flavor used at my shop), there are probably as many different ways to store boolean data as there are programmers. True vs. false could be represented as “0” vs. “1”, or as “1” vs. “2”, or as “T” vs. “F”, or as “t” vs. “f”, or as “true” vs. “false”, or as “Y” vs. “N”, etc. (In one of my consulting engagements, I actually saw all of these plus a couple more in a single application.) To handle a golf cart endorsement’s indicator of collision coverage, the system must be able to reliably map between the stored data and a run-time choice of true/false.
The relationships between endorsements and other entities. Some endorsements are related to the risk being insured (such as the earthquake endorsement), and some are related to the (potential) policy itself (such as an “Additional Insured” endorsement).
The relationships between endorsement attributes. The “HO 04 65” endorsement (scheduled property) contains a set of schedules; each schedule is designated by a letter such as “A” or “J” and has a description (the personal property being insured) and a limit. Since descriptions and limits are stored in separate tables, the system must have some way of identifying and associating the schedules’ descriptions and limits.
Rules and constraints on various endorsements. The 6 schedules on a “HO 04 65” endorsement have base (default) limits, for example, such that the total limit of a schedule can be described as the base limit plus an additional limit. Mathematically speaking, we use the formula Total Limit = Base (fixed by rule) + Additional (stored in EndorsementLimit table). So the system must be able both to provide base, additional, and total limits (given the stored additional limit) and to update the stored additional limit (based on user entry).

Complexity Resolved: A Domain Model

The beauty of our team's domain model is that it completely hides all of this complexity from the user interface.

An endorsement class is defined for each type of endorsement, and it provides an interface that is radically simple for the UI developer to use. To give just one example, the golf cart endorsement provides a boolean CollisionIncluded property that can be mapped to a checkbox.
All of the other issues (which EndorsementDesc record the indicator is stored in, how the boolean is mapped to a varchar, etc.) are managed inside an endorsement class—frequently by using capabilities inherited from the EndorsementBase class or borrowed from utility classes in the domain layer.
Responsibilities are clearly grouped and assigned in this way of designing a system. Tasks and attributes that are common to all endorsements are the responsibility of the EndorsementBase class. The tasks and attributes that are unique to a particular endorsement are the responsibility of the corresponding subclass of EndorsementBase (which already has the common endorsement capabilities via its inheritance relationship with EndorsementBase). Neither of these classes needs to know anything about the application or user interface which will use them, which in turn need to know nothing at all about the internal implementation details of an endorsement class. The diagram below depicts the assignment of some endorsement responsibilities to classes in our domain layer.
The association of an endorsement with a policy or with a risk is managed via its membership in an EndorsementCollection that is accessed via the HomeApplication object or the HomeApplication.Home object (of type HomeRisk), respectively. The relationship between these various entities is depicted below.

Conclusion

There are some things that should never leak. Space shuttle O-rings. Tires. Diapers. And now that you've read this article, add your business domain model to the list. Always isolate your business domain logic in a cohesive model; do not let the logic leak into a "smart UI" or into the data layer! If you follow this rule, you will save yourself and your team much time and effort when you need to modify the business logic in your application.

Also, keep the importance of your domain model in mind when it is time to choose a development tool. A rapid application development (RAD) tool that can only design screens and logic flows might be a very good choice for building a very simple system that needs little complexity in its business logic. However, it is very difficult to envision how a RAD tool would be able to represent the relationships and constraints inherent to a complex business domain, such as homeowners insurance endorsements. Given the inherent limitations of a RAD tool, the complexity that my team's domain model currently manages quite capably would have to spill out into the flows and screens themselves.

While the result may initially seem counterintuitive, a RAD tool that at first glance makes everything look simple might very well in the end produce a system far more complex than a system produced with a set of tools that offer a robust and complete set of programming capabilities. And this unanticipated complexity can make the systems you develop far more difficult to implement on time and to extend with new customer-requested capabilities.

Refactoring to Comply with the DRY principle (Don't Repeat Yourself)

Chris Falter — Fri, 07 Mar 2008 13:45:40 GMT

If you're not living DRY, you're not a good programmer.

Okay, I'm not talking about alcohol consumption! I'm talking about the Don't Repeat Yourself principle--a principle every programmer should live by. Recently I did a code review for a project we outsourced, and demonstrated how you can refactor bad cut-and-paste code into well-designed code. You will note that the capabilities of the MagicStringTranslator class really help to reduce code clutter. Without further ado, I present the relevant portion of my code review:

...your branching logic has 12 lines of code in each branch except the final one. I am inserting an excerpt for reference:

if (m_record.Text.Substring(13, 6).Trim() == "IDENT")

{

writer.WriteBreak();

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write("SUBJECT INFORMATION");

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

}

if (m_record.Text.Substring(13, 6).Trim() == "SUMRY")

{

writer.WriteBreak();

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write("SUMMARY");

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

}

if (m_record.Text.Substring(13, 6).Trim() == "COLLT")

{

// this code and several more near-identical branches are omitted for brevity’s sake

}

Eleven of these lines of code are identical. This is bad for 3 reasons:

What would happen if one of the lines of code had a bug? You would have to fix it in each branch, and be sure to do it the same way in each one. This code structure is bug-prone.
The structure implies that each branch does different things, when the code in fact does essentially the same thing. As a result, the code structure is misleading.
The code ends up being way too verbose; it is saying the same thing over and over and over. As a result, the code structure is hard to read and understand.

In fact, your code does suffer from an insidious little bug. You are comparing a substring of length 6 to a literal of length 5.

if (m_record.Text.Substring(13, 6).Trim() == "IDENT")

This only happens to work when the 6th character is a blank, because in this circumstance the Trim() method reduces the string to length 5, and the comparison is valid. What would happen if the 6th character did not happen to be a blank?

But don't try to fix this bug in the seven places where it occurs! There are better ways to improve the code. One way is to restrict the branching logic to the one line of code, then use that one line together with the other 11 exactly once.

string title = String.Empty;

switch (m_record.Identifier)

{

case "IDENT":

title = "SUBJECT INFORMATION";

break;

case "SUMRY":

title = "SUMMARY";

break;

case "COLLT":

title = "COLLECTION ITEMS";

break;

case "ACCNT":

title = "TRADE ACCOUNT ACTIVITY";

break;

case "MSSGE":

title = "MESSAGE";

break;

case "EMPLY":

title = "EMPLOYMENT";

break;

case "INQHS":

title = "INQUIRY HISTORY";

break;

}

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write(title);

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

An even better way is to delegate the relationship between magic string (e.g., “INQHS”) and description (e.g., “INQUIRY HISTORY”) to a class specialized for this purpose. Then you can simply use the class directly, without writing any branching logic at all. In this situation, define a MagicStringTranslator subclass for the Identifier property:

public class IdentifierCode : MagicStringTranslator

{

public const string SUBJECT_INFO = "IDENT";

public const string SUMMARY = "SUMMARY";

public const string COLLECTION_ITEMS = "COLLT";

public const string TRADE_ACCOUNT_ACTIVITY = "ACCNT";

public const string MESSAGE = "MSSGE";

public const string EMPLOYMENT = "EMPLY";

public const string INQUIRY_HISTORY = "INQHS";

}

Then make the class’ Identifier property of type IdentifierCode:

public IdentifierCode Identifier

{

get{ return new IdentifierCode(segments[(int)Fields.Identifier].Data); }

set { } // no-op setter provided so that XmlSerializer can serialize this property

}

Finally, use the Identifier directly, without any need for branching logic:

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write(m_record.Identifier.Description);

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

And you're done.

A Good Solution for "Magic String" Data

Chris Falter — Thu, 06 Mar 2008 16:08:45 GMT

Dealing with vendor data (or your own) in the form of "codes" can pose significant challenges. You must ensure that your source code remains readable, that data are properly validated, and that data can be displayed as user-friendly descriptions. The built-in solutions (named constants and enums) help, but they have some significant shortcomings. If you derive a class of named constants from the MagicStringTranslator class, though, you can vanquish all 3 challenges in one fell swoop!

Egghead Cafe has kindly published the improved version of my article here. Enjoy!

Make Magic Strings Easy to Understand and Type Safe

Chris Falter — Wed, 27 Feb 2008 07:40:16 GMT

As organizations pass data back and forth, they often use codes to represent the data. For example, a marital status of divorced might be represented as "D", married as "M", and so forth. You have to solve three problems when you are dealing with magic strings:

When you write logic to handle the data, things can get chaotic on a hurry if you are not careful; the use of literal magic strings in your source code can make it incomprehensible.
You can get into trouble by passing a string that is not in the set of valid codes as a parameter to a method that is expecting one of the codes. Since the parameter type is typically string, the compiler will not help you detect the error.
You often have to translate codes into it description so a user of your system will know which data have been gathered.

Using named constants can help make your source code more readable, but you still have more work to do: you must write extra logic to check whether a string belongs to the set of valid codes, and to translate a code into a description that a user can understand. If you declare your named constants in a class that inherits from the MagicStringTranslator class, though, you will get the data validation and the translation for free. Check out the article I wrote for the details!