Heute möchte ich mich mit dem Thema Webpart-Deployment auseinandersetzen und beschreiben, wie ein Webpart mithilfe einer Solution auf einer SharePoint Farm bereitgestellt werden kann. Aus meiner Sicht liefern SharePoint Solutions die wohl komfortabelste Möglichkeit, Webparts zu deployen. In diesem Artikel werde ich zunächst erklären, was eine Solution ist und im Anschluss die einzelnen Schritte zur Erstellung und Bereitstellung eines Solutions Packages beschreiben.

Was ist eine Solution?

Eine Solution liefert die Möglichkeit, Anwendungen auf eine SharePoint Farm zu transportieren und bereizustellen. Sie wird verwendet, um Webparts, Features, Site Definitions, Vorlagedateien (für das Layouts-Verzeichnis oder die Masterpage Galerie), Ressourcendateien, Assemblies oder Code Access Security-Dateien auf eine SharePoint Farm zu deployen. Die Solution ist sozusagen der Nachfolger des wppackager-Tools der SharePoint Services v2 und macht endlich Schluss mit dem manuellen Deployment von Dateien und Einstellungen.

 
Quelle: SharePoint SDK

Ein Solution Package ist im Wesentlichen eine Cabinet-Datei, die alle Elemente der Solution enthält. Die interne Struktur der Datei wird über eine XML-basierende Manifest-Datei beschreiben. Das Solution Package endet mit der Dateierweiterung WSP und wird verwendet, um die Solution auf der Farm zu installieren und auf eine Web Applikation zu deployen. Der komplette Deployment-Prozess wird über STSADM und die SharePoint Zentraladministration unterstützt. Ein besonderer Vorteil in der Verwendung von Solution Packages ist das automatische Deployment auf alle an der Farm beteiligten Fronend Server.

Erstellung eines Solution Packages Step by Step

Im Folgenden werde ich detailliert beschreiben, wie ein Solution Package erstellt werden kann, was dabei beachtet werden muss und welche Tools dazu nützlich sein könnten. In meinem Beispiel möchte ich einen einfachen Webpart über ein Feature zu einer Solution packen.

1. Webpart erstellen

Die erste Aufgabe besteht in der Erstellung eines Webparts. Hierfür habe ich eine neues Visual Studio 2005-Projekt mit der Vorlage einer Class-Library erstellt. Um aus einfachen Klasse ein Webpart zu gewinnen, muss sie von System.Web.UI.WebControls.WebParts.WebPart abgeleitet werden und einige Methoden überschreiben. Da es in diesem Artikel vordergründig um das Deployment geht werde ich mich damit begnügen, über die Render-Methode den Titel der aktuellen Website auszugeben.

using System;

using System.Collections.Generic;

using System.Text;

using System.Web.UI.WebControls.WebParts;

namespace CustomWebPart

{

    public class MyWebPart : WebPart

    {

        public MyWebPart()

        {

            this.ExportMode = WebPartExportMode.None;

        }

        protected override void Render(System.Web.UI.HtmlTextWriter writer)

        {

            base.Render(writer);

            writer.Write("Hallo");            

        }

    }

}

Hinweis: Wie Webparts mit Visual Studio 2005 entwickelt werden können beschreibt dieser Artikel.

2. Feature-Definition erstellen

Der Webpart wird auf dem Frontend Server über ein Feature deployt. Features liefern die Möglichkeit, Webparts in einer SharePoint-Umgebung über eine flexible Art und Weise bereitzustellen. Features sind eigenständige Elemente einer SharePoint Farm und sind in der Lage Funktionalität auf Ebene einer Web Applikation, Site Collection oder Website bereitzustellen. Neben Webparts können auch Site Definitions, Inhaltstypen, Websitespalten oder Workflows als Feature bereitgestellt werden. Features werden auf dem Fronent Server im Verzeichnis %SystemDrove%\Program Files\Common Files\web server extensions\12\TEMPLATE\FEATUES bereitgestellt und können über STSADM oder die Websiteeinstellungen auf einer SharePoint Site aktiviert werden.

Die Basisdatei eines Features ist die Feature.xml. Sie besteht aus einer ID, dem Titel, dem Scope, einer Beschreibung und der Referenz auf das Element Manifest.

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

<Feature xmlns="http://schemas.microsoft.com/sharepoint/" 

         Id="8921453D-2EA8-4326-A2CE-4F8A2DC7987C" 

         Title="Custom WebPart" 

         Hidden="FALSE" 

         Scope="Site" 

         Version="1.0.0.0">

    <ElementManifests>

        <ElementManifest Location="elements.xml" />

        <ElementFile Location="CustomWebPart.webpart" />        

    </ElementManifests>

</Feature>

Über das ID-Attribut bekommt das Feature eine eindeutige GUID, worüber es in der Farm identifiziert wird. Das Hidden-Attribut legt fest, ob das Feature innerhalb der Websiteeinstellungen in der Liste aller Features aufgelistet wird und von dieser Stelle aktiviert werden kann. Teilweise kann es sinnvoll sein, dass das Feature nur von Administratoren der Farm über STSADM aktiviert wird. Für diesen Fall muss das Attribut auf Hidden=“TRUE“ gesetzt werden. Weitere Informationen zu den Attributen des Feature-Elements liefert das SharePoint SDK http://msdn2.microsoft.com/en-us/library/ms436075.aspx

Die eigentliche Funktion des Features wird über das ElementManifest beschrieben. Dieses Manifest ist eine XML-basierte Datei, die über CAML-Ausdrücke die Elemente des Features beschreibt. Mögliche Elemente sind Inhaltstypen, benutzerdefinierte Controls, Felder, Listenvorlagen, Workflows oder Module. Eine Liste aller verfügbaren Elemente liefert das SharePoint SDK http://msdn2.microsoft.com/en-us/library/ms474383.aspx

Das Module-Element wird verwendet, um Dateien auf der Farm bereitzustellen.

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

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

    <Module Url="_catalogs/wp" RootWebOnly="TRUE">

        <File Url="CustomWebpart.webpart" Type="GhostableInLibrary">

            <Property Name="Group" Value="My Webpart Group" />

            <Property Name="Title" Value="My Custom Webpart" />

        </File>

    </Module>

</Elements>

Im aktuellen Beispiel wird über das Module-Element die Referenz auf die webpart-Datei und zusätzliche Einstellungen des Webparts beschrieben.

Hinweis: Die Erstellung der feature.xml oder element.xml muss nicht manuell erfolgen. Das SharePoint SDK oder Codeplex liefern hilfreiche Code Snipptes, die die Erstellung dieser beiden XML-Dateien erheblich vereinfachen. http://www.codeplex.com/SPDevMod

Neben dem ElementManifest wird in der Feature.xml noch ein ElementFile definiert, das den Pfad zur webpart-Datei enthält. Diese Datei ist der Nachfolger der DWP-Datei und definiert Eigenschaften des Webparts.

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

<webParts>

    <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">

        <metaData>

            <type name="CustomWebPart.MyWebPart, CustomWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

            <importErrorMessage>Error importing the Web Part.</importErrorMessage>

        </metaData>

        <data>

            <properties>

                <property name="Title" type="string">Custom Viewer Web Part</property>

            </properties>

        </data>

    </webPart>

</webParts>

Die Webpart-Definition besteht aus allgemeinen Metadaten, wie dem Titel oder der Beschreibung und einer Referenz auf die Webpart-Assembly. Weitere Informationen zu den optionalen Elementen und Attributen liefert diese Website. http://msdn2.microsoft.com/en-us/library/ms227561.aspx

Die Feature.xml, Element.xml und CustomWebpart.webpart-Datei können im selben Verzeichnis innerhalb des Projekts abgelegt werden.

3. Solution-Definition (manifest.xml) erstellen

Die Manifest.xml beschreibt die interne Struktur der Solution. Die Datei referenziert die an der Solution beteiligten Features, Assemblies, Ressourcen oder Code Access Security-Dateien. Das vollständige Solution Schema wird im SharePoint SDK beschrieben. http://msdn2.microsoft.com/en-us/library/ms442108.aspx

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

<Solution SolutionId="F61FFAF3-44AA-4a33-BDA7-4EFE9563E5C4"  xmlns="http://schemas.microsoft.com/sharepoint/">

    <FeatureManifests>

        <FeatureManifest Location="CustomWebPart\feature.xml" />

    </FeatureManifests>

    <Assemblies>          

        <Assembly DeploymentTarget="WebApplication" Location="CustomWebPart.dll">

            <SafeControls>

                <SafeControl Assembly="CustomWebPart" Namespace="CustomWebPart" TypeName="*"/>

            </SafeControls>

        </Assembly>        

    </Assemblies>

</Solution>

Das FeatureManifest-Element definiert den Pfad zur Feature.xml. Die Webpart-Assembly wird innerhalb des Assemblies-Elements spezifiziert. Das DeploymentTarget-Attribut legt fest, ob die Assembly in das BIN-Verzeichnis der Web Applikation oder im Global Assembly Cache gespeichert werden soll. Über das Location-Attribut wird der relative Pfad zur DLL-Datei der Assembly definiert. Das SafeControls-Element definiert die SafeControl-Einträge, die beim Deployment der Solution automatisch der der web.config der Web Applikation eingetragen werden. Mit diesem SafeControl-Eintrag wird der Webparts als „sicher“ registriert und kann auf einer Website hinzugefügt werden.

4. DDF-Datei erstellen

Mit der Erstellung der Feature-Dateien und der manifest.xml haben wir die Basis für die Generierung eines Solution Packages geschaffen. Jetzt kann die Solution gepackt werden. Eine Möglichkeit das Solution Package zu erstellen ist makecab.exe. Dieses Tool erwartet eine DDL (Diamond Directive File)-Datei, die die interne Struktur der Solution beschreibt. Wenn man diese Datei genauer betrachtet fühlt man sich eher an alte Zeit erinnert, da sie über INI-basierende Befehle seine Struktur beschreibt.

;

.OPTION EXPLICIT ; Generate errors 

.Set DiskDirectoryTemplate=CDROM 

.Set CompressionType=MSZIP 

.Set UniqueFiles=Off 

.Set Cabinet=On 

.Set DiskDirectory1=Package 

;************************************************** 

manifest.xml manifest.xml

..\bin\Debug\CustomWebPart.dll CustomWebPart.dll 

; *** add feature files

..\TEMPLATE\FEATURES\CustomWebPart\feature.xml CustomWebPart\feature.xml 

..\TEMPLATE\FEATURES\CustomWebPart\elements.xml CustomWebPart\elements.xml

..\TEMPLATE\FEATURES\CustomWebPart\CustomWebPart.webpart CustomWebPart\CustomWebPart.webpart 

;***End

Die Package.ddf enthält allgemeine Einstellungen und die externen und internen Pfade zu den Dateien der Solution. Makecab.exe nutzt diese Informationen, um die Inhalte der Cabinet-Datei zusammenzustellen und zu strukturieren. Eine vollständige Referenz der DDF-Datei liefert das Cabinet SDK.

Hinweise: Wem das hier alles zu aufwändig ist, findet eine Tool zur Generierung der DDF-Datei auf Codeplex.

Beide Dateien (manifest.xml und package.ddf) werden im Solution-Verzeichnis innerhalb des Projekts gespeichert.

5. Solution Package erststellen

Über den Befehl makecab.exe /F package.ddf /D CabinetNameTemplate=MySolution.wsp kann nun das fertige Solution Package erstellt werden.

Die resultierende WSP-Datei wird innerhalb des Projektverzeichnisses im Ordner Package gespeichert.

6. Solution installieren

Die durch makecab.exe gewonnene Datei kann nun auf den SharePoint Server kopiert und dann über den Befehl stsadm –o addsolution –filename MySolution.wsp installiert werden.

Als Ergebnis wird die Solution innerhalb der Zentraladministration in der Liste aller Solutions aufgeführt. Zentraladministration > Operations > Solution Management.

7. Deployment der Solution

Für das Deployment der Solution stellt SharePoint unterschiedliche Möglichkeiten bereit. Sie kann über den Befehl STSADM -o deploysolution oder über die Zentraladministration auf eine oder mehrere Web Applications deployt werden.

Die wohl einfachste Variante ist die Verwendung des Deploy-Buttons. In den Einstellungen besteht die Möglichkeit den Zeitpunkt des Deployments und die Web Applikation aufzuwählen.

Der Befehlt stsadm -o deploysolution -name mysolution -url http://dev -immediate führt zum gleichen Ergebnis.

Fazit

Mit der neuen Technologie der Solutions stellt SharePoint endlich die Möglichkeit bereit, ein professionelles Deployment von SharePoint-Anwendungen durchzuführen. Keine Kopie von Webpart-DLLs, keine manuellen Anpassung von web.config-Einstellungen und keine manuelle Wiederholung der Einstellungen für weitere Frontend Server. Solutions können über die Zentraladministration bequem verwaltet und über wenige Arbeitsschritte auf einer Zielanwendung deployt werden.

Die hier vorgestellten Schritte wirken auf den ersten Blick sehr aufwändig, allerdings gibt es viele Gründe, die diesen Aufwand rechtfertigen. Zudem existieren zahlreiche Werkzeuge, die die Erstellung von Solution Packages vereinfachen.

Nicht verschweigen möchte ich auch, dass die Visual Studio Extensions für Windows SharePoint Services die Erstellung von Solution Packages automatisiert durchführten. Ich persönlich bin kein Freund von diesen Erweiterungen, weil sie mir kaum Möglichkeiten geben, die Erstellung der Solution Packages zu beeinflussen. Zudem stehen die Extensions aktuelle nur für 32-Bit-Systeme bereit.

In einem weiteren Artikel werde ich zweigen, wie mehrere Webparts über eine Solution deployt werden können.