Nate's Stuff : Standards / Conventions

Exception Handling Philosophy

Nathan Zaugg — Mon, 23 Mar 2009 19:40:00 GMT

It's time for another episode of Good Idea / Bad Idea:

Good Idea! Catching a specific exception from a suspect numeric conversion and showing a polite input error message.
Bad Idea! Catching all exceptions and "swallowing" the exception.

Okay, so it's not as funny as it is on Animaniacs, but true none-the-less.

Exception Handling in C#

In terms of exception handling I am a big fan of "catch it only if you can do something with it" and/or "catch it only if you mean it". Putting a try / catch around every method makes debugging very difficult and can leave your application in an unexpected state. Besides the code is less readable, more complex, and slower performing.

Before I get in to good practices, lets review some bad ones. The first and most obvious is throwing away exceptions (without regard to what they are). Example:

// Anti-pattern #1: Throw away the exception
private void button1_Click(object sender, EventArgs e) {
    try {
        AddPerson(new Person() { Name = txtName.Text });
    } catch { }
}

Another example of what not to do is what I call the “catch just because” pattern. Example:

// Anti-pattern #2: Needless Try / Catch
private void DoStuff(string shipping) {
    try {
        // Call down to middle tier to do the shipping calculation            
        decimal ShippingCost = MyApi.Shipping.GetShippingCost(orderNum);
    } catch (Exception ex) {
        throw ex;
    }
}

//  Needless Try / Catch
private void button2_Click(object sender, EventArgs e) {
    try {
        // CalculateShipping has it's own Try / Catch; see below.
        CalculateShipping();
    } catch (Exception ex) {
        MessageBox.Show(ex.Message);
    }
}

There are multiple problems with the second example. First, there was no reason for “DoStuff” to catch the exception if all it was going to do was re-throw any exception it encountered. Second, “DoStuff” is catching any exception rather than limiting the scope to the kinds of exceptions it might expect like “Unknown Zipcode”, “Order not found”, etc. Next, the “button2_Click” is catching any exception and showing the raw message.

Rather than showing the exception message which is only part of the clues given in the exception object you should either show a user-friendly message indicating the kind of error that has taken place and save the exception information for later debugging. Alternatively, you can show ex.ToString() which will show you all information in the exception class. This is very unimpressive for end-user applications but can be acceptable with internal corporate apps and a simple screen shot will give you the information you need to find and take care of the problem.

Remember, an exception doesn’t necessarily mean that there is a bug in the software. If you do show a user an “unfriendly” exception message they will immediately think that the software has a bug when the issue could be as simple as the network is down or a database is temporarily unavailable. I always recommend taking the time to display user-friendly messages and saving the exception information elsewhere.

In the next section I will show some good examples on what "layer" to catch and/or re-throw an exception.

Presentation Layer

Personally I think that any event here should catch any/all expected exceptions and show them in a user-friendly manor. Notice I said "expected exceptions", this could be pretty vague unless you have an design pattern in place for exceptions in your applications so I'd start with that. One way to start is to make some "base" exceptions like "DataException", "ValidationException", "InputException", etc. More specific types of exceptions can be derived from these.

When do you make a new type of exception? Well, the exception should have the information needed to solve the problem. Stack traces and exception information are like clues; leave your self a breadcrumb trail to follow later. Throwing an ApplicationException because you couldn't connect to the database isn't very helpful.

It is also acceptable to use pre-defined / framework exception types when appropriate. For example:

public void DivideMyObjects(MyObjectType o1, MyOtherObjectType o2)
{
    if (o1 == null || o2 == null)
        throw new NullReferenceException(
            "The numerator or the denominator cannot be null!");

    if (o2.Value == 0)
        throw new DivideByZeroException(
            "Denominator may not be zero!");

    if (o1.Value == null)
        throw new ArgumentException(
            "There is no value for the numerator");
    ...
}

You may notice in the code example above that a null reference may occur organically. I am a strong believer in organic exceptions as good practice. I define an organic exception as an error that is thrown by the Framework. The only exception to that rule is when there isn’t enough information from that exception to track down the problem. Remember, you need to leave yourself enough clues that you should be able to know what is wrong from the exception information given rather than expecting users to be able to remember what steps led up to the exception. Few, if any, end users will be able to help you reproduce any particular error. If this can’t be accomplished by an organic exception then you may want to re-throw that exception with the appropriate information and/or change the type of the exception to be more appropriate for the callers.

// Presentation Layer Good Example
private void Calculate_Shipping(object sender, EventArgs e) {
    try {
        decimal shippingCost = MyApi.Shipping.CalculateShipping(order);
        txtShippingCost.Text = shippingCost.ToString("C");
    } catch (UnknownZipcode uzipEx) {
        // Specific
        MessageBox.Show(
            "Could not locate shipping information for this zip code!");
        btnSave.Enabled = false;
    } catch (ShippingException shipEx) {
        // Less specific, but still helpful to the user.
        MessageBox.Show("Unable to calculate shipping!"
            + Environment.NewLine +
            shipEx.Message);
        MyLogging.Log(shipEx);
    } catch (Exception ex) {
        MessageBox.Show(
            "An unknown error has occured, Please report this error");
        MyLogging.Log(ex);
        Close();
    }
}

In general you are pretty safe catching exceptions in the presentation layer. The only real thing to watch out for here is that your control states don’t become invalid because an exception is caught but the event still altered the state. For example, if a call to “Calculate_Shipping” throws an exception you will want to be careful to invalidate the shipping cost control and disable the “save order” button.

You will notice in the code above that I did catch generic exception. The presentation layer is usually okay doing this so long as it is taking adequate measures to protect application integrity. You will notice that I am closing the order form if I get an exception back that that is unknown. Of course this will give you plenty of motivation to make sure you know what kinds of exceptions are expected as end users will generally hate having their order forms close. You may be tempted to leave the form open or take lesser action but it is very important that you keep application integrity. Otherwise you will spend your life chasing down un-reproducible bugs.

Middle Layer

Most of your code should end up being middle layer code. We want the presentation layer to be as light as possible! The middle layer should act as the API of the application. Anything that the application “does” this layer should do it either directly or indirectly. In this sense the middle layer needs to be very up front in which exceptions are possible from any given call.

Take for example a method call in the middle layer that inserts a new customer into the database. Because you use the database objects you are exposed to any exceptions that are possible from the objects that you use such as SqlExceptions. You will either need to publish that you are going to allow SqlExceptions to be bubble through this API or you need to catch the expected exceptions from those objects and throw your own brand of exception.

Here is an example of publishing the exceptions that are known to be thrown:

// Middle Layer Exceptions
/// <summary>
/// Calculates shipping for a given order
/// </summary>
/// <param name="order">The order to calculate shipping for</param>
/// <returns>the shipping amount applied to the order</returns>
/// <exception cref="UnknownZipcode">Unknown Zip Code / Zip Not Found</exception>
/// <exception cref="BadWeightException">The weight of the order is zero or unknown</exception>
public decimal CalculateShipping(Order order) {
    ...
}

Simply using ndoc XML style comments will give the consumer of the API enough information to make good decisions regarding the use of exception handling from the intellisense.

Another thing you should avoid while designing your middle tier is the use of exceptions as “message handling” in non-exceptional cases. Remember, the reason you are throwing an exception is because something happened that was catastrophic enough that you were unable to continue with the normal flow of the method. I admit that there is still a lot of gray area here. Some of that gray area can be demonstrated in the sample code already shown. For example, rather than throwing an exception in the “CalculateShipping” method we could refactor so an exception wouldn't be necessary. Anytime this can be done cleanly I usually opt for these types of changes.

Refactor to return a ShippingResult class that contains information about the calculation along with the rate. Such information could include whether it was able to successfully get a shipping rate.
Create a ValidateShippingAddress method that looks up the address before the calculate shipping is run. It could return true if we know we can get shipping information for that address.
We could pass back a nullable decimal result. A null return would indicate a failure to retrieve shipping information. We would want to make sure it was clear in our ndoc comments that this is why the value is nullable.
We could pass pack a zero or negative result. Again, making sure this behavior is documented.
We could implement the “Get Last Error” pattern; though at this point I’d rather see an exception.

Another question I am often asked is “When is it appropriate to re-throw an exception”. The answer to that questions is, of course, it depends. The next few sections will discuss some of these nuances of this question.

Bottom Layer

The bottom layer of an application could be a database layer, a Framework of some sort but the philosophy is very different from the middle layer. As the bottom layers deal with primitive classes and data and as such can stick pretty well to exception handling ideals. One of the big differences is that you won’t be using nearly as many user defined exception types. It is not taboo to use a user defined type in a Framework layer but it’s just likely to be unnecessary. The difficulty here is the exception message that you are going to pass along. There could be any number of middle layer calls that call your method so by nature these messages are going to be far more generic. Generic, however, does not mean it can’t be insightful. You should include as much information as possible about the exception and the data that caused the exception. Take the two following exception statements:

“Invalid DateTime”
“The date ‘4/11/2089’ is an invalid birth date! The date cannot be in the future!”

The first exception tells us that there is an invalid date time but other than a stack trace gives us no other information. The second exception is extremely helpful and specific, including as many clues as possible. The user may have entered the value ‘4/11/89’ and the computer may have just assumed the wrong century. The first error message would cause greater confusion whereas the second, if the user were to see that message, could be helpful.

Summary

Of course there are lots of different ideas and philosophies on exception handling so you need to do what makes sense for your project. Simply avoiding the two anti-patterns on the top of this blog will improve your code a lot. MY ONE LAST PEICE OF ADVIECE IS THAT SOMETIMES YOU REALLY WANT TO USE A DEBUG.ASSERT RATHER THAN AN EXCEPTION! The advantage of the assertion is that only debug builds show these messages. This is good for testing scenarios in which you want to be aware of a certain condition but it’s not necessarily an exception.

Encrypting Configuration Information for ASP.NET

Nathan Zaugg — Wed, 16 Jul 2008 22:11:22 GMT

Every company I consult with invariably has their own "security" assembly and they all have a hard-coded encryption key with the IV and the method to decrypt is right next to the method to encrypt. This is what I call marginal protection. Yes, it's encrypted and will probably get a security auditor off of your back but don't be fooled into thinking that you are protected! A similar thing is done with information in the database, but I'll cover how to do this on an upcoming post.

Why aren't you protected? The answer to this question is actually quite simple. If an attacker has access to download your web.config file (say, they brute forced a password on the FTP server) then there is nothing stopping them from downloading the your Security.dll which is responsible for decrypting the password. Once they have that library it's seconds, not minuets, before they have got the password.

One possible work around is to encrypt configuration sections of your web.config file using DPAPI as outlined in this MSDN How-to. This is immune to the download attack because the DPAPI uses encryption that is based on a machine or a user. Even if someone was able to download your web.config they would effectively have no way to decrypt that information.

What happens, though, if the attacker has the ability to upload files? Well, in theory, they may be able to grab that configuration in code which will, of course, be decrypted before it is returned. Ahh, but they don't even know what the name of the connection string (in the case of databases) is because the entire section was encrypted. However, they could guess it or get it from other code. By the way, you really shouldn't deploy the .cs files to production anyway; you should use the "publish website" option with the setting to not allow the site to be updated. If you follow all of the standards pretty closely your in good shape. Another great idea is to use Integrated Authentication for database access -- that way there is no password to steal!

The How to outlines 3 basic steps summarized below:

Identify the configuration sections to be encrypted

You may only encrypt the following:

<appSettings>. This section contains custom application settings. 
<connectionStrings>. This section contains connection strings. 
<identity>. This section can contain impersonation credentials. 
<sessionState>. The section contains the connection string for the out-of-process session state provider.

Choose Machine or User store

Use Machine store if this is a dedicated server with no other applications running on it or you want to be able to share this information with other applications running on this machine.
Use User store if the above does not match your situation and in a scenario in which the user has limited access to the server.

Encrypt your configuration file data

To encrypt using Machine Store, run the following command from a .NET command prompt:
aspnet_regiis.exe -pef "{ConfigSectionName}" {PhysicalDirectory} –prov "DataProtectionConfigurationProvider"
OR
aspnet_regiis.exe -pef "{ConfigSectionName}" -app "/{VirtualDirectory}" –prov "DataProtectionConfigurationProvider"
To encrypt using User Store:
Add the following section to your configuration file:

<configProtectedData> 
    <providers> 
        <add useMachineProtection="false" keyEntropy="" 
                name="MyUserDataProtectionConfigurationProvider" 
                type="System.Configuration.DpapiProtectedConfigurationProvider, 
                System.Configuration, Version=2.0.0.0, Culture=neutral, 
                PublicKeyToken=b03f5f7f11d50a3a" /> 
    </providers> 
</configProtectedData>

Open a command prompt using the user you plan to encrypt the file with. To do so, Right click on the Command Prompts shortcut, right click -> Run As. Or use the following command:

Runas /profile /user:domain\user cmd

Run the following command:
Aspnet_regiis -pe "connectionStrings" -app "/{VirtualDirectory}" -prov "MyUserDataProtectionConfigurationProvider"

It really is that simple! The great thing is that we don't have to do anything special in development to benefit from the encryption of the configuration sections.

References:

http://msdn.microsoft.com/en-us/library/ms998280.aspx

Database Naming Conventions

Nathan Zaugg — Wed, 02 Jul 2008 20:50:00 GMT

Naming conventions are like arm pits. Everyone has them and they all stink! Well, at least that's the perspective of pretty much every developer an DBA alike. I will present my own personal philosophy for naming conventions on databases and hopefully spawn some discussion in the process.

Basic Principles

Consistency

As annoying as certain standards are (such as putting tbl_ before everything) it is more annoying and more difficult when there are no conventions or mixed conventions. Being able to reliably predict the schema once the basic relational structure is understood is key to productivity. Therefore, even if you get stuck with standards you disagree with, so long as they are consistent they will be much better than the alternative. Unless you get to make the decision, my guess is that there are going to be some conventions that you do not agree with.

Abbreviations

It is a good idea to abbreviate, when appropriate, in the naming of objects in your database. It may be a good idea to have a list of abbreviations that you plan to use in the database as part of your data dictionary. However, if there is not a good, clear abbreviation for an object, don't make one up. When in doubt, spell it out! Especially with SQL Server where you don't have the pesky 30 char limit for tables and columns like Oracle.

Identities

Every table should have an Identity as it's primary key! Sometime, in a future blog post I will explain why this is so critical, but suffice it to say that any table that does not have a primary key is considered by SQL Server a "heap". If you are using something other than an Identity column for the primary key you better have a really compelling reason because it will cause major performance problems. THERE IS NO SUCH THING AS A NATURAL KEY AND THEY SHOULD NEVER BE USED IN PLACE OF AN IDENTITY! So always use a surrogate key approach, even with join tables.

Security

I believe that with a good data layer like Linq to SQL there is no need for relegating all database access through stored procedures. While it does remove some of the service area for venerability and bugs robust solutions like Linq to SQL are very limited by this approach. You should grant specific access to tables and procs by user. A good approach can be found on another one of my blog posts.

Object Naming

Table Names

If you are running a database that preserves case (like SQL Server) tables should have no prefixes and should not contain underscores "_" unless it is a join table. Table names should also be Pascal Cased. If you are running a database that makes all tables upper case (like Oracle) then you have little choice but to use underscores everywhere.
Avoid pluralizing table names (User vs Users). This is a good idea for two reasons, first it can be confusing when doing the keys. Do we use UserID or UsersID? Second not all tables pluralize well (Addresses) so avoiding any plural names will keep it consistent. It you are using Linq to SQL the designer will pluralize for you automatically.
Join tables should the two or three tables that they are joining together as part of the name seperated by underscores. (ex: User_Address, User_Order). Although they are many-to-many relationship see if you can find a principle table. Users have orders, orders do not have users, therefore the User table comes first in the name.

Column Names

Name the Primary Key Identity column the table name with ID. (ex: UserID) With the possible exception of join tables, in which case just name the Identity ID.
Use Pascal casing (ex: EachWordsStartsCapolatized)
Do not use the table name as part of the column name. If this is a shipping table don't name your columns ShippingAddress, just name it Address.
Do not prefix column names with the type (ex: strUserName). It makes the database much more difficult to work with.
Use the correct data types. Always use nvarchar types (unicode) rather than varchar types. This avoids substantial complexity if you are ever requried to store non latin-based data! Trust me, you do not want to have to deal with code pages in the database! Also, use Date fields for dates, bit fields for boolean, etc.
Don't make every column nullable! Think through what data is absolutely required. If you want to hold "partally complete records" then I would suggest a different table or different "staging" database.
Don't make a bit field nullable unless you have a great reason!
Try to include a TimeStamp column if you think you may have to worry about concurrency.
Don't prefix with anything.

Constraint & Index Names

Name your constraints and indexes. With the exception of foreign key constraints they are not automatically assigned meaningful names.
Don't use prefixes and make light use of underscores.

Stored Procedure Names

Don't prefix your stored procedures! People used to prefix them with "sp" because existing procs in the database use this convention. It has been presumed that sp stands for system procedure and it wouldn't make any sense to use that. Seriously, prefixes are not very helpful in the database!
The first part of the name of a proc should be the table name it works upon (ex: User_Insert). If the proc works on multiple tables try to give it the name of the portion of the database this proc deals with. For example, if it's a proc that the invoicing system uses it would be acceptable to name it Invoicing_Update, for example.
Don't generate procs for simple Insert, Update, Delete, and Select unless you have a policy in place for accessing data exclusively from procs.
Don't create any stored procedure you don't need or plan to immediately use. At some point you will change the schema and you won't update procs your not using. Someone may eventually want to use that proc later only to find it broken.
The verb in the naming convention does not have to be relegated to "Insert, Update, Delete, Select". It should say what it does. Just be careful that if there is another procedure that does this same thing to another table that the verbs are named the same.
You can add additional information to the proc name to help distinguish it from others. (ex: User_Select_ByDate, User_Select_ByState)
Don't use a prefix for arguments (ex: @ArgUserID). In my experience they don't help at all and are quite annoying!

Tips & Tricks

SQL Server 2008 has a policy manager that can help create and enforce policies like naming conventions! Regardless of using SQL 2008 be sure to keep a Data Dictionary of your database! The database is the heart and soul of your business processes and should be well documented! There is nothing worse than an unclean database!

Nathan Zaugg