4.4. Solutions

The WSS v3 Solution Framework is a most welcome addition to the WSS v3 framework. Solutions are used to package and deploy custom actions, site definitions, templates, Web Parts and assemblies, and other WSS v3 components. The WSS v3 Solution Framework provides you with a way to bundle the components of a particular customization into a new type of file, called a Solution file. A Solution file is simply a cabinet (.cab) file with a .wsp extension. Solutions not only allow you to deploy your customizations, but they also allow you to disable and upgrade them as well. Some of the benefits of and reasons for using the WSS v3 Solution Framework described in the SDK include the following. The more you work with the Solution Framework, the more you will ask yourself how you had managed to do SharePoint deployments in the past. Most of the time, it was a manual process, and considering that this is the SharePoint team's first stab at trying to ease the pain, they have done a pretty good job.

• A unified infrastructure for deploying solutions—For ease of functionality changes, sites should not be permanently bound to the Features and functionality of the site when it was first created. By using Features, you can easily enable and disable functionality at the site level, as well as convert sites from one type to another.

• Integrated deployment—Solutions enable developers and administrators to easily install files on the front-end web servers in a server farm. Windows SharePoint Services can package all of the Windows SharePoint Services entities into one file, add the file to the Solution Store, and deploy it to the front-end web servers. The Solution Framework allows you to do the following:

  • Deploy new solutions and upgrade existing solutions across the farm.

  • Synchronize a front-end web server so that its state is consistent with the state of other servers in the farm.

• Unified localization—There are central facilities for specifying localization settings, as well as ways to specify localizable token databases.

4.4.1. Solution Schema

A Solution manifest file is used to define the parts of a solution, including its files, assemblies, code access security, Web Parts, Features, site definitions, and other resources. The WSS v3 Solution Framework uses this file to determine where on the front-end servers to put the other files in the Solution package.

4.4.1.1. Solution Element

The Solution element (attributes shown in the following table) is the top-level element for a Solution manifest file. Of note is that because solutions can be scheduled to be deployed at a particular time by a SharePoint administrator, and some Features such as a Site Definition require an IIS reset to be visible in the user interface, you can choose to have the deployment perform an IIS reset, preferably at a time when usage would be minimal on the server(s).

Solution Element Attribute	Description
DeploymentServerType	Optional Text. Determines whether the solution is deployed to a front-end web server or to an application server. Possible values include ApplicationServer and WebFrontEnd.
ResetWebServer	Optional Boolean. TRUE to specify that the web server be reset through Microsoft Internet Information Services (IIS).
SolutionId	Optional Text. Contains the GUID for the solution.

The start of a Solution file may look like the following snippet:

<Solution
  xmlns="http://schemas.microsoft.com/sharepoint/"

SolutionId="B1A9415C-D804-4877-8DE2-9A9EA2015B59"
  DeploymentServerType="WebFrontEnd">

  ...contents...

</Solution>

Solution packages have a hierarchical structure. A manifest file is located at the root, while the directories for the various pieces of the solution described in the previous sections are stored in their respective subdirectories. It is important to note that the directory structure inside of the .wsp file determines the final directory structure on the server file system. For example, if the location attribute of a FeatureManifest element in a Solution manifest is set to MyFeature/Feature.xml, the Feature, along with any ElementManifest elements defined within its ElementsManifests element, are copied to a folder called MyFeature in the Features folder on each of the front-end web servers when the solution is deployed. Note that it is not necessary to specify the Features folder itself. The WSS v3 Solution Framework knows where to put the Features defined within the FeatureManifests element.

The Solution element may contain any combination of the following child elements depending on the components involved. They are all described in more detail throughout the following pages.

• ApplicationResourceFiles

• Assemblies

• CodeAccessSecurity

• DwpFiles

• FeatureManifests

• Resources

• SiteDefinitionManifests

• RootFiles

• TemplateFiles

4.4.1.2. ApplicationResourceFiles Element

The ApplicationResourcesFiles element is used to specify the application resource files to include in a solution. It can contain one to many ApplicationResourceFile child elements whose attributes are listed in the following table.

ApplicationResourceFile Element Attribute	Description
Location	Required Text. Specifies a relative location within the Solution that contains the application resource file.

4.4.1.3. Assemblies Element

The Assemblies element is used to specify the assemblies to include in a solution. It contains one to many Assembly child elements whose attributes are listed in the following table. Some Features such as a custom field, require that the assembly be placed in the Global Assembly Cache, whereas best practice dictates that a Web Part's assembly be placed in the web application's bin folder.

Assembly Element Attribute	Description
DeploymentTarget	Optional Text. The preferred target of deployment of the assembly. The assembly is copied to the target specified by the DeploymentTarget attribute (for a Web application) or the Global Assembly Cache (for a server farm). Possible values are GlobalAssemblyCache and WebApplication.
Location	Required Text. The relative file path of the assembly within the Solution.

An example of an Assembly Element would resemble the following snippet:

<Assemblies>
  <Assembly
    Location="MyAssembly.dll"
    DeploymentTarget="GlobalAssemblyCache">
  </Assembly>
</Assemblies>

The Assembly element may contain any combination of the following child elements, depending on the components involved.

• ClassResources

• SafeControls—In the case of a Web Part you would need to include this element.

4.4.1.3.1. ClassResources Element

The ClassResources element is used to specify the class resources of an assembly that is included in a Solution. It contains one to many ClassResource child elements whose attributes are listed in the following table.

ClassResource Element Attribute	Description
FileName	Optional Text. The name of the class resource file.
Location	Optional Text. The relative path of the class resource within the Solution.

4.4.1.3.2. SafeControls Element

The SafeControls element is used to specify the safe controls of an assembly that are included in a Solution. It contains one to many SafeControl child elements whose attributes are listed in the following table. The Solution Framework will handle adding and removing these entries to and from the appropriate web.config files as needed as you deploy and retract your Solutions. It will even create backups of your web.config files for you.

SafeControl Element Attribute	Description
Assembly	Optional Text. The name of the control assembly.
Namespace	Optional Text. The namespace associated with the assembly.
Safe	Optional Boolean. TRUE to add the control to the safe controls list; FALSE to remove it.
TypeName	Optional Text. The control type.

4.4.1.4. CodeAccessSecurity Element

The CodeAccessSecurity element is used to specify the code access security for the Solution. It contains one to many PolicyItem child elements. PolicyItem elements contain the following two child elements.

• Assemblies

• PermissionSet

4.4.1.4.1. Assemblies Element

The Assemblies element is used to specify the assemblies that are associated with a Solution's code access security policy. It contains one to many Assembly child elements whose attributes are listed in the following table.

Assembly Element Attribute	Description
Name	Optional Text. The name of the assembly.
PublicKeyBlob	Optional Text. The assembly's public key, in binary format.
Version	Optional Text. The version of the assembly.

4.4.1.4.2. PermissionSet Element

The PermissionSet element is used to specify the permissions for a Solution's code access security policy and contains the following attributes. It contains one to many IPermission child elements that are each used to specify an individual permission in a permission set. The attributes of an IPermission element are listed in the following table:

IPermission Element Attribute	Description
Class	Required Text. The name of the class associated with the permission set.
Description	Required Text. A description of the permission set.
Name	Optional Text. The name of the permission set.
Version	Optional Text. The version of the permission set.

4.4.1.5. DwpFiles Element

The DwpFiles element is used to specify the Web Part files (.dwp or .webpart) to include in a Solution. It contains one to many DwpFile child elements whose attributes are listed in the following table.

DwpFile Element Attribute	Description
FileName	Optional Text. The name of the Web Part file.

4.4.1.6. FeatureManifests Element

The FeatureManifests element is used to specify the Features to include in the Solution. It contains one to many FeatureManifest child elements whose attributes are listed in the following table. The Solution Framework will parse each FeatureManifest element and determine what other files to include in the Feature deployment such as Element.xml files and supporting resource files if any are needed.

An example of an Assembly element would resemble the following snippet:

<FeatureManifiests>
  <FeatureManifiest Location="WileyFeatureFeature.xml">
<FeatureManifiests>

FeatureManifest Element Attribute	Description
Location	Required Text. Specifies a relative location within the Solution that contains the Feature description file.

4.4.1.7. Resources Element

The Resources element is used to specify the resources to include in the Solution. It contains one to many Resource child elements whose attributes are listed in the following table:

Resource Element Attribute	Description
Location	Required Text. Specifies a relative location within the Solution that contains the resource file.

4.4.1.8. SiteDefinitionManifests Element

The SiteDefinitionManifests element is used to specify the Site Definitions to include in the Solution. It contains one to many SiteDefinitionManifest child elements whose attributes are listed in the following table:

SiteDefinitionManifests Element Attribute	Description
Location	Required Text. The relative path of the root folder for a Site Definition.

Each SiteDefinitionManifest element should also contain a WebTempFile element that is used to specify a web template file that is associated with a Site Definition manifest. It contains the attribute noted in the following table:

WebTempFile Element Attribute	Description
Location	Required Text. Specifies a relative location within the Solution that contains the Web template file.

4.4.1.9. RootFiles

The RootFiles element is used to specify the root paths to which Solution files are copied. It contains one to many RootFile child elements whose attributes are listed in the following table:

RootFile Element Attribute	Description
Location	Required Text. The root path to which Solution files are copied.

4.4.1.10. TemplateFiles

The TemplateFiles element is used to specify the template files to include in the Solution. It contains one to many TemplateFile child elements whose attributes are listed in the following table:

TemplateFile Element Attribute	Description
Location	Required Text. Specifies a relative location within the Solution that contains the template file.

4.4.2. Deploying a Solution

Solution deployment is designed so that developers can essentially hand off a solution file to a SharePoint administrator who can then deploy it in a predefined, safe and consistent way. Solution deployment can be summarized as the process of distributing, unpacking and installing solution files to the SharePoint servers. The three main components of solution deployment, as explained in the SDK, are:

• The solution store—A centralized collection of all SharePoint solutions for the server farm. The first step in deploying a solution is to add the solution to the store.

• Deployment—Distribution, unpacking, and installation of the solution to the front-end web servers. After adding a solution, whether it is a new solution or an upgrade for an existing solution, to the server farm Solution Store, it must be deployed uniformly to the front-end web servers.

• Synchronization—Process of taking a new front-end web server, or a damaged or inconsistently performing front-end web server, and synchronizing its state to that of the other front-end web servers.

4.4.2.1. Solution Store

The Solution Store is an area in the WSS v3 configuration database that stores solutions and their files. Solutions can be added to the Solution Store in one of three ways.

• Command line—An administrator can add and remove solution files from the Solution Store using the stsadm command-line utility.

• Central Administration—An administrator can manage solutions by clicking on the Solution management link in the Global Configuration section of the Operations tab in Central Administration. Solutions can only be removed from the Solution Store this way, not added.

• Object model—As with almost all SharePoint functionality, solutions can also be added and removed via the object model.

4.4.2.2. Deployment

The first step in deploying a solution is to add it to the Solution Store. This process can be initiated from either the stsadm command-line tool by using the addsolution command (see the following table) or by using the object model. A Solution cannot be added to the Solution Store via the user interface in Central Administration. The following command is used to add a Solution to the Solution Store. This process also validates the Solution manifest file and ensures that all files referenced within it can be found in the Solution file.

Command	Description
stsadm.exe -o addsolution	{-filename <Solution filename>} [-lcid <language>]

A Solution is deployed locally, or by using a timer service irrespective of whether it is a new deployment or a deployment of a Solution upgrade (discussed later). Both local and timer-based deployments can be triggered by using command-line instructions or through the object model.

Local and Timer Service Deployment The following descriptions from the SDK may come in handy as you're working through this chapter. In a local deployment, Solution files are deployed only to the computer from which the deployment operation was initiated. Under this scenario, the Solution is not marked as "deployed" in the configuration database until the Solution files are deployed to all applicable servers in the server farm. Then, in the case of new Solution deployments, Solution features are registered, and schema and definition files are committed to the configuration store. In deployments that use the timer service, the deployment creates a timer job. This timer job is picked up by the timer service on each web server in the server farm. The timer job uses the WSS v3 administrative web service to access appropriate privileges to deploy Solution files to each computer. Initially, manifests and Feature manifests are parsed to find assembly and _layouts files, which are copied to the appropriate locations. All other files contained within a feature directory are copied to the feature directory. After Solution files are copied to the target computers, a configuration reset is scheduled for all front-end web servers; the reset then deploys the files and restarts IIS. For upgrades, the deployment has no impact on the end user experience. The new versions of the Solution files do not overwrite the old files; therefore, if a computer is restarted or the upgrade process is aborted, the servers are synchronized with their other data files. Finally, for new Solution deployments, Solution features are registered, and schema and definition files are committed to the configuration store.

The deploysolution command is used to deploy a Solution that is present in the Solution Store. A Solution can also be deployed by navigating to and clicking on the Solution management link in the Global Configuration section of the Operations tab in SharePoint Central Administration (see Figure 4-19). This will display a list of Solutions added to the store by either of the two methods previously mentioned. Clicking on a Solution will take you to the Solution status screen. If the Solution is not deployed, the menu bar will present the user with both a Deploy Solution button and a Remove Solution button (see Figure 4-20). If the Solution is deployed, the menu bar will present the user with a Retract Solution button (see Figure 4-21). Clicking either Deploy Solution or Retract Solution will present the user with the option to perform the operation immediately or to schedule it for a more convenient time. Clicking Remove Solution will generate a confirmation dialog and remove the Solution immediately from the Solution Store if accepted.

A number of things can occur that may cause a Solution deployment to fail. The timer service may not be activated on a front-end web server. In this case, the deployment will remain in a pending state until the timer service is started. In addition, the WSS v3 administrative service may not be activated on one of the servers, which will cause an administrative alert to be sent to an administrator with this information. Additionaly, the actual extraction of the solution package itself could fail on one of the servers or a file copy failure may also cause a solution deployment to fail. Whatever the case may be, the solution will not be marked as deployed.

A deployment can only be cancelled if the deployment timer job has not yet started running on any of the deployment target servers. If a deployment timer job begins running on any of the target servers, the deployment can no longer be canceled.

The contents of a Solution may change over time, and the SDK defines two fundamental types of changes that can happen to a Solution:

• Makeup change—Features or site definitions are added to a solution. A solution may have entire features added. If a newer version of a solution is defined (solution versions are different solution packages that share a GUID) that is missing features or site definitions, then those features and site definitions are removed.

• Definition change—Elements are added to or removed from Features or Site Definitions. As a result of definition changes, a Feature or a site template may add or lose files. As the Feature or site definition changes over time, files that are no longer defined in the Feature Definition are removed. This applies to assemblies as well. If a solution with global scope loses its assemblies, those assemblies are removed from the Global Assembly Cache. If a feature with web application scope loses its assemblies, those assemblies are removed from the local bin directory.

4.4.2.3. Synchronization

The synchronization process pulls solutions that the front-end web server does not have. These solutions are then redeployed onto the computer selected for synchronization. This process will help you immensely should you need to add a server to your farm.

4.4.3. Upgrading a Solution

Upgrading a Solution is possible using the WSS v3 Solution Framework. This may happen if you have a need to add or update one or more of the components of a Solution already stored in the Solution Store. The Solution Framework handles the backing up of existing Solution files (in the case of an exception), the removal of the old files and the delivery of the new file(s). Only certain types of Solution upgrade scenarios are supported. The following two lists illustrate those that are supported and those that are not.

The SDK states that in all cases where supported changes or additions are made to feature files (either feature .xml files or element .xml files), you must perform a reset (iisreset) of Microsoft Internet Information Services (IIS) to refresh the cache with the new .xml files. For existing feature activations, best practice is to reactivate the feature.

4.4.3.1. Supported Upgrades

The following list from the SDK outlines the supported upgrade options available when choosing to upgrade a Solution. Essentially, you can add new functionality and update existing files and functionality.

• Adding new files in a solution upgrade and removing old versions of the files

• Adding new features in a solution upgrade

• Updating or changing the receiver assembly for existing features in a new version of a solution

• Adding or changing feature elements (element .xml files) in a new version of a solution

• Adding or changing feature properties in a new version of a solution

Unsupported Upgrades The following list from the SDK outlines the unsupported upgrade options not available when choosing to upgrade a Solution. Essentially, you cannot remove existing functionality or change the scope of existing features. Removing old features in a new version of a solution Changing the ID or scope of old features in a new version of a solution Removing feature elements (element .xml files) in a new version of a solution Removing feature properties in a new version of a solution

The following table illustrates the syntax used to perform a Solution upgrade via the stsadm command-line utility. A Solution can also be upgraded via the object model.

Command	Description
stsadm.exe -o upgradesolution	{-name <Solution name> -filename <upgrade filename>} [-time <time to upgrade at>] [-immediate] [-local] [-allowgacdeployment] [-allowcaspolicies] [-lcid <language>]

There are a couple of things to keep in mind when performing Solution upgrades, the first being that the Solution must be in the Solution store. In addition to the requirement just mentioned, we need to be aware that at the time of an upgrade the Solution may be deployed or the Solution may not be deployed. If the Solution is not deployed, you should not use the -immediate or the -time flags in the upgradesolution command (if deploying via command line). Doing so will cause an exception, as an upgrade cannot be scheduled if a Solution is not deployed. If the Solution is deployed, be sure to use either the -time or -immediate flags in the upgradesolution command, as a time must be specified to run an upgrade if the Solution is already deployed.

4.4.4. Retracting a Solution

Retracting a Solution can be viewed as the opposite of deploying a Solution. The process will remove assemblies, files, resources, safe control entries, and other Solution components from all of the servers to which they have been deployed. The process also uninstalls Features if necessary as part of a complete retraction. As with Solution deployment, a Solution can be retracted immediately using the context of the SharePoint administrator, or scheduled using the timer service and its context. As stated in the SDK, retracting a Solution involves the following concepts:

• Only one active retraction with one particular solution is supported in a given server in the farm at any particular time.

• A solution cannot be retracted unless all the language packs associated with it are retracted first.

• A solution cannot be removed from the Solution Store if the solution is deployed.

• When a solution is retracted, all files for that solution are retracted, even if another solution points to the same file. This can be avoided by ensuring that each solution points to a unique set of files. This last item is crucial. Sharing files across Solutions may result in a very bad end-user experience if one is retracted.

As with adding and deploying Solutions, Solutions can be retracted and deleted through the stsadm command line tool, the object model or the user interface within Central Administration. The stsadm commands to retract and delete a Solution are listed in the following table:

Command	Description
stsadm.exe -o retractsolution	{-name <Solution name>} [-url <virtual server url>] [-allcontenturls] [-time <time to remove at>] [-immediate] [-local] [-lcid <language>]
stsadm.exe -o deletesolution	{-name <Solution name>} [-override] [-lcid <language>]

4.4.5. Creating a Solution

A solution can be created, like almost everything else, in a variety of different ways. The method described in the following section is a robust, repeatable, and reliable process. For demonstration purposes, let's package up the Feature you built in the previous section into a WSS v3 Solution.

4.4.5.1. Create MakeCAB Directive File

You will use MakeCAB.exe to package the Solution file. MakeCAB.exe is a tool included with Windows 2000 or later. If you would like more information on MakeCAB.exe, you can download the Microsoft Cabinet Software Development Kit from http://msdn2.microsoft.com/en-us/library/ms974336.aspx.

In examining the preceding code, you can see that you are setting some initial properties. You are instructing the utility to name the file WileyFeature.wsp. That is the file extension that the WSS v3 Framework is expecting. You are also instructing the utility to place the file into a certain directory, in your case c:wsp. This is completely arbitrary, since in most cases you will be delivering the Solution file to an administrator. However, since you want to test your Solution deployment, it would be marginally easier to place it in a location that is easy to type. All file paths in a directive file are relative to the location of the wsp.ddf file, which in this case is the root of your project. In addition, ensure that the folder path you specify as the DiskDirectoryTemplate above exists or the utility will throw an exception. Remember, the only way to add a Solution to the solution store is to add it either through the object model or by using the stsadm -o addsolution command. You will be using the latter in this example.

4.4.5.2. Create Solution Manifest

Only three files need to be in this particular Solution. All WSS v3 Solutions need a manifest file. As discussed earlier, this file informs the WSS v3 Solution Framework of the various components of our Solution. The WSS v3 Solution Framework knows how to read and interpret this file. The only other files you need to include in this Solution are the Feature.xml and Elements.xml files.

In examining the preceding code, be sure to give your Solution a unique SolutionId. The FeatureManifests element lists the single Feature that you are deploying. Remember, a Solution can contain any number of Features, Site Definitions, Web Parts, and other SharePoint components. The schemas defined earlier should help guide you in including all of the necessary files that may be required by any particular Solution you may need to create.

4.4.5.3. Build the Solution File

Execute the following steps to build the Solution file:

If you are curious, you can change the extension on the .wsp file to .cab and explore its contents. You will see that it has the folder structure you specified in the directive file designed above.

As discussed, the only way to add a Solution to the solution store is to do so via the object model or by using the stsadm command-line utility.

4.4.5.4. Add Solution to Solution Store

Now, add your Solution to the solution store using the stsadm command-line utility.

At this point, when deployment is complete, the items in the Solution are available for use. In this case, it means that your Feature will be available for activation. If you had deployed a Site Definition as part of your Solution, it would now be available as an option if you were to create a new site. If you had deployed a custom field as part of your Solution, it would now be available as an option when creating a new column in a list. The same applies to all of the other different components that you are able to deploy via a WSS v3 Solution.

In the case of your Solution, which contains a single Feature, when you browse to [WSS]TEMPLATEFEATURES, you will see that a WileyFeature folder was created that contains your Feature.xml and Elements.xml files from when your Solution was deployed.

You can now upgrade your Solution if you want to by using the upgrade rules discussed earlier in this chapter. You could also retract your Solution as well as remove it if you wanted to at this point. We leave you to explore the Solution Framework some more on your own and explore how beneficial and welcome this process will be to the SharePoint administrator as well as to many IT departments. Developers, in theory, should no longer need to manually modify files on the SharePoint servers. Also, all of the changes made to the system are now stored in the content database as a Solution.