Importance of Solution Packages

SharePoint deployments vary in size from a stand-alone installation on a single server to large multi-server farms. A solution or feature may require configuration changes to the web application, placing files on the file system, and/or deploying assemblies. As such, manual deployments can be administratively difficult since the possibility of deployment error increases with the number of servers in the farm as features and solutions are moved from a development environment to a test environment and finally to a production environment. In order to reduce deployment complexity and possibility of error, SharePoint uses solution packages a deployment mechanism to ensure consistent deployment of solutions and features to all servers in the farm. This allows the testing of a deployment and enables system administrators to create scripted installations (a typical requirement in most enterprise-class IT organizations).

Anatomy of a Solution Package

A solution package is a compressed CAB file with a WSP (.wsp) extension that contains the contents to be deployed including its required additional meta data.

The contents inside the WSP file may include, but is not limited to, assemblies, aspx files, feature manifests, schema XML files, site definitions, WEBPART files, DWP files, InfoPath forms, resource files, images, javascript files, other media files, html files, XML files and the solution manifest. In other words, it can contain just about any type of file you can think of. I may go into details of some of the SharePoint specific content files in some future post.

Every solution package requires additional meta-data to provide the WSS run time with instructions on what to do with the content of the WSP file. The meta-data is stored in a manifest file in XML that must be located in the root of the WSP file; the file is appropriately named manifest.xml. Perhaps I will dive into the details of the Solution schema that defines the XML structure of the solution manifest in another post in the future.

How Solution Packages Work

Basically, they just do.

But in all seriousness, the deployment of a solution package happens in two stages. In the first stage, or the installation stage, WSS takes the WSP file and copies it to the configuration database. In the second stage, or the deployment stage, WSS takes the WSP file from the configuration database, extracts the content(s), and places the content(s) as specified in the package meta-data. Simple huh? Obviously, a system administrator needs to tell WSS to install and deploy a package. This is easily accomplished by executing three simple STSADM utility commands.

stsadm -o addsolution -filename my.wsp
stsadm -o execadmsvcjobs
stsadm -o deploysolution -name my.wsp

The addsolution and deploysolution operations both take additional operational parameters that may be needed depending on the needs of actual solution to be deployed. It should be noted that the  STSADM utility commands only need to be executed on the server that is hosting the Central Administration application. Let’s look at what each command actually does:

1. The first line (stsadm -o addsolution -filename my.wsp)creates a timer job that asynchronously performs the installation stage of the solution deployment. When the job executes, WSS takes the specified WSP file and copies it to the configuration database.
2. The second line (stsadm -o execadmsvcjobs) forces WSS to execute any timer jobs that are pending. This is necessary because the actual deployment stage cannot commence until the installation stage has been completed successfully.
3. The last line (stsadm -o deploysolution -name my.wsp) creates another timer job that asynchronously performs the actual deployment stage of the solution deployment. When the timer job executes, WSS gets the WSP file from the configuration database and deploys the contents of the package based on the instructions defined in the solution package meta-data. It should be noted that the WSS service on each server in the farm performs this task at the same time as triggered by the timer job ensuring a consistent and timely deployment on all servers in the farm.

Another great thing about the solution deployment mechanism is that it also simplifies the removal of a solution from a farm. Solution removal also happens in two stages. In the first stage, or retraction stage, WSS uses the solution package meta-data to remove the contents from each server in the farms. In the second and final stage, or deletion stage, WSS deletes the copy of WSP file from the configuration database. A system administrator can accomplish this easily be executing three STSADM utility commands on the server hosting the Central Administration application.

stsadm -o retractsolution -name my.wsp
stsadm -o execadmsvcjobs
stsadm -o deletesolution -name my.wsp

The retractsolution and deletesolution operations both take additional operational parameters that may be needed depending on the needs of actual solution to be removed. Like we did with the deployment commands, let’s now review what each command actually does:

1. The first line (stsadm -o retractsolution -name my.wsp) creates a timer job that asynchronously tells the WSS service on each server in the farm to go get the WSP file from the configuration database, take a look at the solution package meta-data, and retract any features, files, and/or assemblies that were previously deployed. This command initiates the retraction stage of the removal process.
2. The second line (stsadm -o execadmsvcjobs) forces WSS to execute any timer jobs that are pending. This is necessary because the actual deletion stage cannot commence until the retraction stage has been completed successfully.
3. The last line (stsadm -o deletesolution -name my.wsp) creates another timer job that asynchronously performs the deletion stage of the solution removal. This job tells the WSS run-time to delete the copy of WSP file from the configuration database.

And that is how solution packages work.

Creating a Solution Package

While SharePoint elegantly utilizes Microsoft’s most advanced bleeding edge technology (such as SQL Server, the .NET 3.5 framework, etc.), the actual process of creating a WSP file is ironically a bit archaic. If you are using Visual Studio 2005 for development, then the Visual Studio 2005 extensions for WSS 3.0 can jump start the process of creating the WSP file (but it won’t save you as much time as I expected it to when I first used the extensions). The process of creating a WSP file is the same as creating a  CAB file using the MAKECAB operating system utility. The MAKECAB utility creates the WSP file by reading and processing the cabinet definition contained in a DDF file, also known as the Data Description File. Creating a DDF file is not difficult and can be done with any plain text editor, but the maintenance of the DDF file is manual (this is why I called the process a bit archaic) and become quite tedious with large solutions.In any case, let’s build a sample solution package.

The first step is to create the data description file (DDF) that describes the files for the CAB archive. You can use any text editor to create the file.

; ** my.wsp **

.OPTION EXPLICIT                   ; Generate Errors
.Set CabinetNameTemplate=my.wsp
.Set DiskDirectoryTemplate=CDROM   ; All cabinets go in a single directory
.Set CompressionType=MSZIP         ; All files are compressed in cabinet files
.Set UniqueFiles="ON"
.Set Cabitet=on
.Set DiskDirectory1=Package

; All solution packages require additional metadata

manifest.xml   manifest.xml

; Deployment files, Schemas, and Assemblies

my.html        LAYOUTS/mysample/my.html

There are lot of things going on in the DDF file, but here is what I think is important to understand.

• Comments in the file begin with a semi-colon
• .OPTION lines tell the MAKECAB utility what options to use when building the CAB archive
• .Set lines tell the MAKECAB utility what values to apply to certain parameters that are used when building the CAB archive
  • Make sure the CabinetNameTemplate parameter is set to what the name of the WSP file will be (in the example above the MAKECAB utility will generate a CAB archive named my.wsp)
• Each content file to be added to the CAB archive is listed on a line in a space separated source-destination format
  • For example, this CAB archive will contain an HTML file (my.html); the last line in the example above tells the MAKECAB utility to grab the my.html file from the file system (the source location) and place copy it to LAYOUTS/mysample/my.html in the CAB archive (the destination location)
  • Double quotes can be used to define sources that contain spaces in the path or file name
  • Make sure to include the solution meta-data XML file (manifest.xml) at the root of the CAB archive

The next step is to create the solution manifest file .

<Solution SolutionId="01234567-89AB-CDEF-0123-456789ABCDEF"
  xmlns="http://schemas.microsoft.com/sharepoint/">
  <TemplateFiles>
    <TemplateFile Location="LAYOUTS/mysample/my.html" />
  </TemplateFiles>
</Solution> 

The example is a very simple solution manifest, but there are a couple of things to take away from it.

• Every solution has a GUID (globally unique identifier) that identifies uniquely
• As a general rule, every deployment file, schema, and/or assembly contained in the CAB archive must also be listed in the solution manifest or another manifest listed in the manifest.xmlfile; otherwise it will be ignored by the WSS runtime
• The locations of the deployment file, schema, and/or assembly in the manifest refer to the location in the CAB archive

The last step is to use the MAKECAB utility to generate the solution package – the actual WSP file . This is done by using a command window and executing a simple command:

makecab /f my.ddf

And that’s how a solution package (WSP file) is created.