The nature of the SharePoint Products and Technologies platform causes files to be placed in a variety of locations. Definitions and features are copied to a folder on the WFE servers; modules and list instances are created in the content database; Web configuration files in the wwwroot folders are updated; and custom locations are used for additional files created by developers. To address this problem, the platform has a unified infrastructure for deploying components. This infrastructure uses solution files, which are compressed cabinets called CAB files.
The deployment of development artifacts to test or production servers must be performed using the solution framework. If you attempt to do so outside of this framework, service outages can result. For example, features are deployed to a subfolder of the root SharePoint directory. By default, the root folder is located at C:Program FilesCommon FilesMicrosoft SharedWeb server extensions12. If a folder is created manually by right-clicking on the parent folder in Windows Explorer, the new folder will not inherit permissions from its parent. This may cause the folder to be inaccessible to the Web server process, which will cause the rendering of any site that uses the feature to fail.
The creation of solution files is a detailed process. The solution file must contain a manifest file that details the source and target locations of all other files in the solution. In addition, the tool provided by Microsoft for creating the cabinet file requires an input list of files to include. There are several open-source projects on Microsoft’s CodePlex site (http://www.codeplex.com) that will automate the creation of solution files. Use of one of these tools is recommended.
Solution files for the SharePoint platform are created using the MAKECAB.EXE program. MAKECAB.EXE has many options, all of which are documented in the Cabinet SDK available from Microsoft at http://suport.microsoft.com/kb/310618. The Cabinet SDK is not required. The program is included with the operating system starting in Windows 2000. The options that are necessary for SharePoint solution files are discussed in this section.
The easiest approach for running the MAKECAB.EXE program is to create a directive file that is used as input for the program. The directive file is a plain-text file that contains commands, one per line, that dictate how the cabinet file is created. The list of commands is quite extensive, but the only commands required for SharePoint solutions are the Set Variable and File Copy commands. The file can contain comments, which are recommended. Comments are noted by a single semicolon (;) at the beginning of a line.
The File Copy command is the most frequently used and has the simplest syntax. The source file is specified, followed by the destination within the output cabinet. The destination is optional, which means the File Copy command can simply be the name of a file. The Set Variable command, as well as all other commands, is prefixed with a single period (".Set"). The Set Variable command has a large list of variables, of which only a few are necessary.
At the top of the directive file, use the following commands to specify the name of the solution file and the output directory. The single period for the DiskDirectory1 variable indicates the current directory. Using absolute paths (i.e., C:SolutionDirectory) will cause incompatibilities between developers if they use differing development environments.
.Set CabinetNameTemplate="Image Upload Web Part.wsp" .Set DiskDirectory1=.
Note
The value of the CabinetNameTemplate will be the only description available to operations when referencing the solution. It is best practice to use fully descriptive names for Windows SharePoint Services Solution Packages.
Next, add commands that override the default size settings. By default, the MAKECAB.EXE program will create as many cabinet files as necessary to hold the files provided, with each cabinet file formatted to fit on a single 3.5-inch, high-density floppy drive (1.44 MB).
; Override size limits for the wsp (cab) file ; .Set CabinetFileCountThreshold=0 .Set FolderFileCountThreshold=0 .Set FolderSizeThreshold=0 .Set MaxCabinetSize=0 .Set MaxDiskFileCount=0 .Set MaxDiskSize=0
After these initialization commands are entered, the remainder of the file contains File Copy commands. Folders in the cabinet file are not necessary unless the cabinet file needs to contain two files with the same name (for example, if the cabinet will contain two features, each with a feature.xml file). Although this is not strictly necessary, building a folder structure in the cabinet file that matches the destination folders in the SharePoint root folder will provide a directive file that is much easier to understand in the future.
Note
It is a best practice to group files in a Windows SharePoint Services Solution Package within folders that mimic the deployment destination structure.
Specifying the folders in a cabinet file can be accomplished in two ways. First, the File Copy command can include the destination that includes a relative path.
feature.xml ImageUploadfeature.xml
Commands in the directive file are limited to 256 characters. As an alternative to specifying the file path in the source and destination names, the SourceDir and DestinationDir variables can be set. Then, the File Copy command needs only the file name. Using .Set is the preferred method of specifying folders in a .ddf file.
.Set SourceDir=. .Set DestinationDir=ImageUpload feature.xml
In addition to the artifacts created for a solution—assemblies, pages, and definition files—a solution must contain a manifest file. This file is an .xml file that indicates to the solution framework what is contained in the solution and where those contents should be placed. Other settings required by the contents of the solution—such as Code Access Security settings, Safe Control settings, and resources—can be specified in the solution manifest as well.
A solution manifest has elements for each of the component types that can be deployed via the solution framework. These elements have attributes that reference individual files in the solution file, which must match the destination they were assigned in the File Copy command of the MAKECAB.EXE program. The final destination of these files is determined by the element type (FeatureManifest, SiteDefinitionManifest, TemplateFiles, and so on) Where appropriate, the elements provide for specifying additional deployment information.
The root SharePoint folder has been mentioned throughout this chapter. Beneath the root folder are folders for the definitions and components used on the WFE servers.
Fortunately, the solution framework has elements that match the functionality of the components rather than their final location.
The FeatureManifests element and its child FeatureManifest are used to identify the .xml file that describes a feature. The Location attribute of the FeatureManifest element contains the root-relative path of the file in the solution file. It is expected that this location will contain a folder that is unique in the farm. This folder name will automatically be created in the directory 12TEMPLATEFEATURES.
The SiteDefinitionManifests and its child SiteDefinitionManifest are used to identify the folder on the file system that will contain the files that make up the site definition via the Location attribute on the SiteDefinitionManifest element. This folder is created automatically in the directory 12TEMPLATESiteDefinition. In addition, the framework creates a subfolder below this location named "xml" and puts the onet.xml file (required for a site definition) into this subfolder. The onet.xml file must exist in the solution file (in a folder named "xml"), but the onet.xml file is not referenced in the solution manifest file.
The SiteDefinitionManifest element has a child element named WebTempFile. The WebTempFile element specifies the location in the solution file of the webtemp*.xml file. (This is another file required in a site definition.) WebTemp files must be installed in a folder below 12TEMPLATE that is named after the locale ID of the definition’s language. The value for U.S. English is "1033xml." Notice that it does not contain TEMPLATE. Accordingly, the source file must be in a folder with the same name in the solution cabinet file.
The solution manifest specifies the location to which assemblies are deployed—the GAC or the bin folder of the Web application. This location is specified via the DeploymentTarget attribute. If the location is the bin folder, then the deployment of the solution will require the URL of the target Web application. (The STSADM command will need the -url parameter. If deployed via the Central Administration Web page, then the Deploy Solution form will display a drop-down list at the bottom.)
If the assembly being deployed contains a control that is rendered on Web pages, SharePoint will require an entry in the SafeControls section of the Web.config file. The solution framework provides for specifying the details of this Web.config file entry. When the solution is deployed to a Web application, the Web.config file will be updated automatically based on the values provided on the SafeControl element(s) in the solution manifest. Because Web applications can be hosted on multiple servers, using this facility is recommended instead of manually updating the Web.config files.
Similarly, any resources required by the assembly’s controls can be deployed automatically by including a ClassResources element. These resources are external to the assembly file (.dll), such as images, browser script files, and style sheets. The physical location of assembly resources depends upon the deployment target (GAC vs. Web application) of the assembly. However, this resource location does not need to be specified in the solution manifest—the framework will deploy the files correctly.
The most common elements used in the solution manifest are the TemplateFiles and RootFiles elements. These elements copy the referenced file to the like-named folder on the WFE servers. These elements should be used for files that are not handled by other elements, such as application pages (those that are accessed via the _layouts address), administration pages (displayed in Central Administration), user controls, and images.
As discussed in detail in Chapter 17, a custom Code Access Security policy can be set for a Web application during solution deployment. The CodeAccessSecurity element is required only for assemblies that are deployed to the Web application bin folder. Assemblies deployed to the GAC will execute with full trust.