Custom SharePoint STSADM Commands

• Download demo project - 7.36 KB
• Download source - 34.87 KB

Introduction

With Microsoft Office SharePoint Server 2007 (MOSS) and of course the WSS v3, it is possible to implement custom commands for the STSADM Administration Tool.

Why?

You want to implement little helpers for developing/testing without an administration interface.

You want to add functionality for administrators to help them, including the possibility to script those commands for batch usage.

There might be some other reasons to implement custom commands, but the ones above are the most asked questions and purposes.

My intention in this is mainly supposed to help developers who implement custom timer jobs like I did.

How?

Developing a custom command is very simple. There is only a small overhead of managing the project and deploying it. That's good, so you can focus on the main goal.

You need one class which implements ISPStsadmCommand and an XML file for the registration of your command so that the stsadm.exe knows what to do with your command.

Depending on the parameters and functionality you provide, you write some help messages for the user to display on the command prompt. If you are an aesthetic, this might take longer than normal.

I give you a short sample on how to implement a custom command. Detailed instructions can be found in an article by Tony Bierman.

1. Create a Class Library Project in Visual Studio and reference the Microsoft.Sharepoint.dll
2. Create a class with the name of your command, for example GetJobInfo.cs
3. Let the class implement the interface ISPStsadmCommand found in Microsoft.SharePoint.StsAdmin
4. Return some useful helptext in the method GetHelpMessage
5. Implement your functionality in the method Run including argument validation and useful help for the user if he missed some parameters
6. Sign, compile and deploy your assembly to the gac
7. Create the XML file and add your commands and reference to the assembly and copy this XML to your \webs server extensions\12\CONFIG folder.
8. Check your return values and messages and feel good that you have just implemented a custom SharePoint administration command which might find someone useful ;)

In my current project, I have developed some timer jobs for SharePoint and found it very unhandy to administrate the jobs. So I started to implement a set of commands which I want to share with you. If new commands get developed, I update this collection.

Commands

GetJobInfo

Displays information about a specific timer job.

I found it useful to get the range of the next occurrence. Moreover, I used this command to verify changes I made to the job definition.

GetJobInfos

Similar to the GetJobInfo command, but displays the information for all timer jobs available.

With this information, you can get the name of the timer job needed for the GetJobInfo command.

RunTimerJob

Executes the specified Timer Job immediately.

To test the functionality of a job when YOU need it, you can now simply execute a timer job. With that, you can execute a job on a test/live server although it's configured for a daily schedule. That's what I did in my current project. On my development machine, I have set a minute schedule and on the live server, there needs to be a daily schedule. As I know, the only place where you set the time a job executes is a feature with the FeatureActivating/FeatureDeactivating method overwritten (FeatureReceiver Link). It's unhandy for development and test machines to change this in code and to redeploy the assemblies. This can also be done with the next command.

SetJobSchedule

Sets the schedule of a specified job.

With this command you can change the time a job executes. Very handy for development to live changes and vice versa. Look at what I mentioned in the command before.

HINT: It's not possible to change a OneTimeSchedule to another type of schedule.

Recommendations/Optimizations

Use resource files to translate error/hint messages if applicable.

Although it's possible, do not implement more than one command functionality in one class. You get the command passed in the Run method and so you could use a switch statement. It's easier to find commands on the class name. I also name the class equal to the command name. It's also easier to document.

What I don't know at this time is the handling of the int return parameter of the run method. Maybe it's the exit code which you can use in batch modes. If so, this should also be documented. If someone knows the behavior on this, please let me know.

I will update this "command set" when I develop new commands (and I can publish that).

If you like this information and perhaps find the commands useful, or even better if you can use them, please let me know.