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
command
Type: System.StringThe name of the custom operation.
keyValues
Type: System.Collections.Specialized.StringDictionaryThe parameters, if any, that are added to the command line.
output
Type: System.StringAn output string, if needed.
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
Microsoft.SharePoint.StsAdmin Namespace