Michael O'Donovan's SharePoint and Stuff : Windows SharePoint Services 3.0

How to build a custom site definition which has child sites (webs)

modonovan — Thu, 11 Sep 2008 11:48:37 GMT

I did this for a customer over a year ago, and have simply just not had the chance to put key to screen and document it. Perhaps someone out there has already done this, but I thought it might still be useful looking at the way in which I did it. Grab some coffee, this post is long.

In MOSS you get a Collaboration Portal definition and a Publishing Portal site definition, when you create a site from either of these the site automatically has sub-sites (sub-webs) provisioned. This is unlike the team site definition, which only creates a root site (web). The question which arose from this was "how do I create a site definition which automatically provisions sub-sites (webs) just like the collaboration portal and publishing portal site definitions?"

I found two ways, an unsupported method and a supported method. In the unsupported technique you use an existing feature which is included in the collaboration and publishing site definitions which does the provisioning for you. The exact steps are described here, on a blog post from SharePointHack. It works, but is not officially supported by Microsoft.

The second technique is essentially to develop a custom feature which does exactly what the unsupported feature does. Their are 2 advantages to this; 1 - it is supported :-), and 2 - you own the code so you can extend it, change it in anyway which makes sense to you e.g. you might want to add extra provisioning steps for the sub-sites that are created, such as setting a default master page and style sheet.

Lets assume that we want to have a team site definition which automatically creates sub sites, the result of which is shown in the graphic below.

Lets look at how to do this

In summary, you create a custom feature (lets call it a provisioning feature) which is executed when the root site is created i.e. team site in this scenario. This custom feature reads an XML file which holds the definition for the sub-sites (webs) to be created, and for each sub-site in the XML file the provisioning feature creates sub-sites (webs) using the WSS API. That's it! Sound simple enough? Now lets walk through the exact steps. All sample code can be found at the end of the post too.

Step 1 - create custom provisioning feature Visual Studio project
Step 2 - add XML file for sub-site definitions, and add code to provision sub-sites
Step 3 - deploy and install the new provisioning feature
Step 4 - create a new site definition which references the provisioning feature
Step 5 - create a new site ... done !!!

Step 1 - create custom provisioning feature Visual Studio project

I am personally not a fan of using the Visual Studio extensions for WSS to create my custom features (can explain why another day), I prefer to create an empty Visual Studio class library project and then manually add all the elements I need. You might want to read this article which explains the elements of a custom feature before continuing with this post.

This graphic above shows my custom feature project in Visual Studio. The template folder contains the feature definition files (feature.xml and subwebs.xml) which will be copied into the SharePoint features folder on successful compilation of the project. The CollabPortalFeature.cs class contains the provisioning code which reads the subwebs.xml file and creates the sub-sites. The Contoso.snk is used to sign the assembly (assembly gets deployed into GAC later) and install.bat is what copies the feature files into the SharePoint feature directory and installs the feature using STSADM.exe.

Step 2 - add XML file for sub-site definitions, and add code to provision sub-sites

Lets look at feature.xml. Here you will see the definition for the feature, the title and description. Importantly it is a hidden feature, this prevents users manually activating it from SharePoint administration screens. Why? Because the feature will be activated by the site definition which references it, more on that later. Also we have reference to the assembly and class which hosts the provisioning code. This is also discussed later.

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

       2:         Title="Contoso Collaboration Portal Provisioning Handler" 

       3:         Id="5664944F-24C5-4524-BABB-D1FAC37709CF" 

       4:         Description="This feature is designed to be added to a custom site definition,and will create sub sites inside the new root web" 

       5:         Version="1.0.0.0" 

       6:         Scope="Web" 

       7:         Hidden="TRUE"

       8:         DefaultResourceFile="core" 

       9:         ReceiverAssembly="Contoso.SharePoint.ProvisioningHandler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=179f3ffc3fc551f9" 

      10:         ReceiverClass="Contoso.SharePoint.ProvisioningHandler.CollabPortalFeature" >

      11:     <ElementManifests>

      12:         <ElementFile Location="subwebs.xml" />

      13:     </ElementManifests>

      14: </Feature>

Now let's look at the XML inside of subwebs.xml.

       1: <rootWeb>

       2:     <webs>

       3:         <web url="Wiki" siteDefinition="WIKI#0" displayName="Our Wiki" description="Our teams wiki allows us to brainstorm online." />

       4:         <web url="Blog" siteDefinition="BLOG#0" displayName="Our Blog" description="Our department's blog shows key updated information about our department." />

       5:         <web url="Search" siteDefinition="SRCHCENTERLITE#0" displayName="Search" description="We need to be able to search dont we" />        

       6:     </webs>

       7: </rootWeb>

What you can see if that in this scenario we are going to get 3 sub-sites created, a team wiki, a team blog and a search site. You can add, remove and edit as many nodes as you want here. Each sub-site needs a URL, a site definition name which it should be based on, a display name and a description. Of course you could extend this schema to include any custom fields or flags you may want to use during provisioning. e.g. inherit permissions from parent web.

Note: some sub-sites require certain features to be activated on the parent site in order for them to work e.g. if you tried to create a report center under a team site it would break, unless the team site had the publishing feature activated.

Now for the logic inside the class which does most of the work. Let's look at some code inside the featureactivated method. I have left out some code which I don't think needs explanation, but have kept the most important snippet to show you.

       1: //get the file path to the path to subwebs.xml, this is where the subweb to create are defined

       2: string filePath = this.GetProvisioinerFilePath(properties.Definition);

       3:            

       4: if (System.IO.File.Exists(filePath))

       5: {

       6:  

       7:    XmlDocument doc = new XmlDocument();

       8:    doc.Load(filePath);

       9:  

      10:    XmlNode subWebs = doc.DocumentElement.SelectSingleNode("webs");

      11:    if (subWebs != null)

      12:        CreateSubWebs(web, subWebs);

      13:  

      14: }

In the above code the first step is to get the path to the subwebs.xml file (you could hard code the path, but that probably wouldn't be a good idea). It then calls CreateSubWebs for each web node inside the subwebs.xml file. Let's now look at the CreateSubWebs method.

       1: private void CreateSubWebs(SPWeb web, XmlNode websNode)

       2: {

       3:    foreach (XmlNode webItem in websNode.ChildNodes)

       4:    {

       5:        //only attempt to create it if XML node has all the information required

       6:        if (webItem.Attributes["url"] != null && webItem.Attributes["siteDefinition"] != null

       7:            && webItem.Attributes["displayName"] != null && webItem.Attributes["description"]!=null)

       8:        {

       9:            string url = webItem.Attributes["url"].Value;

      10:            string siteDefinition = webItem.Attributes["siteDefinition"].Value;

      11:            string displayName = webItem.Attributes["displayName"].Value;

      12:            string description = webItem.Attributes["description"].Value;

      13:  

      14:            Debug.WriteLine("ProvisioningHandler:CollabPortal, Creating sub web called " + displayName);

      15:            //create the new subweb

      16:            SPWeb newWeb = web.Webs.Add(url, displayName, description, web.Language, siteDefinition, false, false);

      17:            //tell new subweb to use parents navigation

      18:            newWeb.Navigation.UseShared = true;

      19:                                

      20:            web.Properties["__IncludeSubSitesInNavigation"] = "True"; //make sure sub webs show their child sites in navigation

      21:            //update props

      22:            web.Properties.Update();

      23:            //update new web created

      24:            newWeb.Update();

      25:        }

      26:  

      27:    }

      28: }

Once again, not rocket science, just a simple function which takes the attributes from the web node and uses them to create the sub-site (sub-web). You will also see that some defaults are set.

Step 3 - deploy and install new provisioning feature

To deploy the feature, you need to:

1. Compile the project and take the assembly generated and add it to the GAC. I do this manually for now i.e. drag and drop it into the GAC

2. You must then copy the public key token and place it in your feature.xml on your receiver class definition file. This is so that your feature is referencing the correct assembly.

3. Now it is time to install the feature, if I run install.bat this will do all that work for me i.e copy feature files to SharePoint feature directory and then run the feature install command (note: we do not active the feature)

Here is a snippet from install.bat

       1: @SET TEMPLATEDIR="c:\program files\common files\microsoft shared\web server extensions\12\Template"

       2: @SET STSADM="c:\program files\common files\microsoft shared\web server extensions\12\bin\stsadm"

       3:  

       4: Echo Copying files

       5: xcopy /e /y TEMPLATE\* %TEMPLATEDIR%

       6:  

       7: Echo Installing features

       8: %STSADM% -o installfeature -filename  ContosoProvisioningHandler\feature.xml -force

Step 4 - create a new site definition which references the provisioning feature

Now that the feature is installed, we need to create a new custom site definition which references the custom provisioning feature. Therefore when a site is created from the new site definition, the custom provisioning feature will execute and create the sub-sites.

I am not going to walk through the steps for creating a custom site definition, rather have a good read of the following article which describes it in great detail.

In my example, I copied and pasted the team site definition and then added a reference to the custom provision feature in ONET.xml. The snippet below shows that reference in the <WebFeatures> section of ONET.xml.

       1: <WebFeatures>

       2:    <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />

       3:    <!-- TeamCollab Feature -->

       4:    <Feature ID="F41CC668-37E5-4743-B4A8-74D1DB3FD8A4" />

       5:    <!-- MobilityRedirect -->

       6:    <!-- Custom provisioning handler feature-->

       7:    <Feature ID="5664944F-24C5-4524-BABB-D1FAC37709CF" />  

       8:  </WebFeatures>

Here the feature ID is the one which is found in the feature.xml for the custom feature.

Step 5 - create a new site

Now if we try and create a new site, we should have the new site definition as an option in the create site page. This is shown below, where in my case my new site definition was called "Team site with sub sites"....boring but simple.

Now if we navigate to the new site and select the sites link we will have the list of sub-sites under it.

Important: Where is my top navigation with links to my sub-sites? Because I chose to create the top level site as a team site and a team site doesn't have publishing features enabled the top navigation does not list the sub-sites. If you want it to, you could enable the publishing feature for the top site (site collection feature and site feature). Once that is done, you can edit the sites navigation to show sub-sites. If you started with your top site being the collaboration or publishing portal, they would already have these features enabled and you won't have this issue.

Once that is done, you will have the full top navigation.

Done!! :-)

The full Visual Studio project with all the code used in this sample can be downloaded using the link below.

You can imagine the power of the provisioning feature, where you could set default master page for sub-sites, set custom style sheet for sub-sites, permissions, add stuff the web property bags etc.

I hope this made some sense and you found it useful. Happy Provisioning!

Debugging Tip: I scatter in my code debug output statements e.g. Debug.WriteLine("some statement");. Then I use DebugView tool from sysinternals to view those statements when the provisioning code executes. For example, if nothing shows it is probably because your provisioning assembly is not being called / loaded. The image below shows the code being executed and debugging statements showing that the 3 sub sites are being created.

Another options if for you to attach the Visual Studio debugger to the code, insert a break point and let the code break where you need to start debugging, just make sure you have the PDF file inside your local bin folder for the IIS site where you are creating the site from alternatively their is a wacky way to get the PDB into the GAC for this to work too.

Michael

Content Management Interoperability Services (CMIS) proposed standard announced

modonovan — Wed, 10 Sep 2008 19:29:22 GMT

Today, EMC, IBM and Microsoft (along with other leading ECM industry vendors Alfresco, Open Text, Oracle and SAP) announced a jointly developed specification called the Content Management Interoperability Services (CMIS) specification. CMIS uses Web Services and Web 2.0 interfaces to enable applications to interoperate with multiple Enterprise Content Management (ECM) repositories by different vendors. The companies intend to submit the CMIS specification to OASIS (Organization for the Advancement of Structured Information Standards) for advancement through its rigorous standards development process.

For more information, and to download a preview copy of the CMIS technical specification draft, please see the website of any of the contributing companies: EMC Corporation (www.emc.com/about/news/press/2008/091008-smr-content-management-interoperability-services.htm); IBM (www.ibm.com/software/data/content-management/cm-interoperablity-services.html); and Microsoft (http://go.microsoft.com/fwlink/?LinkId=127855).

The SharePoint team have recently posted about this here:

View Video Interview of Jeff Teper Corp VP, Office SharePoint Server Group.

http://www.microsoft.com/presspass/events/cmis/default.mspx

Updates for SharePoint Released

modonovan — Wed, 16 Jul 2008 11:01:00 GMT

Yesterday, the SharePoint product team announced the release of important rollup updates for SharePoint Server 2007, Windows SharePoint Services 3.0, Project Server 2007, Search Server 2008, Search Server 2008 Express and Project Professional 2007.

I strongly recommend reading their release announcements, and start planning for the implementation of these ASAP.

Technorati Profile

SharePoint Introduction for .NET developers webcast series

modonovan — Wed, 21 May 2008 18:23:20 GMT

New to SharePoint development or want to brush up? Check out this free webcast series targeted at YOU!

In this 10-part series, you will receive practical technical information from Robert Bogue and Andrew Connell, Microsoft SharePoint Most Valuable Professionals (MVPs), covering 10 fundamental developer topics on SharePoint Products and Technologies via Live Meeting Webcast

About the series:

Every Tuesday and Wednesday from May 20 to June 18
Starts at 9:00 AM Pacific Standard Time (12:00 PM Eastern Standard Time)
60 minutes long

Click on the Register Today! links to learn more about the specifics covered in each webcast

20-May-08 ... Introduction to SharePoint for .NET Developers: Web Parts. Register
21-May-08 ... Introduction to SharePoint for .NET Developers: Data Lists. Register
27-May-08 ... Introduction to SharePoint for .NET Developers: Silverlight and SharePoint. Register
28-May-08 ... Introduction to SharePoint for .NET Developers: Using Event Handlers. Register
03-Jun-08 ... Introduction to SharePoint for .NET Developers: Page Branding. Register
04-Jun-08 ... Introduction to SharePoint for .NET Developers: Workflows. Register
10-Jun-08 ... Introduction to SharePoint for .NET Developers: Web Services. Register
11-Jun-08 ... Introduction to SharePoint for .NET Developers: Page Navigation. Register
17-Jun-08 ... Introduction to SharePoint for .NET Developers: User Management. Register
18-Jun-08 ... Introduction to SharePoint for .NET Developers: Custom Content Types. Register

SharePoint Communication Protocol Documentation Released

modonovan — Fri, 18 Apr 2008 09:10:13 GMT

Have you ever wondered how Microsoft Office communicates with SharePoint, for example how does Outlook create a meeting workspace? In the past you would need to put some type of IP tracing tool between the client and the server to see what was going on, which was pretty hard and not always that clear.

Well now as part of the Microsoft Protocol Program Microsoft has released the first version of the protocol documentation for SharePoint. This documentation can be viewed and downloaded from here: SharePoint Product and Technologies Protocols

Enjoy.

Download SP1 for MOSS, WSS 3.0 and Office 2007 Now

modonovan — Tue, 11 Dec 2007 23:21:26 GMT

Office 2007 SP1

http://www.microsoft.com/downloads/details.aspx?FamilyId=9EC51594-992C-4165-A997-25DA01F388F5&displaylang=en

SharePoint Designer SP1

http://www.microsoft.com/downloads/details.aspx?FamilyId=B57C805D-2821-4625-A6F1-80725267F887&displaylang=en

WSS 3.0 SP1

http://www.microsoft.com/downloads/details.aspx?FamilyId=4191A531-A2E9-45E4-B71E-5B0B17108BD2&displaylang=en

MOSS 2007 SP1

http://www.microsoft.com/downloads/details.aspx?FamilyId=AD59175C-AD6A-4027-8C2F-DB25322F791B&displaylang=en

SharePoint End-User Training Released

modonovan — Mon, 10 Dec 2007 10:12:23 GMT

This is a great new resource to download and either install on a user's desktop or in you SharePoint environment for all users to access. It includes videos, tutorials, articles and more.

Download it now

Great SharePoint Designer Workflow How To's, Tips and Tricks

modonovan — Thu, 15 Nov 2007 17:25:40 GMT

There are some great new articles on the SharePoint Designer team blog which are really useful if you are new to SharePoint Designer workflows, or are looking for some cool workflow tips and tricks.

Check it out

SharePoint Pedia has Gone Live

modonovan — Mon, 05 Nov 2007 17:57:58 GMT

Check it out at http://sharepointpedia.com, looks pretty cool. Another awesome example of a solution built on MOSS.

SharePoint End User Training Kit (SLK) Released

modonovan — Fri, 12 Oct 2007 17:36:15 GMT

For so long we have had minimal end-user training resources. Well, now the product team has released the SharePoint End User Training Kit - http://blogs.msdn.com/sharepoint/archive/2007/10/11/sharepoint-end-user-training-kit-now-available.aspx.

Also, just a couple of other links which might be useful from an end-user perspective:

End user “How To” site launched - http://office.microsoft.com/en-us/sharepointserver/FX101211721033.aspx
End user quick online video “How To’s” - http://office.microsoft.com/en-us/training/CR102146081033.aspx. You could download them and add to your own SharePoint deployment for others in the company to view.
“Get the Point” end user focused blog - http://sharepoint.microsoft.com/blogs/GetThePoint

Use Windows Live Writer to create blog posts ... for MOSS

modonovan — Fri, 14 Sep 2007 14:54:33 GMT

I have just recently downloaded Windows Liver Writer Beta (http://get.live.com/betas/home), and have used it to create my previous blog post. The tool is very simple to use, and the best part about it is that it can be used to post entries to a MOSS hosted Blog site. And it Just Works, with proper in context previous, categories, uploading of images in the post and more!!! The screen shots below how simple it is to setup:

Step 1: Choose SharePoint as the blog destination (other than Windows Live Space or Other)

Step 2: Specify the path the SharePoint Blog site where blog posts should be created

Step 3: Configure the authentication mechanism

Step 4: Create your blog post, preview it (this is really cool, check the image below of this blog post) and then hit "Publish"

How to recover SharePoint document once deleted from recycle bin

modonovan — Fri, 14 Sep 2007 14:07:37 GMT

In the scenario whereby a document has been deleted from both levels of the SharePoint recycle bin, you may have a request to recover it. Assuming you have a SQL database backup of the content database which hosted the document, you can get it back with minimal effort by following the steps below.

Important: Do not run these steps on the production SQL Server deployment. The idea is that this is done on a development or testing SQL Server environment where the content database which holds the document you wish to extract is restored to. This is because these steps are not officially supported by Microsoft.

Step 1: Get TextCopy utility and make sure it works

The textcopy utility comes with the SQL Server 2000 resource kit and is designed to run on SQL Server 2000. However it can be used on SQL Server 2005. Get textcopy.exe from the resource kit and place it in a folder on the SQL Server 2005 machine e.g. C:\Temp. Also add into this folder a file from a SQL Server 2000 installation called ntwdblib.dll. Both of these files need to be in the same folder to work.

Run textcopy.exe to ensure it works, you should see a list of textcopy commands.

Step 2: Determine the content database to use for extracting the document

In order to extract the document you need to know where the document was located in the site structure. For example, below we see a document titled “CoreIOModels”, which is hosted in the sub site “Docs” in the root site collection of http://moss.litwareinc.com web application. The document is in the documents document library.

You now need to determine which content database holds the document. This is done easily through Site Collection List option in the central administration application. Here you can see that the root site collection for http://moss.litwareinc.com is found in the content database WSS_Content_MOSS. You need the name of the content database because SQL scripts (and textcopy) will run against this database. Also, you now know which database to restore to a test / development environment instead of restoring all you SQL databases.

Step 3: Determine the record which holds the binary image of the document to extract

Run the following script on the database, using SQL Query Analyser in SQL Server 2005. This script will return all the records which hold document that you are looking. You may get more than one record returned, as their might be several previous versions of the document.

USE [@database]

SELECT AllDocStreams.Id, AllDocStreams.[Content], AllDocStreams.Size, AllDocs.Version, AllDocs.TimeLastModified, AllDocs.CheckoutUserId,

AllDocs.CheckoutDate, AllDocs.IsCurrentVersion, AllDocs.DirName, AllDocs.LeafName, AllDocs.[Level]

FROM AllDocs INNER JOIN

AllDocStreams ON AllDocStreams.Id = AllDocs.Id AND AllDocs.[Level] = AllDocStreams.[Level]

WHERE (AllDocs.DirName = @dirname) AND (AllDocs.LeafName = @leafname)

Variables

@leafname = filename

@dirname = directory name of file

For example in my scenario above this would be

USE WSS_Content_MOSS

SELECT AllDocStreams.Id, AllDocStreams.[Content], AllDocStreams.Size, AllDocs.Version, AllDocs.TimeLastModified, AllDocs.CheckoutUserId,

AllDocs.CheckoutDate, AllDocs.IsCurrentVersion, AllDocs.DirName, AllDocs.LeafName, AllDocs.[Level]

FROM AllDocs INNER JOIN

AllDocStreams ON AllDocStreams.Id = AllDocs.Id AND AllDocs.[Level] = AllDocStreams.[Level]

WHERE (AllDocs.DirName = 'docs/documents') AND (AllDocs.LeafName = 'coreiomodels.doc')

This returns the following records in my case:

If you get multiple records returned, you will want to use the Version field and the isCurrentVersion and perhaps the TimeLastModified fields to determine which record in the one you want to extract.

Take note of the ID of the record any other unique field data from the AllDocStreams table so that you can uniquely identify the record in the AllDocStreams table.

Step 4: Extract the document using Textcopy

From the command prompt run the textcopy.exe command to extract the document (from the content field) in the AllDocStreams table.

Example TextCopy cmd to extract file:

textcopy /s @server /u @user /P @password /d “@database" /t docs /c content /F c:\temp\filename /O /Z /W "where ID= ‘@IdofRecord’ and Level=’@levelofrecord’”

Variables

@database = content database

@server = name of SQL Server machine to use

@leafname = filename

@dirname = directory name of file

@IdofRecord = Id of the content record to extract

@levelofrecord = level of content record to extract

For example, in my scenario this would be:

textcopy.exe /S MOSS /D wss_content_moss /T alldocstreams /C content /U sa /P pass@word1 /F c:\temp\coreidmodels.doc /O /Z /W "where ID='2381F6A5-0AED-4F28-A031-BAC6E08B151F' and Level='255'"

This will dump the file into the C:\Temp folder and allow me to email or place the file onto the site for the user who needs it.