When helping customers migrate their Internet sites to Microsoft Office SharePoint Server (MOSS) 2007, I've found it very helpful to create wireframes showing the various fields, Web Parts, and master page content. For the last several years, I've been doing this in Microsoft Office Visio, but you could certainly achieve similar results with other tools, such as Expression Design.

I start by taking a series of screenshots of the existing Web site using Screengrab! (which makes it very easy to capture entire Web pages). For example, here is a screenshot of a "Generic" page on the Agilent Technologies - LSCA site that I captured a couple of years ago.

Figure 1: "Generic" page

See full-sized image.

I then paste the screenshot into Visio.

Next, I deemphasize the portions of the page rendered by the master page. To accomplish this, add a rectangle with the text Header (Master Page) over the top portion of the page. Then fill the rectangle with light gray (Shade 15%) and set the transparency to 30%. Repeat similar steps for the footer and other content provided by the master page.

The next step is to emphasize the various fields that we need to define in the corresponding content type. In Figure 1, it is easy to discern that we have a Title (i.e. "Glycomics Solution"), a Page Image (i.e. the circular image on the right side of the page), and some arbitrary amount of Page Content (i.e. the "stuff" in the middle). I also chose to provide a Subtitle field for the bold text at the top of the page. Isolating the Subtitle allows us to provide "semantic markup" and better control the formatting and layout of this content.

To highlight these various fields, I create rectangles with corresponding text and fill them with a very light red (Tint 35%) and again set the transparency to 30%.

We now have a "wireframe" that shows the various portions of the page with just enough visibility of the underlying content to understand what each portion refers to.

Figure 2: "Generic" page (Page Layout)

See full-sized image.

Here is another example, based on a press release.

Figure 3: Sample Press Release

See full-sized image.

Figure 4 shows the corresponding page layout.

Figure 4: Press Release (Page Layout)

See full-sized image.

Note the importance of choosing good sample pages when mocking up the wireframes for page layouts. I chose the example press release above based on the fact that it had "additional contact" information. In other words, all press releases have primary contact information (which I chose to map to the out-of-the-box Contact Name, Contact Phone, and Contact E-mail Address fields), but only some press releases have additional contacts -- which may consist of one more more individuals. Rather than attempting to create separate fields for each individual's name, phone number, and e-mail address, we chose to simply provide a single field for greater flexibility.

Some pages may be comprised of both fields and Web Parts. For example, consider the following product detail page.

Figure 5: Sample product detail page

See full-sized image.

In this scenario, the "Buy Zone" and "Announcements" features are both implemented as individual Web Parts (due to the dynamic nature of this content). Figure 6 shows the corresponding page layout, highlighting the Web Parts in a different color.

Figure 7: Product Detail (Page Layout)

See full-sized image.

Wireframes like these are valuable when you are trying to define the various content types and page layouts, as well as when it comes time to document your various feature specs. So the next time you start a SharePoint project -- or any Web development project for that matter -- I recommend creating a Screenshots library right from the start and adding artifacts like these. I also keep a copy of the Visio file (typically named Models - Page Layouts.vsd) so I can quickly make changes as the content types and page layouts evolve over time.

This post continues on the original post for my simple, but highly effective approach to logging and the follow-up post which introduced configuring logging for console applications.

Obviously not all solutions are simple console-based applications. With ASP.NET Web services and applications -- including Microsoft Office SharePoint Server (MOSS) and Windows SharePoint Services (WSS) -- you can still view log messages from the Logger class very easily on a per-request basis.

Note that the System.Web.WebPageTraceListener can be specified in Web.config to enable logging to the ASP.NET tracing feature:

  <system.diagnostics>
    <sources>
      <source name="defaultTraceSource" switchName="allTraceLevel">
        <listeners>
          <add name="webPageTraceListener" />
        </listeners>
      </source>
    </sources>
    <sharedListeners>
      <add type="System.Web.WebPageTraceListener, System.Web, Version=2.0.0.0,
Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
        name="webPageTraceListener" traceOutputOptions="None" />
    </sharedListeners>
    <switches>
      <add name="allTraceLevel" value="All" />
      <add name="verboseTraceLevel" value="Verbose" />
      <add name="infoTraceLevel" value="Info" />
      <add name="warningTraceLevel" value="Warning" />
      <add name="errorTraceLevel" value="Error" />
      <add name="offTraceLevel" value="Off" />
    </switches>
  </system.diagnostics>

Also note that ASP.NET tracing must be enabled using the <trace> element within <system.web>:

  <system.web>
    <trace enabled="true" pageOutput="false" requestLimit="50" localOnly="true" />
  </system.web>

Be sure to set the requestLimit high enough to enable access to the page trace you are interested, but also be aware that you can easily clear the captured traces and then browse to the page of interest again.

Once configured, browse to the page on the site. Then modify the URL to browse to Trace.axd (e.g. http://fabrikam-local/Trace.axd) to display the Trace Viewer.

Figure 1: ASP.NET Trace Viewer

See full-sized image.

Locate the request that you want to view log messages for and click the corresponding View Details link.

Figure 2: ASP.NET Trace Viewer

See full-sized image.

Notice that the WebPageTraceListener even formatted the warning message in red. How cool is that?! [For all you SharePoint developers out there, compare this with "diving" into the ULS logs to find an error or warning for a particular page request!]

Be aware that the Web.config file you use for SharePoint applications varies depending on whether you want to view log messages for a content page or for an application (i.e. _layouts) page. This is covered in my next post.

A common question that frequently arises both with customers and fellow consultants is what do I recommend for logging? As experienced software developers, we know that there are going to be errors in our solution -- as well as other important events that we want to monitor -- and therefore we know we need a robust way of logging these.

However, with numerous options available -- e.g. log4net, Enterprise Library, Common.Logging, SharePoint ULS, etc. -- it's no wonder this is frequently a "hot" topic.

Several years ago, I created a simple, but highly effective approach to logging based on the (then) new System.Diagnostics features in the .NET Framework version 2.0.

Before introducing my logging feature, it is first important to understand the goals (and non-goals) of the solution.

Goals and Non-Goals

The primary goals of the logging feature are:

• Provide solution components a way of logging messages of various levels (e.g. errors, warnings, information) with minimal custom code.
• Ensure log messages can be enabled in all environments (e.g. DEV, TEST, and PROD); in other words, in both Debug and Release builds (unlike the Debug.WriteLine method, which relies on the DEBUG conditional compilation constant).
• Through configuration, enable log messages to be routed to various outputs such as a text file, the Windows Event Log, or ASP.NET tracing.
• Ensure that different levels of log messages can be filtered and potentially routed to different outputs; for example, log all messages to the console, but only log errors and warnings to a text file.

Non-goals of the logging feature include:

• Providing the fastest possible logging implementation; rather the performance impact of logging should be insignificant when compared with the "real" work performed by the solution components.
• Changing logging configuration without reinitializing the solution; for example, to change the logging for an ASP.NET application, it is acceptable to restart the corresponding application pool.
• Filtering log messages based on subsystems (or feature areas) of the solution; for example, when logging is enabled for debug messages, then log messages from all components are output.

Introducing the Logger Class

With the custom Logger class, logging a debug message is simply a matter of calling a static method, specifying nothing more than a string containing the message :

    Logger.LogDebug("Successfully loaded search results into DataSet.");

This example shows how the Logger class achieves the primary design goal. Note that there is no need to explicitly create objects within each class -- or create additional classes within an assembly -- for logging purposes.

Also note that the Logger class provides additional overloads to easily format log messages:

    Logger.LogDebug(
        CultureInfo.InvariantCulture,
        "Successfully loaded embedded resource ({0})"
            + " ({1:n0} bytes) from assembly ({2}).",
        resourceName,
        resourceContent.Length,
        resourceAssembly.FullName);

Note that the Logger.LogDebug method is simply a convenient alternative to the Logger.Log method:

    /// <summary>
    /// Logs an event to the trace listeners using the specified
    /// event type and message.
    /// </summary>
    /// <param name="eventType">One of the System.Diagnostics.TraceEventType
    /// values that specifies the type of event being logged.</param>
    /// <param name="message">The message to log.</param>
    public static void Log(
        TraceEventType eventType,
        string message)

Other methods such as LogInfo and LogError provide similar overloads for convenience.

The simplicity of the Logger class is made possible by the improved tracing functionality introduced in the .NET Framework version 2.0. Specifically, the Logger class is simply a "wafer-thin" wrapper around the System.Diagnostics.TraceSource class.

The Logger class declares a singleton TraceSource that is used to log all messages:

    private static TraceSource defaultTraceSource =
        new TraceSource("defaultTraceSource");

Various listeners can then be configured to output log messages. Each type of listener derives from TraceListener.

Note that the .NET Framework includes listeners for logging to a file, the Windows Event Log, as well as ASP.NET tracing. Consequently, with just a little bit of custom code (i.e. the Logger class) combined with all the "goodness" baked into the core .NET Framework, we have a logging feature that meets all of the established goals.

In my next post, I introduce how to configure logging (starting out with a console application).

Here is the complete source for the Logger class:

#define TRACE

using System;
using System.Diagnostics;
using System.Globalization;
using System.Text;

namespace Fabrikam.Demo.CoreServices.Logging
{
    /// <summary>
    /// Exposes static methods for logging various events (e.g. debug,
    /// informational, warning, etc.). This class cannot be inherited.
    /// </summary>
    /// <remarks>
    /// All methods of the <b>Logger</b> class are static
    /// and can therefore be called without creating an instance of the class.
    /// </remarks>
    public sealed class Logger
    {
        private static TraceSource defaultTraceSource =
            new TraceSource("defaultTraceSource");

        private Logger() { } // all members are static

        /// <summary>
        /// Flushes all the trace listeners in the trace listener collection.
        /// </summary>
        public static void Flush()
        {
            defaultTraceSource.Flush();
        }

        /// <summary>
        /// Logs an event to the trace listeners using the specified
        /// event type and message.
        /// </summary>
        /// <param name="eventType">One of the System.Diagnostics.TraceEventType
        /// values that specifies the type of event being logged.</param>
        /// <param name="message">The message to log.</param>
        public static void Log(
            TraceEventType eventType,
            string message)
        {
#if DEBUG
            // Some debug listeners (e.g. DbgView.exe) don't buffer output, so
            // Debug.Write() is effectively the same as Debug.WriteLine().
            // For optimal appearance in these listeners, format the output
            // for a single call to Debug.WriteLine().
            StringBuilder sb = new StringBuilder();

            sb.Append(eventType.ToString());
            sb.Append(": ");
            sb.Append(message);

            string formattedMessage = sb.ToString();
            Debug.WriteLine(formattedMessage);
#endif

            defaultTraceSource.TraceEvent(eventType, 0, message);
        }

        /// <summary>
        /// Logs a debug event to the trace listeners using the specified
        /// format string and arguments.
        /// </summary>
        /// <param name="provider">An System.IFormatProvider that supplies
        /// culture-specific formatting information.</param>
        /// <param name="format">A composite format string.</param>
        /// <param name="args">An System.Object array containing zero or more
        /// objects to format.</param>
        public static void LogDebug(
            IFormatProvider provider,
            string format,
            params object[] args)
        {
            string message = string.Format(
                provider, format, args);

            LogDebug(message);
        }

        /// <summary>
        /// Logs a debug event to the trace listeners.
        /// </summary>
        /// <param name="message">The message to log.</param>
        public static void LogDebug(
            string message)
        {
            Log(TraceEventType.Verbose, message);
        }

        /// <summary>
        /// Logs a critical event to the trace listeners using the specified
        /// format string and arguments.
        /// </summary>
        /// <param name="provider">An System.IFormatProvider that supplies
        /// culture-specific formatting information.</param>
        /// <param name="format">A composite format string.</param>
        /// <param name="args">An System.Object array containing zero or more
        /// objects to format.</param>
        public static void LogCritical(
            IFormatProvider provider,
            string format,
            params object[] args)
        {
            string message = string.Format(
                provider, format, args);

            LogCritical(message);
        }

        /// <summary>
        /// Logs a critical event to the trace listeners.
        /// </summary>
        /// <param name="message">The message to log.</param>
        public static void LogCritical(
            string message)
        {
            Log(TraceEventType.Critical, message);
        }

        /// <summary>
        /// Logs an error event to the trace listeners using the specified
        /// format string and arguments.
        /// </summary>
        /// <param name="provider">An System.IFormatProvider that supplies
        /// culture-specific formatting information.</param>
        /// <param name="format">A composite format string.</param>
        /// <param name="args">An System.Object array containing zero or more
        /// objects to format.</param>
        public static void LogError(
            IFormatProvider provider,
            string format,
            params object[] args)
        {
            string message = string.Format(
                provider, format, args);

            LogError(message);
        }

        /// <summary>
        /// Logs an error event to the trace listeners.
        /// </summary>
        /// <param name="message">The message to log.</param>
        public static void LogError(
            string message)
        {
            Log(TraceEventType.Error, message);
        }

        /// <summary>
        /// Logs an informational event to the trace listeners using the specified
        /// format string and arguments.
        /// </summary>
        /// <param name="provider">An System.IFormatProvider that supplies
        /// culture-specific formatting information.</param>
        /// <param name="format">A composite format string.</param>
        /// <param name="args">An System.Object array containing zero or more
        /// objects to format.</param>
        public static void LogInfo(
            IFormatProvider provider,
            string format,
            params object[] args)
        {
            string message = string.Format(
                provider, format, args);

            LogInfo(message);
        }

        /// <summary>
        /// Logs an informational event to the trace listeners.
        /// </summary>
        /// <param name="message">The message to log.</param>
        public static void LogInfo(
            string message)
        {
            Log(TraceEventType.Information, message);
        }

        /// <summary>
        /// Logs a warning event to the trace listeners using the specified
        /// format string and arguments.
        /// </summary>
        /// <param name="provider">An System.IFormatProvider that supplies
        /// culture-specific formatting information.</param>
        /// <param name="format">A composite format string.</param>
        /// <param name="args">An System.Object array containing zero or more
        /// objects to format.</param>
        public static void LogWarning(
            IFormatProvider provider,
            string format,
            params object[] args)
        {
            string message = string.Format(
                provider, format, args);

            LogWarning(message);
        }

        /// <summary>
        /// Logs a warning event to the trace listeners.
        /// </summary>
        /// <param name="message">The message to log.</param>
        public static void LogWarning(
            string message)
        {
            Log(TraceEventType.Warning, message);
        }
    }
}

Note that the Logger.cs file actually includes #define TRACE at the top of the file. This is because I originally wrote this class with an old version of Visual Studio (which did not define this compilation constant by default when creating new projects). Visual Studio 2008 projects include this in the project options by default (for both Debug and Release configurations), so this is superfluous.

As you can see, there's really not much to this class (which hopefully means there isn't much that can go wrong with it). Most, if not all, of it should be very straightforward. I'll explain the importance of the Logger.Flush method in my next post.

One of the common tasks when using the "DR.DADA" approach to SharePoint development is programmatically creating and configuring pages on a site. This often requires adding numerous Web Parts to various zones on a page -- for example, to configure search results pages.

Over the past couple of years, my teammates and I have created numerous "helper" classes that simplify this task in Windows SharePoint Services (WSS) 3.0 and Microsoft Office SharePoint Server (MOSS) 2007 -- including SharePointWebPartHelper.

/// <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>    
public sealed class SharePointWebPartHelper

SharePointWebPartHelper contains public methods like EnsureWebPart and FindWebPartByTitle. As you can probably tell from the names of these methods, this allows you to locate an existing Web Part on a page or create one if the specified Web Part doesn't currently exist on the page.

EnsureWebPart attempts to find a Web Part based on the specified webPartId and if the Web Part is not found, then it uses the CreateWebPart method to create a new Web Part. Here is the original implementation of the CreateWebPart method:

    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 ApplicationException(message);
        }

        webPart.ID = webPartId;
        wpm.AddWebPart(webPart, zoneId, zoneIndex);        
        zoneIndex++;
        
        Logger.LogDebug(
            CultureInfo.InvariantCulture,
            "Successfully created Web Part ({0}) on page ({1}).",
            webPartId,
            wpm.ServerRelativeUrl);

        return webPart;
    }

Note that SPWebPartPages is simply an alias for the Microsoft.SharePoint.WebPartPages namespace (in order to avoid "collisions" with the System.Web.UI.WebControls.WebParts namespace). Also, please ignore the use of ApplicationException -- apparently there's still a little "code cleanup" to be done here.

As I called out above, this code shows the original implementation of the method. It turns out there's a very obscure bug in it, that I only discovered within the last couple of months.

As you can probably guess from the title of this post, the problem is that zoneIndex (i.e. the position of the Web Part relative to other Web Parts within the same Web Part zone) isn't always incremented as you would expect.

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).

I suspect it is due to the SPWebPartManager.MakeSpaceForWebpart method (which is called from SPLimitedWebPartManager.AddWebPart). However, the SPWebPartManager.MakeSpaceForWebpart method is obfuscated and therefore I can’t see what it is doing using Reflector.

This behavior caused some Web Parts to appear in the wrong location, and therefore I had to come up with a hack for it. Here is my updated version of the CreateWebPart method:

    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 ApplicationException(message);
        }

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

        // Bug 68288:
        //
        // 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.LogDebug(
            CultureInfo.InvariantCulture,
            "Successfully created Web Part ({0}) on page ({1}).",
            webPartId,
            wpm.ServerRelativeUrl);

        return webPart;
    }

I was curious to know why SharePoint behaves this way and to see if this behavior is documented somewhere and I just missed it. Unfortunately, the e-mail I sent back in March to an internal discussion list received no responses. So I guess this will just have to remain a mystery.

The project I am currently working on is nearing the end. Last week we reached our "Feature Complete" milestone and now we have formally transitioned into the "Stabilizing" phase.

In a couple of team meetings this week, I mentioned the concepts of "Tell Mode" and "Ask Mode" -- a couple of terms I've been using for more years than I can remember. However, not everyone on the team was aware of these concepts. Consequently, I "recycled some bits" (meaning I searched through my e-mail archive and found a message I sent awhile back) in order to provide some more background and details on Tell Mode and Ask Mode.

I thought this worth sharing with a broader audience.

I'll warn you...this is a rather long post and not one I'm expecting many people to read in its entirety. Rather, I think a lot of people would benefit from reading just enough of my e-mail to understand the key concepts and perhaps skim the example bugs to get a feel for the level of detail expected during the "investigation" phase after switching to Ask Mode.

---

From: JAMESON,JEREMY (Non-A-BPI-AM,unix1)
Sent: Thursday, October 18, 2007 8:03 AM
Subject: v2.0 Transition from "Tell Mode" to "Ask Mode"

On Sunday night, October 21st, RC4 of the [Project] v2.0 solution will be deployed to TEST. This will mark the official transition from "Tell Mode" to "Ask Mode."

What does this mean?

Microsoft uses Tell Mode and Ask Mode to refer to different time periods after the Feature Complete milestone but prior to a release.

During Tell Mode the Development team tells the rest of the team which issues are actively being worked on (resolved). In other words, Development is primarily driving the stabilization process based on what they think should be fixed -- as determined by priority, severity, complexity (i.e. risk), and effort required. This works for a while, but at some point you have to reign in Development in order to ship, er, release.

Thus we transition into Ask Mode whereby Development must ask permission before resolving any issues. It is okay to investigate issues, but no code changes can be made to address an issue until approval by the “War Team” (er, Triage Team) is granted.

During Ask Mode we look first at the scenario that is being fixed (i.e. the motivation for fixing it), we look at why the bug happens (regression, test hole, coding error, etc.), and then we investigate the necessary source code changes and associated risk. Every potential change is heavily scrutinized to evaluate whether it is worth the risk to fix it, because at this point in the schedule, every change -- even one that seems trivial -- has the potential to destabilize the solution and slip the schedule.

While the overall process of the daily triage meetings stays the same as we transition from Tell Mode to Ask Mode, there is a noticeable shift in focus.

During Tell Mode, work items are often immediately triaged as Approved, or work items triaged as Investigate are often just fixed without further review. This is no longer the case once we enter Ask Mode.

In Ask Mode every work item is first assigned a triage of Investigate. The person responsible for investigating the item must thoroughly document details about the item -- in the Description field of the work item, unless a more formal DCR (Design Change Request) is deemed necessary.

The investigator (typically a member of the Development team) documents the:

• Motivation -- "Why are we making this change?"
• Proposal -- "How should we resolve the issue?"
• Risks -- "What is the worst case scenario if we make this change?"
• Solution -- "What specifically needs to change?"
• Teams Impacted -- "How much work is required by Development, Test, Release Management, and (potentially) Product Management teams?" (note that the estimates need to come from the respective team members -- the investigator should not "guess")

Note that both Solution and Teams Impacted are not needed, one or the other is fine. If the necessary change (and associated risk) is very small -- such as a configuration change -- then just documenting the Solution should suffice. The goal is not to overburden ourselves with process -- but we also need to ensure that no change is made unless it has been thoroughly evaluated. If the change (or risk) is substantial, then document the impact on each of the various teams.

You can see some example bugs from v1.0 for more details: 1592, 1505, 1533, 1582, and 1549.

After documenting these details, the investigator then changes the Triage field to Recommend Approve (if the value in making the change is greater than the associated risk) or Recommend Reject (if the risk of making the change outweighs the value). The Triage Team then reviews the detailed information about the work item and either changes the Triage field to Approved or Not Approved (i.e. "punt to v.Next").

Note that the Triage Team can certainly “overrule” the investigator, which is why it is critical that no work be done on actually resolving the work item until approval is received from the Triage Team (i.e. the Triage field is set to Approved). Also note that, unless you are a member of the Triage Team – and even then, only during a formal triage meeting – you should not change the Triage field to anything except Recommend Approve or Recommend Reject. Otherwise, you should fully expect a thorough hazing from virtually all team members.

Everyone who was involved in v1.0 knows that we didn't strictly follow this process in the first release of [Project], but we also have the "scars" to remind us that we need to improve our process for this release.

It is also important to note that Microsoft fully acknowledges that we had many more QFEs for v1.0 than we intended, and we never did deploy v1.1 as a separate release. We need to be committed to ensuring that we don't repeat this in v2.

Yes, we will release v2.0 with known issues. By now, everyone has heard Jeremy's anecdote about the 64,000 "issues" in the RTM version of Windows 2000 -- so no sense repeating that. Rather we need to focus on making sure that most of the "issues" are known, we understand the impact of those issues on the user experience, and -- where necessary -- we find creative ways to circumvent the issues until the underlying changes can be implemented, tested, and deployed.

Note that I have replaced the project code name with [Project] in order to protect the innocent. I also "spoofed" the links to the referenced bugs, since these referred to a "Work Items" list on a secured team site we used for the project (which obviously you wouldn't have access to -- unless you just happen to be one of my cohorts on the project).

I have included slightly "scrubbed" versions of a couple of the bugs below, in case you are interested in seeing examples. If you don't understand all of the acronyms, terms, and technical details...don't worry, you're not supposed to -- unless you actually were a member of this project ;-)

Bug 1592 - LiteratureResults.asp is not working

Motivation:

There appear to be (at least) two problems when following the repro steps:

1. The Literature Summary list (rendered by LiteratureResults.asp when isortorder=9) should show the number of publications matching the specified criteria, grouped by Literature Type (a.k.a. publication type, a.k.a. Content Type in SharePoint, a.k.a. the ContentType2 managed property). The list should be ordered by Literature Type.
2. Clicking on a publication type in the Literature Summary list should show the search results for publications of the selected type. According to the original description for this bug, an error occurred at this point.

Proposal:

Correct the Literature Summary view to properly group and order by publication type. Increase the maximum number of search results in this scenario from 200 to 1000.

Ensure that clicking a publication type in the list shows the matching publications of the specified type.

Risk:

The current implementation of LiteratureResults.asp uses a hard-coded maximum of 200 search results (this limit was chosen for performance reasons since there is significant cost in sending large result sets from the SharePoint farm to the legacy ASP farm). Therefore, simply changing the sort order to publication type could potentially truncate the Literature Summary view such that it only showed one publication type (for example, if more than 200 Applications matched the specified criteria).

While it is simple to increase the maximum number of results (for example, from 200 to 1000) when rendering the Literature Summary view, this will put considerable load on SharePoint Search for two reasons:

1. We need to order first by ContentType2 in order to return the result set in the order expected by the legacy ASP code that generates the Literature Summary view.
2. SharePoint Search is optimized to sort by rank first (since it is typically desired to show the "best" results at the top of the list). In order to return a result set of, say, 1000 items sorted by something other than rank, SharePoint must do a lot more work before it can trim the result set.

Therefore it is quite possible that SharePoint Search will require > 10 seconds to generate these large result sets (although it is expected that duplicate searches will be cached and therefore return the result set much faster). As noted in bug 1151, this may cause "sporadic errors" in the legacy ASP pages.

Teams Impacted

Development
Modify LiteratureSearchResults.asp to change the max number of results to be a variable with a default value of 200.

Modify SetSortParameters in SearchModule.inc to set the sort expression used in ESI (strSortExpression) and to override the default max results value to allow 1000 results. (1 hour).
 
Release Management
Merge updated ASP files into legacy VSS and deploy to WCOSLSD and CAGCHEM (1 hour)
 
Test
Retest ESI Chromatogram searches through legacy General Site (2 hours)

Bug 1505 - There are no results displayed in WCOSLSCD if a search is performed on few publication types

Repro steps:

1. Log on to http://wcoslscd.cos.fabrikam.com/scripts/library.asp
2. Select the publication type as “Certificate of Analysis” or “Material Safety Data Sheet”  from the drop down and click on search
3. There are no results displayed for these publication types even though there are lot of documents under these publication types in TEST

Motivation:

LiteratureResults.aspx currently excludes the following content types (since the number of publications of these types is disproportionately higher than other publication types and also because these publication types have separate search forms):

• Chromatogram
• Certificate of Analysis
• Material Safety Data Sheet

However, the current user experience is not desirable since the search form allows users to narrow their search results to just Certificate of Analysis or MSDS publications (which will never return results).

Proposal:

Remove Certificate of Analysis and MSDS from the search criteria. This would allow users to search specifically by these publication types and would also include these results by default.

Risk:

Of the roughly 33,000 publications in the EPI Warehouse, there are approximately 1,300 Certificate of Analysis and 7,100 MSDS publications.

Since the new SharePoint search includes full-text indexing as well as metadata, including these two publication types by default may dramatically change the search results.

Teams Impacted

Development
Modify LiteratureResults.asp to no longer exclude Certificate of Analysis and MSDS publications by default (0.5 hours).

Release Management
Merge updated ASP file into legacy VSS and deploy to WCOSLSCD and CAGCHEM (0.5 hours)

Test
Retest ESI Library searches through legacy General Site (2 hours)

Product Management
Review new Library search results on legacy General Site to determine if the large number of Certificate of Analysis and MSDS publications has a negative impact on search results. (2 hours)

In yesterday's post, I noted the errors I encountered when trying to install Windows Server 2008 Service Pack 2 (SP2) due to "insufficient" disk space. I ended up having to expand numerous VHDs (one for each of my VMs running Windows Server 2008 x64) in order to have roughly 5 GB of free space to allow SP2 to install.

Note that SP2 certainly didn't use the 5 GB of free space, but apparently it insists on having that much for some "factor of safety" during the install.

Note that SP2 for Windows Server 2008 and Windows Vista include a new tool which helps recover hard disk space: the Windows Component Clean Tool (COMPCLN.exe). According to the Windows Server 2008 SP2 Deployment Guide this tool permanently removes the files that are archived after Windows Vista SP2 or Windows Server 2008 SP2 is applied. It also removes the files that were archived after Windows Vista SP1 was applied, if they are found on the system.

The deployment guide also states that "running this tool is optional" -- however I, personally, highly recommend it. Of course, you have to weigh this decision with the probability that you will need to uninstall SP2 -- which, in my case, is essentially "zilch."

On my x64 VMs, running COMPCLN.exe freed up roughly 800 MB of disk space. This might not seem like a lot -- given that many hard drives these days exceed 1 TB -- but it is very significant on VHDs that you are trying to keep as "lean" as possible.

Note that I'm still a little disappointed in the disk space requirements for SP2. Up until yesterday I had been running each of my domain controller VMs on 16 GB VHDs, and many of my other VMs on 20-22 GB VHDs. Note that on some of those VMs, disk space was certainly getting tight -- due to all of the patches that have been installed since I originally built them -- but they were functioning just fine until Windows Server 2008 SP2 came along. Although I have to say that on a 20 GB VHD, a WinSxS folder consuming 8-10 GB seems a little ridiculous.

I ended up having to expand the system VHD for my MOSS 2007 development VM to 25 GB -- which I really didn't want to do -- since it essentially gives the SharePoint Unified Logging System another 5 GB of free space to fill with useless log messages. [That is, of course, until I get the April 2009 Cumulative Update installed -- which supposedly fixes this issue.]

A couple of months ago, I had to SysPrep a copy of one of my VMs in order to remove dependencies on my home domain (I had to work out of the Microsoft office for a couple of days because my DSL router cratered).

However, while the SysPrep process was quick and painless, after the reboot I found that I could no longer use my domain account to administer SQL Server. Sure, I had local Administrator access, but starting with SQL Server 2005, being a local Admin no longer grants you seamless and unlimited access to SQL Server.

So the question that I had was: How do I add a user to the sysadmin role in SQL Server 2008 if all I have is local Administrator access?

Based on my experience with SQL Server 2005, I remembered this was done as part of the installation using the Surface Area Configuration wizard. However, I couldn't find the equivalent in SQL Server 2008. The SQL Server Books Online clearly stated that the Surface Area Configuration tool was discontinued, but the "Replacement" information didn't help me in the slightest.

I tried an Internet search (using both Windows Live Search and Google) for:

add sysadmin SQL Server 2008

However, neither search returned anything useful (at least not within the first two pages of results -- which is typically my threshold before I move on to a different approach to solving a problem).

Fortunately for me, I didn't have to wait long for a response to my inquiry to one of the internal discussion lists. David Browne, a Technology Architect here at Microsoft, pointed me to the following:

I wish that would have come up in my search!

I haven't blogged in almost 8 weeks. Ouch.

However, I like to think I have a good excuse -- at least for a good portion of that time.

On April 17, 2009, I broke my left leg in 6 places skiing one of my favorite runs at Mary Jane called "Outhouse." I've skied it countless times before, but the snow had been falling very heavy the previous day and into the morning, and consequently the bumps were rather "choppy" and it was just one of those fluke accidents where my ski binding did not release when it should have. Let's just say that the human ankle isn't meant to rotate 90 degrees :-(

It took two surgeries -- and a lot more metal than I'd prefer to have in my body -- to put me back together again.

In the first operation (performed the night of my accident), the surgeon attached an "external fixator" to my shin, ankle, and foot in order to hold it all in place for about a week in order for the swelling to go down.

Figure 1: Broken tibia - external fixator

See full-sized image.

In the second operation, the surgeon removed the "external fixator" and implanted an "internal fixator." Let's just say that you really don't want to be behind me in the airport security screening line.

In the last X-ray that I saw, the lower half of my left leg looks like one big metal lattice. It took the surgeon about 4-1/2 hours to complete the second surgery (an hour longer than originally planned).

Unfortunately, while the first surgery was relatively noneventful, the second was not. It involved two of the worst nights -- from a physical pain perspective -- that I've ever experienced.

The good news is that the pain is quite manageable now -- actually it has been since I left the hospital after my second surgery. The bad news is that I can't put any weight on my left leg for 12 weeks after the second operation. At least I've greatly improved my ability for going up and down stairs on crutches.

I've even been working for the past 4 weeks, rejoining a project where we are helping a large, international company deploy an Internet platform based on Microsoft Office SharePoint Server 2007. I just prop my leg up on a filing cabinet here in my home office and I'm good to go ;-)