How to: Extend the STSADM Utility
Applies to: SharePoint Foundation 2010
Warning
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.
Create a class that implements the ISPStsadmCommand interface.
Inform STSADM about your extension by registering the class and its assembly.
Create a class that implements ISPStsadmCommand
Start a Class Library project in Visual Studio.
Add using statements for Microsoft.SharePoint and Microsoft.SharePoint.StsAdmin.
Use a namespace that follows the pattern CompanyName.TechnologyName.Feature.SubFeature. For example, AjaxInc.SharePoint.StsAdmin.CustomCommands. (See Names of Namespaces.)
Use a class name that expresses the common denominator of the new STSADM operations that you will be creating; for example, "SortCommands".
The class should inherit ISPStsadmCommand; with a declaration similar to the following.
public class SortCommands : ISPStsAdminCommand
Write the implementation of the GetHelpMessage method. See the example below.
Write the implementation of the Run method. See the example below.
Compile the project, using the namespace name as the name of the assembly.
Deploy the assembly to the global assembly cache; for example C:\Windows\Assembly.
Register the new class and assembly
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>.
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>Replace command_name, fully_qualified_class_name, and assembly_name with the appropriate values. (Do not include the ".dll" extension on the assembly name.)
Replace value with the public key token for your assembly which you obtain with these steps.
Right-click your assembly in the global assembly cache and select Properties.
On the General tab, copy the Public Key Token value.
Paste it as the value for PublicKeyToken.
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>