I'm planning to migrate a Microsoft SharePoint Portal Server 2003 installation from one hardware platform to another. I know how to use the SPBackup tool (part of SharePoint Portal Server) to restore the SharePoint databases on the new server, but I also need to redeploy our in-house and third-party Web Parts. Can I automate this process and still ensure that the Web Parts that end up on the new server are the same versions that are installed on the current server?
SharePoint Portal Server and Windows SharePoint Services both include the stsadm.exe command-line tool for deploying individual Web Part compressed cabinet format (CAB) files. You might already know about this tool, but let's look at how to use it to deploy CAB files to a SharePoint Web site's BIN folder or the Windows Global Assembly Cache (GAC).
To deploy a single CAB file—let's use a sample file named webpart1.cab—to the BIN folder of your new (i.e., target) SharePoint portal server, open a command prompt on that server and navigate to the directory that contains the CAB file. This example uses the stsadm.exe program in the %CommonProgramFiles%\Microsoft Shared\web server extensions\60\BIN\ folder. Assuming that the BIN folder is in your path specification, type
stsadm -o addwppack -filename webpart1.cab
Otherwise, either add stsadm.exe to the BIN folder or append the entire path to the previous example. (All commands should be typed on one line.)
If webpart1.cab contains an assembly that was signed when it was compiled (aka a strong-named assembly), you can install webpart1.cab to the GAC by using the following command:
stsadm -o -addwppack -filename webpart1.cab -globalinstall
By combining stsadm.exe with SharePoint Configuration Analyzer and the For command (part of cmd.exe), you can deploy your custom Web Part packages to the target server in a fraction of the time it would take you to complete the same task by using stsadm.exe alone. By taking this approach, you can also be sure that the redeployed Web Parts are exactly the same as those on the source server.
Microsoft provides SharePoint Configuration Analyzer at no charge; you can download the tool at http://www.microsoft.com/downloads/details.aspx?familyid=918f8c18-89dc-4b47-82ca34b393ea70e1&displaylang=en. SharePoint Configuration Analyzer is primarily a diagnostic tool for verifying and reporting your SharePoint configuration, but it's also a powerful deployment tool. You run SharePoint Configuration Analyzer on a front-end SharePoint portal server in a Web farm or (in a single-server implementation) the server on which you've installed all SharePoint Portal Server components. To dump all the installed CABs from the source server to a directory for reinstallation on the target server (on which you've already installed SharePoint Portal Server and recovered the SharePoint databases), follow this procedure:
- Start SharePoint Configuration Analyzer on the source server.
- In the Server address text box, verify or type your SharePoint Portal Server URL.
- Verify that the Site path text box contains a single forward slash (/).
- Ensure that the Explore results, List Web Part Packages, and Retrieve packages check boxes are selected. (You can select other check boxes as well, but these three are the only ones necessary to get a list of your custom Web Part packages.)
- Click Go.
When you select the List Web Part Packages check box, SharePoint Configuration Analyzer will list (in its Analysis results pane) which Web Part CAB files are installed in the BIN directory and which are installed in the GAC. Selecting the Retrieve packages check box causes the tool to dump all the CAB files to a directory that the tool creates below the folder that contains SharePoint Configuration Analyzer. SharePoint Configuration Analyzer names the folder VirtualServerName_PortNumber_AnalyzerPackage_time, where VirtualServerName is the name of the SharePoint Portal Server instance, PortNumber is the TCP port (typically either 80 or 443) that SharePoint Configuration Analyzer uses when it runs, and time is the time, to the second, at which SharePoint Configuration Analyzer created the folder to store the Web Part packages.
Now that you've extracted all the custom Web Parts, use the information from the Analysis results list to copy or move the CAB files that are installed in the BIN directory into one folder on the target server and copy or move the Web Parts that are installed in the GAC into another folder on the target server. Open a command prompt, navigate to the folder into which you placed the BIN directory CAB files, then type
FOR %I IN (*.cab) DO stsadm.exe -o addwppack -filename %I -force
Navigate to the folder into which you placed the GAC CAB files, then type
FOR %I IN (*.cab) DO stsadm.exe -o addwppack -filename %I -globalinstall -force
I'd like to tell you that your task is finished, but SharePoint Configuration Analyzer isn't particularly robust when it comes to Web Part deployments. One of my colleagues, Tom Lucas, uncovered several weaknesses in the tool.
First, if you've deployed more than one version of a Web Part, be aware that SharePoint Configuration Analyzer detects and auto-generates a CAB file for only one version. I haven't specifically analyzed which version the tool finds, but I imagine it's the first version listed in the source server's web.config file. After you've identified which version SharePoint Configuration Analyzer deploys, find the original CAB file that wasn't deployed and manually deploy it by using stsadm.exe or by placing it in the appropriate CAB folder for deployment using the For commands I've described.
Second, SharePoint Configuration Analyzer doesn't deploy any secondary resources that are included with a Web Part. For example, a Web Part might have an associated graphic file or .xml file stored in the _wpresources virtual directory, which points to the %CommonProgramFiles%\Microsoft Shared\web server extensions\wpresources folder. Web Parts installed to the BIN folder also store resources in the wpresources folder (below the Microsoft IIS root directory—typically c:\inetpub\wwwroot). To simplify the deployment of these secondary resources, copy the contents of the wpresources folders on the source server to equivalent locations on the target server after you deploy the CAB files.
After installing assemblies to the GAC, you need to restart IIS to make the Web Parts available. To restart IIS, open a command prompt and type
Both of the For commands listed above run stsadm.exe with the parameters specified after the Do statement. The first part of each statement, For %I IN (*.cab), tells the For command to place the full name of the CAB file in the %I variable. The second %I variable specification passes that name to stsadm.exe. The For command syntax is admittedly a little confusing, but once you use it a few times, you'll see how powerful it can be at automating many repetitive tasks.
These examples illustrate a simple way to efficiently redeploy your custom Web Part packages. You can extend this deployment method by placing these For commands in the batch-file format that Listing 1 and Listing 2 show. Note that when you use the For command at the command line, the command uses a single percent sign (%) for the variable. In contrast, you must use double percent signs (%%) when you use the variable as shown in Listings 1 and 2. You might also want to automatically move successfully installed CAB files to an alternative directory following the deployment and log the results of the installation.