Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

How to: Extend the STSADM Utility

Published: May 2010

Caution note Caution

Extending STSADM.EXE has been deprecated and will not be supported in future releases of Microsoft SharePoint Foundation 2010. This topic is provided solely to assist in troubleshooting existing extensions of STSADM.EXE. You should not create new extensions. Instead, consider extending Windows PowerShell. See Windows PowerShell in the SharePoint Management Shell.

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.

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;
        }
    }
}
<?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>
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.