Home > Blogroll, development, event handlers, MOSS, MS SharePoint Sever, sharepoint, sps, Uncategorized > SharePoint Solution Packages (.wsp files)

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 elements in 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 elements within 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 handler post 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 the element 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 your everyday needs :). Lemme know how you go.

Hope this helps–
 

Advertisements
  1. Carol
    February 26, 2010 at 6:30 pm

    It was awesome.

    I have a WSP solution. I need to do an installer for it. Can you tell me if you have any idea of how to do it. FYI, my WSP has two features.

  2. Atul
    March 12, 2010 at 7:30 pm

    simplest & best

  3. lok bahadur G.C.
    March 30, 2010 at 5:02 am

    This blog is very helpful to customize your own solution in sharepoint developer.

  4. dipali
    September 27, 2010 at 11:33 am

    thanks for the post. It helped me to understand basics of WSP and impotance of each item. Thanks.

  5. Sak
    October 15, 2010 at 12:36 am

    Hello, can u please help me with sharepoint. please reply back if u can help me i am really stuck! I need to create an event handler that gets fired up when something new is added in a “CustomList” and the this should create a folder in a document library with the same name as the customlist document title.

  6. October 15, 2010 at 4:41 am

    Hi Sak,

    Please look here for a detailed post on event handlers:

    https://rehmangul.wordpress.com/2009/11/17/writing-event-handlers-and-deploying-using-features/

    • sak
      November 18, 2010 at 3:47 pm

      Hello rehman,
      thanks for your help! I followed everything exact same way as u illustrated in the link above but when i deploy the event handler…it doesn’t work. Whenever i add a new item in the list, it does not send me any emails.

      What could be wrong? I am changing adding the item in the lists and not document library.

      also, i am deolying using the automatic WSp builder! I just click “Build WSP” and once its done, i click on “DEPLOY”.
      It seems to deploy it…i even activated the feature under site settings ->site features.

      I have no clue what is missing or what am i doing is wrong. Please Please Please Help.

      Thank you so much for your help in Advance.

      Sakshi

  7. Rickky
    January 17, 2011 at 7:26 pm

    Very nice and very simple. I have found this article very useful and easy to implement. Other places people have given half cooked steps for solution package generation.

  8. dsk
    June 2, 2011 at 6:34 am

    I have deployed a wsp solution file in the production server. Now we have got some changes for that. so we have rebuild the solution file and trying to deploy in the server. the wsp has deployed successfully but the changes what we have done are not affected. can any one help how can i solve this?

    • subbareddy kola
      June 28, 2012 at 9:56 am

      first remove the wsp solution from the solution store by stsadm or admin ui also check in the feature folder , remove any of feature was created by wsp name , run iis reset , then again deploy the solution what u have changed wsp file , test it and deploy by command line

      Thanks
      subbareddy kola

  9. sridhar
    June 13, 2013 at 4:38 pm

    we have one application server and two WFE, so if we want to deploy a solution through command prompt using stsadm commands. from which server I should run stsadm command?
    Do I need to open the command prompt and run stsadm command from application server or from the WFE server

  1. December 2, 2009 at 11:12 pm
  2. January 6, 2010 at 6:26 am
  3. January 7, 2010 at 5:58 am
  4. January 9, 2010 at 7:39 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: