Jeremy Caney

We've done quite a few SharePoint 2007 sites but this one required diving deeper into the product than previous projects, including extensive use of custom web parts, search indexes, and registration on top of the standard arsenal of master pages, layouts, XSL style sheets, web part definitions, etc.  Additionally, this was the first MOSS project for two of the team members which meant a steep learning curve for the team.  There were some valuable lessons learned.

Lesson #1: Take nothing for granted.  There are a lot of features in SharePoint that work great within certain operational constraints, but which may perform unexpectedly in different contexts.  Moving away from an NTLM authentication model is one such context that has a big impact on site functionality.  Yes, technically SharePoint supports any anonymous access as well as any ASP.NET authentication provider - but that doesn't mean that all pieces of SharePoint will work as expected.  Some examples:

• Audience Filtering.  Works, but requires authentication.  Any page including filtered content (including "All Site Users") will force the user to authenticate before viewing the page.  If you have a filtered navigation item, this effectively disables anonymous access.
• Content Query Web Part.  The CQWP redirects through a file "CopyUtil.aspx" which requires authentication [reference].  The most practical work-around is to rewrite CopyUtil.aspx.  (The CQWP's "UseCopyUtil" property almost solves this, but not quite).
• SSP Association.  When using a Shared Service Provider (SSP) MOSS should pull profile attributes (such as PreferredName, which displays in the Welcome Control) automatically.  This worked as expected, but not with all attributes.  In our case, we had to create a local Site User to act as the "glue" between the site and the SSP.
• Privacy.  By default, MOSS exposes information such as username and email address to the world.  This introduced privacy concerns when working with an internet site.  We ended up implementing a custom user profile page to mitigate this.

These "gotchas" impact scope and scheduling (discussed below) as committing to one feature can have a snowball effect on other functionality.  In our case, we ended up re-writing or tweaking a lot of out-of-the-box SharePoint features to ensure compatibility; for example, to address the limitations of audience profiling we wrote a series of custom personalization web parts that effectively replace audience filtering.

Lesson #2: Choose your friends.  Not all sources are as reliable as others.  As with most Microsoft technologies, my preference is, in order, the SDK, MSDN, MSDN Blogs, a handful of third-party bloggers and then, last, the Internet at large.  For example, setting up FBA is really quite simple - but if you rely on any number of articles posted it seems like voodoo.  You could run in circles with Dan Attis' guide (no offense, Dan), or you could just go right to the source. 

I attribute this largely to the fact that the internet includes content from previous SharePoint versions (including betas) from before Microsoft started to get its act together with the documentation - as such, you have a lot of well-intending engineers who figured out a way that worked for them and did the service of sharing it with the world.  However, this isn't necessarily the quickest, most accurate, or universal approach.  Sources like the ECM Blog tend to provide more well-rounded guidance that is thorough yet focused.

Unlike other Microsoft products, I found the Microsoft hosted forums to be completely useless. In the ASP.NET forums, for instance, developers from Microsoft regularly participate and provide insight, as do MVPs and other experienced developers. With SharePoint, however, there are a lot of questions but few answers. I feel this is partially due to the fact that there is no single authoritative community; Microsoft, for instance, maintains both a set of newsgroups as well as a set of forums – each with their own strengths and weaknesses (one supports threading, the other supports rich text), but neither with a critical mass of experts. I hope Microsoft’s SharePointPedia site will help provide a more central community of best practices for experts to share their findings.

Lesson #3: Pad your numbers.  In the last thirteen years I've gotten pretty good at estimating development projects, but I'm having to revise my formula for SharePoint.  The .NET platform, for example, is fairly predictable and well documented - it's not that there aren't bugs or unexpected behavior, but they're reasonably uncommon and when they occur are generally easy to resolve (e.g., the behavior may be different than expected or documented, but it's easy to isolate and predict).  SharePoint is like that in some areas and in other areas it's like working with a home-brewed web application that has evolved based on different development philosophies, varying degrees of documentation and a mix of available source code and black box components. There are a lot of areas which behave unexpectedly or which aren’t as mature as one might expect from a Microsoft enterprise product. 

When setting up our development environment, we ended up needing to recreate applications, zones, web sites and shared service providers multiple times because seemingly innocent changes had broad impacts. A few examples:

• Orphaned Users. There is no foreign key constraint or safety check for deleting users. So, for instance, if a user is deleted who created a page you will then be unable to view the properties for that page; SharePoint throws an error due to its inability to find the reference to that user. The fix? Modify the SharePoint backend to change the tp_id references to a known good user.  (It should be noted that Telligent's Community Server product does a much better job at this, allowing content from users to be reassigned to another user or the anonymous user).
• IIS Updates. I follow a rigid directory structure. You know those programs that allow you to change the install location, but they only honor it for half the files? That’s SharePoint. If, for instance, you create an IIS site and point the home directory to a custom location then a number of modifications in the Central Administration (such as modifying the Authentication Provider) will reset the value back to the default. You may find similar behavior with DNS entries being overwritten via the local Hosts file with cached IP data.
• Blog Lists. Create a blog, edit the page, modify the view for “My Blogs”. Where’d the title go? Good luck getting it back. This is pretty a pretty specific situation, but the pattern can be seen across the application. There are a lot of areas where SharePoint is beautifully simple: a set of predictable building blocks put together to create a variety of results. There are other areas where the behavior is unpredictable and sometimes difficult to reproduce.
• API. In general the API is fairly sophisticated and easy to use. It’s not consistent, however. In our case we had to use the web services for some things (such as creating User Profiles in the SSP, which failed via the API) and the API for other things (such as adding Site Users to groups, which failed via the Web Service); same credentials, same sites, different results.  

Conclusions: Is it worth it? Yes. It’s all part of the learning curve. As with most technologies, once you have the code written and you’ve learned the lessons you intuitively avoid the pitfalls and projects go more smoothly. In a year, we’ll have forgotten most of these lessons as we’ll simply know that when creating a custom DispForm.aspx that you must hide (not remove) the ListFormWebPart if you don’t want to mess up the integrity of the backend data bindings, or whatever the goofy exception of the day is. 

And, all said, when the content owners take over the site and are able to maintain it on their own, or when they want to add a column and it takes five minutes without the need for modifying three layers of code and running through regression tests – that’s when the full value of SharePoint becomes evident. That’s the part that we take for granted when neck deep in the idiosyncrasies of establishing the initial structure.  And, until then, it’s a trial of patience, accumulating historical data, adjusting estimating formulas and, most importantly, sharing findings and best practices with the community so that we don’t each have to individually learn these lessons the hard way.