Monday, June 14, 2010

Extending Stsadm.exe with Custom Commands using the ISPStsadmCommand Interface !

Extending Stsadm.exe with Custom Commands using the ISPStsadmCommand Interface

Windows SharePoint Services ships with the stsadm.exe utility to provide administrators a command line interface for managing SharePoint servers and sites. In the new WSS v3/MOSS 2007, Microsoft has greatly expanded stsadm.exe with several new operations to help us manage the vastly expanded functionality these new versions of SharePoint provide . During a recent SharePoint Solutions company meeting to review the curriculum of our new Upgrading From SharePoint 2003 to SharePoint 2007 training course, one of our SharePoint experts brought to our attention that the WSS v3 administrator's documentation briefly mentions the stsadm.exe utility is now extensible for developers to create custom operations to augment OOB functionality. The potential to extend stsadm.exe immediately piqued the curiosity of our software development team, so fellow SharePoint Solutions' software engineer Jeremy Luerkens and I set about to discover the means by which we could add custom operations to this useful command line utility.

Jeremy subsequently came across some Spartan documentation from Microsoft for the ISPStsadmCommand interface. As with most API documentation currently available for WSS v3/MOSS 2007, very little along the lines of examples and usage instructions is provided as of yet, so I took over the process of investigating and reverse engineering how we could make use of the ISPStsadmCommand interface to create custom operations for stsadm.exe. Utilizing Lutz Roeder's .NET Reflector utility and also SysInternal's Filemon application, I determined that extending stsadm.exe is really just a two-step process which involves creating a .NET class library for housing our custom operations, and placing an appropriately named XML configuration file in the right location for stsadm.exe to find it. For the remainder of this article I'll explain how you can extend stsadm.exe with custom commands of your own, and provide you with a Visual Studio 2005 solution download containing examples to get you started in the right direction.

Let's start by taking a look at the syntax used to execute commands with stsadm.exe. Note that the stsadm.exe utility itself is located in the folder [12 Hive]\BIN where "12 Hive" is typically C:\Program Files\Common Files\Microsoft Shared\web server extensions\12 in most WSS v3 implementations. The stsadm.exe utility makes use of named parameters to parse the values and flags provided by an administrator in order to execute a particular operation. All operations which stsadm.exe is capable of executing contain the named parameter -o <operation> where operation indicates the command to be executed. A canonical example would be stsadm.exe -o createweb to create a new WSS web. The createweb operation also requires the additional named parameter -url to specify a web address at which our new web will be created. Although other named parameters may also be included to further refine the operation's execution, the simplest example to create a new WSS web would follow the syntax stsadm.exe -o createweb -url http://beta/mynewweb.

Getting help and usage instructions for a particular operation is accomplished by executing stsadm.exe -help <operation> e.g. stsadm.exe -help createweb. The subsequent output from stsadm.exe will provide administrators with usage information for all named parameters and flags available for the given operation. Also note that summary help and usage for all operations can be viewed by executing stsadm.exe -help or simply stsadm.exe with no parameters at all.

Now that we understand how to execute operations and get help with usage, we can begin extending OOB stsadm.exe functionality with our own custom operations. As it turns out, the configuration files that indicate to stsadm.exe which operations are available for execution are intuitively located in the [12 Hive]\CONFIG folder. Remember that the "12 Hive" is usually C:\Program Files\Common Files\Microsoft Shared\web server extensions\12. Configuration files must follow the well known naming convention stsadmcommands.customcommands.xml where customcommands is arbitrary but must be unique. Through this naming convention for configuration files, stsadm.exe implements a pluggable architecture for declaring custom operations.

The configuration file itself is a simple XML document with a <Commands/> root element containing one or more <Command/> sub-elements. These <Command/> sub-elements are where we declare custom operations and include two attributes name and class. As would be expected, the name attribute indicates the name of the operation to be executed by stsadm.exe. Note that the exact value of the name attribute will be specified by an administrator at runtime using the -o named parameter in order to execute the declared custom operation. The second attribute class specifies the class and .NET Assembly name where our classes that implement the ISPStsadmCommand interface live.

The .NET assembly containing our compiled custom operation(s) will be placed in the Global Assembly Cache (GAC) prior to runtime. This assembly contains one class for each custom stsadm.exe operation, and each of these classes must implement the ISPStsadmCommand interface. Each class that implements the ISPStsadmCommand interface is required to contain a GetHelpMessage method and a Run method. The GetHelpMessage method returns a string value containing help and usage information for the custom operation.

At runtime, the Run method will receive a StringDictionary parameter from stsadm.exe which consists of key/value pairs containing all named parameters, values and flags input from the WSS administrator. The Run method also takes an out type parameter which will be echoed back to the console window upon execution of the custom operation.

The example Visual Studio 2005 solution accompanying this article contains a configuration file and three custom stsadm.exe operations.

The custom operations are trivial implementations meant solely for illustrative purposes. Upon compilation, the class library's post-build event will place the stsadm.exe configuration file in the appropriate [12 Hive]\CONFIG folder and also place the compiled .NET assembly into the Global Assembly Cache. A link to download the sample solution is provided below.

UPDATED June 12th, 2009 to new Visual Studio 2008 sample download:

Download (5 KB)

No comments:

Post a Comment