Scripting STSADM commands

Article
11/08/2007

This posting contains tips 'n tricks for using STSADM commands within batch files.

Note, the primary Microsoft reference for STSADM: TechNet article Stsadm command-line tool (Office SharePoint Server).

Testing results

STSADM returns 0 as ERRORLEVEL in DOS when it succeeds, or -1 when it fails. To test for success, IF %ERRORLEVEL% EQU 0 can be used.

Redirecting output

When scripting stsadm, sometimes it’s desired to redirect output to a file, using the “>” operator. This works as expected, but if stsadm displays error messages from executing its requested operation, the messages still go to the screen and not into the file. This is because DOS has two standard output devices, stdout and stderr. The > operator redirects stdout only. Fortunately, we can add another operator that will redirect stderr to stdout so that all messages go into the output file:

stsadm -o addsolution -filename MySoln.wsp >output.txt 2>&1

>& is a command redirection operator. Stderr is handle 2, and stdout is handle 1. Therefore, 2>&1 means redirect stderr to stdout. Since we've already redirected stdout to output.txt, then all messages will now go into this file.

See Microsoft article Using command redirection operators for further applications of this and related operators.

Finally, remember that >> will appendmessages from stdout to the specified file instead of overwriting; >>output.txt 2>&1 works to append all messages and errors.

Asynchronous commands

Some stsadm commands create a timer job to execute the operation so that it may be executed on multiple farm servers. Commands that use the following modifiers may behave this way:

-immediate Use a timer job to execute the operation on all applicable servers immediately… the job will start within one minute.

–time <time> Use a timer job to execute the operation on all applicable servers at the specified <time>.

-local Execute the operation on the local server immediately; return only after operation completes.

When using -immediate or -time, stsadm will return after creating the timer job. However, the operation itself will take a little while longer to finish its execution. This can become a problem in scripts such as

stsadm -o retractsolution -name mysolution.wsp -immediate

stsadm -o deletesolution -name mysolution.wsp

Here, the second command will fail because the retractsolution operation will not have been completed on all servers yet. The simplest fix that can be recommended is to ask for human intervention:

stsadm -o retractsolution -name mysolution.wsp -immediate

echo Wait for mysolution.wsp to be retracted across farm

pause

stsadm -o deletesolution -name mysolution.wsp

Note that the stsadm command execadmsvcjobs might seem to offer a clever solution, because it will cause outstanding deployments to complete synchronously. However, this command affects the local server only, so the same situation still exists on a multi-server farm.

Customer stsadm scenario… with a challenge

Many customers have requirements to deploy required configurations to their farm; this typically means they must deploy to several environments such as Dev, UAT and Production. They want to script these configurations whenever possible so that the process can be automated. Stsadm supplies operations to set some configurations, but not all. In addition, some of the ones that it does not cover can be very tedious to configure manually, such as search scopes, profile properties and audience definitions.

In these situations, creating an stsadm extension is a great approach to setting these configurations in an automated way. It matches the approach of scripting default stsadm commands to execute in different environments. Also, stsadm extensions can be deployed as other customizations are deployed, using SharePoint Solution files.

A flexible way to design these extensions to supply an import/export pair of operations. This way, a developer can configure their SharePoint instance to have the appropriate configurations, then use the stsadm extension to export the configuration settings as an xml file. On the UAT and Production farms, the stsadm extension can then be used to import from the xml file to make the appropriate configuration settings. This approach allows the process to be maintained throughout production, usually without requiring the developer’s involvement for further changes.

One challenge with this is deploying and executing the stsadm extension. These two operations should be performed as separate steps, because the deployment must be fully completed before attempting to execute. On a local server, a script can ensure the deployment step is complete by using the -local argument, but on a farm with multiple servers, the deployment must use -immediate, which executes as soon as possible, but asynchronously.

To do both operations in a script, it is necessary to wait for deployment explicitly, as shown in the following example:

stsadm -o addsolution -filename ImportProfileProperties.wsp

stsadm -o deploysolution -name ImportProfileProperties.wsp -immediate -allowgacdeployment

echo Wait for ImportProfileProperties.wsp to be deployed across farm