Share via


ISPStsadmCommand.Run Method

Executes the specified operation. This method is deprecated and may not be supported in future releases of SharePoint Foundation. For custom command line operations, see the Microsoft.SharePoint.PowerShell namespace.

Namespace:  Microsoft.SharePoint.StsAdmin
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)

Syntax

'Declaration
Function Run ( _
    command As String, _
    keyValues As StringDictionary, _
    <OutAttribute> ByRef output As String _
) As Integer
'Usage
Dim instance As ISPStsadmCommand
Dim command As String
Dim keyValues As StringDictionary
Dim output As String
Dim returnValue As Integer

returnValue = instance.Run(command, keyValues, _
    output)
int Run(
    string command,
    StringDictionary keyValues,
    out string output
)

Parameters

Return Value

Type: System.Int32
An Int32 that can be used to signal the result of the operation. For proper operation with STSADM, use the following rules when implementing.
Return 0 for success.
Return GeneralError (-1) for any error other than syntax.
Return SyntaxError (-2) for a syntax error.
When 0 is returned, STSADM streams output, if it is not a null reference (Nothing in Visual Basic), to the console.
When SyntaxError is returned, STSADM calls GetHelpMessage and its return value is streamed to the console, and it streams output, if it is not a null reference (Nothing in Visual Basic), to stderr (standard error). To obtain the content of stderr in managed code, use Error.
When any other value is returned, STSADM streams output, if it is not a null reference (Nothing in Visual Basic), to stderr.

Remarks

Warning

This method is documented only to provide assistance in troubleshooting existing extensions of STSADM.EXE. Do not create new extensions. Instead, extend PowerShell. See the Microsoft.SharePoint.PowerShell namespace.

Each member of keyValues is a pair consisting of a parameter name (which cannot be a null reference (Nothing in Visual Basic)) followed by a value (which can be a null reference (Nothing in Visual Basic)).

This method is called when the user enters the following at the system prompt, where myOperation is the name of your custom operation and parameters is the set of parameter/value pairs. Each parameter begins with a "-" and is separated from its value, if any, by a space.

stsadm -o myOperation [parameters]

If there are restrictions on the combination of parameters or parameter values that can be used, these restrictions should be enforced by your implementation.

Consider explaining these restrictions with the output parameter whenever they are violated. This parameter is streamed to stderr whenever, Run returns a value other than 0.

For example, suppose an operation is meant to operate on sites that may or may not be optimized for viewing on mobile devices, such as Web-enabled cell phones. Such an operation might test for mobile device awareness with an "ismobile" parameter that can have "true" or "false" as values. The operation might also require a "renderinglimit" parameter that sets the maximum size of a message string whenever "ismobile" is "true". If a user fails to include a "renderinglimit" value on a command line that sets "ismobile" to true, Run should return a value other than 0 or SyntaxError (-2), and the string returned by the output parameter should specify that when "ismobile" is true, "renderinglimit" must be present and set to a value.

Examples

The following example shows an implementation of Run for an operation that itemizes the features of a site. Note that because the custom class in this example creates only one new operation, the switch statement (Select Case in Visual Basic) must account for only that one operation ("enumfeatures") and the default (Else in Visual Basic) case. If more than one new operation were being defined, the case statement would need to handle each possible value of command.

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

namespace MS.Samples.SharePoint
{
    public class SimpleCommandHandler : ISPStsadmCommand
    {
        //GetHelpMessage() implementation not shown. 

        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 
        Implements ISPStsadmCommand 
        'GetHelpMessage() implementation not shown. 
        
        Public Function Run(ByVal command As String, ByVal keyValues As StringDictionary, 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, 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 + "':" & Chr(10) & "") 
            
            For Each feature As SPFeature In features 
                sb.AppendLine(feature.Definition.DisplayName + " (" + feature.DefinitionId + ")") 
            Next 
            
            output = sb.ToString() 
            
            Return 0 
        End Function 
    End Class 
End Namespace

See Also

Reference

ISPStsadmCommand Interface

ISPStsadmCommand Members

Microsoft.SharePoint.StsAdmin Namespace

Other Resources

How to: Extend the STSADM Utility

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