Met de komst van WSS v3 en MOSS 2007 zijn de mogelijkheden voor het ontwikkelen van oplossingen op het SharePoint platform enorm uitgebreid. Hierdoor wordt ook de noodzaak van een goede aanpak voor het deployen van oplossingen erg groot. Microsoft onderkent in SharePoint 2007 twee belangrijke deployment mechanismen, te weten Content Deployment en Solution Deployment. Voor maatwerkoplossingen zal de meest voor de hand liggende deployment vorm die van Solution Deployment zijn.
In dit artikel zal ik een overview geven van de mogelijkheden van Solution Deployment in SharePoint 2007.
The Old Way
Iedereen die custom oplossingen heeft gebouwd voor SharePoint 2003 en daarbij gebruik gemaakt heeft van een OTAP omgeving, zal hebben ondervonden dat er in SharePoint 2003 geen goed mechanisme aanwezig was voor het deployen van deze oplossingen. Bij het deployen van een eenvoudig webpart met een DWP-file, een user control, een DLL en een plaatje moest al rekening gehouden worden met:
- Locatie van de dll (GAC of BIN folder)
- Afhankelijk van de locatie van de DLL verwachtte SharePoint het DWP-file en de user control in verschillende folders
- Sla je de image op bij de user controls of in de layouts folder
- Aanpassingen in WEB.CONFIG
Het kon echter nog complexer door het maken van bijvoorbeeld:
- Eigen site en lijstdefinities
- CSS-files en theme's
- ASPX-pagina's
- Enz…
Er was geen enkel mechanisme beschikbaar voor het deployen van al deze verschillende files naar de goede locatie. Dit betekende dat alleen een ervaren SharePoint ontwikkelaar in staat was om een custom oplossing te deployen. En dan nog hoefde je tijdens de deployment maar één vergissing te maken en er was een probleem dat kon variëren van het nieuwe webpart dat niet goed werkte tot hele sites die niet meer getoond werden.
De kans op fouten werd nog vergroot doordat alle deployment stappen op elke SharePoint web front-end server herhaald moesten worden.
Het deployen van een custom oplossing voor SharePoint 2003 was dus ingewikkeld, foutgevoelig en tijdrovend.
Het deployment mechanisme van SharePoint 2007 wordt het Solution Framework genoemd
The New Way
SharePoint 2007 wordt door Microsoft gepositioneerd als een platform voor het ontwikkelen van oplossingen. Dit kunnen zowel maatwerkoplossingen zijn als oplossingen op basis van configuratie van out of the box SharePoint functionaliteit. Bij het ontwikkelen van oplossingen hoort ook een OTAP omgeving en dus een goed deployment mechanisme. Gelukkig heeft Microsoft hier bij SharePoint 2007 ook voor gezorgd.
Het deployment mechanisme van SharePoint 2007 wordt het Solution Framework genoemd. Het Solution Framework zorgt ervoor dat er een manier is om alle files die je wilt gebruiken in je oplossing samen te voegen in een solution file. Een solution file is een gecomprimeerd CAB-bestand met een .WSP extensie. Bij het deployen van een solution file worden alle bestanden in het file uitgerold naar de juiste folders op alle web frontend servers in de farm.
De bestanden die uitgerold kunnen worden met behulp van het Solution Framework kunnen variëren van assemblies van custom webparts en eigen site definitions tot images en features om content types en site columns uit te rollen.
Behalve voor het uitrollen van een oplossing kan het Solution Framework ook gebruikt worden voor het retracten (deïnstalleren en verwijderen) van een solution en voor het uitrollen van updates van een solution. Het framework zorgt er ook voor dat alle solutions uitgerold worden naar een nieuwe web frontend server op het moment dat deze aan de farm wordt toegevoegd.
Om ervoor te zorgen dat alle files uit de solution file op de juiste plek worden uitgerold moet de solution file een metadata file bevatten met de naam MANIFEST.XML. Bij het deployen van de solution gebruikt de SharePoint installer MANIFEST.XML om te bepalen wat voor files er in het package zitten en waar deze files naar uitgerold moeten worden. Zo wordt in MANIFEST.XML b.v. aangegeven of een assembly uitgerold moet worden naar de GAC of naar de BIN van de web-application. Daarnaast bevat MANIFEST.XML informatie om b.v. features te kunnen installeren en activeren en om SafeControl entries aan WEB.CONFIG toe te voegen.
Solution File
Alle typen files die gebruikt kunnen worden om een SharePoint oplossing te bouwen kunnen uitgerold worden met behulp van een solution file. Denk hierbij onder andere aan:
- Site en lijst definities
- Feature definities en bijbehorende element manifest files en helper files
- Web Part files (*.WEBPART, *.DWP)
- Template files en root files (b.v. _LAYOUTS-files en resources (*.RESX))
- Assemblies
- Code access security policies
Je kunt een solution file genereren m.b.v. tools, maar het blijft nuttig om de achterliggende techniek te begrijpen, zodat je weet hoe het werkt
Er bestaan tools om een solution file te genereren, zoals de WSP Builder (http://www.codeplex.com/wspbuilder). Deze tool genereert het solution file en MANIFEST.XML en kan dus veel werk besparen. Het blijft echter wel nuttig om de achterliggende techniek te begrijpen en te weten waarnaartoe de verschillende typen files uitgerold moeten worden. Deze kennis kan nodig zijn om een probleem op een server op te lossen, maar ook willen systeembeheerders vaak weten welke files waar op hun server neergezet worden bij het installeren van een solution. Ik zal daarom hier uitleggen hoe het solution file en MANIFEST.XML met de hand gecreëerd kunnen worden.
Voordat we het solution file kunnen creëren moet er MANIFEST.XML gemaakt worden, omdat deze onderdeel uitmaakt van het solution file.
Het manifest file dat we gaan gebruiken zal de volgende functionaliteit toevoegen aan de SharePoint omgeving:
- Twee features
- Drie assemblies
- Eén webpart
- Eén image
- Eén stylesheet
Het manifest file kan er dan uitzien zoals in figuur 1.
Fig. 1: Inhoud van MANIFEST.XML
In het manifest file wordt eerst de metadata van de solution gedefinieerd. Daarna worden alle files uit het solution file op de goede plek benoemd, waardoor ze naar de juiste locatie op de server worden uitgerold. De structuur van het manifest schema is als volgt (en diverse van de beschreven elementen komen terug in de voorbeeld MANIFEST.XML hierboven).
Solution
Het Solution-element is het root-element en kent drie metadata properties, te weten:
- DeploymentServerType. De waarde van deze property kan WebFrontEnd zijn voor het deployen naar een SharePoint web frontend server, of ApplicationServer voor het deployen naar een SharePoint application server.
- SolutionId - dient uniek te zijn, op zijn minst op de machine waar de solution uitgerold wordt. SharePoint identificeert een solution via het id, dus voor de SharePoint omgeving is een identieke id een identieke solution, ongeacht de inhoud van de solution.
- ResetWebServer - om aan te geven of er na deployment een IIS reset uitgevoerd moet worden op de servers van de omgeving.
Daarnaast bevat het volgende child elements:
- FeatureManifests
- FeatureManifest - om aan te geven welke features er uitgerold moeten worden. De location property vertelt waar de files in het solution file te vinden zijn en waar in de folder C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES ze gedeployed moeten worden. Alleen de feature.xml files worden hier gespecificeerd. De element manifest files die in FEATURE.XML benoemd zijn worden automatisch mee uitgerold.
- Assemblies
- Assembly - heeft twee metadata properties, namelijk:
- DeploymentTarget. Geeft aan of de assembly uitgerold moet worden naar de GAC (C:\Windows\Assembly) of naar de BIN van de webpplicatie (C:\Inetpub\wwwroot\wss\VirtualDirectories\[[webapplication name]]\bin). Indien de assembly helper files, zoals een user control, bevat, bepaalt de locatie van de assembly ook de locatie van de user control. Als de assembly in de GAC staat worden de helper files in de C:\Program Files\Common Files\Microsoft Shared\web server extensions\wpresources directory geplaatst. Staat de assembly in de BIN van de webapplicatie, dan staan de helper files in C:\Inetpub\wwwroot\wss\VirtualDirectories\[[webapplication name]]\wpresources.
- Location - de locatie van de assemblies in het solution file en op het filesysteem, hoewel de GAC geen subfolders kent, dus die zullen bij deployment naar de GAC genegeerd worden.
- SafeControls
- SafeControl - definitie van safe control tags voor in WEB.CONFIG van de webapplicatie.
- ClassResources
- ClassResource - wordt gebruikt voor het deployen van alle resource files die bij de assembly horen (b.v. images). De tag heeft een FileName property, die de file uitrolt naar de wpresources directory die van toepassing is voor de assembly.
- DwpFiles
- DwpFile - voor het uitrollen van .DWP en .WEBPART files. Deze tag kent slechts één property, te weten de filename tag. Deze tag bevat zowel de filename als eventuele subfolders. De files worden uitgerold naar de C:\Inetpub\wwwroot\wss\VirtualDirectories\[[webapplication name]]\wpcatalog folder.
- RootFiles
- RootFile - tag voor het deployen van files naar de C:\Program Files\Common Files\Microsoft Shared\web server extensions\12 directory. Subfolders binnen deze directory en het solution file kunnen gedefinieerd worden in de location property.
- TemplateFiles
- TemplateFile - tag met dezelfde werking als de RootFile tag, maar de TemplateFile tag deployt files naar de C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\Template directory.
- SiteDefinitionManifests
- SiteDefinitionManifest - voor het deployen van SharePoint site definitions. Kent alleen de Location property om aan te geven waar in het solution file de site definition files zich bevinden en waar op het filesysteem ze uitgerold moeten worden. De standaard SharePoint folder voor site definitions is C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates.
- WebTempFile - de location property van deze tag geeft aan welke webtemp-files er zijn en waar ze naartoe uitgerold moeten worden. De webtemp-files van een SharePoint omgeving zijn terug te vinden in de folder C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\[[LCID]]\XML
- ApplicationResourceFiles
- ApplicationResourceFile - deze tag kan gebruikt worden voor het deployen van resource files (.RESX-files) op webapplicatie niveau. De tag heeft een location property; als de location MyResources\My1043Resource.resx is zal de file uitgerold worden naar C:\Inetpub\wwwroot\wss\VirtualDirectories\[[webapplication name]]\MyResources\My1043Resource.resx
- Resources
- Resource - net als ApplicationResourceFile een tag voor het deployen van resource files. De resource tag deployt echter niet in de context van de webapplicatie, maar in de features folder. Als voor Location MyFeature\My1043Resource.resx wordt ingevuld, zal de file uitgerold worden naar C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\MyFeature\My1043Resource.resx.
- CodeAccessSecurity - tag voor het instellen van een Code Access Security policy voor de solution. Dit is een zeer complex en uitgebreid onderwerp. In dit artikel zullen slechts de verschillende tags genoemd worden.
- PolicyItem - Eén solution kan meerdere policies hebben die worden aangegeven met de PolicyItem tag
- PermissionSet - deze tag definieert de rechten voor de CAS policy en heeft vier properties en child-elements:
- Naam van de permissionset class
- Version. Versie van deze PermissionSet
- Name. Naam van de PermissionSet
- Description. Omschrijving van deze PermissionSet
- IPermission - elke IPermission tag definieert een CAS permission zoals nodig om de assembly correct te laten werken. Kan vele properties en subtags bevatten, waaronder de properties Class en Version.
- Assemblies
- Assembly - definieert de assemblies waar dit PolicyItem betrekking op heeft. De Assembly tag heeft drie properties:
- Name. Naam van de assembly.
- PublicKeyBlob. Binaire weergave van de public key van de assembly
- Version. Versie van de assembly.
Nu het manifest file gecreëerd is kan het solution file gegenereerd worden. Voor het creëren van het solution file is het gemakkelijk om alle files die met behulp van het solution file uitgerold moeten worden, in een logische structuur in een folder neer te zetten, en dan vervolgens de files in dezelfde structuur in het solution file in te pakken.
De structuur van de files in de folder zou er dan uit kunnen zien zoals in figuur 2.
Fig. 2: Folderstructuur van de SharePoint Solution File
.DDF File
Om de files in deze structuur in de solution file te krijgen moet een .DDF file gemaakt worden. De inhoud van een .DDF file lijkt op die van een .INF file; in het .DDF file wordt eigenlijk in tekst de structuur van de files in de folders beschreven en daarachter, gescheiden door een spatie, de manier waarop deze in het solution file terecht moeten komen. In listing 1 is de structuur van een .DDF file te zien.
.OPTION EXPLICIT ; Generate errors
.Set CabinetNameTemplate=MySolutionFile.wsp
.set DiskDirectoryTemplate=CDROM
; All cabinets go in a single directory
.Set CompressionType=MSZIP
;** All files are compressed in cabinet files
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package
Feature-Macaw.IWSDesign.Moss2007.Design.Design\
MasterPages\mymaster.master
Feature-Macaw.IWSDesign.Moss2007.Design.Design\
MasterPages\mymaster.master
Feature-Macaw.IWSDesign.Moss2007.Design.Design\
Feature.xml
Feature-Macaw.IWSDesign.Moss2007.Design.Design\
Feature.xml
Feature-Macaw.IWSDesign.Moss2007.Design.Design\
Design.xml
Feature-Macaw.IWSDesign.Moss2007.Design.Design\
Design.xml
Feature-Macaw.IWSDesign.Moss2007.Design.DesignStapler\
Feature.xml
Feature-Macaw.IWSDesign.Moss2007.Design.DesignStapler\
Feature.xml
Feature-Macaw.IWSDesign.Moss2007.Design.DesignStapler\
DesignStapler.xml
Feature-Macaw.IWSDesign.Moss2007.Design.DesignStapler\
DesignStapler.xml
GAC\Macaw.IWSDesign.Moss2007.Design.SharePoint.
Features.dll
GAC\Macaw.IWSDesign.Moss2007.Design.SharePoint.
Features.dll
GAC\Macaw.IWSFoundation.Wss3.Framework.
OperationalManagement.dll
GAC\Macaw.IWSFoundation.Wss3.Framework.
OperationalManagement.dll
GAC\Macaw.IWSNews.Moss2007.EnhancedNews.Presentation.
WebPartUI.dll
GAC\Macaw.IWSNews.Moss2007.EnhancedNews.Presentation.
WebPartUI.dll
TEMPLATE\Images\Moss2007Design\titlegraphic.gif TEMPLATE\Images\Moss2007Design\titlegraphic.gif
TEMPLATE\Layouts\1033\Styles\mycss.css TEMPLATE\Layouts\1033\Styles\mycss.css
WebPart-Macaw.IWSNews.Moss2007.EnhancedNews\
NewsRollupWebPart.webpart
WebPart-Macaw.IWSNews.Moss2007.EnhancedNews\
NewsRollupWebPart.webpart
manifest.xml manifest.xml
Listing 1: Structuur van het .DDF file
Nadat het .DDF file gecreëerd is, kan het solution file gegenereerd worden. Hiervoor gebruiken we MakeCab.exe. Vul in een command prompt het commando uit listing 2 in, en hiermee wordt het solution file MySolutionFile.WSP gecreëerd.
MakeCab.exe /f MyDDFFile.ddf
Listing 2: Commando voor het aanmaken van het solution file
Installatie en deployment van het solution file
Nu het solution file gecreëerd is moet deze nog geïnstalleerd en deployed worden. Om dit de kunnen doen is toegang nodig tot één van de web frontend servers om de volgende stappen uit te voeren:
- Kopieer het solution file naar de server
- Open een command prompt
- Voer het volgende commando uit voor het installeren van het solution file. Dit voegt het solution file toe aan de SharePoint database.
- stsadm -o addsolution -filename "C:\Deployment\MySolutionFile.wsp"
- De volgende stap, het deployen van het solution file, kan nu zowel via de user interface van de Central Administration als met behulp van een STSADM commando. Voer dus één van de volgende stappen uit:
- Gebruik het volgende STSADM commando:
- stsadm -o deploysolution -name MySolutionFile.wsp -url http://MyWebApplication -immediate -allowGacDeployment -force
OF
- Gebruik de user interface van de SharePoint Central Administration:
Ook voor het Solutions Framework geldt: "Leuker kunnen we het niet maken, maar wel weer een beetje makkelijker"
Conclusie
Microsoft heeft met het Solutions Framework in SharePoint 2007 gezorgd voor een deployment mechanisme voor SharePoint oplossingen. Door gebruik te maken van het framework wordt het deployen van oplossingen naar een SharePoint omgeving eenvoudiger en minder foutgevoelig en wordt het veel gemakkelijker om voor SharePoint development gebruik te maken van een OTAP omgeving.
Toch blijft het creëren van de solutions nog steeds behoorlijk complex, aan de ene kant omdat lang niet alle stappen geautomatiseerd zijn, en aan de andere kant gewoon door de grote verscheidenheid aan typen files die er uitgerold kunnen worden. Gelukkig zijn er tools zoals de WSPBuilder om dit te automatiseren, waardoor het aanmaken van een solution veel minder tijd kost. Wel is het goed om te weten hoe het Solutions Framework werkt als je er gebruik van maakt, zodat je het uit kunt leggen aan systeembeheerders en zodat je in kunt grijpen als er iets niet werkt. Als een systeembeheerder vraagt om een overzicht van welke files er door het installeren van de solution naar welke folder op de server uitgerold worden kun je MANIFEST.XML als leidraad gebruiken. In dit file staat benoemd welke typen files er zijn en waar deze uitgerold moeten worden.
Eigenlijk geldt voor het Solutions Framework de slogan van de belastingdienst: "Leuker kunnen we het niet maken, maar wel weer een beetje makkelijker".