SharePoint Solution Packages (.wsp files)

http://rehmangul.sauftveyr.com/2009/12/02/sharepoint-solution-packages-wsp-files/

I tried to look for the exact standing for the letters ‘WSP’ but couldn’t find a reasonable reference. So, please select one of your liking 

• WSS Solution Package
• WSS Solution Project
• SharePoint Solution File
• SharePoint Solution……………………..whatever.

In any case, it’s a Solution.

Before I write what it is, I have to write why it is there at all.

What problems WSP solves?Suppose you developed a custom solution for sharepoint and now is the time to deploy that to production. Your solution included set of Features, site definitions, assemblies, Web Part packages, class resources etc etc. Now the production has 3 Web Front Ends, an Application server and a SQL backend.

In an ideal world, the infrastructure (i.e. the farm) is under the control of Administrators and you handed over your solution to them for deployment. Now the Administrator has no idea what your solution does, what are these resources, where to put them and what configuration is necessary to make them work. He is simply baffled at what you just handed over to him, coz he knows that he has to do that for all the 3 Web Front Ends and the Application server one by one. This is problem no. 1.

In a real world, ofcourse it will be you yourself who will be deploying the solution to production (yeah, we all know that). So, even if you know exactly how the solution works and where should you put what, it is going to be tedious and error prone to get everything right for all the Front Ends and Application Servers. You miss one file or one configuration setting at one place and you could be fired  . Why, coz when you deployed everything, you tested and you were hitting Web Front End1 all the time and it was sublime, however, when your Boss tested, he managed to hit Web Front End2 because of load balancing among the 3 Web Front Ends, which was exactly the server where you messed up a configuration setting or was missing a file and the application failed. This is problem no. 2

So, to resolve these two problems we use solution files (.wsp). Read on.

Definition and Benefits: Wsp is a single file that contains all your resources including Features, site definitions, assemblies, Web Part packages, class resources etc etc. This file is used to deploy your solution to the entire farm in one go. You do not need to go to separate servers one by one for deployment. Timer Jobs will be created on each Web Front End in the farm. When the timer service on each server will run, it will execute the timer jobs and completes the deployment.

Now the farm Admin is happy coz he needs not know whats inside the wsp. He simply has to take the .wsp file and deploy once and for all, no need to go to each and every Web Front End or Application Server (solves problem no.1). And, you are happy coz you dont need to worry that all the files are gonig to all the places, and i.e. all the right places, making sure all configuration settings are OK, and last but not the least, your Boss tested successfully (solves problem no.2).

Deployment is a process of Distributing, Unpacking and Installing solutions to a SharePoint server farm.
Solution File is an Easy, Safe, Consistent and Reusable way of Deployment.
Sounds great, isn’t it.

Now let’s see how to build wsp files.

Building Solution Packages (.wsp files):There could be three ways to build a solution package (.wsp file).

1. Manually
2. DDF File
3. WSPBuilder

Manually, you dont want it.

DDF stands for Diamond Definition File, Diamond Directive File…………whatever you may want to call it. Using DDF is tedious. It’s the ancient way of building WSPs. You have to write a Manifest.xml manually (this file tells what to put on the server farm and where to put it), then you have to write a .ddf file manually (its an instruction file that tells the compiler what to put in the wsp package i.e. in .wsp file), and then compile using makecab.exe which will read your .ddf file and give you a .wsp file. So, this is the old way of doing things, what’s new then.

It is WSPBuilder. What WSPBuilder does:

1. Generates the solution package (.wsp file) for you automatically with a click, Period.

So, you save all the hassle of writing Manifest.xml. WSPBuilder will automatically generate it for you and put that in the .wsp file. No need for DDF file. No need for makecab.exe.

Newer versions of WSPBuilder will even Deploy, Upgrade, Uninstall solution packages along with many other features. I am trying to stick myself only to building and deploying solution packages and their schema.

Real World Example:Now, I want to do a real world example of a WSPBuilder and talk about some of the elementsin Manifest.xml file and how to manipulate them for our custom needs.

Why Manifest.xml, coz we said that “what to put and where to put” is specified in Manifest.xml. So, if this is automatically generated by WSPBuilder, it can know about “what to put” as we will be using WSPBuilder from within Visual Studio where our custom solution is, but how will it know “where to put”. Here is the reason why we want to discuss elementswithin Manifest.xml.

Download and Install WSPBuilder Extensions from here (latest version as of today is 1.0.6):
http://wspbuilder.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=30858

Open any of your sharepoint projects in Visual Studio. I wrote a sharepoint event handlerpost here and will be using the same project for this example. So, I will create a solution package using “WSPBuilder Extensions for Visual Studio” to deploy my “Event Handler Feature” to a sharepoint farm.

Installation is very simple and I assume you did that successfully. In visual studio right click your project and you will see the following:

 

 You can now see lots of features available with this tool. Click Build WSP. Output screen will display something like this:

 

 If you received an error message about cablib.dll, look here.

Now go to your project directory on the file system. You will see that two new files are added there:

 

 Solutionid.txt contains just a GUID that is used in Manifest.xml. So, where is Manifest.xml. Lets find out. Rename your .wsp file and change the extension to .cab:

 

 Double click the .cab file and open. This is what you see:

 

Note the Path tab in the figure above. WSP will not show you folder structures but it will keep track of folders using this path value. 

So the wsp contains my ”Event Handler’s DLL”, “Feature.xml” and “Elements.xml” (remember that I am implementing my event handler as feature). Three of these files are part of my custom solution and not generated by WSPBuilder. The only thing WSPBuilder generated is the Manifest.xml. Lets see whats inside it and what it means (and ofcourse how to manipulate it):

 

What’s this Manifest.xml:
<?xml version="1.0"?>
<!-- Solution created by WSPBuilder. 2/12/2009 4:31:46 PM  -->
<Solution SolutionId="f33a01ff-84d9-481f-8c60-8f3e661c734b" xmlns="http://schemas.microsoft.com/sharepoint/">
  <Assemblies>
    <Assembly Location="EventHandler.SharePoint.SendEmail.Feature.dll" DeploymentTarget="GlobalAssemblyCache" />
  </Assemblies>
  <FeatureManifests>
    <FeatureManifest Location="EventHandler.SharePoint.SendEmail.Feature\feature.xml" />
  </FeatureManifests>
</Solution>

First element of a Manifest.xml is always a <Solution>. You can see the GUID from solutionid.txt being used in SoutionId attribute.

Other elements in Manifest.xml specify three things:

1. What is in the WSP
2. Where is it placed in the WSP
3. Where should it be placed in the server farm

Note these questions as I’ll refer to these below. Anwers to these questions will vary with theelement type. Every element has an associated default location with it that answers question no. 3 i.e. Where should it be placed in the server farm.

<Assembly>******************************************************
Lets examine these elements and their attributes one by one. Lets first take the element <Assembly>.

<Assemblies>
    <Assembly Location="EventHandler.SharePoint.SendEmail.Feature.dll" DeploymentTarget="GlobalAssemblyCache" />
</Assemblies>

• Assembly element is telling the installer that this is going to be an assembly. Answers question no. 1. 
• Location attribute is telling the installer to look for the “EventHandler.SharePoint.SendEmail.Feature.dll” at the root of the WSP file. Answers question no. 2.
• DeploymentTarget is telling the installer to deploy it to GlobalAssemblyCache (GAC). Answers question no. 3. 

So, the Manifest is telling the installer to get EventHandler.SharePoint.SendEmail.Feature.dll from the root directory from within the wsp and deploy it to Global Assembly Cache (GAC).

Other option would have been DeploymentTarget = “WebApplication”, in that case the dll would have been deployed to the bin folder of the web application.
********************************************************

<FeatureManifest>********************************************************
In the case above, DeploymentTarget was mentioned separately, however, this is not the case with <FeatureManifest> element. Let’s have a look:

<FeatureManifests>
    <FeatureManifest Location="EventHandler.SharePoint.SendEmail.Feature\feature.xml" />
</FeatureManifests>

• FeatureManifest is telling the installer that this is a feature. Answers question no. 1.


• Location is telling the installer to look for feature.xml file in EventHandler.SharePoint.SendEmail.Feature directory within wsp file. So, once again, you wont see “EventHandler.SharePoint.SendEmail.Feature” folder inside the .wsp file, it is calculated based on the path value as shown above. Answers question no. 2.


• Now how does the installer find out where to deploy this feature.xml. That is hidden in the element type as mentioned before. FeatureManifest element is used to specify features, so this element type has a location associated with it. That location is root of all the Features in sharepoint. Can you guess it now, yeah it is 12\TEMPLATE\FEATURES, where all sharepoint Features reside. Answers question no. 3.

So, the Manifest is telling the installer to get feature.xml from EventHandler.SharePoint.SendEmail.Feature directory from within the wsp and deploy it to
12\TEMPLATE\FEATURES\EventHandler.SharePoint.SendEmail.Feature\feature.xml.

*******************************************************

<TemplateFile>*******************************************************
Similarly, there could have been a TemplateFile element in the Manifest.xml had my solution contained a user control:

<TemplateFiles>
    <TemplateFile Location="ControlTemplates\SendEmailForm.ascx"/>
</TemplateFiles>

• TemplateFile is telling the installer that this is a Template File. (Answers question no. 1).


• Location is telling the installer to look for the control SendEmailForm.ascx file in ControlTemplates directory within the wsp file. Answers question no. 2.


• Now how does the installer find out where to deploy SendEmailForm.ascx control. That is hidden in the element type. TemplateFile element is used to specify template files, so this element type has a location associated with it. That location is the root of all the templates in sharepoint. Ofcourse you guessed it this time i.e. 12\TEMPLATE, where all sharepoint templates reside. Answers question no. 3.

Now, if you examine the TEMPLATE folder under 12 hive, you will notice that there is a CONTROLTEMPLATES directory with lots of user controls already in there.

So, the Manifest is telling the installer to get SendEmailForm.ascx from ControlTemplates directory from within the wsp and deploy it to 12\TEMPLATE\CONTROLTEMPLATES\SendEmailForm.ascx.
******************************************************

Conclusion (sort of  )
In the case of FeatureManifest, “EventHandler.SharePoint.SendEmail.Feature” folder was not available in FEATURES directory but mentioned in Manifest.xml, so the installer will create a new folder with that name and put “feature.xml” in it. In the case of TemplateFile, ”CONTROLTEMPLATES” directory was already available under “TEMPLATE” folder, but “CONTROLTEMPLATES” was also mentioned in Manifest.xml, even then the installer will not create a new directory and use the existing “CONTROLTEMPLATES” directory and put “SendEmailForm.ascx” in it.

So, if its an existing directory, use the same one, otherwise create new.

I hope by now you have got a good idea of how this works. Here is a list of Elements and the associated root locations:

Manifest Element	Root Location
WebTempFile	12\Template
Assembly	Web Application bin or GAC
FeatureManifest	12\TEMPLATE\FEATURES
RootFileResourceFile	12
ResourceFile	12\TEMPLATE\FEATURE
SiteDefinitionManifest	12\TEMPLATE\SiteTemplates
TemplateFile	12\TEMPLATE
ApplicationResourceFile	12\Resources

Manipulating Manifest.xml:Now, you may be thinking that directory structures could be specified as of our likinng in Manifest.xml. That’s not always true. Some may actually fail. For instance, if you specify “Location = MyFeature\EventHandler.SharePoint.SendEmail.Feature\feature.xml” for a <FeatureManifest> element, this will not work and you may actually receive an error message. Its coz Features can only locate directly under FEATURES directory. The immediate directory under FEATURES directory should have feature.xml in it. If you try to create ”MyFeature” directory, then “EventHandler.SharePoint.SendEmail.Feature” directory and this has feature.xml in it, this will not work.

However, if you want a different directory for your controls to separate them from sharepoint controls then you may specify the following directory structure without any problems:



<TemplateFiles>
    <TemplateFile Location="ControlTemplates\MyCustomControls\SendEmailForm.ascx"/>
</TemplateFiles>

This will create “MyCustomControls” directory in “CONTROLTEMPLATES” and put “SendEmailForm.ascx” in it.

Deploying using solution packages (.wsp files):Oh, I forgot, we still have to deploy the solution. So, first we add it to the Solution Store and then deploy it. Here are the commands to do so:



stsadm.exe -o addsolution -filename "c:\EventHandler.SharePoint.SendEmail.Feature.wsp"

Adding always involves STSADM command. You can deploy either by STSADM or Central Administration. If you wish you can deploy using the following STSADM command, but I am going to do it using Central Administration:

stsadm.exe -o deploysolution -name "c:\EventHandler.SharePoint.SendEmail.Feature.wsp" -immediate -allowGacDeployment -allowCasPolicies -force


Go to Central Administration -> Operations -> click Solution Management (under Global Configuration)
You will see your solution as “Not Deployed”, though added to the solution store:

Click the wsp file and click “Deploy Solution on the following screen:

Select “Now” and click OK:

Wait for sometime and (if everything goes fine), you should see the following screen with status as “Deployed”:

Now you can go and see your feature created under FEATURES directory in 12 hive (only if your custom solution created a Feature):

Your feature will also appear in “Site Features”:

That’s it. Lets call it the day. It’s already 2:18 AM on my machine. I hope now you have a much better understanding of solution packages and how to manipulate them for youreveryday needs  . Lemme know how you go.