Peter Seale's weblog

Tuesday, August 19, 2008 8:00:31 AM UTC 

One of my friends is starting his first SharePoint project, and I had a few words of advice for him. He doesn't know exactly what his project entails, I don't know what his project entails, but we will start with the following assumption:

The following advice assumes that we are working on a small-to-medium sized, line-of-business application, possibly something attached to a traditional portal (i.e. intranet). We are not working on a BI project, not rolling out an entire enterprise intranet, not creating a publishing site (WCM), not even doing formal records management.

First tip: Read this other guy's post on the subject

I found an excellent post by Mark Jones written mid-2007, which is ancient history in SharePoint terms. If you can't be bothered to read both his post and mine, choose his: Mark Jones on SharePoint projects (original post disappeared, this is a link to the post in my Google Reader)

Second tip: Use either WSPBuilder or STSDEV in Visual Studio

It is well known that no one really uses the Microsoft-created Visual Studio Extensions for Windows SharePoint Services (VSeWSS). Well, no, if everyone already knew, then I wouldn't be writing here, would I now?

So let's start with a fresh mind. You're new to SharePoint, and you need to do … something, let's say change the PDF icon that appears in document libraries on your SharePoint farm. Terrible example, I know!

I'll assume you have rudimentary knowledge of SharePoint's Solutions and SharePoint's Features. If not, read up on it, there are intro books and articles out the wazoo. I'm not going to into depth here; read up on Solutions and Features elsewhere.

Moving along.

So you fire up Visual Studio. You've already installed VSeWSS, and now you've got this "SharePoint" tab in Visual Studio, and you click on it.

I'm not here to only throw rocks; I'm here to say that, unless you want to endure a great deal of pain, don't stick with only VSeWSS.

You have alternatives:

• WSPBuilder via the WSPBuilder extensions
• STSDEV
• "Naked" class library project with WSPBuilder as a post-build task
• "Naked" class library project with MAKECAB (!!!) as a post-build task/MSBuild task

To the initiate, to the untrained eye, these are all equally good options. They're not. Let's work through the list again, this time with a critical eye:

VSeWSS - Visual Studio Extensions for Windows SharePoint Services 1.2

You're going to have to install this as it is the easiest way to get the SharePoint-specific Workflow activities. Otherwise, don't use it. Search for others' complaints about VSeWSS; general consensus is that it's okay, but painful.

STSDEV - a proof-of-concept utility

Link to STSDev project home 

Contrary to the aggravating unnecessary disclaimer prominently displayed on the CodePlex project home page, STSDEV can be useful in actual, real-life projects! Shh, don't tell anyone, they might figure it out!

Aside from my nitpicking, this is a good tool.

• Generates the Solution manifest.xml for you, for limited scenarios
  • In fact, generates an entire project skeleton. This includes the feature.xml manifest, something for which you'll be thankful if you're learning the ropes.
• Builds your Feature event receivers for you
• Screencasts on how to use it! Ted Pattison is an excellent communicator and presents three screencasts, available from the 1.2 (previous release) page on CodePlex.
• In other words, STSDev is a good way to start off a new project, assuming it has a template for the thing you're trying to build. I don't use this as I've pretty much settled with WSPBuilder, but acknowledge it's a good solution, and will definitely use it in the future if I find STSDev has something WSPBuilder lacks.

WSPBuilder extensions

Link to WSPBuilder project home

The WSPBuilder Extensions are relatively new—they add Visual Studio project templates, quick shortcuts, and WSPBuilder-specific item types. LIke the WSPBuilder command-line tool, the WSPBuilder Extensions also completely eliminate the pain of Solution packaging.

• WSPBuilder project template is a real, new Visual Studio project template. It saves you the trouble of manually configuring your Visual Studio project to work with SharePoint; stuff like making a .snk file, adding a "Build WSP/deploy/upgrade/uninstall" option to your project (further note: uses SharePoint object model directly for faster performance); and other little bonuses (see screenshot above).
• Downside: Unlike STSDev, you're locked into WSPBuilder Extensions once you start using the Project Template. I'm not worried, because I would feel comfortable switching the project over to a raw class library, but you may be allergic to dependencies like this.
• New Item templates (like "Web Service") - I haven't tried these, nor have I heard reports of how well they work; so I'll just say—try them out, if they work for you, great; if not, definitely don't use them.
• Assuming you arrange your artifacts in the correct directory structure, WSPBuilder will eliminate the pain of building Solutions. See my review of WSPBuidler.exe below for more details on what this does.

WSPBuilder.exe - command-line tool only

Link to WSPBuilder project home

In ye olde days, as far back as almost a full year ago, we were not blessed with either STSDev or WSPBuilder Extensions. We made do with what we had; WSPBuilder.exe.

WSPBuilder.exe is great because it is focused: it does one thing, and it does it very well. What is that one thing, you may ask?

It eliminates the pain of Solution packaging. That's all it does. To be honest, I don't even know how to build a Solution manifest XML file, and I attribute my brazen, unashamed ignorance to WSPBuilder. I don't need to know because WSPBuilder takes care of that for me.

The pain begins, however, with the rest of your project. WSPBuilder Extensions address some of this pain, and I recommend you start with WSPBuilder Extensions for new projects, but you'll find many projects that were started during the "WSPBuilder-only" era. Don't make fun of these old projects; we can only hope someday that we will be able to look back and say "what primitive tooling we had in 2008!" Just like you're wont to do when you see a project that uses WSPBuilder.exe or MAKECAB.exe to build its Solutions. We can only hope the tooling improves.

If you want to see a simple example of how to work WSPBuilder.exe into your Visual studio project, I demonstrate one way of doing this in my terrible CodePlex project. F5 is my build, and I'm (almost) unashamed!

Raw MAKECAB.EXE

This seems to be the preferred method for the "old school" SharePoint experts who have been around. I assume that, for them, they have learned how to use MAKECAB.exe and build their own Solution manifests. Ugh. Ultimately if you know what you're doing, this is as good as any other way, but for the first-time SharePoint developer, this isn't a good option. I want to point out MAKECAB's existence because the MSDN-sponsored articles and project templates all rely on MAKECAB.EXE. You don't have to listen to those articles; save yourself some pain and pick something else. There are far better alternatives to hand-crafting your own Diamond Directive Files and hand-crafting your own Solution manifests. Look around; better ways of doing this exist!

Recap

Both WSPBuilder Extensionss and STSDev are good solutions for the budding SharePoint developer; they both provide some tools to help you create and build SharePoint projects in Visual Studio. They are in no way complete tooling; you will still experience pain, but they both help greatly. Try both out, choose one and go.

Just don't stick with only VSeWSS or only MAKECAB; save yourself some pain and choose one of the alternatives.

MORE TO COME!

This post has gotten ridiculously long, and I barely just compared the major competing developer tools! We're nowhere close to done; more posts to follow on this subject.