Let it be known that Microsoft's terrible design of list paging is inexecusable and to make matters worse, the documentation is practically non-existent.  You would think that paging with a SPQuery would be a piece of cake!  I mean, I write paged data queries all the time.

NOT!

Colby Africa has a good overview of the issues and some basics that gave me some good insight into the core issues.  Of course, the difficulty with the SPQuery and paging isn't really with going forward, it's with going backwards.  One MSDN poster suggested storing the previous pages (see the last post here), which when you think about it, isn't a really good solution given the amount of paging strings you'd have to store (you can't just store the last navigation since going "Previous" twice requires going back twice).

Since going forward is the easy part, I won't get into that.  With regards to paging to previous pages, I hacked around a bit and spent a good 2-3 hours trying to deduce how the paging query string worked before I finally figured it out.

The algorithm works like so:

1. When paging FORWARD, capture the ID <AND SORT FIELD VALUE> of the first item on the newly retrieved result collection.
2. When paging BACKWARDS, use the previously captured ID <AND SORT FIELD VALUE> of the first item on the current result collection to generate the paging string.
3. Once paged BACKWARDS, capture the ID <AND SORT FIELD VALUE> of the first item on the loaded page for the next BACKWARDS operation (just leave this off of the input query if going forwards again).

By capture, I mean to store the data and persist the data somehow (perhaps in the ViewState or SessionState).

And there you have it: three simple steps

As an example, consider the following data set, sorted by Title:

ID		TITLE
---------------------------PAGE 1
17		Apple
21		Banana
18		Currant
---------------------------PAGE 2
19		Durian
5		Elderberry
1		Fig
---------------------------PAGE 3
7		Guava
10		Honey Dew
12		Indian Gooseberry

Consider a scenario where we're building a web application.  After the result set for page 3 of the data is loaded, I want to capture three pieces of data if I want to be able to load the previous page:

1. The value of the ID of the FIRST item on the page
2. The value of the TITLE of the FIRST item on the page (or whatever field you are sorting on)
3. The PagingInfo string after the query is executed

The PagingInfo is already set for paging foward again.  When I page backwards, I will need to generate a new query using the PagingInfo.  To do so, I will need to:

1. Replace the p_ID and set it to p_ID=7
2. Replace the p_Title and set it to p_Title=Guava (replace p_Title with the static name of your sort field)
3. Add two parameters:
   1. PagedPrev=TRUE
   2. PageLastRow=6 (last index of the second page, where we're going - this is easily calculated if you know your page size and your current page (keep these in the ViewState))

I used the following two regular expression patterns:

Regex _pidPattern = new Regex("p_ID=(?'pid'\\d+)");
Regex _pTitlePattern = new Regex("p_Title=[^&]+");

To replace the values in the string like so:

pagingInfo = _pidPattern.Replace(pagingInfo, 
	string.Format("p_ID={0}", firstItemId));
pagingInfo = _pTitlePattern.Replace(pagingInfo, 
	string.Format("p_Title={0}", firstTitle));

In this case, if I'm on page 3, the string for going back to page 2 should be:

Paged=TRUE&PagedPrev=TRUE&p_ID=7&p_Title=Guava&PageLastRow=6

And once I'm on page 2, the string required to go back to page 1 should be:

Paged=TRUE&PagedPrev=TRUE&p_ID=19&p_Title=Durian&PageLastRow=3

Well, actually, you don't need the string to go back to page 1; but this is just to give you the general idea.  In summary, the trick is pretty simple: you always need to store the PageInfo string for paging SharePoint queries and when you retrieve a resultset, you want to capture the ID and sort field of the first item.  When you go forward, the PageInfo string is enough.  When you go backwards, you need to use the captured pieces of info.

Hope that this has shed some light on the otherwise nebulous paging functionality with SharePoint list queries!

As I was working on an AJAX upload web part for SharePoint, I looked around to see if there was anything out there that would be suitable before I rolled my own after discovering that the ASP.NET UpdatePanel doesn't play nicely with file inputs.  Since I'm using jQuery, I figured I'd start there and see if there were any plugins which would meet the need.

To my dismay, it seems as if kids these days are all using flash (flash!) to implement asynchronous upload.  This was wholly unacceptable to me for some reason (not to mention it might cause compatibility issues for downstream clients) so I ended up tackling it myself

The basics of getting this to work are simple enough; the solution is made of three main components:

1. The main page that is displaying the upload control.  Since I was using this in a SharePoint site, I wanted to write my uploader as a web part (the control) that could be placed on any page.  The main page is simply the container for your control.  It does not post back.
2. The control that basically just renders the <iframe/>.  The control is relatively simple.  It provides a container for the <iframe/> and also the scripts which are executed when the frame is loaded and unloaded.  The control also holds the progress layer since we want this to be shown when the user starts the upload.   This also does not post back.
3. The upload page that receives the actual file.  This page is the target for the <iframe/> and contains the logic that validates the posted file.  This is the only page that posts back.

Before we go into the details, let's look at the screens of this in action (pay particular attention to the times):

The first screen shows the general layout of the page in the default state.  In case you're wondering, I found a handy guide for hacking the file input control and used that to customize the appearance.  Again, note the time.

Once you click "Upload", a progress layer is shown over the control.  You can also see that we've got an unloaded time now as well.

And finally, you can see that the loaded time changed once the form upload completes.

The control ASCX file contains two very simple scripts:

    function handleFrameLoaded() {
        // Do animation here.
        $("#progress").hide();
        
        $("#load").html("<b>Loaded!</b> " + 
            (new Date()).toTimeString());
    }

    function handleFrameUnloaded() {
        // Do animation here.
        $("#progress").show().fadeTo("fast", .90);
        
        $("#unload").html("<b>Unloaded!</b> " + 
            (new Date()).toTimeString());
    }

The first function is called when the frame is loaded and the second function is invoked when the file upload is submitted.  Note that both functions are called from the upload page in the <iframe/>.  In this case, I've just added simple animation calls to show and hide a progress panel.  You can hook up whatever custom code you want here.

On the upload page itself, we need to wire the events to the functions above:

    $(window).load(function() {
        parent.handleFrameLoaded();
    });

    $(document).ready(function() {
        $(".upload-button").click(function() {
            parent.handleFrameUnloaded();
        });

        /* simulate hover */
        $("#fake-container").hover(
            function() {
                $(this).addClass("hover");
            },
            function() {
                $(this).removeClass("hover");
            });

        /* simulate populating the file value since 
            we can't see the file input */
        $("input.file").change(function() {
            $("#fake input").val($(this).val());
        });
    });

It's important to note that the upload page gets its own set of window events since it's loaded inside of the frame.  The upload page makes calls to functions in the control.  I've highlighted the points of interest; you'll note that I only bind the load event of the window (I don't bind the unload).  It's also possible to do this using the onbeforeunload event, but I found that this would fire the progress layer even if I was browsing away from the page (which may confuse your users).  So it made more sense to just do it simply from the upload button click.

The upload page itself is remarkably simple:

<body>
    <form id="_form" runat="server">
    <div>
        <div id="fake-container">            
            <input type="file" id="_file" runat="server" class="file"/>            
            <div id="fake">
                <input type="text" />
            </div>            
        </div>
        <asp:Button runat="server" ID="_upload" 
            Text="Upload" OnClick="HandleUploadClick" 
            CssClass="upload-button"/>
    </div>
    </form>
</body>

The control isn't much more complex either:

<div id="frame">
    This is an asynchronous upload control.  
    The control load time is <asp:Label ID="_time" runat="server"/>

    <iframe id="upload-frame" src="Upload.aspx" 
        frameborder="0" scrolling="no" height="100px">

    </iframe>  
    <div id="progress" style="display:none;"></div>
</div>
<div>
    <div id="load"></div>
    <div id="unload"></div>
</div>

There's no codebehind for the control to speak of. The only place where you need to implement custom code is in the codebehind of the upload page to receive the posted file:

using System;
using System.Threading;
using System.Web.UI;

namespace AsyncUploadControlTest
{
    /// <summary>
    /// This is the actual page that handles the upload.
    /// </summary>
    public partial class Upload : Page
    {
        /// <summary>
        /// Handles the Load event of the Page control.
        /// </summary>
        /// <param name="sender">The source of the event.</param>
        /// <param name="e">The <see cref="System.EventArgs"/> 
        /// instance containing the event data.</param>
        protected void Page_Load(object sender, EventArgs e)
        {
            
        }

        /// <summary>
        /// Handles the upload click.
        /// </summary>
        /// <param name="sender">The sender.</param>
        /// <param name="e">The <see cref="System.EventArgs"/> 
        /// instance containing the event data.</param>
        protected void HandleUploadClick(object sender, EventArgs e)
        {
            // Just fake a long running upload for dramatic effect
            Thread.Sleep(2500);

            // Add your logic here
        }
    }
}

There you have it. Works in SharePoint 2007 just fine.  Works in IE7 and Firefox 3.5 as well.  Because the receiving upload page is just an ASPX page, you can simply output your errors or success messages to the page itself; no special hackery required.

Download the source code here: AsyncUploadControlTest.7z (17.54 KB)

One of the cool features of SharePoint 2010 is the simplification of content type management/synchronization.

In SharePoint 2007, site collections formed a metadata boundary meaning that content types defined in one site collection could not be used in another site collection without redeploying the content type to the other site collection.  This works well enough if you are using features to deploy your content types (and I mean, who isn't!?), but what about managing those content types and keeping them synchronized after you've deployed them?

Nightmare.

While it's relatively easy to set up, I came across an immediate error when trying to publish my first content type:

Using the correlation ID, I looked through the logs and found the following:

No proxy associated with the site http://metadata.dev.com
recognizes the site as a hub site d4d22525-2e9d-4ea4-becc-fe1d42735ee4 

A user failed to publish or unpublish a content type
Microsoft.SharePoint.Taxonomy.ContentTypeSync.ContentTypeSyndicationException:
No valid proxy can be found to do this operation.

I came across Chakkaradeep Chandran's instructions here, but his instructions seemed to have a small gap.

To access the functionality, you need to go to Central Administration -> Application Management -> Manage service applications (under Service Applications)

In this screen, select (don't click the link) Managed Metadata Service.

Again, very important: don't click the link (that takes you to the screen for managing keywords/terms/taxonomy; click somewhere next to the text and select the row to enable the Properties button at the top.

Next click Properties:

This will bring up the pane where you can set the Content Type hub setting (scroll to the bottom of the screen).  Just enter the URL of your hub application (as an example, http://metadata.dev.com)

Next, you need to select the Managed Metadata Service Connection (the indented Managed Metadata Service) and again, click Properties.  This brings up the pane that will allow you to check the Consumes content types from the... setting.

As Chakaradeep mentions, you need to run two timer jobs to get the content types to sync up.  You can access this via Central Administration -> Check Job Status (under Monitoring):

Then page through that list looking for Content Type hub and Content Type subscriber.  Clicking on the link to the job will open it up and allow you to click the Run now button to execute the job immediately.

In any case, it's a neat feature.  I wonder, though, if there are improvements for managing deployment of content types via features (i.e. an incremental feature which adds new fields to exsiting content types and pushes the changes down) as opposed to UI based management of content types (which I'm not a terribly big fan of).  My guess is "no".

Hope this helps someone!

Well, spent the good amount of time trying to figure this out.  See the configuration info below from my trac.ini file.

[mimeviewer]
max_preview_size = 262144
mime_map = text/x-dylan:dylan,text/x-idl:ice,text/x-ada:ads:adb,
php_path = php
pygments_default_style = trac
pygments_modes = text/x-csharp:csharp:7,text/plain:aspx-cs:7
tab_width = 4
treat_as_binary = application/octet-stream,application/pdf,application/postscript,application/rtf

Oh yeah, it helps if you actually install Pygments, too.

In the previous entry, we looked at how we can model a SharePoint list item using a more domain specific model to simplify programmatic access to the list item thus reducing otherwise error prone data access code and making the overall framework easier to use.  Again: the idea is to promote reuse and decrease complexity through domain specific code that abstracts the underlying SharePoint object models, making it easier for a team to build functionality on top of this framework.

One interesting point is that if you're already building your fields and content types using features XML, the work required to generate the domain specific wrappers can be simplified dramatically using automation.  In a sense, a content type is basically a class (this is generally how I map them in my domain design); why double your effort and write both the content types and the classes?

So how do we go about this?

(Side note: this isn't so much a "design pattern" as it is an "implementation pattern")

As an example, here is a simple XML file which defines a set of fields and content types which use those fields:

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field DisplayName="Model Code"
    Name="Model_Code"
    StaticName="Model_Code"
    ID="{F0000000-0000-0000-0000-000000000001}"
    Type="Integer"
    SourceID="http://schemas.someusedcarinventory.com"
    Group="My Custom Columns"/>
  <Field DisplayName="VIN"
    Name="VIN"
    StaticName="VIN"
    ID="{F0000000-0000-0000-0000-000000000002}"
    Type="Text"
    SourceID="http://schemas.someusedcarinventory.com"
    Group="My Custom Columns"/>
  <Field DisplayName="Make"
    Name="Make"
    StaticName="Make"
    ID="{F0000000-0000-0000-0000-00000000003}"
    Type="Text"
    SourceID="http://schemas.someusedcarinventory.com"
    Group="My Custom Columns"/>
  <ContentType Name="Vehicle"
    ID="0x0100FC000000000000000000000000000001"
    Description="Used car inventory"
    Group="My Custom Content Types" >
    <FieldRefs>
      <FieldRef ID="{c042a256-787d-4a6f-8a8a-cf6ab767f12d}" Name="ContentType" />
      <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Name="Title" 
        Required="TRUE" ShowInNewForm="TRUE" ShowInEditForm="TRUE" />
      <FieldRef ID="{F0000000-0000-0000-0000-000000000001}" Name="Model_Code"/>
      <FieldRef ID="{F0000000-0000-0000-0000-000000000002}" Name="VIN"/>
      <FieldRef ID="{F0000000-0000-0000-0000-000000000003}" Name="Make"/>
    </FieldRefs>
  </ContentType>  
  <Field DisplayName="Dealership Code"
    Name="Dealership_Code"
    StaticName="Dealership_Code"
    ID="{F0000000-0000-0000-0000-00000000004}"
    Type="Integer"
    SourceID="http://schemas.someusedcarinventory.com"
    Group="My Custom Columns"/>
  <Field DisplayName="Dealership Fax Number"
    Name="Dealership_Fax_Number"
    StaticName="Dealership_Fax_Number"
    ID="{F0000000-0000-0000-0000-00000000005}"
    Type="Text"
    SourceID="http://schemas.someusedcarinventory.com"
    Group="My Custom Columns"/>
  <ContentType Name="Dealership"
    ID="0x0100FC000000000000000000000000000002"
    Description="Dealerships"
    Group="My Custom Content Types" >
    <FieldRefs>
      <FieldRef ID="{c042a256-787d-4a6f-8a8a-cf6ab767f12d}" Name="ContentType" />
      <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Name="Title" 
        Required="TRUE" ShowInNewForm="TRUE" ShowInEditForm="TRUE" />
      <FieldRef ID="{F0000000-0000-0000-0000-000000000004}" Name="Dealership_Code"/>
      <FieldRef ID="{F0000000-0000-0000-0000-000000000005}" Name="Dealership_Fax_Number"/>
    </FieldRefs>
  </ContentType>    
</Elements>

When approaching this problem, I considered three ways of handling the class file generation:

1. Use an object model and StringTemplate to create .cs files.  This invovled writing POCO classes (or generating them from the schema) which I could deserialize the XML to and then passing those objects to a template instance.  This seemed like too much work, given that I really didn't feel like maintaining all of that code as well.  Plus, while StringTemplate isn't - by any sense of the imagination - hard, it is a non-standard syntax that someone would have to learn to maintain and/or extend the conversion.
2. Use an XDocument and CodeDom to create .cs files.  This seemed like even more work!  While it's framework supported, I feel like this solution would be hard to extend and maintain for most developers.
3. Use an XSL transform to create .cs files.  This seemed to be the most natural solution given that the source file is already in XML format and a the target content structure is far from complex (the basic class file is fairly simple).  Plus, while XSLT isn't trivial, it's not that hard either (and the syntax is "standard").

One of the cool features of XSL 2.0 is the xsl:result-document element which allows you to create multiple documents from one source document.  Only one problem: .NET's XSLT engine doesn't implement XSLT 2.0!  What a bummer; it seemed like if I wanted to get this to work and generate multiple output files, it was going to take some work in code or find an XSLT 2.0 capable processor.

Enter Saxon, which provides an XSLT 2.0 processor for .NET.  The following code takes the XML above and uses the xsl:result-document to create two class files, one for each content type:

using System;
using System.IO;
using Saxon.Api;

namespace FeatureToClass
{
    internal class Program
    {
        private static void Main(string[] args)
        {
            Uri xmlFile = new Uri(
                @"C:\Users\Charles\Desktop\elements.xml");

            // Create a Processor instance.  
            Processor p = new Processor();

            // Load the source document.  
            XdmNode node = p.NewDocumentBuilder().Build(xmlFile);

            using (Stream stream = File.OpenRead("core-transform.xslt"))
            {
                // Create a transformer for the stylesheet.  
                XsltTransformer transformer = 
                    p.NewXsltCompiler().Compile(stream).Load();

                // Set the root node of the source document
                // to be the initial context node.  
                transformer.InitialContextNode = node;

                // BaseOutputUri is only necessary for xsl:result-document.  
                transformer.BaseOutputUri = xmlFile;

                transformer.SetParameter(
                    new QName("ct", "http://www.customtransform.com", "namespace"), 
                    new XdmAtomicValue("My.Custom.Package"));

                // Create a serializer.  
                Serializer serializer = new Serializer();
                transformer.Run(serializer);
            }
        }
    }
}

The code above is a simple console program that takes a (hardcoded) path to a source XML file (a SharePoint elements.xml file) and (hardcoded) namespace and loads an XSL file to transform the XML to C# class files.

Here's the transform (it's a bit messy for output formatting reasons, so you're best off copying it into an XML aware text editor to get a better view):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE stylesheet [
    <!ENTITY space "<xsl:text> </xsl:text>">
    <!ENTITY cr "<xsl:text>
</xsl:text>">
]>

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:sp="http://schemas.microsoft.com/sharepoint/"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:functx="http://www.functx.com"
  xmlns:ct="http://www.customtransform.com"
  version="2.0">
    <xsl:param name="ct:namespace"/>
    <xsl:output method="text"/>

    <xsl:template match="/">
        <xsl:for-each select="//sp:ContentType">
            <xsl:variable name="classname" select="replace(@Name, ' ', '')"/>
            <xsl:variable name="filename" select="concat($classname,'.cs')" />
            <xsl:value-of select="$filename" />
            <!-- Creating  -->
            <xsl:result-document href="{$filename}">
using System;

    namespace <xsl:value-of select="$ct:namespace"/>
    {
        public partial class <xsl:value-of select="$classname"/>
        {
            private string _contentTypeId;
            
            public string ContentTypeId {
                get { return _contentTypeId; }
                set { _contentTypeId = value; }
            }

            public <xsl:value-of select="$classname"/>()
            {
                _contentType = "<xsl:value-of select='@Name'/>";
                _contentTypeId = "<xsl:value-of select='@ID'/>";
            }

            <xsl:apply-templates/>
    }
}
            </xsl:result-document>
        </xsl:for-each>
    </xsl:template>

    <!--///
        Templates
    ///-->
    <xsl:template match="sp:FieldRef">
        <xsl:variable name="fieldname" select="functx:lower-first(replace(@Name, '_', ''))"/>
        <xsl:variable name="fieldid" select="@ID"/>
        <xsl:variable name="dotnettype">
            <xsl:choose>
                <xsl:when test="//sp:Field[(@ID = $fieldid) and (@Type = 'Integer')]">int</xsl:when>
                <xsl:otherwise>string</xsl:otherwise>
            </xsl:choose>
        </xsl:variable>

        private <xsl:value-of select="$dotnettype"/> _<xsl:value-of select="$fieldname" />;
        <xsl:call-template name="attribute"><xsl:with-param name="fieldid" select="$fieldid"/></xsl:call-template>
        public <xsl:value-of select="$dotnettype"/>&space;<xsl:value-of select="replace(@Name, '_', '')"/>
        {
            get { return _<xsl:value-of select="$fieldname" />; }
            set { _<xsl:value-of select="$fieldname" /> = value; }
        }
    </xsl:template>

    <xsl:template name="attribute">
        <xsl:param name="fieldid"/>
    <xsl:if test="exists(//sp:Field[@ID = $fieldid]/@ID)">[Caml(Id="<xsl:value-of select='//sp:Field[@ID = $fieldid]/@ID'/>", StaticName="<xsl:value-of select='//sp:Field[@ID = $fieldid]/@StaticName'/>", Type="<xsl:value-of select='//sp:Field[@ID = $fieldid]/@Type'/>")]</xsl:if></xsl:template>


    <!--///
        Custom functions
    ///-->
    <xsl:function
        name="functx:lower-first" as="xs:string"
        xmlns:functx="http://www.functx.com" >
        <xsl:param name="arg" as="xs:string"/>
        <xsl:sequence select="concat(lower-case(substring($arg,1,1)), substring($arg,2))"/>
    </xsl:function>
</xsl:stylesheet>

I borrowed one function from the FunctX library to create the camelCased field names.  The XSL probably isn't nearly as clean or optimized as it should be (my XSL is admittedly a bit rusty), but it gets the job done.  Here's one of the two classes (and class files) which get generated at the source directory of the input XML file:

using System;

namespace My.Custom.Package 
{
    public partial class Dealership
    {
        private string _contentTypeId;
        public string ContentTypeId {
            get { return _contentTypeId; }
            set { _contentTypeId = value; }
        }   

        public Dealership()
        {
            _contentType = "Dealership";
            _contentTypeId = "0x0100FC000000000000000000000000000002";
        }
                        
        private string _contentType;
        public string ContentType
        {
            get { return _contentType; }
            set { _contentType = value; }
        }      

        private string _title;
        public string Title
        {
            get { return _title; }
            set { _title = value; }
        }
    
        private int _dealershipCode;
        [Caml(Id="{F0000000-0000-0000-0000-000000000003}", 
            StaticName="Dealership_Code", Type="Integer")]
        public int DealershipCode
        {
            get { return _dealershipCode; }
            set { _dealershipCode = value; }
        }
    
        private string _dealershipFaxNumber;
        [Caml(Id="{F0000000-0000-0000-0000-000000000004}", 
            StaticName="Dealership_Fax_Number", Type="Text")]
        public string DealershipFaxNumber
        {
            get { return _dealershipFaxNumber; }
            set { _dealershipFaxNumber = value; }
        }
    }
}

Awesome!  It's amazing how little code was required to get this basic scenario working.

Now we have a single source which defines our SharePoint artifacts and our code artifacts; I love it.  Write your fields and content types in your feature and you get class files for free!  You'll note that I've added a simple CamlAttribute where applicable.  This will prove handy when it comes time to automate construction of the object instance from a SharePoint list item, which we'll look at next time (for the time being, feel free to modify the XSL and remove the line for it or write an implementation of CamlAttribute).

Again, to reiterate: the goal is make it easy to build applications on top of a SharePoint deployment by adding a layer of domain specific APIs and objects so that a team can be productive while reducing duplication and the ramp up time required to understand the business domain. 

Other points for improvement and enhancement (look for these in a future installment):

1. Parameterize the program.
2. Consider making it a Visual Studio add-in or a custom tool.
3. Make it go the other way; in other words: generate the content type and field XML from class files (which would be cool, too).

But even as it is, it's incredibly useful.  On the next installment, we'll see how we can build more intelligence into the model and make it more useful.

I've been working on setting up a VM to play around with SharePoint 2010 and kept running into a weird issue where I would be prompted for my credentials repeatedly and I was denied access to the site entirely, even when using an administrator account.

I had set up my SharePoint web application using a host header; for example, beta.dev.com.

Meanwhile, I was able to access the same site from my host environment without any issue.  What gives?  Turns out that there is a slight registry tweak you have to make when working with host headers and IIS.

Phil Harding has a good writeup with links to the Microsoft KBs and additional details.

As I've been working with a client which has demanded rigorous sequence diagrams as deliverables for the design phase of the project, I've started to use WebSequenceDiagrams.com more and more.

I've blogged about it previously, but I've only come to truly appreciate it after having to use Visio for a few days before I convinced the client that I could deliver the content faster and in an easier to maintain format (well, text) using WSD. 

What Visio Gets Wrong

I ran out of connection points.  Yes, it's possible; for a long activation sequence, you can actually run out of connection points.  One could argue that this calls for a refactoring of the diagram in the first place, but then I would say that you've never tried to actually refactor a Visio diagram...I still find it hard to believe: the activation box ran out of connection points; I wouldn't have believed it if I didn't see it myself:

I kept having to resize the page.  By default, you can't really fit much on the page.  But as I started to build my sequence up, I found that I had to keep toggling around with the paper size just so that I would have a grid.  This was annoying since it also involved then zooming out so that I could select everything and reposition it to the top left corner of the page then zooming back in.  You'd think that Visio would be smart enough to do this, but it isn't...

I kept having to move elements around.  Want to add a new step?  What about introducing a new actor in between two existing actors?  Prepare for some carpal tunnel my friend.  There's simply no easy way to do it aside from zooming out, grabbing everything to the right and shifting it around while counting gridlines and getting your result some 10-20 clicks later.  What's worse is that you end up having to scroll around horizontally (reordering actors) and vertically (reordering steps) while dragging a bunch of stuff around.

I kept having to fix connection lines.  This was absolutely mindboggling: if I extended an activation, it would cause the first connection on the activation to jump, which would then require me to manually drag the connection back to where it belonged.  I probably spent a good 10% of my time simply fixing these connection points as a adjusted activations:

This is an incomprehensible design flaw; I have no idea how people work around this in Visio since I adjust activations multiple times as I'm working through a diagram.

There was no representation of alternate paths or optional steps.  I ended up having to draw a rectangle and manually managing the size of it as I changed steps and added more steps.  What made this even more annoying was that having the rectangle, even though I sent it to the back, then made it difficult to select elements that were enclosed by the rectangle like a message line or a connection point or a note; I'd end up selecting this stupid rectangle instead.

I had to keep managing the location of notes.  The notes don't seem to anchor to anything and it's not clear to me how that's supposed to work.  That meant that I had to keep moving notes around as I changed activations and modified connection points.

The lifelines didn't synchronize.  For the life of me, I couldn't figure out how to get the lifelines to synchronize in length so I didn't have to manually go back and drag each one down to the same length.  You can't actually CTRL+click two lifelines, as one would think you'd be able to do, and drag them both to extend them simultaneously.  I mean, this seamed like pretty basic stuff to me.

So yeah, all in all, I'm not sure why anyone would want to subject themselves to the pain of creating sequence diagrams in Visio.  Maybe if it's a final product and you don't plan on touching it ever again and you've already done most of the work on paper or something, but it's a terrible tool if you're just trying to think an idea out and see it visually.

What WebSequenceDiagrams.com Gets Right

I can't speak to the console program or the DLL (yet), but I decided that the only way that I could do this right was to do it in WSD first and then just use Visio to render the final output.  While doing it in the browser is fine, I found it much easier to do it in EditPlus, my text editor of choice.

The first step was to create a syntax and auto-complete file so that it was a little more user-friendly.

Here's my .stx syntax file:

#TITLE=WSD

#DELIMITER=,(){}[]+*%/="'~!&|<?:;.
#QUOTATION1="
#LINECOMMENT=note
#CASE=y

#KEYWORD=Activate
activate

#KEYWORD=Deactivate
deactivate
destroy

#KEYWORD=Alias
as
participant

#KEYWORD=Notes
note
over
right
left

#KEYWORD=Control
alt
else
end
opt

#KEYWORD=Newline
\n

#KEYWORD=Transition
->
-->
#

And my .acp auto-complete file:

#TITLE=WSD

#CASE=y

#T=act
activate ^!
#T=de
deactivate ^!
#T=pa
participant ^!
#T=alt
alt ^!
    
else
    
end
#T=opt
opt ^!
	
end
#

What I get from this is:

I know what you're thinking: Chuck, that looks like code!  By golly, it does!  And -- at least to me -- that's the beauty; all of a sudden, a frustrating, time consuming, mouse-centric activity becomes a keyboard-centric, coding-like activity.  Moving objects around becomes a matter of moving lines of text.  Reordering actors involves moving your participant declarations around.  Notes stay in their context if you add a step since everything gets pushed down.  There's no manual resizing of anything.  There's no fixing connection points.  There's no stupid.  It actually makes working with sequence diagrams, beyond just whiteboarding, much more useful and much more productive as it lets you kind of think out the code by actually writing pseudocode.

I highly recommend downloading EditPlus (you can keep using it for free, perpetually, if you're a cheap bastard or pony up the $20 for such an awesome editor).  For me, EditPlus is a perfect pairing for WSD due to the easy to create language syntax/autocomplete files and the handy split-document feature so you can easily reference your participants at the top.

Simply create a new file type and add the .stx and .acp files I defined:

Now the downside of this whole affair is that you have an extra step of having to copy out the text and pasting it into the browser, but even with that extra little bit of annoyance, the time and frustration saved over working with Visio is more than worth it.

The next step, once I get my hands on the command line tool, is to hook it up to the external tools feature of EditPlus for a quick hit.  I'm also considering writing an integration for Visual Studio for custom rendering within VS or at least something quick-and-dirty like an add-in.

One additional note is that WSD has an HTML/Javascript API whereby you can render a diagram inline with your HTML by simply using a set of <pre></pre> tags and a reference to a Javascript file.

What's cool about this is that now you can use the standard CTRL+B/CTRL+E shortcut keys to preview without a copy/paste step!  For free!  That's pretty awesome.

Of course, the downside is that using this method, there is a limit to the size of the sequence that you can send up as well as the fact that you need some additional hijinks to make the syntax highlighting work (I gave up on that part ) .  But if were doing it in the browser to begin with or using notepad and you don't care for the syntax highlighting, then this is a huge upgrade.

Conclusion: stop using Visio Now I'm just looking forward to WebERDiagrams.com, WebStateMachineDiagram.com, and....well, you get the idea.

My EditPlus .stx and .acp files for anyone that wants 'em: wsd-files.zip (.52 KB)

Cool story because Galileo is one of my top 5 scientists:

(CNN) -- Two fingers cut from the hand of Italian astronomer Galileo nearly 300 years ago have been rediscovered more than a century after they were last seen, an Italian museum director said Monday.

Removing body parts from the corpse was an echo of a practice common with saints, whose digits, tongues and organs were revered by Catholics as relics with sacred powers.

There is an irony in Galileo's having been subjected to the same treatment, since he was persecuted by the Catholic Church for advocating the theory that the earth circles the sun, rather than the other way around. The Inquisition forced him to recant, and jailed him in 1634.

The people who cut off his fingers essentially considered him a secular saint, Galluzzi said, noting the fingers that were removed were the ones he would have used to hold a pen.

"Exactly as it was practiced with saints of religion, so with saints of science," Galluzzi said. "He was a hero and a martyr, keeping alive freedom of thought and freedom of research."

Very awesome.

If you've deleted the DLL or if you reinstalled a DLL which no longer contains the codebehind class for a user control in a web part, you could end up in a scenario where you have a "dead" web part on the page.  In my case, it prevented the page from loading and resulted in an error because it couldn't load the type.

Don't panic!  The solution is to add a ?Contents=1 to the URL (i.e. http://moss.dev.com/default.aspx?Contents=1), which will allow you to delete the web part from the page.

UML is a useful tool, no doubt.  It's a tool to help model complex logic in a visual manner.  It's a language in and of itself and it can aid in communicating design ideas with exacting precision, leaving little room for error.  However, at the same time, as with any formal language, it creates strict rules for communicating in that language.  Syntax, vocabulary, "grammar"...these all apply to propperly using UML.

Myself, I've never been a big fan of UML.  There are different ways to convey ideas, intent, and understanding of a set of requirements, but imposing UML is like asking a blogger to write all of their posts in iambic pentameter when prose would work just as well.  What's the point?  Your colleagues can already all read English, but not everyone reads UML...why add that burden and rigor?

There's a big difference between the rigor required to build a bridge and the rigor required to build a web application.  Miss your target by a foot, and it's a multi-million dollar mistake if you're building a bridge.  If your bridge throws you an "unexpected exception"? You're talking possible risk of life!  A web application or a portal?  Unless there are fundamental, framework level mistakes, most changes are negotiable; it's software for a reason (and oddly enough, on large projects, the cost overhead isn't necessarily associated with the development side, but with the business side and the specific processes for validation, testing, and change management - maybe those guys need to fix their processes...).

Now this isn't to say that getting it right isn't important, but at some point, process and progress starts to drag as you impose an inordinate amount of rigor. 

With regards to sequence diagrams, Scott Ambler puts it very well:

The most important things that you can do is to keep your diagrams simple, both content wise and tool wise.  I will sketch sequence diagrams on whiteboards to think something through, either to verify the logic in a use case or to design a method or service.  I rarely keep sequence diagrams as I find their true value is in their creation.   

A common mistake is to try to create a complete set of sequence diagrams for your system.  I’ve seen project teams waste months creating several sequence diagrams for each of their use cases, one for the basic course of action and one for each alternate course.  My advice is to only create a sequence diagram when you have complex logic that you want to think through – if the logic is straightforward the sequence diagram won’t add any value, you had might as well go straight to code.

I agree wholeheartedly; the exercise itself is more important than the final artifact.  It's far too easy to interpret the intent of UML incorrectly; the value is not the artifact, the value is the process.

At the end of the day, it is not a silver bullet! It doesn't make your design more complete.  It doesn't mitigate all of the risk.  It doesn't make your intent free from misrepresentation or misinterpretation.  It doesn't make a design document bulletproof.