Chapter 4
Working with Sites and Webs
IN THIS CHAPTER
When users interact with SharePoint, the majority of that interaction is done through the SharePoint concepts of sites and webs. It is often confusing for both developers and users to determine the difference between site collections, sites, web collections, and webs.
This chapter takes you through the SPSite and SPWeb classes and shows you how to create and delete both site collections and webs as well as how to interact with sites and webs.
Understanding Webs and Sites
Within SharePoint, there are two different concepts: a web and a site. The site, as far as SharePoint is concerned, is actually a site collection. The SPSite class models a collection of websites and the SPSiteCollection contains the list of all root-level site collections on a virtual server. Each site collection consists of one or more root websites. You cannot have a site collection that doesn’t have a root website. For example, if you use the object model to create a site collection and you indicate that the template for that site collection should be a Team site, what you have actually done is created a site collection and a root website (an SPWeb instance) that was provisioned from the Team Site template.
As long as you remember that the SPSite class is the model for a collection of SPWeb objects, you shouldn’t get lost. To get at the list of site collections on a given web application, you simply reference the Sites property of an instance of the SPWebApplication class.
Websites and Web Applications
It can be incredibly easy to get confused between sites, webs, web applications, and site collections. The farm is the topmost level in the hierarchy. Below the farm, you have web applications represented by the SPWebApplication class, which typically correspond to an IIS application pool. Below that, you have a collection of site collections contained in the SPSiteCollection class. Finally, you have site collections represented by the SPSite class and individual websites represented by the SPWeb class.
In a default installation of SharePoint, the root site collection (instance of the SPSite class) contains several stock webs (instances of the SPWeb class). They are Home, Document Center, News, Reports, Search Center, and Sites.
Using the SPSite Class
The SPSite class represents a collection of sites contained on a virtual server, which includes the top-level (root) site and all its subsites. Each SPSite object can be found within the Sites property of an SPWebApplication class.
This section covers the basic properties and methods of the SPSite class, followed by code samples of the SPSite class in action—including creating, deleting, and updating site collections. For the complete listing of all properties and methods, consult the online SharePoint Software Development Kit (SDK) found on MSDN (http://msdn2.microsoft.com/en-us/library/aa905858.aspx).
Table 4.1 covers the commonly used properties of the SPSite class.
Table 4.1. Common SPSite Properties
Table 4.2 highlights some of the most commonly used methods of the SPSite class.
Table 4.2. Common SPSite Methods
Creating Sites
Site creation is done by calling the Add() method on an SPSiteCollection class instance. There are multiple overloads that allow you to supply progressively more information to create the new site collection.
To create a new site collection, you need some basic information such as the URL of the new site, the name of the site, the site description, and its locale identifier (default is 1033 for U.S. English). You can also supply an optional web template ID string to control the type of site collection you are creating.
The following code illustrates creating a new site collection (SPSite instance) at the URL http://win2k3r2lab/sites/NewTestSite:
After executing the above code for your own lab server, go ahead and open a new browser window at the new site to see that it has been created with the values you supplied.
When executing code like this in a production application, you might want to run the code in a background thread. The process of creating and provisioning a new site collection can take a very long time, even on a relatively traffic-free server.
Most of this code is pretty self-explanatory. The only really tricky parts are figuring out the web template ID, and remembering that you need the preceding slash on the server-relative URL. If you don’t include the preceding slash, you might run into errors complaining that a site already exists at the URL of the root site. To help you determine which template ID you need to create your site, take a look at Tables 4.3 and 4.4.
Table 4.3. Stock/Default Web Template IDs
Table 4.4. Additional Web Template IDs
After executing the previous code to create a new site, a site similar to the one shown in Figure 4.1 is created.
Figure 4.1. Creating a new site collection programmatically.
Accessing Site Information
Table 4.1 provides a list of some of the most commonly used properties on the SPSite class. You can obtain a reference to a site collection in a couple of different ways.
The easiest method is to use the site collection constructor with a fully qualified URL of the site collection’s root web:
SPSite mySite = new SPSite("http://win2k3r2lab/sites/NewTestSite");
You can also obtain a reference to a site by finding the site in the web application’s Sites collection:
SPSite mySite = myWebApplication.Sites["New Test Site"];
Updating Sites
Site collection updating is a bit misleading. There are very few properties that you can modify on the site collection itself. For example, if you created a new site by using the previous code, such as the one shown in Figure 4.1, you might notice that you can’t change any of the properties such as the site title or description on the SPSite instance.
Instead, you need to get an instance of the SPWeb class for the root web of the site collection (which was created by default when you created a new site collection). Working with the SPWeb class is discussed in the next section.
Using the SPWeb Class
The SPWeb class represents an instance of a single website. It is often confusing to developers because the root web of a site collection (which is created when a site collection is created) is an instance of the SPWeb class. As shown in Tables 4.5 and 4.6, the SPWeb class provides most of the functionality of single websites, whereas the SPSite class is designed to deal with site collections.
Table 4.5. Common SPWeb Properties
Table 4.6. Common SPWeb Methods
Creating Webs
Creating a new web involves calling the Add() method on any SPWebCollection instance. To add a new web to the root web of a site collection (for instance, the “New Test Site” site collection created in the preceding sample), you obtain a reference to that site and then call the Add() method on the AllWebs property, as shown in the following code that adds a blog as a subweb of the parent site collection:
Note that when you’re creating a new site collection, you use a server-relative URL, which requires a preceding forward slash and when creating a new website, you use a site-relative URL, which cannot start with a forward slash. It is an important distinction that can save you some debugging hassles if you remember it.
Running the preceding code creates a new blog site such as the one shown in Figure 4.2.
Figure 4.2. Programmatically created blog website.
Accessing Web Information
You can obtain a reference to an SPWeb instance either by obtaining it through an indexer property on an SPWebCollection instance:
SPWeb myWeb = parentSite.AllWebs["blog"];
or by calling the OpenWeb() method on a site collection:
SPWeb myWeb = parentSite.OpenWeb("blog");
Updating Webs
Committing changes made to an SPWeb instance are only saved after you call the Update() method. There are some properties on a website that cannot be changed after the site has been created. Take a look at Table 4.4 and the MSDN SDK for a full list of which properties can and cannot be modified. The following code illustrates how to change the title of the blog site created in the preceding code sample:
SPSite parentSite = new SPSite("http://win2k3r2lab/sites/TestNewSite");
SPWeb blogWeb = parentSite.OpenWeb("blog");
blogWeb.Title = "Modified Blog Site";
blogWeb.Update();
Summary
Working with sites and webs is actually a fairly simple process. The most difficult part of the development process is remembering which properties and methods are available on the SPSite and SPWeb classes. This chapter provided a thorough reference for both of these classes. This chapter also provided code samples illustrating how you can write code that examines and manipulates properties on sites and webs.
After reading this chapter, you should feel confident in your ability to create new sites and webs, locate existing sites and webs, and update existing sites and webs.