http://www.developer.com/net/asp/article.php/3675576/Creating-Advanced-Solutions-for-SharePoint-2007.htm

Back to article

Creating Advanced Solutions for SharePoint 2007


May 3, 2007

Introduction: Building Solutions, Hands-On

My previous article Creating Solutions for SharePoint 2007 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>

CodeAccessSecurity Element

The CodeAccessSecurity element characterizes the CAS policies for the Solution. The Element contains a chain of sub-elements:

<CodeAccessSecurity>
   <PolicyItem>
      <PermissionSet
         class = "Text"
         Description = "Text"
         Name = "Text"
         version = "Text">
      </PermissionSet>
      ...
      <Assemblies>
         <Assembly
            Name = "Text"
            PublicKeyBlob = "Text"
            Version = "Text">
         </Assembly>
      </Assemblies>
   </PolicyItem>
</CodeAccessSecurity>

The next example delineates a CAS policy, an aspect of the Full Trust standard CAS policy of SharePoint:

<CodeAccessSecurity>
   <PolicyItem>
      <PermissionSet
         class = "UnionCodeGroup"
         Description = "This code group grants code signed with
                        the Microsoft strong name full trust"
         Name = "Microsoft_Strong_Name"
         version = "1">
      </PermissionSet>
      <Assemblies>
         <Assembly
            Name = "System.Security.NamedPermissionSet"
            PublicKeyBlob = "00000000000000000400000000000000"
            Version = "1">
         </Assembly>
      </Assemblies>
   </PolicyItem>
</CodeAccessSecurity>

DwpFiles Element

As a final point, the recommended way of installing WebParts in SharePoint 2007 is via Solutions. The previous system in SharePoint 2003, applying CAB files and the "stsadm" administrator utility, is still supported, but principally to maintain the compatibility between the two versions. The syntax for the manifest file looks like this:

<DwpFiles>
   <DwpFile
      Location = "Text">
   </DwpFile>
   ...
</DwpFiles>
Caution: The Software Development Kit indicates the name of the parameter for the "DwpFile" subsection to be "FileName", but that is an error in the sporadically inaccurate SharePoint 2007 SDK. There are numerous syntax errors in the information about Solutions, so caution is advised as regards the information from the SDK.

It is important to consider that, in most working situations, a single element will rarely be used in a manifest for a Solution. For example, to install a WebPart, in addition to employing the "DwpFiles" component, the "Assemblies" element to install the DLL of the WebPart and the "SafeControls" element are needed to configurate it. And, if the WebPart uses resources files (icons, translations), you also will need the "Resources" component and the "CodeAccessSecurity" element to define the Security Police.

Consequently, a complete manifest solution file to install a WebPart may appear as:

<Solution SolutionId="4AFC1350-F354-4439-B941-51377E845ABC"
          xmlns="http://schemas.microsoft.com/sharepoint/">
<DwpFiles>
   <DwpFile Location = "MyLibrary.webpart"></DwpFile>
</DwpFiles>
   <Assemblies>
      <Assembly DeploymentTarget="WebApplication"
                Location="MyLibraryWebPart.dll">
         <SafeControls>
            <SafeControl
               Assembly="MyLibraryWebPart, Version=1.0.0.0,
                         Culture=neutral,
                         PublicKeyToken=6a50a9d627073d83"
               Namespace="MyLibraryWebPart"
               TypeName="*" Safe="True" />
         </SafeControls>
      </Assembly>
   </Assemblies>
   <ApplicationResourceFiles>
      <ApplicationResourceFile
         Location="pic.gif"/>
   </ApplicationResourceFiles>
</Solution>

In SharePoint 2007, it is possible to use traditional DWP files (.dwp) or the more current DotNet 2.0 WebPart definition files (.webpart).

Creating a CAB File and Some Helpful Tools

After the creation of the manifest file, the next step is to compress all the required files into a CAB file. Microsoft provides the key software in the "Cabinet Software Development Kit," which can be downloaded from the Microsoft site, http://support.microsoft.com/kb/310618.

To construct a CAB file, apply the "Cabarc" tool with the syntax:

CABARC [options] command cabfile [@list] [files] [dest_dir]

The support commands are:

  • N: Create new cabinet
  • L: List contents of an existing cabinet
  • X: Extract files from a cabinet

And the support options are:

  • -c: Confirm files to be operated on
  • -o: When extracting, overwrite without asking for confirmation
  • -m: Set compression type [LZX:<15..21>|MSZIP|NONE], (default is MSZIP)
  • -p: Preserve path names (absolute paths not allowed)
  • -P: Strip specified prefix from files when added
  • -r: Recurse into subdirectories when adding files (see -p also)
  • -s: Reserve space in cabinet for signing (for example, -s 6144 reserves 6 Kb bytes)
  • -i: Set cabinet set ID when creating cabinets (default is 0)

To make a simple .wsp Solution file, utilize the following:

CABARC N mySolution.wsp file1.aspx file2.dll manifest.xml

This command creates the Solution file mySolution.wsp containing the files "file1.aspx", "file2.dll", and "manifest.xml" (bear in mind the "manifest.xml" file is obligatory), in a single folder, drawing on the default compression mode, MSZIP.

To make Solution files that deploy files to special directories in the 12 hive of SharePoint, it is essential that the directory structure within the WSP file is preserved relative to the 12 hive. For example, to deploy a Feature, the files need to be located in a "TEMPLATEFEATURES" directory in the WSP file. Figure 1 illustrates the directory structure for the files of a sample feature:



Click here for a larger image.

Figure 1: File structure for a Solution

In this case, where the file structure is preserved, the syntax to make the Solution_Test.wsp at the root of C: directory will be:

CABARC.EXE -p -P TemporaryJupiterMediaFeature n C:Solution_Test.wsp
   C: TemporaryJupiterMediaFeatureResources*.*
   C: TemporaryJupiterMediaFeature CTypes.xml
   C: TemporaryJupiterMediaFeatureFeature.dll
   C:Temporarymanifest.xml

This is considerably more complicated than employing a simple structure. To assist with the construction of the file, there is a gratis windows application that can be downloaded from www.gavd.net/servers/sharepointv3/spsv3_item.aspx?top=5&itm=431. This application asks for the files to be compressed and their location inside the 12 hive; after configurating the location and type of output (WSP or CAB), all the intricacies will be assumed by the application:



Click here for a larger image.

Figure 2: Making a .wsp file with the SolutionBuilder

There is also a Visual Studio 2005 Template that can be downloaded for free from http://www.codeplex.com/sptemplateland. This Template creates a Visual Studio 2005 Project that takes care of the construction of the .wsp file.

Conclusion

The litany of grievances regarding development and the installation process, and specifically deployment of custom-made software, with SharePoint Portal Server 2003 or Windows SharePoint Services 2.0 is legion. The tiresome process of manual copy-and-paste of files and the time-consuming construction of custom-installed programs were the only options available.

With the launch of SharePoint 2007 (MOSS and WSS) and the introduction of the SharePoint Solutions framework, in one sweep, there was a solution to these inadequacies. the framework ensures the deployment, activation, deactivation, and removal of the customizations, as well as deployment in all of the servers in the farm. It does this in a controlled and time-tabled manner, allowing for version organization and complete transparency for system administrators.

Solutions can be employed programmatically, from the user interface of the SharePoint Central Administration or using the administrators' tool "stsadm". The construction of the manifest file is efficient and orderly, and there are tools to assist in the construction and compilation of the final WSP file.

About the Author

Gustavo Velez is a MCSD Senior Application Developer for Winvision (http://www.winvision.nl), a Microsoft Gold Partner in the Netherlands. He has had many years experience in developing Windows and Office applications, and more than five years of daily programming experience with SharePoint. The author's articles—in English, Dutch, and Spanish—can be found in many of the leading trade magazines and he's pleased to be Webmaster of http://www.gavd.net/servers, the only Spanish-language dedicated SharePoint site. Spanish-language readers may want to consult the author's new book; Programación con SharePoint 2007.

Sitemap | Contact Us