STSADM, das Werkzeug für den Administrator, lässt sich bei Bedarf um benutzerdefinierte Kommandos erweitern. Wie Extensions für STSADM implementiert und bereitgestellt werden, möchte ich in diesem Artikel beschreiben. In meinem Beispiel möchte ich eine Erweiterung implementieren, die mir eine beliebige URL dekodiert. Hinter diesem Projekt steckt auch ein praktischer Aspekt, da ich oft die Anforderung habe, die GUID aus einer kodierten List-ID (z.B. List=%7BEA98DB28%2D51B3%2D41D7%2D8A96%2DB1C55328020B%7D) auszulesen.

Los geht!

1. Visual Studio Class Library-Projekt erstellen

Die Extension wird als Class Library implementiert und spätter im Global Assembly Chache des SharePoint Servers bereitgestellt. Aus diesem Grund muss die Assembly zwingend mit einem Strong Name Key signiert werden.

2. ISPStsadmCommand-Interface implementieren

Das Interface ISPStsadmCommand implementiert zwei Methoden: GetHelpMessage zur Ausgabe der Hilfemeldung, sowie die Run-Methode, die für die Ausführung der eigentlichen Operation verantwortlich ist.

Die Grundstruktur der Klasse sieht wie folgt aus:

   1: public class UrlDecoder : ISPStsadmCommand

   2: {

   3:     public string GetHelpMessage(string command)

   4:     {

   5:         // Code for displaying the help message

   6:     }

   7:  

   8:     public int Run(string command, StringDictionary keyValues, out string output)

   9:     {

  10:         // Implementation of the stsadm command

  11:     }

  12: }

3. Kommando implementieren

Im Anschluss kann innerhalb der Run-Methode die neue STSADM-Erweiterung implementiert werden. Die Methode bekommt als Parameter den Namen des Kommandos sowie die Parameter als StringDictionary-Objekt. Das Ergebnis der Methode wird über die output-Variable zurückgeliefert. Der eigentliche Rückgabewert ist ein Integer. Bei einer fehlerfreien Ausführung der Methode wird der Wert 0 zurückgegeben. In diesem Fall gibt STSADM den Wert der output-Varialbe aus. Andernfalls wird die Nachricht der Hilfemeldung dargestellt. In meinem einfachen Beispiel wird die Plausibilität der Parameter überprüft, wonach der übergebene Wert über die HttpUtility-Klasse dekodiert bzw. kodiert wird.

   1: public string GetHelpMessage(string command)

   2: {

   3:     StringBuilder sb = new StringBuilder();

   4:     sb.Append("\r\n\r\nDecodes or encodes url strings.\r\n\r\nParameters:");

   5:     sb.Append("\r\n\t-url <the input string to decode or encode>");

   6:     sb.Append("\r\n\t[-decode] decode the url string (default)");

   7:     sb.Append("\r\n\t[-encode] encode the url string");

   8:  

   9:     return sb.ToString();

  10: }

  11:  

  12: public int Run(string command, StringDictionary keyValues, out string output)

  13: {

  14:     output = string.Empty;

  15:     try

  16:     {    

  17:         command = command.ToLowerInvariant();

  18:  

  19:         switch (command)

  20:         {

  21:             case "fm-decodeurl":

  22:             {

  23:                 return this.Execute(keyValues, out output);

  24:             }

  25:             default:

  26:             {

  27:                 throw new InvalidOperationException();

  28:             }

  29:         }

  30:     }           

  31:     catch (Exception ex)

  32:     {

  33:         output += ex.Message;

  34:         return (int)ErrorCodes.SyntaxError;

  35:     }

  36: }

  37:  

  38: private int Execute(StringDictionary keyValues, out string output)

  39: {

  40:     if (!keyValues.ContainsKey("url") || String.IsNullOrEmpty(keyValues["url"]))

  41:     {

  42:         throw new InvalidOperationException("The source guid string was not specified.");

  43:     }

  44:  

  45:     String sourceGuid = keyValues["url"];

  46:     bool encode = keyValues["encode"] != null ? true : false;

  47:  

  48:     if (encode)

  49:     {

  50:         output = HttpUtility.UrlEncode(sourceGuid);

  51:     }

  52:     else

  53:     {

  54:         output = HttpUtility.UrlDecode(sourceGuid);

  55:     }

  56:             

  57:     return 0;

  58: }

Die generierte Assembly muss danach in den Global Assembly Cache installiert werden.

4. STSADM-Erweiterung registrieren

Im letzten Schritt muss die Erweiterung auf dem SharePoint Server registiert werden. SharePoint verwaltet seine STSADM-Kommandos in XML-Dateien (z.B. stsadmcommands.sps.xml) innerhalb des CONFIG-Systemverzeichnisses (%ProgramFiles%\Common Files\microsoft shared\Web Server Extensions\12\CONFIG). Innerhalb dieser XML-Datei werden der Name sowie die Referenz auf die Assembly des Kommandos hinterlegt. Für das benutzerdefinierte STSADM-Kommando muss nun eine neue Deklaration mit der Signatur stsadmcommands.<MyExtension>.xml erstellt und in dieses Verzeichnis kopiert werden.

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

   2: <commands>

   3:   <command

   4:       name="fm-decodeurl" 

   5:       class="FM.Demos.STSADMExtensions.UrlDecoder, FM.Demos.STSADMExtensions, Version=1.0.0.0, Culture=neutral, PublicKeyToken=6d460c5222b8f2c1"/>

   6: </commands>

Durch die Kopie der XML-Datei in das CONFIG-Verzeichnis wird die neue Erweiterung automatisch für STSADM registriert. Weitere Schritte sind nicht erforderlich. Das neue Kommando direkt im Anschluss getestet werden:

Das hier vorgestellt Beispiel habe ich noch um eine SharePoint-Solution erweitert, die alle Komponenten der STSADM-Erweiterung automatisch in der Zielumgebung bereitstellt. Das Visual Studio-Projekt sowie die SharePoint-Solution können hier heruntergeladen werden.