Creating Advanced Solutions for SharePoint 2007

Introduction: Building Solutions, Hands-On

My previous article discussed the importance of SharePoint 2007 Solutions for developers in the shadow of the difficulties deployment of the customizations posed for SharePoint 2003. The article introduced the three methods of utilizing Solutions: employing the "stsadm" administration tool of SharePoint, using the Central Administration Web interface, or proceeding programmatically.

The .cab deployment solution for WebParts in SharePoint 2003 was the basis for the design of SharePoint 2007 Solutions. A SharePoint Solution consists of all the files needed for the components to be deployed plus a manifest (xml) file that describes the modus operandi of the files. The Solution file is a cabinet-based .cab file with a ".wsp" extension in place of the ".cab" extension.

By way of a Solution, it is possible to install most types of customizable components of SharePoint such as Site definitions, Features, WebParts, Templates and assemblies. Additionally, the Code Access Security (CAS) policies can be modified in the web.config.

Solution Schema and Walking Through the Creation of Solutions

The .wsp file can have an internal tree structure, and the Solution manifest file (obligatory to have the name "manifest.xml") must be located in the root of the structure. The manifest file gives instructions to the Solution engine in SharePoint regarding the modus operandi of the other files in the Solution; however, it does not define the structure of the components. Subsequently, a file may exist in the .wsp Solution file, but if the file is not mentioned in the manifest, it will always be disregarded.

The general schema of the manifest file is:

<Solution
 DeploymentServerType = (Optional) "ApplicationServer" | "WebFrontEnd"
 ResetWebServer = (Optional) "TRUE" | "FALSE"
 SolutionId = (Optional) "Text or GUID"
 xmlns="http://schemas.microsoft.com/sharepoint/">
   <Elements...
      ApplicationResourceFiles
         ApplicationResourceFile
      Assemblies
         Assembly
            SafeControls
               SafeControl
            ClassResources
               ClassResource
      CodeAccessSecurity
         PolicyItem
            PermissionSet
               IPermission
            Assemblies
               Assembly
      DwpFiles
         DwpFile
      FeatureManifests
         FeatureManifest
      Resources
         Resource
      RootFiles
         RootFile
      SiteDefinitionManifests
         SiteDefinitionManifest
            WebTempFile
      TemplateFiles
         TemplateFile
   ...>
</Solution>

The parameters of the "Solution" section define the scope of deployment; the Solution initiates "iisreset" after activation ("ResetWebServer" Parameter), as well as the ID (a string or GUID) and the NameSpace. Inside the Solution tag, the Elements of the Solution can be defined. The following illustrates a Solution with different elements, beginning with the Solution metadata:

<Solution SolutionId = "12345678-90AB-CDEF-1234-567890ABCDEF"
 xmlns="http://schemas.microsoft.com/sharepoint/">

 . . .

</Solution>

The GUID can be created with the Visual Studio generator or constructed manually.

RootFiles Element

The "RootFiles" element copies the defined files in a particular directory:

<RootFiles>
   <RootFile
      Location = "Text">
   </RootFile>
   ...
</RootFiles>

The "Location" parameter identifies the final localization of the file. The localization in the structure of the .wsp file needs to mirror the final localization in the server, and is relative to the 12 hive where the SharePoint files are localized. Thus, the tags

<RootFiles>
   <RootFile
      Location = "TEMPLATE\IMAGES\MyPic.jpg">
   </RootFile>
</RootFiles>

will copy the file "MyPic.jpg", found in the directory "TEMPLATE\IMAGES" in the .wsp file, to the directory "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\IMAGES" of SharePoint.

If the file cannot be found in the correct place in the .wsp file, the installation of the Solution will be aborted.

TemplateFiles, Resources, and ApplicationResourceFiles Element

The TemplateFiles, Resources, and ApplicationResourceFiles elements are very similar to the RootFiles element; they create a copy of one or more templates, resources, or resource files for the complete application in the chosen directory:

<TemplateFiles>
   <TemplateFile
      Location="Text"/>
   ...
</TemplateFiles>


<Resources>
   <Resource
      Location="Text"/>
   ...
</Resources>


<ApplicationResourceFiles>
   <ApplicationResourceFile
      Location="Text"/>
   ...
</ApplicationResourceFiles>

Resource files need to be installed in a feature directory. In the following example, the resource file "JupiterMedia.es-co.resx" will be copied to the "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\FeatureName" directory:

<Resources>
   <Resource
      Location="FeatureName\JupiterMedia.es-co.resx "/>
</Resources>

Application Resource Files are general resources that SharePoint will use for different purposes, for example, localization files that can be installed in the "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\Resources" directory.

FeatureManifests Element

Features are a new concept introduced in SharePoint 2007, and offer services to install, activate, deactivate, and uninstall functionality. There are some notable differences between Solutions and Features: the former were created to install complete packets of functionality, covering the entire SharePoint system; Features can install only one element at a time. However, within that limitation, Features modify the user interface of SharePoint (add menu's, for example) in an uncomplicated way.

Features can be installed using Solutions (the opposite is not possible). The syntax is:

<FeatureManifests>
   <FeatureManifest
      Location="Text"/>
</FeatureManifests>

For example:

<FeatureManifests>
   <FeatureManifest Location="JupiterMediaFeature\feature.xml"/>
</FeatureManifests>

Install the "JupiterMediaFeature" feature in the features directory "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\FEATURES". Observe that Features will be installed, but not activated, by the Solution.

SiteDefinitionManifests Element

To install SharePoint Site Definitions, the following syntax is applied:

<SiteDefinitionManifests>
   <SiteDefinitionManifest
      Location="Text">
      <WebTempFile
         Location="Text">
   </SiteDefinitionManifest>
   ...
</SiteDefinitionManifests>

Each Site Definition needs to be linked to a location in the Template structure of SharePoint. The subsequent example copies the Site Definition "webtempSTS.xml" to the "STS" Template:

<SiteDefinitionManifests>
   <SiteDefinitionManifest Location='STS'/>
      <WebTempFile Location='1033\STS\webtempSTS.xml'/>
   </SiteDefinitionManifest>
</SiteDefinitionManifests>

Assemblies and ClassResources Elements

Installing assemblies is also possible using a Solution. The assembly can be installed in the GAC or in the local Bin directory, together with its registration in the web.config file by means of the following:

<Assemblies>
   <Assembly
      DeploymentTarget = "GlobalAssemblyCache" | "WebApplication"
      Location = "Text">
      <SafeControls>
         ...
      </SafeControls>
   </Assembly>
</Assemblies>

The "DeploymentTarget" parameter determines whether the assembly reaches the GAC or goes to the Bin directory; the "SafeControls" element ensures its registration in the Safe Controls section of the web.config (this element is not obligatory):

<Assemblies>
   <Assembly DeploymentTarget="GlobalAssemblyCache"
             Location="JupiterMediaAssembly.dll">
      <SafeControls>
         <SafeControl
            Assembly="JupiterMediaAssembly, Version=1.0.0.0,
            Culture=neutral, PublicKeyToken=f435cbfb3fb57aec"
            Namespace="JupiterMediaAssembly"
            TypeName="*" Safe="True" />
      </SafeControls>
   </Assembly>
</Assemblies>

The "ClassResources" element identifies the resources class for an assembly. The syntax permits defining the file name and location, in the same way as previously explained for other elements:

<ClassResources>
   <ClassResource
      FileName = "Text"
      Location = "Text">
   </ClassResource>
   ...
</ClassResources>