Customizing SharePoint Site Creation : Page 2

Customizing the Provisioner

Both the code samples you've seen passed a parameter of type SPWebProvisioningProperties to the Provision method. In one example that parameter was used to get a reference to the site being created through the Web property of this object. However, there is another useful property of this object that you can use to pass data into our custom process—a string property named data. This property can contain any string value you wish, but typically, it contains the path to an XML file containing values used to customize the provisioning process. The XML structure is entirely up to you; you can write code to parse it and retrieve values that are meaningful to your process. Notice, too, that because the property typically contains the path to an XML file, you'll also need to write the code to open and read the file.

The value of this functionality is significant. Imagine a scenario in which you need to have two different provisioning processes that differ only in a few details. Using the XML file approach, rather than writing and maintaining two separate custom classes, you simply pass in different configuration values. Take this one step further, and imagine that rather than simply working from the values contained in the XML file, your provisioning process had to call a web service to retrieve or supply values. Rather than hard-coding the web service information, you could pass it inside the XML file. Later changes would then only require the updating the XML file, not the whole provisioning class.

If your needs are simple, rather than specifying a path for this property, you can simply specify a string meaningful to the custom provisioning class. In either case, you'll see how to specify the data property value in the next section.

Modifying the Site Definition

Other than the code you've seen, the only modification necessary to the standard site definition files is to register your custom provisioning class. You do this in the WEBTEMP_.xml file by adding three new attributes to the Configuration element: ProvisionAssembly, ProvisionClass and ProvisionData, as shown below:

If you do not need to pass in any custom values (see the earlier section titled "Customizing the Provisioner"), you can simply pass in an empty string for the ProvisionData parameter. For more information on the WEBTEMP_.xml file, see Todd Baginski's blog.

Preventing Circular References

The only trouble spot in creating a custom provisioning process is that there's a danger of circular references. This comes into play because, as the sample code shows, you attach a custom provisioning process directly to a particular configuration of a site definition. Also, as shown in the sample class file, there's a call to the ApplyWebTemplate method to tell SharePoint which site definition or site template to apply to the site. Here's the problem: If the name of the site definition and specific configuration passed to ApplyWebTemplate is the same as the site definition configuration to which the custom provisioning process is attached, you have a circular reference.

Figure 1. Circular Reference Exception: Applying your custom provisioning class to the site definition selected in the UI by the user causes a circular reference exception.

In this scenario, creating a new site based on that configuration (e.g. MySiteDef#1) will call your custom provisioning class (because it's attached to the configuration in the WEBTEMP_.xml file). The call to ApplyWebTemplate specifying MySiteDef#1 as the parameter causes SharePoint to apply the custom configuration, which again launches the custom provisioning class.

If you're debugging in this situation, you'll get an exception inside Visual Studio as shown in Figure 1.

The solution to this problem is to create an empty configuration inside your site definition's ONET.XML file:

This is the configuration (#0) to which you attach the site provisioning class inside your WEBTEMP_.XML file, as shown earlier.

Next, you need to create your "real" configuration, in this case as configuration #1, that has all of your typical ONET content (again, see Todd's blog for details). Now, inside your WEBTEMP_.XML file, create a new configuration but set its Hidden attribute to true:

This keeps the second configuration (#1) from showing in the user interface, so users can never select it while still allowing you to apply this configuration programatically (which, after all has all the actual ONET configuration details), simply by specifying it in the call to ApplyWebTemplate.

Deploying the Assembly

After compiling your custom class into an assembly, you need to deploy it. The recommended way to handle this is via a SharePoint Solution (wsp file). The only critical information about deployment is that you need to place the assembly into the Global Assembly Cache (GAC)—which means you need to give it a strong name. Other than that, you can package and deploy it the same way you typically deploy solutions—using batch files, WSPBuilder, STSDev, SharePoint Installer, etc.

Wrap Up

There you have it—a custom provisioning class that gives you a great deal of control over the process by which new SharePoint sites are created. While you may not use this functionality often, simply having it as a weapon in your arsenal can make the difference between success and failure—especially when you can't meet some specific need any other way.