How to: Extend the STSADM Utility

Applies to: SharePoint Foundation 2010

The STSADM.EXE utility enables many administrative operations in Windows SharePoint Services that cannot be done with the Central Administration application. See the article Stsadm.exe command-line tool (Office SharePoint Server) in Microsoft TechNet for details. With Windows SharePoint Services 3.0 you can extend the functionality of the STSADM utility by adding your own operations and command line parameters with simple projects using any .NET language.

Creating such a project requires two major tasks.

1. Create a class that implements the ISPStsadmCommand interface.

2. Inform STSADM about your extension by registering the class and its assembly.

Create a class that implements ISPStsadmCommand

1. Start a Class Library project in Visual Studio.

2. Add using statements for Microsoft.SharePoint and Microsoft.SharePoint.StsAdmin.

3. Use a namespace that follows the pattern CompanyName.TechnologyName.Feature.SubFeature. For example, AjaxInc.SharePoint.StsAdmin.CustomCommands. (See Names of Namespaces.)

4. Use a class name that expresses the common denominator of the new STSADM operations that you will be creating; for example, "SortCommands".

5. The class should inherit ISPStsadmCommand; with a declaration similar to the following.

   public class SortCommands : ISPStsAdminCommand

6. Write the implementation of the GetHelpMessage method. See the example below.

7. Write the implementation of the Run method. See the example below.

8. Compile the project, using the namespace name as the name of the assembly.

9. Deploy the assembly to the global assembly cache; for example C:\Windows\Assembly.

Register the new class and assembly

1. Create a text file (UTF-8) named stsadmcommands.uniqueID.xml, where uniqueID is the name of your company or some other ID that ensures uniqueness on any server on which your extension of STSADM might be deployed. The XML declaration should read simply <?xml version="1.0" encoding="utf-8" ?>. The top-level element is <commands></commands>.

2. For each custom STSADM operation you created—that is, each possible value of the command parameter of GetHelpMessage and Run—add a <command/> element (inside the <commands> element) to your stsadmcommands file with the following syntax. (See the following example.) Change the version and culture values as needed.

   <commands>
       <command 
           name="command_name" 
           class="fully_qualified_class_name, assembly_name, 
           Version=1.0.0.0, 
           Culture=neutral, 
           PublicKeyToken=value"/>
       <!-- other command elements, if any -->
   </commands>
   

3. Replace command_name, fully_qualified_class_name, and assembly_name with the appropriate values. (Do not include the ".dll" extension on the assembly name.)

4. Replace value with the public key token for your assembly which you obtain with these steps.

   1. Right-click your assembly in the global assembly cache and select Properties.

   2. On the General tab, copy the Public Key Token value.

   3. Paste it as the value for PublicKeyToken.

5. Copy the stsadmcommands.uniqueID.xml file to C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\CONFIG.

Example

The following example shows the *.cs file and, below that, the stsadmcommands.uniqueID.xml file for a custom STSADM operation, called enumfeatures, that will list the features at a site.

using System;
using System.Collections.Specialized;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.StsAdmin;

namespace MS.Samples.SharePoint
{
    public class SimpleCommandHandler : ISPStsadmCommand
    {
        public string GetHelpMessage(string command)
        {
            return "-url <full url to a site in SharePoint>";
        }

        public int Run(string command, StringDictionary keyValues, out string output)
        {
            command = command.ToLowerInvariant();

            switch (command)
            {
                case "enumfeatures":
                    return this.EnumerateFeatures(keyValues, out output);

                default:
                    throw new InvalidOperationException();
            }
        }

        private int EnumerateFeatures(StringDictionary keyValues, out string output)
        {
            if (!keyValues.ContainsKey("url"))
            {
                throw new InvalidOperationException("The url parameter was not specified.");
            }

            String url = keyValues["url"];

            SPFeatureCollection features = null;
            SPWeb web = null;

            try
            {
                SPSite site = new SPSite(url);

                web = site.OpenWeb();

                features = web.Features;
            }
            catch (Exception e)
            {
                throw new InvalidOperationException("Error retrieving url '" + url + "'.  Please check the format of your url, and ensure that the site exists.  Details: " + e.Message);
            }

            StringBuilder sb = new StringBuilder();

            sb.AppendLine("Features at '" + web.Url + "':\n");

            foreach (SPFeature feature in features)
            {
                sb.AppendLine(feature.Definition.DisplayName + " (" + feature.DefinitionId + ")");
            }
            
            output = sb.ToString();

            return 0;
        }
    }
}

Imports System
Imports System.Collections.Specialized
Imports System.Text
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.StsAdmin

Namespace MS.Samples.SharePoint
    Public Class SimpleCommandHandler
        Inherits ISPStsadmCommand
        Public Function GetHelpMessage(ByVal command As String) As String
            Return "-url <full url to a site in SharePoint>"
        End Function

        Public Function Run(ByVal command As String, ByVal keyValues As StringDictionary, <System.Runtime.InteropServices.Out()> ByRef output As String) As Integer
            command = command.ToLowerInvariant()

            Select Case command
                Case "enumfeatures"
                    Return Me.EnumerateFeatures(keyValues, output)

                Case Else
                    Throw New InvalidOperationException()
            End Select
        End Function

        Private Function EnumerateFeatures(ByVal keyValues As StringDictionary, <System.Runtime.InteropServices.Out()> ByRef output As String) As Integer
            If Not keyValues.ContainsKey("url") Then
                Throw New InvalidOperationException("The url parameter was not specified.")
            End If

            Dim url As String = keyValues("url")

            Dim features As SPFeatureCollection = Nothing
            Dim web As SPWeb = Nothing

            Try
                Dim site As New SPSite(url)

                web = site.OpenWeb()

                features = web.Features
            Catch e As Exception
                Throw New InvalidOperationException("Error retrieving url '" & url & "'.  Please check the format of your url, and ensure that the site exists.  Details: " & e.Message)
            End Try

            Dim sb As New StringBuilder()

            sb.AppendLine("Features at '" & web.Url & "':" & vbLf)

            For Each feature As SPFeature In features
                sb.AppendLine(feature.Definition.DisplayName & " (" & feature.DefinitionId & ")")
            Next feature

            output = sb.ToString()

            Return 0
        End Function
    End Class
End Namespace

<?xml version="1.0" encoding="utf-8" ?>

<commands>
    <command 
        name="enumfeatures" 
        class="MS.Samples.SharePoint.SimpleCommandHandler, MS.Samples.SharePoint.CustomStsAdmCommand, 
        Version=1.0.0.0, 
        Culture=neutral, 
        PublicKeyToken=4da7a49e92ae373c"/>
</commands>

See Also

Reference

ISPStsadmCommand

GetHelpMessage

Run

Other Resources

Names of Namespaces

Stsadm.exe command-line tool (Office SharePoint Server)