Random Musings of Jeremy Jameson

Constraining Tables with CSS

2009-11-01T14:15:00Z

Have your ever wanted to display data in a table but limit the size of the rows and columns within the table?

For example, consider the classic master/detail view that we often find in software applications, in which items are shown in a summary table and each row provides a link to allow users to see more detail about the item.

However, unlike the typical master/detail scenario, you need to limit the amount of real estate consumed on the page by the summary table. In addition, if text within a column is too long to fit within the constrained area, you want to show the full text when the mouse cursor hovers over the cell.

The following figure illustrates the desired end result:

Figure 1: Constrained table

See full-sized image.

Here is the sample ASP.NET page that I created this morning to demonstrate this:

<%@ Page Language="C#" AutoEventWireup="true"
    CodeBehind="ConstrainedTable.aspx.cs"
    Inherits="Fabrikam.Demo.Web.UI.ConstrainedTable" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Demo - Constrained Tabular Data</title>
    <link rel="Stylesheet" href="http://meyerweb.com/eric/tools/css/reset/reset.css" />
    <style>
        /* Basic formatting
        ----------------------------------------------------------------------*/
        body {
            color:#000000;
            font-family: Verdana, Arial, Helvetica;
            font-size: small;
            margin: 10px;
        }
        h1, h2, h3, h4, h5, h6, strong {
            font-weight: bold;
        }
        h1 {
            font-size: 1.5em;
            margin: .67em 0;
        }
        table caption {
            font-weight: bold;
            margin: 10px 0;
        }
        table.displayTable {
            border-left: 1px solid #36295E;
            border-right: 1px solid #36295E;
            margin: 1em 0;
        }
        table.displayTable th {
            text-align: left;
        }
        table.displayTable th, table.displayTable td {
            border-bottom: 1px solid #36295E;
            padding: 5px 10px;
            vertical-align: top;
        }
        table.displayTable thead th {
            background: #36295E;
            color: #FFF;
            padding: 8px 10px;
            border-bottom-width: 0;
        }        
        table.displayTable tr.altRow {
            background: #F4F4F4;
        }
        /* =constrainedTable
        ----------------------------------------------------------------------*/
        table.constrainedTable {
            table-layout: fixed;
            width: 540px;
        }
        table.constrainedTable th.nameColumn {
            width: 140px;
        }        
        table.constrainedTable td {
            overflow: hidden;
            -o-text-overflow: ellipsis; /* Opera */
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    </style>
</head>
<body>
    <form id="form1" runat="server">
        <h1>Demo - Constrained Tabular Data</h1>
        <asp:GridView ID="ConstrainedGrid" runat="server"
            AutoGenerateColumns="false"
            Caption="Constrained Table"
            CssClass="displayTable constrainedTable"
            OnRowDataBound="ConstrainedGrid_RowDataBound"
            EnableViewState="false"
            UseAccessibleHeader="true">
            <AlternatingRowStyle CssClass="altRow" />
            <RowStyle CssClass="row" />
            <Columns>
                <asp:HyperLinkField
                    DataTextField="Site"
                    DataNavigateUrlFields="URL"
                    HeaderText="Site"
                    HeaderStyle-CssClass="nameColumn" />
                <asp:BoundField
                    DataField="Notes"
                    HeaderText="Notes"
                    HeaderStyle-CssClass="notesColumn" />
            </Columns>
        </asp:GridView>
    </form>
</body>
</html>

The most interesting parts of the ASP.NET page are the CSS rules for the constrainedTable class:

table.constrainedTable {
    table-layout: fixed;
    width: 540px;
}
table.constrainedTable th.nameColumn {
    width: 140px;
}        
table.constrainedTable td {
    overflow: hidden;
    -o-text-overflow: ellipsis; /* Opera */
    text-overflow: ellipsis;
    white-space: nowrap;
}

Changing the table-layout to fixed constrains the table to the specified width. Since I don't specify a width for the notesColumn it consumes the remaining width of the table.

Next, I specify that all cells in the constrained table should truncate the text within each cell if it is too wide to fit within the width of the column. This is achieved using the combination of overflow: hidden and white-space: nowrap. Finally, I use the text-overflow CSS property to show ellipsis when text within a cell is clipped (as well as a slight variation for the Opera browser).

Note

Support for the text-overflow CSS property is somewhat limited. In particular, you will find that a clipped table cell renders without the ellipsis in Firefox (at least in version 3.5.3). Oddly enough, this appears to have been supported in Internet Explorer since version 6. In addition to Internet Explorer and Opera, this also appears as expected in Safari.

Also note that constraining table cells using CSS does not automatically display the tooltip with the complete text. For that, you are on your own.

When using an ASP.NET GridView control, I recommend using the RowDataBound event in order to set the ToolTip property of the table cell. Just be sure to decode the contents of the cell to avoid having it encoded twice:

        protected void ConstrainedGrid_RowDataBound(
            object sender,
            GridViewRowEventArgs e)
        {
            foreach (TableCell cell in e.Row.Cells)
            {
                // Note: We need to decode the cell text in order to avoid
                // having it encoded twice (e.g. "&amp;gt;")
                cell.ToolTip = HttpUtility.HtmlDecode(cell.Text);
            }
        }

This is somewhat of a "brute force" approach since it makes no attempt to determine if the text will be truncated, but rather sets the ToolTip (in other words, the title attribute on the HTML element) for every cell. However, the simplicity of this approach -- and the resulting user experience -- far outweighs any extraneous markup (at least in my opinion).

Be aware that this simple approach for setting the ToolTip property doesn't support columns generated from a HyperLinkField, in which case cell.Text is empty (because the cell contains child controls, not simple text). In other words, it's a good thing my demo doesn't specify very long site names that don't fit within the 140 pixel width column constraint ;-)

Here is the complete code-behind for my sample ASP.NET page so you can run it yourself:

using System;
using System.Data;
using System.Globalization;
using System.Web;
using System.Web.UI.WebControls;

namespace Fabrikam.Demo.Web.UI
{
    public partial class ConstrainedTable : System.Web.UI.Page
    {
        protected void Page_PreRender(
            object sender,
            EventArgs e)
        {
            BindSampleData(this.ConstrainedGrid);

            this.ConstrainedGrid.HeaderRow.TableSection =
                TableRowSection.TableHeader;
        }

        #region BindSampleData

        private static void BindSampleData(
            GridView grid)
        {
            DataTable sampleData = new DataTable();
            sampleData.Locale = CultureInfo.InvariantCulture;

            sampleData.Columns.Add("Site");
            sampleData.Columns.Add("URL");
            sampleData.Columns.Add("Notes");

            sampleData.Rows.Add(
                new object[]
                {
                    "Microsoft",
                    "http://www.microsoft.com",
                    "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                        + "Morbi at sem lorem, ac blandit leo. Phasellus at"
                        + "ligula vitae enim dignissim tincidunt ornare nisl."
                });

            sampleData.Rows.Add(
                new object[]
                {
                    "MSDN",
                    "http://msdn.microsoft.com",
                    "Sed posuere mattis egestas. Aliquam commodo dolor"
                        + " vulputate odio lacinia bibendum. Nullam bibendum,"
                        + " neque vitae ullamcorper elementum, ligula dolor"
                        + " mollis erat, ut ultricies mauris tortor ut eros."
                });

            sampleData.Rows.Add(
                new object[]
                {
                    "TechNet",
                    "http://technet.microsoft.com",
                    "Vestibulum a leo nisl, sit amet porta eros. Proin vitae"
                        + " semper nunc. In facilisis nunc sit amet lacus"
                        + " accumsan mattis. Nulla facilisi. Pellentesque nisl"
                        + " sapien, dignissim ultrices semper et, mollis"
                        + " interdum sem. "
                });
            
            grid.DataSource = sampleData;
            grid.DataBind();
        }

        #endregion

        protected void ConstrainedGrid_RowDataBound(
            object sender,
            GridViewRowEventArgs e)
        {
            foreach (TableCell cell in e.Row.Cells)
            {
                // Note: We need to decode the cell text in order to avoid
                // having it encoded twice (e.g. "&amp;gt;")
                cell.ToolTip = HttpUtility.HtmlDecode(cell.Text);
            }
        }
    }
}

Recommendations for Code Analysis

2009-10-31T13:44:00Z

In my previous post, I briefly mentioned the Code Analysis feature of Visual Studio in the context of using check-in policies with Team Foundation Server (TFS). However, there's a lot more to talk about with regards to using Code Analysis.

If you are ever find yourself "starting from a clean slate" on a software development project, I hope you take advantage of the opportunity to not only enable Code Analysis, but also to treat all Code Analysis warnings as errors. That's right, go ahead and check all of those boxes (for both Debug and Release configurations, of course) so that whenever potential issues are reported by Code Analysis, it stops developers dead in their tracks and considers the build to be broken.

While you're at it, go ahead and select the All option in the Treat warnings as errors section on the Build tab (something I definitely recommend as a best practice). Again, be sure to do this for all build configurations.

Yes, this is going to be really painful for some developers.

For example, you can say goodbye to using the overload of string.Format() that doesn't specify a CultureInfo:

            string foo = "here";

            string logMessage = string.Format(
                "Imagine something interesting {0}.",
                foo);

Attempting this will now result in a broken build:

Error 2 CA1305 : Microsoft.Globalization : Because the behavior of 'string.Format(string, object)' could vary based on the current user's locale settings, replace this call in 'Program.Main(string[])' with a call to 'string.Format(IFormatProvider, string, params object[])'. If the result of 'string.Format(IFormatProvider, string, params object[])' will be displayed to the user, specify 'CultureInfo.CurrentCulture' as the 'IFormatProvider' parameter. Otherwise, if the result will be stored and accessed by software, such as when it is persisted to disk or to a database, specify 'CultureInfo.InvariantCulture'.

To avoid the CA1305 error, you will need to use something like this instead:

            string foo = "here";

            string logMessage = string.Format(
                CultureInfo.InvariantCulture,
                "Imagine something interesting {0}.",
                foo);

You will also need to enable signing of all assemblies with a strong name key, and also specify various assembly level attributes (e.g. [assembly: CLSCompliant(true)]). However, if you follow the steps I've provided in a previous post, this should only take you at most 1-2 minutes.

Like I said before, this will probably cause some heartburn in the beginning, but trust me, developers will quickly get used to it and the code they write will be much better as a result.

Now what about the other 99% of the time when you aren't starting from a clean slate, but instead are dealing with a substantial code base that causes the Code Analysis feature in Visual Studio to "light up like a Christmas tree" when you turn it on?

Well, as with all software bugs, it all comes down to triage. You obviously cannot simply halt all feature development in order to resolve code analysis issues. Instead, you should go for the "low hanging fruit" (meaning the issues that occur frequently but can be resolved with relatively little effort or risk of changing). You should also try to enable the Code Analysis rules that are most important, such as potential security issues.

The following post provides some great information about which Code Analysis warnings to focus your attention on first:

What rules do Microsoft have turned on internally? 2007-08-09.

http://blogs.msdn.com/fxcop/archive/2007/08/09/what-rules-do-microsoft-have-turned-on-internally.aspx

This article is obviously a little dated, but still very relevant over two years later.

Note that you will undoubtedly need to suppress some specific Code Analysis warnings from time to time, and therefore you'll have to choose how to suppress the warnings (whether inline within the source, or in a GlobalSuppressions.cs file). However, I hope you'll choose to fix the underlying issue that causes the Code Analysis warning (whenever practical) instead of simply suppressing a bunch of warnings.

So, in conclusion, think of the Code Analysis feature in Visual Studio as a way of choosing a more strict compiler. For example, back in the days when I used to program in C on Unix, the compiler wouldn't complain when I wrote something like this (even though this is obviously very wrong):

I was relieved when I switched to C++ and these kinds of bugs were a thing of the past. [Note that I never switch my coding style to use something like "1 == i" in order to avoid these errors.]

Fortunately, in C# you don't have a choice about whether or not this compiles (it doesn't).

I like to think of enabling all of the Code Analysis rules in a similar fashion. In other words, I want the compiler to tell me whenever I am doing something potentially wrong, because then I can spend just a little bit of time fixing my code to do it right. By forcing the Code Analysis warnings as errors, I don't have a choice -- meaning I have to fix them before check-in.

Recommended Check-In Policies for Team Foundation Server

2009-10-31T12:14:00Z

I love using Team Foundation Server (TFS). There's just an amazing amount of "goodness" for software development that comes out-of-the-box; and there's even more available from Microsoft and other sources in the form of add-ons (many of which are free).

From a source control perspective, one of my favorite features is check-in policies. Anything that improves the quality of software development with minimal effort is really a "no-brainer" in my opinion.

The check-in policies that I prefer to have configured on all TFS projects are listed in the following table.

Recommended TFS Check-In Policies
Policy Type	Description
Builds	This policy requires that any code changes have been compiled and the last build was successful.
Work Items	This policy requires that one or more work items be associated with every check-in.
Changeset Comments Policy	Reminds users to add meaningful comments to their check-ins.
Code Analysis	This policy requires that Code Analysis is run with a defined set of rules before check-in.
Testing Policy	Ensures that tests from specific test lists are successfully executed before checking in.

The first two check-in policies are virtually painless and can be applied to any existing project at any time. These policies ship with Visual Studio Team System 2008, and assuming your developers have good software development discipline already, there's absolutely no reason not to enable these policies.

After all, why would any developer want to check-in code that hasn't been verified to at least compile? Similarly, why would a developer make a code change that isn't specifically related to a work item (even if that work item is simply something like "Refactor X" or "Code cleanup (M5)")?

However, the last three policies in the table above require a little more effort.

The Changeset Comments Policy is included in the Team Foundation Server Power Tools, which means that every member of the Development team will need to download and install this in order to use it. (Note that if you don't have the Power Tools installed, you can still override the check-in policy in order to avoid being blocked.)

The Code Analysis policy can definitely cause a little heartburn for your Development team, depending on how many code analysis rules you enable and whether or not you treat these warnings as errors. I'll talk more about Code Analysis in a separate post.

The Testing Policy is not one that I consider essential for all projects. For projects in which you have a good set of Build Verification Tests (BVTs) that give you a signficant amount of code coverage and don't take very long to execute, then enabling this policy just makes sense. However, keep in mind that you should definitely be running BVTs as part of your automated build, so if these tests require a substantial amount of time to execute (for example, they require signficant setup or teardown), then forcing developers to run these tests before every check-in could definitely impede their productivity.

Of course, you can always separate your tests into "quick tests" and "long running tests" like I've mentioned in a previous post, and consequently only require the "quick tests" to be executed before check-in.

If you are fortunate enough to be using TFS on your project, I hope you are reaping the benefits of check-in policies.

Latest Version of Opera Ignores Hosts File

2009-10-29T13:17:00Z

As I mentioned in my previous post, I discovered a rather nasty UI bug last week with the new portal we are building for a customer. Unfortunately, the layout issue only occurred in the Safari browser.

Since I couldn't repro the issue in Internet Explorer or Firefox, I decided to see if Opera exhibited the same problem as Safari. Consequently, I downloaded and installed the latest version of Opera (note that I've rebuilt both my desktop and development VM since the last time I used Opera).

Unfortunately. I discovered there's a known bug with Opera version 10 that causes it to ignore your local hosts file (e.g. %SystemRoot%\drivers\etc\hosts).

Oh c'mon, Opera Team, you've got to be kidding!

How can you expect a developer to even try your browser if he can't browse to a site in his local development environment using a fully qualified domain name (e.g. http://www-local.fabrikam.com)?

Needless to say, I didn't spend much time trying to workaround the issue. My prediction: Opera is all but extinct in another year or two.

That's too bad. From what I remember, Opera used to be a pretty good browser -- and maybe it still is, aside from the bug with the hosts file. It was certainly years ahead of IE6 in terms of Web standards compliance.

Does anyone know the current browser stats? It wouldn't surprise me if Opera was surpassed by Safari some time ago.

Troubleshooting Layout Problems with Safari

2009-10-29T12:57:00Z

I discovered a rather nasty UI bug last week with the new portal we are building for a customer. Unfortunately, the layout issue only occurred in the Safari browser. Even worse, I discovered it only a day before the CEO of customer discovered it himself on his Mac! Ouch.

Note that I typically test Web sites using Internet Explorer and Firefox. In fact, that's what our statement of work contractually obligates for this project (and not IE6, thankfully, but rather IE7 and IE8).

I've occasionally tested with Opera and Safari in the past, but in general I've found this to be unnecessary because most of these browsers have strong support for modern Web standards.

However, this week I discovered that a page that looks good in Internet Explorer and Firefox doesn't necessarily look good in Safari.

Since I didn't have access to my faithful Firebug or Internet Explorer Developer Tools, I was initially stumped on troubleshooting the problem. However, a little bit of searching uncovered the following gem:

Firebug For Safari

http://vision-media.ca/resources/misc/firefox-for-safari

Unlike many of the other search results that I looked at, this one doesn't actually discuss using Firebug in Safari (which I was reluctant to try because, from what I read, all of the CSS rules are read-only when you use Firebug with Safari). Rather, this page shows the similar set of tools that Apple provides with their browser. It also shows how to easily enable the Safari developer tools without hacking a preferences file (which I initially tried locating on my Windows VM using instructions based on a Mac, but I quickly gave up on that effort).

After spending about 45 minutes with the Safari developer tools, I was finally able to track down the float CSS rule that was causing my Login Form Web Part to be displayed behind the <h1> heading for the main content of the page in Safari.

A few minutes later and I had my fix checked-in to TFS. Whew!

DataNavigateUrlFormatString Does Not Allow "javascript:"

2009-10-26T14:49:00Z

I encountered an interesting bug last Friday with the ASP.NET HyperLinkField control. To understand the scenario, think of the typical "view detail" feature when showing summary data in a table. In other words, you want to provide users the ability to click a cell in a table (e.g. a GridView control) in order to see more information.

I've implemented this scenario before, so I was a stumped when I couldn't get it to work right away. However, this time the scenario was a little different because we want to display a popup window to an external site. Also note that several visual properties of the popup window need to be specified for our application -- such as the width and height of the window, as well as hiding the menu bar, status bar, etc.

In other words, we need the links in the table to actually call a JavaScript function instead of specifying a simple URL.

My initial attempt was to specify something like :

<asp:GridView ID="summaryGrid" runat="server"
    AutoGenerateColumns="False"
    ...>
    ...
    <Columns>        
        <asp:HyperLinkField DataNavigateUrlFields="Id"
           DataNavigateUrlFormatString="javascript:ShowItemDetail({0})"
           DataTextField="CreateTime"
           DataTextFormatString="{0:ddd MMM dd HH:mm}"
           HeaderStyle-CssClass="dateColumn"
           HeaderText="Date" />  
       ...
    </Columns>
</asp:GridView>

Note that ShowItemDetail is a JavaScript function that simply calls window.open (specifying the URL as well as additional "feature" parameters such as the window width and height).

Unfortunately, if you specify something like "javascript:ShowItemDetail({0});" in DataNavigateUrlFormatString, you will find that ASP.NET renders an anchor element with no href attribute (e.g. <a>Mon Oct 26 08:23</a>) -- which obviously doesn't work. This appears to be "by design" -- in order to "mitigate against cross-site scripting attacks."

Refer to the following for more detail:

asp:GridView does not render HyperLinkField when a colon (:) is included in the DataNavigateUrlFormatString. 2007-06-05.

https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=102300

To workaround this, use a TemplateField instead:

<asp:GridView ID="summaryGrid" runat="server"
    AutoGenerateColumns="False"
    ...>
    ...
    <Columns>
        <%-- HACK: Ideally, we would just use an asp:HyperLinkField,
        but there's a bug when specifying "javascript:" in the
        DataNavigateUrlFormatString:

        https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=102300

        As a workaround, use a TemplateField instead. --%>
        <asp:TemplateField>
           <HeaderTemplate>Date</HeaderTemplate>
           <HeaderStyle CssClass="dateColumn" />
           <ItemTemplate>
               <a href='javascript:ShowItemDetail(<%# Eval("Id")%>)'>
                   <%# Eval("CreateTime", "{0:ddd MMM dd HH:mm}") %>
               </a>
           </ItemTemplate>
        </asp:TemplateField>
        ...
    </Columns>
</asp:GridView>

Or, if you are really paranoid about the performance impact of using reflection in the DataBinder.Eval method, you can use strongly typed objects instead:

<asp:GridView ID="summaryGrid" runat="server"
   AutoGenerateColumns="False"
   ...>
   ...
   <Columns>
      <%-- HACK: Ideally, we would just use an asp:HyperLinkField,
      but there's a bug when specifying "javascript:" in the
      DataNavigateUrlFormatString:
        
      https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=102300
        
      As a workaround, use a TemplateField instead.
      --%>
      <asp:TemplateField>
         <HeaderTemplate>Date</HeaderTemplate>
         <HeaderStyle CssClass="dateColumn" />
         <ItemTemplate>
             <a href='javascript:ShowItemDetail(<%# ((Fabrikam.Demo.Integration.Incident)Container.DataItem).Id %>)'>
                 <%# ((Fabrikam.Demo.Integration.Incident)Container.DataItem).CreateTime.ToString("ddd MMM dd HH:mm") %>
             </a>
         </ItemTemplate>
      </asp:TemplateField>
      ...
   </Columns>
</asp:GridView>

Of course, if you choose to go the strongly-typed route, you will need to reference the assembly containing your custom business objects. For example:

<%@ Assembly Name="Fabrikam.Demo.Integration, Version=1.0.0.0, Culture=neutral, PublicKeyToken=786f58ca4a6e3f60" %>

Essential Add-Ins for Team Foundation Server

2009-10-25T15:32:00Z

In a previous post, I mentioned how I use SourceGear's DiffMerge instead of the out-of-the-box tool that comes with Team Foundation Server (which is also called DiffMerge). If you haven't at least evaluated the SourceGear alternative, I definitely advise you to take a look.

The other "add-in" for TFS that I consider to be essential is the TFS Quick Search Plugin.

If you have Web access to your TFS instance (via Team System Web Access), then quickly locating work items by keywords is actually pretty easy. However if you either don't have access to Team System Web Access or you would simply rather prefer to search for a work item without leaving Visual Studio, then the TFS Quick Search Plugin is definitely the way to go.

Note that it doesn't search all of the fields in all work items, but rather searches the work items currently displayed within Visual Studio. However, if you know a keyword that appears in the title of a work item, this can make it very easy to locate the desired work item.

I tend to use the TFS Quick Search Plugin a lot for the scenario where I am trying to find a duplicate bug and I remember a couple of keywords in the title of the previous bug. It is certainly much faster than scrolling through a few hundred work items in order to find something, or trying to build a query on-the-fly in order to locate a work item.

I am really interested to see the improvements in Visual Studio 2010 and Team Foundation Server 2010, but honestly it's probably going to be a while before I'm able to use that in my day-to-day work. Nevertheless, I hope this kind of work item "quick search" comes out-of-the-box in the next release (as well as a better DiffMerge tool). [I did do some hands-on labs back in February that cover the new branching visualization features in TFS 2010, and I have to say that I absolutely love what I've seen so far.]

Is AutoCorrect making me stupid or just plain lazy?

2009-10-25T15:03:00Z

Yesterday's post got me thinking about something.

Do you find yourself occasionally typing one word when you are actually thinking of a different word that sounds the same? A faint recollection from one or more of my English classes long ago suggested that these words are called homonyms. However, a quick search just now on Wikipedia indicates these are actually homophones.

For example, have you ever typed the word "do" when you meant "due", or similarly "overdo" when you meant "overdue"? Surely you know the difference between the two, yet somehow in the time that it takes your fingers to turn your thoughts into characters, then words, and eventually sentences on the screen, something goes terribly wrong.

I honestly can't ever remember doing this as child, although it undoubtedly happened more than a few times as my vocabulary grew at a faster pace than my ability to spell. I definitely don't remember it happening in high school or college. This made me wonder if this infliction is somehow related to typing -- or more specifically, my typing speed (which has vastly increased since my college days). This got me thinking that perhaps it's not actually related to my skills as a typist, but somehow related to the fact many of the applications I use on a daily basis have some sort of "auto-correct" feature.

Consider the AutoCorrect feature in Microsoft Word -- and Outlook -- as an example. I have to wonder if the fact that this has been fixing my typing and spelling errors for almost fifteen years has somehow made me just a little too dependent on this feature. I can honestly say that I don't do as much proofreading today as I used to a few years ago, and this really isn't a good thing.

It's probably overkill to proofread every single e-mail message before sending it out, but at the same time, isn't it embarrassing to send a message that uses the word "to" when it should be "too"?

Of course, I'm not saying that these errors are the fault of software features like AutoCorrect. Surely I'm the one that bears ultimate responsibility for the words I write. Perhaps I just need to consider disabling the AutoCorrect feature in Word and Outlook for a while -- or better yet, maybe I should look for an old IBM Selectric on ebay and subject myself to some exercises on that for a little while. Without a doubt, a few dozen pages on that -- and a couple of bottles of Liquid Paper, of course -- would cure whatever ailment I seem to have contracted in the last few years.

The Original "Jameson Datacenter"

2009-10-24T13:18:00Z

This morning I was doing some cleanup of my documents folder and I stumbled across a rather old Visio document that showed the beginnings of what I now refer to as the "Jameson Datacenter" (a.k.a. my home lab). For some geeky reason, seeing this again brought a smile to my face and a sense of nostalgia. It also caused me to recall two things:

That old Greatful Dead song "Truckin'" -- specifically the line

Lately it occurs to me: What a long, strange trip it's been.

Update

Doh! You would think a guy with a Master of Science degree in Mechanical Engineering could spell "Grateful Dead" correctly! I suppose that I really should do more proofreading before clicking that Publish button ;-)
An article I read about a year ago describing the origin of Google that also included some photos of the original Google infrastructure in the Stanford University computer lab.

Now, please don't misunderstand -- I most certainly am not claiming that the Jameson Datacenter will ever amount to even the most miniscule fraction of what Google grew into in less than a decade. All I'm saying is that in the incredible way the neurons are wired together in the human brain, things that we see very often trigger distant memories with amazing clarity.

For those of you that may not have seen the original Google server farm, I did a quick search this morning and managed to find the following:

Google Stanford Hardware

http://geektechnique.org/media/google/googlehardware.html

If you haven't seen this, take a quick peek. It will surely bring a smile -- if not a burst of laughter.

After enjoying the nostalgia for a moment, I almost deleted the Visio diagram and continued my cleanup effort. However, then I decided that I might as well "archive" this on my blog. It definitely won't help your efforts of deploying Microsoft technology, but I think it's okay for a blog to wander a little every now and then -- perhaps for no other reason than to keep you guessing as to what may come next on the Random Musings of Jeremy Jameson.

Here's the physical architecture of what I now refer to as the "Old Jameson Datacenter":

Figure 1: Old Jameson Datacenter - Physical Architecture

See full-sized image.

Apparently the last time I updated this Visio diagram, I still hadn't decided what to do with all of the Dell servers I had procured through various channels (primarily the Dell Outlet and ebay). Hence the Dell PowerEdge 4300 with the "??" next to it. As I mentioned in my original post on the Jameson Datacenter, this server was the original BEAST (which is now my "Production" database server). However, it has since been replaced with a home-built server.

From the previous figure, you can start to see why I've consolidated these servers in recent years by leveraging virtualization. The power consumption by all of these servers was really rather ridiculous when you consider what I was using these servers for.

Notice that I use to run a back-to-back firewall configuration with a perimeter network (a.k.a. DMZ):

Figure 2: Old Jameson Datacenter - TCP/IP Configuration

See full-sized image.

This is because I had one server with a public (static) IP address and therefore ran a couple of Web sites on the old "ICEMAN" server -- hence the name "ICEMAN", because it was my "IIS" server. Get it? Yeah, I know...more geekiness.

The naming convention was such that the names corresponding to X-Men heroes were all members of the TECHTOOLBOX domain, whereas servers corresponding to X-Men villains were considered "dangerous" and thus not members of the domain. Egad! Does the geekness ever end?! [I wonder if someday when my daughter is much older, she'll ever bother to read this and seriously start to question her father's sanity.]

Anyway, here's the DNS and DHCP configuration for the original farm:

Figure 1: Old Jameson Datacenter - DNS/DHCP Configuration

See full-sized image.

There's nothing really too interesting about that, I suppose.

Perhaps the most laughable aspect of the Old Jameson Datacenter -- at least when compared to today -- was the storage infrastructure:

Figure 1: Old Jameson Datacenter - Disk Configuration

See full-sized image.

I can still remember when I thought the 18 GB of RAID1 and 72 GB of RAID5 on that Dell 4300 was fashizzle ;-) [Of course, that was long before I was even aware of the term "fashizzle", but you get my point.]

Anyway, I hope you enjoyed this brief diversion down Memory Lane. Perhaps it invoked some distant memories of your own experiences in the world of technology.

Personally, as I'm wrapping up this post, my head is spinning with thoughts of my father's original Apple II+ (which was the first computer I ever "programmed" on) as well as my very own Commodore 64 and all those late nights my dear friend Chris Gatewood and I sat in front of it typing in hundreds of lines of code from a magazine just so we could try to play some silly game based on "sprites." [Note that the games almost never worked due to some error or another, but nevertheless we kept trying anyway.]

Configure IntelliMirror Using Group Policy

2009-10-21T12:57:00Z

Yet another Group Policy object that I use in the "Jameson Datacenter" (a.k.a. my home lab) is one to automatically configure roaming profiles and redirect the Desktop and Documents folders to a server(a.k.a. "IntelliMirror").

Even though I don't have many users in my Active Directory domain -- it's not like I have eight kids, just one -- I still want to keep user data centrally managed on a server that I backup regularly. Besides, I find it really frustrating to have some items on your desktop on one computer, but a different set of desktop items on another computer (or VM).

To automatically configure this in the "Jameson Datacenter", I defined a Group Policy (named Default User Data and Settings Policy) with the following settings:

User Configuration
- Policies
  - Windows Settings
    - Folder Redirection
      - AppData(Roaming)
        
        Setting: Basic (Redirect everyone's folder to the same location)
        
        Path: \\beast\Users$\%USERNAME%\Application Data
        
        Options
        
        Grant user exclusive rights to AppData(Roaming): Enabled
        
        Move the contents of AppData(Roaming) to the new location: Enabled
        
        Also apply redirection policy to Windows 2000, Windows 2000 server, Windows XP, and Windows Server 2003 operating systems: Enabled
        
        Policy Removal Behavior: Leave contents
      - Desktop
        
        Setting: Basic (Redirect everyone's folder to the same location)
        
        Path: \\beast\Users$\%USERNAME%\Desktop
        
        Options
        
        Grant user exclusive rights to Desktop: Enabled
        
        Move the contents of Desktop to the new location: Enabled
        
        Also apply redirection policy to Windows 2000, Windows 2000 server, Windows XP, and Windows Server 2003 operating systems: Enabled
        
        Policy Removal Behavior: Leave contents
      - Documents
        
        Setting: Basic (Redirect everyone's folder to the same location)
        
        Path: \\beast\Users$\%USERNAME%\Documents
        
        Options
        
        Grant user exclusive rights to Documents: Enabled
        
        Move the contents of Documentsto the new location: Enabled
        
        Also apply redirection policy to Windows 2000, Windows 2000 server, Windows XP, and Windows Server 2003 operating systems: Enabled
        
        Policy Removal Behavior: Leave contents
      - Music
        
        Setting: Follow the Documents folder
      - Pictures
        
        Setting: Follow the Documents folder
      - Videos
        
        Setting: Follow the Documents folder

Note

Those of you that have a very keen eye (and also a photographic memory) might recall that in a previous post, I listed BEAST as a database server (it is currently running SQL Server 2005). Yes, it's true, I'm breaking one of my own cardinal sins by having a SQL Server also serve as a file server. I don't recommend doing this unless, like me, you are trying to go as cheap as possible -- and, even then, only for a lab environment like mine.

In order to allow users access to create their own folders on \\BEAST\Users$, I have configured the following permissions on C:\BackedUp\Users:

Domain Users
- Apply onto: This folder only
- Permissions
  - List Folder / Read Data
  - Create Folders / Append Data
CREATOR OWNER
- Apply onto: Subfolders and files only
- Permissions
  - Full Control

I also created a hidden share for the C:\BackedUp\Users folder and granted Full Control to Authenticated Users (since the NTFS permissions above ultimately determine the level of access for all users).

Thus when a new user logs in for the first time, a corresponding folder is created on the server and all of the user's files are stored on the server.

Eliminate MBSA Warnings Using Default Security Settings Policy

2009-10-21T11:57:00Z

Another Group Policy object that I use in the "Jameson Datacenter" (a.k.a. my home lab) is one that I created a couple of years ago in order to eliminate various warnings from the Microsoft Baseline Security Advisor (MBSA).

To automatically change the default security settings in the "Jameson Datacenter", I defined a Group Policy (named Default Security Settings Policy) with the following settings:

Computer Configuration
- Policies
  - Windows Settings
    - Security Settings
      - Account Policies
        
        Password Policy
        
        Maximum password age: 60 days
        
        Minimum password age: 1 day
        
        Minimum password length: 8 characters
      - Local Policies
        
        Security Options
        
        Network security: LAN Manager authentication level: Send NTLMv2 response only. Refuse LM & NTLM
      - System Services
        
        TlntSvr
        
        Startup Mode: Disabled

I don't know about you, but I haven't used Telnet in almost fifteen years -- back when I used to work on Unix systems ;-)

This Group Policy is linked it to the entire domain (i.e. corp.technologytoolbox.com).

Note that I still use the Default Domain Controllers Policy to configure the security settings on the domain controllers (and thus domain accounts). In other words, the settings noted above only affect local accounts (e.g. COLOSSUS\Administrator, not TECHTOOLBOX\jjameson).

New MSDN Theme on My Blog

2009-10-21T11:12:00Z

I noticed this morning that the new color scheme released this past week on MSDN has made its way into our Community Server template (and thus onto my blog, since I'm currently using the default "skin").

I'm still not sure how I feel about the combination of purple ( #36295E ) and this particular shade of blue ( #4EA5D2 ). I certainly like each color by itself, it's just that when you put the two together, my stomach starts to feel a little queasy. Oh well, I'm sure I'll get used to it.

Personally, I would have chosen one of the other color schemes proposed for the overhaul of MSDN. Nevertheless, this is what the Visual Studio marketing team has chosen for their two primary colors for the 2010 release, so -- like I said before -- I'll get used to it.

In the meantime, I've updated some of my custom style elements to match the new color scheme.

Add Rooler to Your Web Development Toolbox

2009-10-21T10:19:00Z

This past May, one of my colleagues notified me of a new tool called "Rooler" that allows you to easily measure anything displayed on your screen.

I definitely consider this tool a "must have" for anyone out there doing Web development. While tools like Firebug and the new developer tools in Internet Explorer 8 are great for analyzing the layout of Web pages, I often find myself using Rooler when tweaking CSS rules in order to achieve that "pixel perfect" design. For example, yesterday I was working on styling the new customer service portal that I'm working on and I wanted to match the customer's current .com site. Rooler enabled me to identify the dimensions of the header and margins of various elements with almost no effort whatsoever.

If you haven't already discovered Rooler, I strongly recommend you download it today.

Introducing the SharePointSmtpHelper Class

2009-10-18T14:29:00Z

Continuing in the spirit of my previous posts for the SharePointPublishingHelper class and SharePointWebPartHelper class, I'd like to introduce another helper class that you may find useful when building solutions for Windows SharePoint Services (WSS) v3 and Microsoft Office SharePoint Server (MOSS) 2007.

Consider the scenario where you need to send an e-mail message from a SharePoint application. Perhaps an unexpected error occurred and you want to notify the operations team, or perhaps you just want to send a confirmation message to a user who has just submitted some important information.

Whatever the case, you'd like to send an e-mail message using the SMTP server configured in SharePoint Central Administration for the farm. SharePointSmtpHelper makes it really easy to do this.

Note that there's really not much code to the SharePointSmtpHelper class -- thanks to the classes provided by the .NET Framework in the System.Net.Mail namespace. It may look like more code than you might expect, but that's just because of all the overloads of the SendMessage method that I provide.

using System;
using System.Net.Mail;

using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

namespace Fabrikam.Demo.CoreServices.SharePoint
{
    /// <summary>
    /// Exposes static methods for sending e-mail messages from a SharePoint
    /// Web application using the Simple Mail Transfer Protocol (SMTP). The
    /// SMTP server must be configured in SharePoint Central Administration.
    /// This class cannot be inherited.
    /// </summary>
    /// <remarks>
    /// All methods of the <b>SharePointSmtpHelper</b> class are static and
    /// can therefore be called without creating an instance of the class.
    /// </remarks>
    public sealed class SharePointSmtpHelper
    {
        private static object lockObject = new object();

        private static string smtpServer;
        private static string defaultFromAddress;
        
        private SharePointSmtpHelper( ) { } // all members are static

        /// <summary>
        /// Sends an e-mail message using the outbound SMTP server and
        /// "From address" configured in SharePoint Central Administration.
        /// </summary>
        /// <param name="toRecipients">The recipients of the e-mail message.
        /// In other words, the addresses on the To line of the e-mail.</param>
        /// <param name="subject">The subject line for the e-mail message.
        /// </param>
        /// <param name="body">The e-mail message body.</param>
        public static void SendMessage(
            string toRecipients,
            string subject,
            string body)
        {
            SendMessage(
                toRecipients,
                subject,
                body,
                false,
                null,
                null);
        }

        /// <summary>
        /// Sends an e-mail message using the outbound SMTP server and
        /// "From address" configured in SharePoint Central Administration,
        /// specifying whether the body of the message is formatted using HTML.
        /// </summary>
        /// <param name="toRecipients">The recipients of the e-mail message.
        /// In other words, the addresses on the To line of the e-mail.</param>
        /// <param name="subject">The subject line for the e-mail message.
        /// </param>
        /// <param name="body">The e-mail message body.</param>
        /// <param name="isBodyHtml"><c>true</c> if the mail message body is
        /// formatted using HTML markup. <c>false</c> if the message is simply
        /// plain text.</param>
        public static void SendMessage(
            string toRecipients,
            string subject,
            string body,
            bool isBodyHtml)
        {
            SendMessage(
                toRecipients,
                subject,
                body,
                isBodyHtml,
                null,
                null);
        }

        /// <summary>
        /// Sends an e-mail message using the outbound SMTP server and
        /// "From address" configured in SharePoint Central Administration,
        /// specifying whether the body of the message is formatted using HTML
        /// and also including carbon copy (CC) recipients.
        /// </summary>
        /// <param name="toRecipients">The recipients of the e-mail message.
        /// In other words, the addresses on the To line of the e-mail.</param>
        /// <param name="subject">The subject line for the e-mail message.
        /// </param>
        /// <param name="body">The e-mail message body.</param>        
        /// <param name="isBodyHtml"><c>true</c> if the mail message body is
        /// formatted using HTML markup. <c>false</c> if the message is simply
        /// plain text.</param>
        /// <param name="ccRecipients">The carbon copy (CC) recipients of the
        /// e-mail message.</param>
        public static void SendMessage(
            string toRecipients,
            string subject,
            string body,
            bool isBodyHtml,
            string ccRecipients)
        {
            SendMessage(
                toRecipients,
                subject,
                body,
                isBodyHtml,
                ccRecipients,
                null);
        }

        /// <summary>
        /// Sends an e-mail message using the outbound SMTP server configured
        /// in SharePoint Central Administration for the farm.
        /// </summary>
        /// <param name="toRecipients">The recipients of the e-mail message.
        /// In other words, the addresses on the To line of the e-mail.</param>
        /// <param name="subject">The subject line for the e-mail message.
        /// </param>
        /// <param name="body">The e-mail message body.</param>        
        /// <param name="isBodyHtml"><c>true</c> if the mail message body is
        /// formatted using HTML markup. <c>false</c> if the message is simply
        /// plain text.</param>
        /// <param name="ccRecipients">The carbon copy (CC) recipients of the
        /// e-mail message.</param>
        /// <param name="from">The e-mail address of the sender.</param>
        public static void SendMessage(
            string toRecipients,
            string subject,
            string body,
            bool isBodyHtml,
            string ccRecipients,
            string from)
        {
            if (string.IsNullOrEmpty(toRecipients) == true)
            {
                throw new ArgumentNullException("toRecipients");
            }

            toRecipients = toRecipients.Trim();
            if (string.IsNullOrEmpty(toRecipients) == true)
            {
                throw new ArgumentException(
                    "In order to send an e-mail message, "
                        + " at least one recipient must be specified.",
                    "toRecipients");
            }

            if (string.IsNullOrEmpty(subject) == true)
            {
                throw new ArgumentNullException("subject");
            }

            subject = subject.Trim();
            if (string.IsNullOrEmpty(subject) == true)
            {
                throw new ArgumentException(
                    "In order to send an e-mail message, "
                        + " the subject must be specified.",
                    "subject");
            }

            if (string.IsNullOrEmpty(body) == true)
            {
                throw new ArgumentNullException("body");
            }

            body = body.Trim();
            if (string.IsNullOrEmpty(body) == true)
            {
                throw new ArgumentException(
                    "In order to send an e-mail message, "
                        + " the message body must be specified.",
                    "body");
            }

            EnsureSmtpSettings();

            // If the "from" address is not specified, default to the address
            // configured in SharePoint Central Administration.
            if (string.IsNullOrEmpty(from) == true)
            {
                from = defaultFromAddress;
            }

            SmtpClient smtpClient = new SmtpClient(smtpServer);

            MailMessage message = new MailMessage(
                from,
                toRecipients,
                subject,
                body);

            message.IsBodyHtml = isBodyHtml;

            if (string.IsNullOrEmpty(ccRecipients) == false)
            {
                message.CC.Add(ccRecipients);
            }

            smtpClient.Send(message);
        }

        private static void EnsureSmtpSettings()
        {
            if (string.IsNullOrEmpty(smtpServer) == true)
            {
                if (SPContext.Current == null)
                {
                    throw new InvalidOperationException(
                        "SharePointSmtpClient can only be called from within"
                            + " a SharePoint site (SPContext.Current is null).");
                }

                lock (lockObject)
                {
                    if (string.IsNullOrEmpty(smtpServer) == true)
                    {
                        SPWebApplication webApp =
                            SPContext.Current.Site.WebApplication;

                        if (webApp.OutboundMailServiceInstance != null
                            && webApp.OutboundMailServiceInstance.Server != null)
                        {
                            smtpServer =
                                webApp.OutboundMailServiceInstance.Server.Address;
                        }

                        if (string.IsNullOrEmpty(smtpServer) == true)                            
                        {
                            throw new InvalidOperationException(
                                "The outbound SMTP server is not specified in"
                                + " SharePoint Central Administration.");
                        }

                        defaultFromAddress = webApp.OutboundMailSenderAddress;
                    }
                }
            }
        }
    }
}

Note that I use static members in order to only read the SMTP server configuration from SharePoint Central Administration one time.

Assuming you just want to send a simple message using the default "From address" specified in SharePoint Central Administration, you only need a single line of code that passes three parameters:

            SharePointSmtpHelper.SendMessage(
                "jeremy_jameson@fabrikam.com",
                "Test message",
                "Testing the SharePointSmtpHelper class");

Introducing the SharePointWebPartHelper Class

2009-10-17T12:54:00Z

In a previous post, I introduced the DR.DADA approach to SharePoint development and how I typically use the concept of a FeatureConfigurator to automatically configure one or more aspects of a SharePoint site when activating my feature.

For example, on my latest project, we needed a login page as well as a legal disclaimer page for a customer service portal based on Microsoft Office SharePoint Server (MOSS) 2007. Thus I created a "PublicSiteConfiguration" feature that, upon activation:

Automatically creates the /Public site
Populates the page content on the /Public/Pages/default.aspx page and adds an instance of a custom Login Form Web Part to the page
Creates the /Public/Pages/Disclaimer.aspx page and populates its default content

I've already introduced the SharePointPublishingHelper class that performs the bulk of the work in creating and configuring publishing pages. In this post, I want to cover the SharePointWebPartHelper class. Like the SharePointPublishingHelper class, the SharePointWebPartHelper class is simply a collection of helper methods for the SharePoint API.

SharePointWebPartHelper makes it really easy to:

Attempt to retrieve a reference to a Web Part by specifying an SPLimitedWebPartManager for a specific page and the title of the Web Part you are trying to find
Ensure a Web Part exists on a page (creating a new Web Part as necessary)
Ensuring a ContentEditorWebPart exists on a page and that it is configured with the specified HTML content and title (as well as removing the "chrome", since -- at least in my experience -- you don't want to show this to users for this type of Web Part)

Note that one could argue that the stuff specific to the Content Editor Web Part doesn't really belong in this class, but nevertheless that's where it ended up after refactoring the code a few years ago on the Agilent Technologies project. [Actually, I believe it originally ended up in an even more generic SharePointHelper class, but I've since refactored it even further into the SharePointWebPartHelper class.]

Anyway, here's the code for the SharePointWebPartHelper class:

using System;
using System.Diagnostics;
using System.Globalization;
using System.IO;
using System.Security.Permissions;
using System.Web.UI.WebControls.WebParts;
using System.Xml;

using Microsoft.SharePoint;
using Microsoft.SharePoint.Security;
using SPWebPartPages = Microsoft.SharePoint.WebPartPages;

using Fabrikam.Demo.CoreServices.Logging;

namespace Fabrikam.Demo.CoreServices.SharePoint
{
    /// <summary>
    /// Exposes static methods for commonly used helper functions for
    /// SharePoint Web Parts. This class cannot be inherited.
    /// </summary>
    /// <remarks>
    /// All methods of the <b>SharePointWebPartHelper</b> class are static and
    /// can therefore be called without creating an instance of the class.
    /// </remarks>
    [CLSCompliant(false)]
    [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]
    public sealed class SharePointWebPartHelper
    {
        private SharePointWebPartHelper() { } // all members are static

        private static WebPart CreateWebPart(
            SPWebPartPages.SPLimitedWebPartManager wpm,
            string webPartId,
            string webPartFilename,
            string zoneId,
            ref int zoneIndex)
        {
            Debug.Assert(wpm != null);
            Debug.Assert(string.IsNullOrEmpty(webPartId) == false);
            Debug.Assert(string.IsNullOrEmpty(webPartFilename) == false);
            Debug.Assert(string.IsNullOrEmpty(zoneId) == false);

            Logger.LogDebug(
                CultureInfo.InvariantCulture,
                "Creating Web Part ({0}) on page ({1})...",
                webPartId,
                wpm.ServerRelativeUrl);

            WebPart webPart = null;

            SPFile wpFile = GetWebPartFileFromGallery(
                wpm.Web.Site,
                webPartFilename);

            Debug.Assert(wpFile != null);

            string errorMessage = string.Empty;

            using (Stream stream = wpFile.OpenBinaryStream())
            {
                XmlReader reader = XmlReader.Create(stream);
                webPart = wpm.ImportWebPart(reader, out errorMessage);
            }

            if (string.IsNullOrEmpty(errorMessage) == false)
            {
                string message =
                    "Error importing Web Part ("
                        + webPartFilename + "): "
                        + errorMessage;

                throw new SPWebPartPages.WebPartPageUserException(message);
            }

            webPart.ID = webPartId;
            wpm.AddWebPart(webPart, zoneId, zoneIndex);

            // HACK: When adding the first, second, third, and fourth Web Parts
            // to a zone:
            //
            //    SPLimitedWebPartManager.AddWebPart(webPart, zoneId, zoneIndex)
            //
            // behaves as expected, meaning that
            // (webPart.ZoneIndex == zoneIndex).
            //
            // However, when adding the fifth and sixth Web Parts to a zone,
            // then (webPart.ZoneIndex == zoneIndex + 1).
            if (webPart.ZoneIndex > zoneIndex)
            {
                Debug.Assert(zoneIndex >= 4);

                Logger.LogDebug(
                    CultureInfo.InvariantCulture,
                    "HACK: webPart.ZoneIndex ({0})"
                        + " is greater than zoneIndex ({1})."
                        + " Setting zoneIndex to {0}...",
                    webPart.ZoneIndex,
                    zoneIndex);

                zoneIndex = webPart.ZoneIndex;
            }

            Debug.Assert(webPart.ZoneIndex == zoneIndex);
            zoneIndex++;
            
            Logger.LogInfo(
                CultureInfo.InvariantCulture,
                "Successfully created Web Part ({0}) on page ({1}).",
                webPartId,
                wpm.ServerRelativeUrl);

            return webPart;
        }

        /// <summary>
        /// Ensures that a specific Web Part exists on a page.
        /// </summary>
        /// <param name="wpm">The Web Part manager for the page.</param>
        /// <param name="webPartId">The unique identifier for the Web Part.</param>
        /// <param name="webPartFileName">The .dwp or .webpart file in the
        /// Web Part gallery (used to import the Web Part if it does not exist).
        /// </param>
        /// <param name="zoneId">The zone the Web Part should reside in.</param>
        /// <param name="zoneIndex">The index of the Web Part relative to other
        /// Web Parts in the zone. If the Web Part is created, the index is
        /// incremented.</param>
        /// <returns>The new or existing Web Part on the page.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage(
            "Microsoft.Design",
            "CA1045:DoNotPassTypesByReference",
            Justification = "The zoneIndex is incremented when the Web Part is"
                + " added.")]
        public static WebPart EnsureWebPart(
            SPWebPartPages.SPLimitedWebPartManager wpm,
            string webPartId,
            string webPartFileName,
            string zoneId,
            ref int zoneIndex)
        {
            if (wpm == null)
            {
                throw new ArgumentNullException("wpm");
            }

            if (string.IsNullOrEmpty(webPartId) == true)
            {
                throw new ArgumentException(
                    "The Web Part Id must be specified.",
                    "webPartId");
            }

            if (string.IsNullOrEmpty(webPartFileName) == true)
            {
                throw new ArgumentException(
                    "The Web Part file name must be specified.",
                    "webPartFileName");
            }

            if (string.IsNullOrEmpty(zoneId) == true)
            {
                throw new ArgumentException(
                    "The Web Part zone must be specified.",
                    "zoneId");
            }

            WebPart webPart = wpm.WebParts[webPartId];

            if (webPart == null)
            {
                webPart = CreateWebPart(wpm, webPartId, webPartFileName,
                    zoneId, ref zoneIndex);
            }
            else
            {
                // HACK: webPart.Zone appears to always be null (SharePoint bug?)
                if (webPart.Zone == null)
                {
                    Logger.LogDebug(
                        CultureInfo.InvariantCulture,
                        "Unable to check zone for Web Part ({0})"
                            + " because webPart.Zone is null.",
                        webPartId);
                }
                else if (webPart.Zone.ID != zoneId)
                {
                    Logger.LogDebug(
                        CultureInfo.InvariantCulture,
                        "Moving Web Part ({0}) to zone ({1})...",
                        webPartId,
                        zoneId);

                    wpm.MoveWebPart(webPart, zoneId, zoneIndex);
                    wpm.SaveChanges(webPart);

                    Logger.LogInfo(
                        CultureInfo.InvariantCulture,
                        "Successfully moved Web Part ({0}) to zone ({1}).",
                        webPartId,
                        zoneId);
                }
            }

            return webPart;
        }

        /// <summary>
        /// Finds the first Web Part with the specified title.
        /// </summary>
        /// <remarks>
        /// This is useful in cases where the Web Part ID is not specified
        /// when it was added to the collection of Web Parts (thus generating
        /// a random identifier and making SPLimitedWebPartCollection[id]
        /// effectively useless).
        /// </remarks>
        /// <param name="wpm">The Web Part manager for the page.</param>
        /// <param name="webPartTitle">The title of the Web Part to find.</param>
        /// <returns>A Web Part object (if one is found), otherwise null.</returns>
        public static WebPart FindWebPartByTitle(
            SPWebPartPages.SPLimitedWebPartManager wpm,
            string webPartTitle)
        {
            if (wpm == null)
            {
                throw new ArgumentNullException("wpm");
            }

            if (string.IsNullOrEmpty(webPartTitle) == true)
            {
                throw new ArgumentException(
                    "The Web Part title must be specified.",
                    "webPartTitle");
            }

            Logger.LogDebug(
                CultureInfo.InvariantCulture,
                "Attemping to find Web Part ({0}) on page ({1})...",
                webPartTitle,
                wpm.ServerRelativeUrl);

            for (int i = 0; i < wpm.WebParts.Count; i++)
            {
                WebPart webPart = wpm.WebParts[i];

                if (string.Compare(
                        webPart.Title,
                        webPartTitle,
                        StringComparison.OrdinalIgnoreCase) == 0)
                {
                    Logger.LogDebug(
                        CultureInfo.InvariantCulture,
                        "Found Web Part ({0}) on page ({1}).",
                        webPartTitle,
                        wpm.ServerRelativeUrl);

                    return webPart;
                }
            }

            Logger.LogDebug(
                CultureInfo.InvariantCulture,
                "Unable to find Web Part ({0}) on page ({1}).",
                webPartTitle,
                wpm.ServerRelativeUrl);

            return null;
        }

        private static SPFile GetWebPartFileFromGallery(
            SPSite site,
            string webPartFilename)
        {
            if (site == null)
            {
                throw new ArgumentNullException("site");
            }

            if (webPartFilename == null)
            {
                throw new ArgumentNullException("webPartFilename");
            }

            webPartFilename = webPartFilename.Trim();
            if (string.IsNullOrEmpty(webPartFilename))
            {
                throw new ArgumentException(
                    "The Web Part filename must be specified.",
                    "webPartFilename");
            }

            Logger.LogDebug(
                CultureInfo.InvariantCulture,
                "Getting Web Part file ({0}) from site ({1}) gallery...",
                webPartFilename,
                site.Url);

            SPList wpGallery = site.GetCatalog(SPListTemplateType.WebPartCatalog);

            string camlQuery = "<Where><Eq><FieldRef Name=\"FileLeafRef\" />"
                + "<Value Type=\"File\">" + webPartFilename + "</Value></Eq></Where>";

            SPQuery query = new SPQuery();
            query.Query = camlQuery;

            SPListItemCollection webParts = wpGallery.GetItems(query);
            if (webParts.Count == 0)
            {
                string message = string.Format(
                    CultureInfo.InvariantCulture,
                    "Web Part ({0}) was not found in the Web Part Gallery.",
                    webPartFilename);
                
                throw new ArgumentException(
                    message,
                    "webPartFilename");
            }

            Logger.LogDebug(
                CultureInfo.InvariantCulture,
                "Found Web Part file ({0}) in site ({1}) gallery.",
                webPartFilename,
                site.Url);

            Debug.Assert(webParts.Count == 1);
            return webParts[0].File;
        }

        /// <summary>
        /// Ensures that a Content Editor Web Part exists on a page
        /// and is configured with the specified settings.
        /// </summary>
        /// <param name="wpm">The Web Part manager for the page.</param>
        /// <param name="webPartId">The unique identifier for the Web Part.</param>
        /// <param name="zoneId">The zone the Web Part should reside in.</param>
        /// <param name="zoneIndex">The index of the Web Part relative to other
        /// Web Parts in the zone. If the Web Part is created, the index is
        /// incremented.</param>
        /// <param name="htmlContent">The content to display within the Web
        /// Part.</param>
        /// <param name="title">The title of the Web Part.</param>
        /// <returns>The new or existing Web Part on the page.</returns>        
        [System.Diagnostics.CodeAnalysis.SuppressMessage(
            "Microsoft.Design",
            "CA1045:DoNotPassTypesByReference",
            Justification="The zoneIndex is incremented when the Web Part is"
                + " added.")]
        public static SPWebPartPages.ContentEditorWebPart
            EnsureContentEditorWebPart(
                SPWebPartPages.SPLimitedWebPartManager wpm,
                string webPartId,
                string zoneId,
                ref int zoneIndex,
                string htmlContent,
                string title)
        {
            if (wpm == null)
            {
                throw new ArgumentNullException("wpm");
            }

            if (webPartId == null)
            {
                throw new ArgumentNullException("webPartId");
            }

            webPartId = webPartId.Trim();
            if (string.IsNullOrEmpty(webPartId))
            {
                throw new ArgumentException(
                    "The Web Part ID must be specified.",
                    "webPartId");
            }

            if (zoneId == null)
            {
                throw new ArgumentNullException("zoneId");
            }

            zoneId = zoneId.Trim();
            if (string.IsNullOrEmpty(zoneId))
            {
                throw new ArgumentException(
                    "The Web Part zone must be specified.",
                    "zoneId");
            }

            if (htmlContent == null)
            {
                throw new ArgumentNullException("htmlContent");
            }

            htmlContent = htmlContent.Trim();
            if (string.IsNullOrEmpty(htmlContent))
            {
                throw new ArgumentException(
                    "The HTML content must be specified.",
                    "htmlContent");
            }

            // Note: title is optional

            Logger.LogDebug(
                CultureInfo.InvariantCulture,
                "Ensuring Content Editor Web Part ({0}) on page ({1})...",
                webPartId,
                wpm.ServerRelativeUrl);

            SPWebPartPages.ContentEditorWebPart webPart =
                (SPWebPartPages.ContentEditorWebPart) EnsureWebPart(
                    wpm,
                    webPartId,
                    "MSContentEditor.dwp",
                    zoneId,
                    ref zoneIndex);

            if (webPart.Content == null
                || webPart.Content.InnerText != htmlContent
                || webPart.Title != title
                || webPart.ChromeType != PartChromeType.None)
            {
                Logger.LogDebug(
                    CultureInfo.InvariantCulture,
                    "Updating properties of Content Editor Web Part ({0}) on"
                        + " page ({1})...",
                    webPartId,
                    wpm.ServerRelativeUrl);

                // To bring content into the Content Editor Web Part,
                // we need to use an XML Document
                XmlDocument xmlDoc = new XmlDocument();
                XmlElement xmlElement = xmlDoc.CreateElement("HtmlContent");
                xmlElement.InnerText = htmlContent;
                webPart.Content = xmlElement;

                webPart.Title = title;
                webPart.ChromeType = PartChromeType.None;

                wpm.SaveChanges(webPart);

                Logger.LogInfo(
                    CultureInfo.InvariantCulture,
                    "Successfully updated properties of Content Editor Web Part"
                        + " ({0}) on page ({1}).",
                    webPartId,
                    wpm.ServerRelativeUrl);
            }
            else
            {
                Logger.LogDebug(
                    CultureInfo.InvariantCulture,
                    "The Content Editor Web Part ({0}) on page ({1}) is already"
                        + " configured with the expected settings.",
                    webPartId,
                    wpm.ServerRelativeUrl);
            }

            return webPart;
        }
    }
}

Most of the code in the SharePointWebPartHelper class is very straightforward. The most interesting hack -- er, I mean workaround -- in the code is to handle the scenario where the zoneIndex is sometimes mysteriously incremented by more than one, but you can read more about this in a previous post -- if you are really interested.

Using the SharePointWebPartHelper class couldn't be easier. For a simple example, consider the scenario that I mentioned earlier about adding a Login Form Web Part to a page:

            // Configure Web Parts
            SPWebPartPages.SPLimitedWebPartManager wpm =
                publicWeb.GetLimitedWebPartManager(
                    page.Url,
                    PersonalizationScope.Shared);

            using (wpm)
            {
                string zoneId = "LeftColumnZone";
                int zoneIndex = 0;

                LoginFormWebPart loginForm =
                    (LoginFormWebPart) SharePointWebPartHelper.EnsureWebPart(
                        wpm,
                        "LoginForm",
                        "Fabrikam_LoginForm.webpart",
                        zoneId,
                        ref zoneIndex);

                loginForm.DisplayRememberMe = false;
                wpm.SaveChanges(loginForm);

                // HACK: Avoid memory leak in SPLimitedWebPartManager
                if (wpm.Web != null)
                {
                    wpm.Web.Dispose();
                }
            }

Just be sure to avoid the memory leak in SPLimitedWebPartManager, like I show in the code example above.

Here's another code example where I configured a bunch of Web Parts on a search results page:

namespace Fabrikam.Web.Search.Configuration
{
    /// <summary>
    /// Exposes static methods for configuring the <b>Fabrikam.Web.Search</b>
    /// feature. This class cannot be inherited.
    /// </summary>
    /// <remarks>
    /// All methods of the <b>FeatureConfigurator</b> class are static and can
    /// therefore be called without creating an instance of the class.
    /// </remarks>  
    [CLSCompliant(false)]
    [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]
    public sealed class FeatureConfigurator
    {
        ...

        private static void ConfigureSearchResultsPageWebParts(
            SPWeb searchWeb,
            PublishingPage searchResultsPage,
            string defaultSearchResultsPageUrl,
            string scopeName,
            string additionalQueryTerms,
            string contextualScopeUrl)
        {
            SPWebPartPages.SPLimitedWebPartManager wpm =
                searchWeb.GetLimitedWebPartManager(
                    searchResultsPage.Url, PersonalizationScope.Shared);

            using (wpm)
            {
                #region Zone1

                string zoneId = "Zone1";
                int zoneIndex = 0;

                SharePointWebPartHelper.EnsureContentEditorWebPart(
                    wpm,
                    "startNewSearchHeading",
                    zoneId,
                    ref zoneIndex,
                    "<h2 class='accent3'>Start a new search</h2>",
                    "Start New Search Heading");

                SearchBoxEx searchBox =
                    (SearchBoxEx)SharePointWebPartHelper.EnsureWebPart(
                        wpm,
                        "searchBox",
                        "SearchBox.dwp",
                        zoneId,
                        ref zoneIndex);

                searchBox.DropDownModeEx = DropDownModesEx.HideScopeDD;
                searchBox.SearchResultPageURL = defaultSearchResultsPageUrl;
                searchBox.Width = string.Empty;

                wpm.SaveChanges(searchBox);

                SharePointWebPartHelper.EnsureContentEditorWebPart(
                    wpm,
                    "refineSearchHeading",
                    zoneId,
                    ref zoneIndex,
                    "<h2 class='accent3'>Refine your search</h2>",
                    "Refine Search Heading");

                FabrikamSearchBoxWebPart searchScopeOptions =
                    (FabrikamSearchBoxWebPart)SharePointWebPartHelper.EnsureWebPart(
                        wpm,
                        "searchScopeOptions",
                        "FabrikamSearchBox.webpart",
                        zoneId,
                        ref zoneIndex);

                searchScopeOptions.ShowSearchBox = false;
                wpm.SaveChanges(searchScopeOptions);

                ConfigureFacetedSearchWebParts(
                    wpm,
                    zoneId,
                    ref zoneIndex,
                    scopeName);

                #endregion
                
                #region Zone2

                zoneId = "Zone2";
                zoneIndex = 0;

                SharePointWebPartHelper.EnsureWebPart(
                    wpm,
                    "searchTabs",
                    "FabrikamListBoundTabStrip.webpart",
                    zoneId,
                    ref zoneIndex);

                SharePointWebPartHelper.EnsureWebPart(
                    wpm,
                    "searchSummary",
                    "SearchSummary.dwp",
                    zoneId,
                    ref zoneIndex);

                bool showBestBetsWebPart = false;

                if (string.Compare(
                    searchResultsPage.Name,
                    "Results.aspx",
                    StringComparison.OrdinalIgnoreCase) == 0)
                {
                    showBestBetsWebPart = true;
                }
                else if (string.Compare(
                    searchResultsPage.Name,
                    "AllSitesResults.aspx",
                    StringComparison.OrdinalIgnoreCase) == 0)
                {
                    showBestBetsWebPart = true;
                }

                if (showBestBetsWebPart == true)
                {
                    ConfigureBestBetsWebPartForSiteSearch(
                        wpm,
                        zoneId,
                        ref zoneIndex);
                }

                SearchStatsWebPart searchStats =
                    (SearchStatsWebPart) SharePointWebPartHelper.EnsureWebPart(
                        wpm,
                        "searchStats",
                        "searchStats.dwp",
                        zoneId,
                        ref zoneIndex);

                searchStats.DisplayResponseTime = false;
                wpm.SaveChanges(searchStats);
                
                SharePointWebPartHelper.EnsureWebPart(
                    wpm,
                    "searchPaging1",
                    "SearchPaging.dwp",
                    zoneId,
                    ref zoneIndex);

                ConfigureCoreResultsWebPartsForSiteSearch(
                    wpm,
                    zoneId,
                    ref zoneIndex,
                    scopeName);

                SharePointWebPartHelper.EnsureWebPart(
                    wpm,
                    "searchPaging2",
                    "SearchPaging.dwp",
                    zoneId,
                    ref zoneIndex);

                if (additionalQueryTerms != null
                    || contextualScopeUrl != null)
                {
                    ConfigureCoreResultsExtensionWebPart(
                        wpm,
                        additionalQueryTerms,
                        contextualScopeUrl,
                        zoneId,
                        ref zoneIndex);
                }

                #endregion
                
                // HACK: Avoid memory leak in SPLimitedWebPartManager
                if (wpm.Web != null)
                {
                    wpm.Web.Dispose();
                }
            }
        }
    }
}

Even though I didn't add any comments to this (rather lengthy) method, I think you'll find it is actually very easy to understand simply by reading the method names and parameters -- or at least that's what I hope for the people that are actually maintaining this code from my previous project ;-)

I hope you find the SharePointPublishingHelper and SharePointWebPartHelper classes as useful as I have over the past several years.

Be sure to stay tuned, because there are more SharePoint helper classes to come, but my daughter just woke up and now I need to go make some pancakes!