Extend Your SharePoint Control with Custom Stsadm Commands
The SharePoint Team Services Administration application (stsadm), a command-line tool Microsoft introduced with SharePoint 2003, is the default way to administer and configure Windows SharePoint Services (WSS 3.0) and Microsoft Office SharePoint Server (MOSS), the company's premier tools for collaboration and knowledge workers. The 2007 version of stsadm offers an extended, richer set of commands, and introduces the ability to develop and configure custom commands.
Stsadm is a command-line program that doesn't provide an interface or other interaction with the user, making it a perfect candidate for use in scripts and automated operations. The program needs to run locally in one of the front-end SharePoint servers in the farm, and requires users to have administrative rights.
You can find stsadm in the directory C:\Program files\Common Files\microsoft shared\Web Server Extensions\12\BIN on any server where SharePoint is installed. To make stsadm usable directly from a command prompt without having to enter the complete path, add its path to the system variables: On the server, navigate to Start → Computer → Properties → Advanced system settings. In the window that appears, select Environment Variables from the Advanced tab, and add a new System variable. The next time that you want to use the tool, you can simply enter stsadm in the command line.
Stsadm contains 184 instructions to manage and administer different aspects of SharePoint. If you execute the stsadm command with no arguments, a complete list of commands appears on the screen. The directives can be separated into several different categories:
- Site maintenance: create, delete and enumerate sites
- Web maintenance: create, delete and enumerate Webs and sub-Webs
- User maintenance: add, delete, enumerate and migrate users
- Manipulate SharePoint Objects: backup and restore, installation and management of WebParts, Features, Solutions, and templates
- Server management: Add, delete, or enumerate databases, managed paths, Web Applications, and SharePoint Jobs
You can perform almost all these operations from the SharePoint interface; however, there are some exceptions, which you can execute only from the command-line stsadm tool:
- Execadmsvcjobs: Forces all configured SharePoint Jobs to run immediately.
- Createsiteinnewdb: Creates a new Site Collection using its own database.
- Getproperty and setproperty: Supports configuring diverse SharePoint properties
- Configures the number of days a "New" icon appears in new List and Library items
- Configures scanning time if new alerts need to be sent
- Configures the maximum number of Site templates
- Configures the maximum size of Blobs to be used in SQL server
You can find the complete command list on-line. Here's the syntax for stsadm:
stsadm -o OperationName -ParameterValue"
For example, to review all sites under the portal, use stsadm -o enumsites -url http://ServerName, where enumsites is the operation name, url is the parameter name, and http://ServerName is the parameter value. The operation name is required; parameters may be obligatory or optional. When values contain spaces, place them inside quotation marks.
As stated previously, stsadm is not interactive, which means you must take care to ensure that parameters and syntax are written correctly. Also, if something is not defined accurately, the operation completes with an error messageleaving you to reinitiate the entire command. On the other hand, stsadm allows developers and administrators to create batch files that run various commands in a timely way. For example, an administrator might write a batch file that initiates Windows Task Scheduler and creates a new batch to generate nightly SharePoint backups. Developers might use the tool to install or uninstall SharePoint components by automatically integrating them in the Visual Studio script engine. For example, you might do this to install components after a successful compilation.
When the built-in commands aren't enough, SharePoint 2007 supports the creation and configuration of custom stsadm operations. Although the default commands are extensive and quite complete, they don't include some operations of potential value to developers.
Two that come to mind immediately are:
- Enumerating features in a site
- The ability to delete web sites recursively
When you need such capabilities, creating new specialized, automatic commands can be extremely useful. The rest of this article shows how to build and add these two specialized custom commands to stsadm.