In this article I’m going to explain the process of setting up a new Sharepoint solution project. The purpose of creating a Sharepoint solution is that it provides the most friction-free method of deploying and managing your custom Sharepoint code. The alternative method of deploying your custom assemblies is quite manual, it involves dropping your assemblies into the GAC on the server and modifying the web.config to allow your new custom web parts to be used by Sharepoint. It also means that when you build an updated assembly you have to manually delete the old one from the GAC and replace it. The trouble with this method is that you’re setting yourself up for pain in the form of manually maintaining your GAC which, trust me, isn’t worth it. If you screw something up you could potentially completely break your Sharepoint sites and if you don’t have the right assembly to hand you have no way to fix them again.
So anyway, moving on, let me show you the right way. This is process will seem pretty long, and I suppose it is, but you only have to do this once per project. It’s about as involved as setting up a continuous integration process.
So in this example I wanted to write a web part that would let me display a Flash movie in a page. The web part is very simple, so the purpose here is to demonstrate how I create the solution and package it up unto a ‘Sharepoint Solution Package’ so that Sharepoint can manage deployment and retraction of the assemblies for me.
1) I begin with an empty class library project.
2) The first thing I’m going to do is create three folders: ‘lib’ for reference assemblies, ‘WebParts’ for my web part classes, and ‘Packaging’ for package information files which Sharepoint will take heed of.
3) I need to reference the Microsoft.Sharepoint.dll in order to inherit my web part classes from the WebPart class. I can find this living on a Sharepoint server in the c:\program files\common files\microsoft shared\web server extensions\12\bin folder. I’m just going to copy that file into the /lib folder inside my project:
4) I’m also going to throw log4net in there just because I’m bound to want to use it. I add a reference to both assemblies:
5) And I go ahead and create my web part. There are loads of tutorials out there for creating web parts and that’s not the focus of this article so I’m going to gloss over it, except to say all I’ve done here is inherit from System.Web.UI.WebControls.WebParts.WebPart and overridden the Render() method:
6) Okay, now we need to add two files to the /Packaging folder: manifest.xml and package.ddf. Manifest.xml is there to describe what your package is supposed to for Sharepoint – what files to add to the server, what to do with your assemblies and what controls you want to be marked as ’safe’. It looks something like this:
<?xml version=“1.0“ encoding=“utf-8“ ?>
<Solution SolutionId=“[generated guid]“
xmlns=“http://schemas.microsoft.com/sharepoint/“>
<Assemblies>
<Assembly DeploymentTarget=“GlobalAssemblyCache“ Location=“[assembly name].dll“>
<SafeControls>
<SafeControl Assembly=“[assembly name], Version=1.0.0.0, Culture=neutral, PublicKeyToken=[public key token]“
Namespace=“[web parts namespace]“
TypeName=“*“
Safe=“True“ />
</SafeControls>
</Assembly>
<Assembly DeploymentTarget=“GlobalAssemblyCache“ Location=“log4net.dll“ />
</Assemblies>
</Solution>
The assembly name and namespace you’ll plug in yourself, the key token is obviously where you paste your assembly’s PKT, and the GUID you can just generate yourself. We’ll generate the public key token in the next step.
7) The other file is package.ddf. We need this file because a Sharepoint Solution Package file is actually a MS Cabinet file, so we use makecab.exe to create it. The package.ddf file is the script for makecab.exe to know what files to package up, where to put them in the archive, and some other meta data about it. Here’s what the contents of my package.ddf file looks like:
.OPTION EXPLICIT ; Generate errors
.Set DiskDirectoryTemplate=CDROM
.Set CompressionType=MSZIP
.Set UniqueFiles=”ON”
.Set Cabinet=on
.Set DiskDirectory1=Package
;Manifest
..\..\Packaging\Manifest.xml manifest.xml
; Assemblies
TequilaSharepointTools.dll TequilaSharepointTools.dll
..\..\lib\log4net.dll log4net.dll
So now I have the two files in my Visual Studio project:
Now the next thing I need is to generate a public key token for my assembly, and in order to do that we need to sign the assembly. That’s really straight forward and again there are tutorials all over the place for that. Just in case here are a couple of shots:
9) Cool, now to get the public key token you can just build the assembly and drop it into your GAC, then right-click on it and view the Properties. The public key token is there. OR you can follow this genius little walkthrough to add a custom external tool to Visual Studio to discover it automatically. That’s what I did so this is what the result looked like:
Now go back and paste the key token into your manifest.xml.
10) The last piece of setting up our project is adding a post-build step to run makecab.exe and generate our Sharepoint Solution Package. Open the properties for your class library project and select the Build Events tab. In the space for post-build paste the following command:
makecab.exe /f ..\..\Packaging\Package.ddf /D CabinetNameTemplate=[YourSolutionName].wsp
Substitute [YourSolutionName] for the name of your solution, mine is TequilaSharepointTools.wsp
11) Build the solution and browse to the output folder (probably /bin/debug). You should see a new folder in there called Package. Inside there’ll be a .wsp file:
12) The .wsp file is actually a cabinet file. You can prove this by changing the extension to .cab and opening the file in a program like WinRAR:
13) Now we’re ready to deploy to Sharepoint. Copy the file to your Sharepoint server and open a terminal window on the server. You’re going to run stsadm.exe which lives in the c:\program files\common files\microsoft shared\web server extensions\12\bin folder on the server. You need to run a couple of commands on it so to save yourself some sanity you should modify the path environment variable first:
path=%path%;c:\program files\common files\microsoft shared\web server extensions\12\bin
Now the first command is to add the solution to Sharepoint:
stsadm -o addsolution -filename TequilaSharepointTools.wsp
And finally, to deploy the solution to a particular Sharepoint site:
stsadm -o deploysolution -name TequilaSharepointTools.wsp -url http://lon-dean-dev3:9003 -immediate -allowgacdeployment
14) My Flash web part is now deployed to my Sharepoint site, but before I can use it I just have to do one quick thing, which is add it to the web part library. In your Sharepoint site browse to the Site Settings page and click the Web Parts link:
In the web parts gallery click the New link:
Scroll down the web part list until you find your web part. Click the checkbox…
… and scroll back up to click the Populate Gallery button.
Finally you can now add your web part to a page!
Woot. That’s the hard work done. Now that you’ve done this it’s only a hop, skip and a jump to integrate it with continuous integration, and your development experience will be nice and simple.
