How To Build a Solution Pack (WSP)

Hey All,
This is a pretty huge topic, so in order to stick it into one post I'm going to break it down into sections. In the next few posts I will be going over building a WebPart solution pack, Feature Solution Pack, and provisioning files to various parts of the 12 Hive. The items out of scope include the building of the components that we are deploying, these will be discussed in a later post.

Let's get started:

To deploy a custom WebPart we'll need a few things:

1. Web Part dll
2. WebPart manifest file
3. WebPart Feature
4. Solution Manifest
   

These items are necessary for us to build a successful webpart solution Pack. For starters I'll be assuming that you at least have the webpart dll, I will walk through the building of the web part manifest and Feature.

For starters let's create a solution folder that's going to host our webpart solution, so create a folder named "TitleWPSolution".

Building the WebPart Manifest

The webpart that we'll be deploying is a "Title" webPart, this webpart shows the title of the current site it's placed on. We'll assume that this webpart is built, so let's create the correlating webpart file. Create a file named "TitleWP.webpart", for now you can place this file in the root of the solution folder. This file will only contain some generic necessary items to get the ball rolling:

< webParts >
< webPart xmlns="http://schemas.microsoft.com/WebPart/v3" >
< metaData >
< type name="TitleWP.TitleWP, TitleWP, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" / >
< importErrorMessage >Cannot import DynamicList Web Part.< /importErrorMessage >
< /metaData >
< data >
< properties >
< property name="Title" type="string" >Title Web Part< /property >
< property name="Description" type="string" >< /property >
< /properties >
< /data >
< /webPart >
< /webParts >

Notice that this file just sets a few properties necessary for the webpart when loaded on the page. This is nothing special :)

Building the WebPart Feature

Ok, we're really flying now so let's get to this feature. The webpart feature is very useful when building enterprise wide sharepoint solutions. Imagine the case where you're building custom site-definitions and the business user decides that they don't want a certain webpart to be displayed on a page using your template. Well this works great with the feature model! This gives you the ability to activate webparts as features only allowing specific webparts to be active on sites using your template.

Let's cut the chit-chat and let's build :)

Create a Folder named "TitleWP".

Inside this folder create a file named "Feature.xml", this file will host necessary information pertaining to the feature definition. Place the following XML in the file:

< Feature Title="TitleWP" Id="e0491111-a4af-48c9-9b35-edc735772d39" Description="" Version="1.0.0.0" Scope="Site" Hidden="FALSE" DefaultResourceFile="core" xmlns="http://schemas.microsoft.com/sharepoint/" >
< ElementManifests >
< ElementManifest Location="elementManifest.xml" / >
< ElementFile Location="TitleWP.webpart" / >
< /ElementManifests >
< /Feature >

You'll notice the "Feature.xml" file is just like any standard feature manifest, containing the feature's scope, Id, Title, version, etc... The unique part of this manifest file is in the "ElementManifest"/"ElementFile" elements. These elements both contain an attribute named "Location" which references two files. The "ElementManifest" element references a "elementsManifest.xml" file which is very common in a feature. The "ElementFile" element references the "TitleWP.webpart" file we've created previously. These are pretty straight forward, let's create the "elementsManifest.xml" file.

Copy the following xml into the "elementsManifest.xml" file:

< Elements xmlns="http://schemas.microsoft.com/sharepoint/" >
< Module Name="WebParts" List="113" Url="_catalogs/wp" >
< File Url="TitleWP.webpart" Type="GhostableInLibrary" / >
< /Module >
< /Elements >

You'll notice that this file contains most of the normal attributes and elements, but in particular a reference to the "TitleWP.webpart" file.

Alright so this is looking good so far! So to finalize our feature, just drop the "TitleWP.webpart" file into the "TitleWP" feature folder. Well that's it :)

Add the webpart dll

This isn't a tough task, but it's necessary to recognize. Copy the webpart dll (in our case, "TitleWP.dll") into the root of the solution folder.

Building the Solution Manifest file

Ok, so here's where things get interesting. Create a file in the root of the solution folder named "manifest.xml". This file will host the definition of your solution. Now copy the following xml into the solution manifest file:

< Solution SolutionId="0fdb3649-99bb-4437-acf4-0f1a81b3d5ec" xmlns="http://schemas.microsoft.com/sharepoint/" >
< FeatureManifests >
< FeatureManifest Location="TitleWP\feature.xml" / >
< /FeatureManifests >
< Assemblies >
< Assembly Location="TitleWP.dll" DeploymentTarget="GlobalAssemblyCache" >
< SafeControls >
< SafeControl Assembly="TitleWP, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" Namespace="TitleWP" TypeName="TitleWP" Safe="True" / >
< /SafeControls >
< /Assembly >
< /Assemblies >
< /Solution >

So this is a bit so I'll do my best to describe this in a few lines.

The "Solution" element contains an "Id" attribute (GUID) which is the unique identifier for this solution.

The "FeatureManifests" element is a parent to the individual "FeatureManifest" elements. The "FeatureManifest" element contains a "Location" attribute which is the relative path from the root directory of the solution to the "feature.xml" file of the feature being added.

The "Assemblies" element is a parent to the individual "Assembly" element. The "Assembly" element contains a "Location" attribute which is the relative path from the root directory of the solution to the assembly being deployed (TitleWP.dll), and a "DeploymentTarget" (GlobalAssemblyCache, Bin).

The "SafeControls" element is a parent to the individual "SafeControl" element. The "SafeControl" element contains the exact same attributes necessary for an assembly in the web config (Assembly, version, Culture, public key token, Namespace, TypeName, Safe).

This pretty much sums up most things needed to build a solution manifest, but not all. There are plenty of items that are outside of the scope of this post.

Creating a ddf file

Now that all the components of the solution are created, it's time to create a diamond directive file to define the structure of our solution package. Create a file named "TitleWPSolution.ddf" and place it in the root of the solution folder. Copy the following code into the file:

.OPTION EXPLICIT ; Generate errors
.Set CabinetNameTemplate=SPSolutionsDemoPackage.cab
.set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory
.Set CompressionType=MSZIP ;** All files are compressed in cabinet files
.Set UniqueFiles="OFF"
.Set Cabinet=on
.Set DiskDirectory1=Package

;adds manifest file
manifest.xml

;adds webpart dll
TitleWP.dll

;sets the title webpart feature directory
.Set DestinationDir=TitleWP

;adds the feature manifest to the feature directory
TitleWP\feature.xml

;adds the element manifest to the feature directory
TitleWP\elementManifest.xml

;adds the webpart manifest to the feature directory
TitleWP\TitleWP.webpart

Building the diamond directive file is a bit confusing at first, but after a while it starts to make sense. In our diamond directive file we create the directory structure that already exists in our solution folder. To create directories in the cab we use the ".Set DestinationDir" command followed by the path of the directory being created. Once the Directory is created we just include the path of the file being added into the directory from the root folder. That's It!

It's now time to build the solution cab.

Creating the cab file
To build the cab file Windows has a native utility called "makecab.exe" (this command can be run from the command line directly because it's in the path). Open the command prompt and navigate to your solution folder. Run the following command:

makecab /f TitleWPSolution.ddf

Once you run this, you'll notice a few new components are created in the root of your solution folder. Navigate to the newly created folder "6.061" for me, and you'll see file named "1.cab". Rename this new cab file as "TitleWP.wsp", and that's it!!!

You now have your webpart solution package!

To add the solution to the SharePoint Solution Store run the following command:

stsadm -o addsolution -filename TitleWP.wsp

To deploy the solution run some variation of this command:

stsadm -o deploysolution -name TitleWP.wsp -allowgacdeployment -immediate -allcontenturls

That's all for creating solution packs for now! We'll pick up more with this on the next few posts ~:)

Check this out, this also a good solution pack post: http://sharepointsolutions.blogspot.com/2006/07/deploying-web-parts-with-solution.html