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.
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.
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>
<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.
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=126.96.36.199, 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>