Understanding the Administrative Object Model of Windows SharePoint Services 3.0
Summary: Learn about the structure and relationships of the high-level classes in the Microsoft.SharePoint and Microsoft.SharePoint.Administration namespaces of Windows SharePoint Services 3.0. (21 printed pages)
Ricky Kirkham, Microsoft Corporation
February 2008
**Applies to:**Windows SharePoint Services 3.0
Contents
Windows SharePoint Services as the Operating System for a Web
Some Goals of Windows SharePoint Services
Three Object Hierarchies
The Content Hierarchy
The Physical Objects Hierarchy
The Services Hierarchy
Deployment Examples
Code Example
Conclusion
Additional Resources
Acknowledgements
Windows SharePoint Services as the Operating System for a Web
You know that Windows SharePoint Services 3.0 is built on Microsoft ASP.NET 2.0. But Windows SharePoint Services 3.0 also greatly expands what can be done with an ASP.NET installation. Besides being the most complex use of ASP.NET ever, it is also the most conceptually innovative in at least two ways. First, it creates a new, abstract Web world in which lists and list items, instead of pages, are the primary entities in the population—and it makes these entities far more creatable, removable, and editable by end users than the pages of the old Web world ever were. Second, it adds to ASP.NET classes that refer more explicitly and precisely to the underlying physical structure of real-world, enterprise, Web service networks: server farms and the load balancing in server farms.
So Windows SharePoint Services 3.0 is a user-friendly system of content creation, storage, and management. But it is also a system of integrating hardware, opening and closing applications, providing personalized experiences to multiple users of the same underlying application and content, and providing always-ready software services. This list of functions should sound familiar: These are the abilities that operating systems provide. Thus, Windows SharePoint Services is a kind of operating system for a Web—a network built on the HTTP and HTML protocols. The high-level classes in the Windows SharePoint Services object model represent the objects that the system coordinates.
This article discusses the most important, high-level classes of the Windows SharePoint Services 3.0 object model and the roles they play on the stage created by Windows SharePoint Services.
Some Goals of Windows SharePoint Services
Often the most puzzling questions about classes in an object model hierarchy are "why" questions, such as, "Why do I as a developer need this class?" and "Why does this level in the hierarchy have to exist?" Getting answers to your "why" questions is much easier if you consider some of the major goals of Windows SharePoint Services 3.0.
The Two Worlds of Windows SharePoint Services
A Windows SharePoint Services site is fundamentally an Microsoft ASP.NET 2.0 Web site, and it can be accessed through browsers. To a browser, the World Wide Web (or an intranet) is a world of pages with links between them; and these pages exist as server-hosted files at particular URL addresses. Windows SharePoint Services, and its object model, creates a new world in which lists are the key type of entity. In the Windows SharePoint Services world, pages and files are greatly deemphasized. Understanding the Windows SharePoint Services object model is much easier if you consider the dual nature of Windows SharePoint Services. A Windows SharePoint Services site must present itself to users (and even to certain kinds of site administrators) as a world of lists, but it must be implemented on top of an older world that dates to the early 1990s—a world of browser-rendered pages.
Amateur Web Site Administration
A second point that is helpful to remember is that Windows SharePoint Services enables a shift of control and responsibility from IT professionals and Web site designers to end users. In some ways, this change is just a continuation of a long process that has given Web users progressively more power to customize what is presented to them on Web pages. For example, browsers have long enabled users to change the text size on Web pages and to selectively block scripts on pages. A more recent and more significant empowerment of Web users is embodied by the notion of a Web Part. A Web Part is a unit of content, such as a personalized list of stocks and bonds, or the current weather in a selected city, or the game scores of an end user's favorite teams. Major portal sites that use Web Parts, such as msn.com, let users add, delete, and reposition the Web Parts. Hence, the content, in addition to the visual aspects of the site, such as the color scheme, are in the control of the end user.
Windows SharePoint Services makes a revolutionary advance in this process because it gives to the user the ability to create and manage lists, list items, other content, and even the Web sites themselves. In general, Web site creation and management in Windows SharePoint Services is performed by people who are amateurs from the standpoint of IT professionals, developers, and professional designers.
For example, a Windows SharePoint Services site for the students that take a literature class in college is created and managed by the professor who teaches the class. A team site for a group of local artists that collaborate on a large mural is created and managed by the lead artist. These amateur administrators are called Site Owners in 2007 Microsoft Office system terminology. The activities at these sites, including the creation and deletion of users, roles, permissions, subsites, pages, and other content, can occur without the intervention, or even the knowledge, of any network or server administrator. (High-level administration of server farms and sets of Web sites is still performed by professionals. Also, some kinds of customization and Web site design require technical skills.)
Farm and Web Server Administration from Inside Windows SharePoint Services
Another goal of Windows SharePoint Services 3.0 is to enable some kinds of server-farm administration tasks from the SharePoint Central Administration Web site. In many situations, administrators do not need to open Internet Information Server (IIS), Windows Control Panel, or their load-balancing software. This capability requires that the Windows SharePoint Services object model have some built-in farm awareness and service awareness that is not provided by either IIS 6.0 or Microsoft ASP.NET 2.0 itself. (IIS 7.0 does have some limited farm awareness.)
Database Storage of Content
Web applications that use back-end relational databases have been familiar for many years now; but Windows SharePoint Services brings the relational database to the forefront. Not only is supporting data stored in a database, so too is most of the top-layer content of a Windows SharePoint Services deployment. The lists, list items, and even most of the files are stored in a content database, instead of in a folder structure in a file system. (For performance reasons, some files are stored in folders, however.)
Three Object Hierarchies
The Windows SharePoint Services 3.0 object model can be usefully divided into three hierarchies.
The Content Hierarchy includes classes that represent publishable items of data, such as list items. There are also classes that represent nested containers of data, such as lists, content databases, Web sites, collections of Web sites, and groupings of site collections called Web applications.
The Physical Objects Hierarchy includes classes that represent physical entities, such as servers and files, and containers of such entities, such as farms and folders.
The Services Hierarchy includes classes that represent services in Windows SharePoint Services. Web services, Windows services, and instances of these are the primary entities here.
These hierarchies overlap in the sense that some classes cannot be easily categorized and can be regarded as belonging to more than one hierarchy.
The Content Hierarchy
Because Windows SharePoint Services must be built on a world of pages, a Windows SharePoint Services Web site, which is represented by the SPWeb class, is a set of files—especially .aspx files—and associated data, users, and permission policies (although it is much more than just a set of files). The Web site may have subsites. (Subsites are also represented by the SPWeb class.) This is no surprise, because we can easily understand why a business division or other institution might want to structure its sites to mirror its own structure, its product line, or its ongoing projects. However, more puzzling at first is the fact that every Windows SharePoint Services deployment groups its Web sites into one or more site collections. A site collection, which is represented by the SPSite class, is also, of course, a set of files because it is a set of Web sites. Moreover, the site collections themselves are grouped into one or more sets that are called content databases, represented by the SPContentDatabase class. These are the children of one or more Web applications in Windows SharePoint Services. A Web application is represented by the SPWebApplication class.
Note
A site collection was called simply a "site" in the original version of Windows SharePoint Services—Microsoft SharePoint Team Services—which is why the class that represents a site collection is named SPSite. Similarly, what is called a "Web site" (or occasionally just a "site") in Windows SharePoint Services 3.0 was originally called a "Web". Therefore, the class that represents it is called SPWeb. Although an SPSite object represents a collection of things, the SPSite class is not a collection in the sense of a class that implements ICollection. An SPSiteCollection class implements the latter interface. It represents a collection of SPSite objects.
So an SPWeb object, an SPSite object, an SPContentDatabase object, and an SPWebApplication object are all, in a sense, partitions of the content in a Windows SharePoint Services deployment. So why do we need four different classes? I try to answer that question in the next four sections.
Figure 1. The primary objects in the content hierarchy
.gif)
Each type of object in Figure 1 contains objects of the type underneath it. The SPList, SPListItem, and SPField classes are not discussed in this article.
Windows SharePoint Services Web Sites
Let's begin with Windows SharePoint Services Web sites, because they are probably the easiest kind of entity to understand. A Windows SharePoint Services Web site, represented by the SPWeb class, is an ASP.NET Web site optimized for content management and collaboration. It differs from other ASP.NET applications mainly in these ways:
It deemphasizes pages and emphasizes lists and list items instead. For example, the Quick Launch of a Windows SharePoint Services site (of the STS type) presents a hierarchy of sites, subsites, and lists (including lists of lists), instead of pages as such. If you add a page to such a site, the new page appears in the Quick Launch as a new item in a list of shared documents, not as a child node under the home page or some other page.
It gives administrative powers to users. How much power any given user has is determined by the permissions granted him or her. End users commonly are able to create whole new Web sites (as subsites) as well as add and edit content on existing Web sites.
It is one of four levels at which a Windows SharePoint Services Feature can be activated. The other levels are site collection, Web application, and farm.
I said earlier that a Web site is a subset of the content of a site collection. That does not imply that the content of two Web sites in a given collection is mutually exclusive: a given list, for example, can appear on more than one Web site.
Some characteristics of the SPWeb class are as follows:
An SPWeb object can be a child of another SPWeb object or of an SPSite object. If it is the child of an SPSite object, it is the top-level Web site in its site collection.
An SPWeb object has a Webs property that returns a collection of other SPWeb objects; specifically, the immediate child subsites under it.
The class has a very rich set of members for programmatic administration and customization of the Web site.
A hierarchy of Web sites always has exactly one top-level Web site. This site is the child of an SPSite object. You can learn more about the top-level Web site in the section Windows SharePoint Services Site Collections later in this article.
Windows SharePoint Services Web Applications
A Windows SharePoint Services Web application, represented by the SPWebApplication class, is foundationally a set of content databases, each of which contains site collections; and the site collections themselves are sets of Web sites, which in turn are sets of files.
But a Windows SharePoint Services Web application is more than just the highest-level grouping of Web sites. It is also the layer at which a Windows SharePoint Services deployment is visible to IIS. Each Windows SharePoint Services Web application is exposed through an IIS Web site and appears in the Web Site tree of IIS Manager. (See Figure 2.) So all of the site collections and Web sites (and subsites) in a Windows SharePoint Services Web application are just one big Web site to IIS.
Note
Terminology can be confusing here: what Windows SharePoint Services calls a "Web application" is served through one or more IIS "Web sites".
Figure 2. IIS Manager immediately after installation of Windows SharePoint Services 3.0 on a single server
.gif)
IIS automatically gives each IIS Web site its own application pool when the site is created and each application pool has its own process. Thus, every Windows SharePoint Services Web application runs in its own process. If one of those processes crashes, the others continue to run. This is the most important way that a Windows SharePoint Services Web application differs from the lower layers in the object model hierarchy. Content databases and site collections do not have process isolation from each other, but Web applications do.
Note
Strictly speaking, the one-to-one relation of IIS Web sites to application pools does not have to be maintained. Within IIS Manager, Web sites can be moved from one application pool to another. Hence, multiple Windows SharePoint Services Web applications could be moved into the same pool and therefore share the same process. In some cases, the performance enhancement that comes from this kind of process sharing justifies the loss of crash protection. Nevertheless, process sharing is not frequently done. Therefore, this article assumes that each Windows SharePoint Services Web application has its own process.
Some other critical differences between Windows SharePoint Services Web applications and Windows SharePoint Services site collections:
Each Web application has one or more of its own child content databases, but each site collection belongs to just one content database (which it may share with other site collections that are enclosed in same Web application).
Security policies, such as authentication and enabling anonymous users, are set at the level of Windows SharePoint Services Web applications.
Figure 2 shows IIS Manager (for ISS 6.0) immediately after Windows SharePoint Services 3.0 is installed on a single server. Notice that the installation created two IIS Web sites and each site has its own application pool (and process). One of the IIS Web sites is for a main Windows SharePoint Services Web application that provides content to end users and is named "SharePoint - 80". (The "80" is the number of the server port through which requests for Windows SharePoint Services pages come.) The other is named "SharePoint Central Administration v3" and is used by IT professionals for high-level administration tasks. You can probably guess why this was made a separate Windows SharePoint Services Web application instead of just a site collection, or even just a Web site, within "SharePoint – 80". Process isolation of the two Windows SharePoint Services Web applications enables network administrators to access Central Administration even when errant code on some Web site within "SharePoint – 80" causes the latter Web application to crash soon after each restart. Moreover, making the administration application a separate Web application enables administrators to give it distinct policies regarding authentication and anonymous users.
If Windows SharePoint Services 3.0 is installed on a farm of more than one server and the configuration distinguishes between front-end servers and back-end servers (called application servers in Windows SharePoint Services), "SharePoint – 80" runs on only the front-end servers. "SharePoint Central Administration v3" runs on one, and only one, of the application servers. You can read more about farms and the different types of servers and their roles later in this article.
In this article, Windows SharePoint Services Web applications other than the "SharePoint Central Administration v3" application are called content-publishing Web applications.
When the initial "SharePoint - 80" Web application is created, and whenever any content-publishing Web application is created, a new content database is created for the Web application. In turn, a site collection is created for the database and a top-level Web site is created for the site collection.
Some characteristics of the SPWebApplication class:
An SPWebApplication object is a child of an SPWebService object.
The SPWebApplication class has a ContentDatabases property that holds all its child SPContentDatabase objects. (It also has a Sites convenience property that enables you to get a reference to all the site collections of all its content databases without first getting a reference to one or more of the content databases.)
Like the Central Administration application, the SPWebApplication class enables administrators to access IIS properties without opening IIS Manager. For example, there is an IisSettings property, and there is an ApplicationPool property that provides programmatic access to the properties of the IIS application pool to which the Windows SharePoint Services Web application is assigned.
SPWebApplication inherits from SPPersistedObject, which means that an object of the class persists in the configuration database. (For more information about using such objects in your code, see Overview: Using the Object Model to Customize Administration and Walkthrough: Creating a Content Service Object.)
SPWebApplication has many members that can be used for developing administration functionality. Some of the more important members can help in the administration of the following:
Security policy
Alerts
Document conversions
Backups and restorations of the Web application
Logging of changes to the Web application
Outbound e-mail
External workflow participation
Use of the Windows Live MetaWeblog API
Use of the Recycle Bin
Unused site collections
Web.config file modifications
The SPWebApplication class has a close relation to the SPHttpApplication class. Objects of the latter class are HTTP request handlers. The process (IIS application pool) to which a Windows SharePoint Services Web application is assigned has one or more SPHttpApplication objects that handle the page requests directed to the Web application.
More Than One Content-Publishing Web Application
At many small and medium-sized institutions, the two Windows SharePoint Services Web applications that are installed by default are the only ones that are ever created. This may be true even if use of the "SharePoint – 80" Web application is intensive enough to require a farm of servers to host it. But there are situations in which additional content-publishing Windows SharePoint Services Web applications are needed and, for each, an IIS Web site and corresponding application pool. Here are examples of some of those situations. (There is never more than one "Central Administration" Windows SharePoint Services Web application for a given farm.)
When an institution is gradually shifting from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0, both may be deployed on the same server. In that case, each version has a separate Windows SharePoint Services Web application.
If a new Windows SharePoint Services solution is under development on a server (or set of front-end servers) that is also hosting a production Windows SharePoint Services deployment, it can be implemented in a separate Windows SharePoint Services Web application until after it has been thoroughly tested. This practice ensures that if the new solution crashes, production Windows SharePoint Services Web applications are not brought down. Additionally, the content database of the untested Web application is kept separate from the database of the production Web application. Finally, the untested Web application can be given a port number other than 80. This reduces the chance that any unauthorized person can access the application because, except for Web sites that use port 80, port numbers must be included in any Web URL; otherwise IIS cannot find the requested page.
Companies that provide Windows SharePoint Services hosting services to small customers typically give each customer its own Windows SharePoint Services Web application. This practice ensures that the customer's Web sites are not brought down by errant code in another customer's Windows SharePoint Services Web application. It also ensures that the customer's database cannot be accessed by other customers.
Web applications perform better when all the sites within them have similar structures. For example, a collection of "My Sites" would have many small sites; but a collection of team sites would typically have a smaller number of larger sites. Housing the team site collection in a separate Web application improves performance of both collections.
Any given Web application can have five separate sets of security policies—one for each of the five possible zones from which requests can come: the Internet, Intranet, Extranet, Default, and Custom zones. If more sets of policies are needed, additional Web applications can be created (possibly with content that is identical to an existing Web application), each with its own five sets of policies.
If enhanced collaboration server software, such as Microsoft Office SharePoint Server 2007, is installed in addition to Windows SharePoint Services 3.0, that software could allow logical grouping of Web applications. For example, it might do this to provide common services across the group or to administratively isolate the group from other Web applications. In such cases, the software may require creating a special Web application to serve as a logical parent or container of the group. This logical parent is called a Shared Services Provider (SSP). (However, such a logical grouping is not known to IIS 6.0 and is not modeled in the Windows SharePoint Services 3.0 object model. To IIS, the SSP is just one more Web site, and to Windows SharePoint Services 3.0 it is just one more Web application.)
Note
In Windows SharePoint Services 3.0, new Web applications are created on the Application Management tab of Central Administration, not in IIS.
Windows SharePoint Services Content Databases
Every Windows SharePoint Services Web application has at least one content database that is automatically created when the Web application is created. More content databases can be added to a Web application as needed. A content database contains all the data (lists, list items, blog posts and comments, wiki pages, and documents in document libraries) and most of the page files that constitute the site collections that belong to the database.
Some of the files that belong to a site collection are stored in the file system of the front-end servers of the Windows SharePoint Services deployment. At first glance, this fact might seem to spoil the neat picture of site collections being subsets of content databases. However, even the files that are not stored in the content database are represented by rows in the database. The table row that represents such a file functions as a kind of alias for the file.
Some characteristics of the SPContentDatabase class:
An SPContentDatabase object is a child of an SPWebApplication object. The collection of a Web application's content databases are referenced in the Web application's ContentDatabases property.
The SPContentDatabase class has a Sites property that holds all its child SPSite objects.
SPContentDatabase inherits from SPPersistedObject, which means that an object that instantiates the class persists in the configuration database.
SPContentDatabase has many members that can be used for developing administration functionality. Some of the more important members can help in the administration of the following:
Backup and restoration of the database
Upgrades of the database
Migration of (moving) the database
Repairs of the database
The database connection string and logon username and password
Limiting the number of site collections
Most of the properties of SPContentDatabase are read-only.
Windows SharePoint Services Site Collections
Site collections represented by the SPSite class exist as an administrative convenience to site owners, server administrators, and businesses that sell Windows SharePoint Services hosting services. Here are some of the most important characteristics of Windows SharePoint Services site collections:
Windows SharePoint Services site collections enable more fine-grained administration of Windows SharePoint Services deployments than is provided by Windows SharePoint Services Web applications, although administration of particular Web sites themselves still belongs to the site owners.
Every site collection has one and only one top-level Web site. For some kinds of administrative tasks, the site collection and its top-level Web site can best be thought of as a single entity. For example, the Site Settings page of the top-level site has a Site Collection Administration area in which the owner of the top-level Web site can activate features for the site collection and restore any of the site collection's deleted content from the Recycle Bin. Also, you can create certain custom entities, such as a custom column, in the top-level Web site. Those entities are then available to all Web sites in the site collection.
Site collections straddle the boundary between the administrative responsibilities of site owners and those of site collection administrators, who are usually IT professionals. As noted in the previous item, some administrative tasks at the site-collection level are handled by the owner of the top-level Web site. But server and network administrators can use the Application Management tab of Central Administration to create and delete site collections and set size quotas for site collections.
A site collection (or, speaking strictly, its top-level Web site) is the highest-level object in the breadcrumb navigation. (Although users of a subsite do not necessarily have access to every Web site higher in the hierarchy, they can see those sites in the breadcrumb navigation.)
A site collection is the level at which pools of site collection–scoped and Web site–scoped features, content types, lists, themes, and workflows are maintained and made available to subsites.
A site collection is one of four levels at which a Windows SharePoint Services Feature can be activated. The other levels are Web site, Web application, and farm.
A site collection is the level at which groups of users are maintained and assigned default rights. (Those rights can be changed at the level of any Web site, list, or list item. You can create groups on the Site Settings page of any Web site. But regardless of where the group is created, it exists at the site-collection level and is available to all Web sites in the collection.)
Master pages and Web Parts can be shared within a site collection but not among site collections.
A site collection is the highest-level object in the hierarchy for which access can be audited. It is also the level at which the auditing database is maintained.
A site collection is the highest level that can be included in a search.
Some characteristics of the SPSite class are as follows:
An SPSite object represents a subset of the content of an SPContentDatabase object.
The SPSite class has a RootWeb property that holds its child top-level Web site. (Top-level Web sites were called "root webs" in the first version of Windows SharePoint Services, Microsoft SharePoint Team Services.) In turn, the SPWeb object that represents the top-level Web site has a Webs property that holds all its immediate child subsites. (The AllWebs property returns all the subsites and the top-level Web site.)
SPSite has many members that you can use to develop administration functionality. Some of the more important members can help in the administration of the following:
The maximum length of Web site URLs
RSS feeds
Auditing
Dead Web sites
Features
Ownership of the site collection
Size quotas for the site collection
Site usage data
Workflows in the site collection
Templates and Web part galleries
Self-service site creation
About half the methods of the SPSite class are Get* methods that return information of some kind, and most of its properties are read-only.
The Physical Objects Hierarchy
The classes in the Physical Objects hierarchy represent entities that are either actual physical objects or objects that, depending on the context, can be regarded either as physical objects or as non-physical.
Figure 3. The Physical Objects hierarchy
.gif)
The SPFolder and SPFile classes are not discussed in this article; but to avoid misunderstanding, notice that the entity represented by an SPFolder object or an SPFile object might be located in a Windows SharePoint Services content database instead of in the file system of a server. For example, a spreadsheet file in a Windows SharePoint Services document library is stored in a cell of a database, not in a folder on one of the servers.
The Farm
A server farm is a load-balanced cluster of physical servers. This means that load-balancing software (or load-balancing hardware) directs an incoming network connection from a client computer to whichever computer in the farm is least busy at the time. Thus, the workload of servicing client connections is spread over many servers and hence many processors, hard drives, and other peripherals. Clients get much better performance. An additional advantage is that if one of the servers should crash, the others can continue to handle all incoming connections. Service is slowed, perhaps, but does not stop completely.
Because the client computer is seeking to interact with a particular application, file, database, or Web site page, all the computers to which the client could potentially be connected must be identically configured. Clients do not care, and usually do not know, which physical server they post to—the farm appears to the outer network as a single server.
The simplest way to accomplish an identical configuration would be to install the same applications on all the computers and to put copies of any needed files, databases, and Web site pages on them all (with the identical directory paths). However, this is rarely practical because it requires that every change a client makes to a file, or database, or anything else that persists on the server, is propagated to all the other servers. The decrease in performance caused by all the propagation cancels the advantages that the farm is supposed to provide.
In a more common setup, some servers in the farm are given special tasks, such as hosting a database. The servers to which clients are connected, called "front-end servers," do not have the database copied to them, but they are still identically configured because they use the same connection string and network address to access the database. If a single server cannot handle all the database access requests, the database itself can be hosted by a separate mirrored cluster in the farm.
Windows SharePoint Services can be hosted on a farm, and when it is, some kinds of farm administration tasks can be performed through Central Administration and through the object model. (Strictly speaking, a Windows SharePoint Services 3.0 deployment is always hosted on a farm, although it may be a "farm" with just a single computer that contains the whole deployment.) The following are some of the characteristics of a Windows SharePoint Services farm:
Each Windows SharePoint Services farm has a configuration database that holds information about the farm, its servers, and the other important child classes of the farm.
The farm is the level of the object model at which Windows SharePoint Services solutions are installed and from which they can be deployed to servers and Windows SharePoint Services Web applications.
A farm is one of four levels at which a Windows SharePoint Services Feature can be activated. The other levels are Web site, site collection, Web application.
An enterprise can have more than one farm hosting Windows SharePoint Services 3.0. For example, if enhanced collaboration server software, such as Microsoft Office SharePoint Server 2007, is installed in addition to Windows SharePoint Services 3.0, that software might require separate farm licenses for Internet-facing content and intranet content.
A Windows SharePoint Services farm is represented by the SPFarm class. These are some of the characteristics of the class:
The SPFarm class represents a farm of one or more physical servers, so it is included in the Physical Hierarchy. But it can also be considered the top level of the Content Hierarchy; for example, all the content of a Windows SharePoint Services farm can be backed up and restored.
In Windows SharePoint Services 3.0, the SPFarm class can also be thought of as representing the configuration database that is associated with the farm because Windows SharePoint Services 3.0 has no class that represents the configuration database itself. For example, the DisplayName property of an SPFarm object is also the name of the configuration database.
An SPFarm object has three major types of child classes: SPServer, SPService, and SPSolution.
SPFarm inherits from SPPersistedObject, which means that the object (there is only one) that instantiates the class persists in the configuration database.
SPFarm has static members for creating farms and returning references to the local farm or a remote farm.
SPFarm has many members that can be used for developing administration functionality. Some of the more important members can help in the administration of the following:
Backup and restoration of the farm
Upgrades of the farm
Migration of (moving) the farm
Error reporting
Caching
Servers
A physical server in a Windows SharePoint Services farm is represented by the SPServer class. In addition to many inherited members, it has an Address property that holds the IP address of the server and a Role property that identifies the server's role in the farm. If there is just one server, its role is SingleServer. If there is more than one, the front-end servers have the role WebFrontEnd and almost all other servers have the role Application. However, the Role property of a server that is physically hosting a Windows SharePoint Services content database typically has the value Invalid. This is because such servers typically run only one Windows SharePoint Services service—the Database Windows service—and this database service is really just an alias for the SQL Server Windows service (see "Applications and Services" later in this article), which is not part of Windows SharePoint Services. Hence, it is not really running any Windows SharePoint Services code, and it does not really fit into the Application role.
The SPServer class also has a ServiceInstances property that holds references to all the instances of Windows services and Web services that are running on the server.
SPServer inherits from SPPersistedObject. Objects that instantiate SPPersistedObject persist in the Windows SharePoint Services configuration database.
The Services Hierarchy
The classes in this hierarchy represent services and instances of services.
Figure 4. The Services hierarchy
.gif)
Applications and Services
The terms "application" and "service" in software have varying meanings; but an application is most frequently taken to be a large program that has a UI and a wide variety of functions. The common denominator of those functions can usually be expressed only with a very broad phrase such as "word processing" or "spreadsheet analysis." Also, applications provide a lot of end-to-end functionality. For example, a word processor can help an author from blank page through writing successive drafts, formatting, inserting graphics, managing reviews, and final publication of a file as, say, an XPS document. A spreadsheet application can support every stage from data insertion to mathematical-function construction and on to final report publication.
By contrast, a service provides a very narrow range of functionality that usually does not include end-to-end functions that are valuable in themselves. But the functionality that the service provides is valuable as a component part of a variety of applications. Services typically run invisibly and have little or no UI. They wait in memory until an application calls them. The Windows Print Spooler is an example of a service that can be called by any application that has to print a file.
A Windows service is any service that is hosted by the operating system and is available to locally running applications. A Web service is a service that is hosted on a network server and can be accessed by applications, such as browsers, running on remote clients.
Services
Windows SharePoint Services includes several Windows and Web services.
**Web Services **
Content Publishing This service makes the data and Web pages available to browsers. It runs on the front-end servers and is the most important service in Windows SharePoint Services.
Note
The names of Windows SharePoint Services services begin with "Windows SharePoint Services", followed by the name of the kind of thing that is "served up" by the service. Thus, there is a "Windows SharePoint Services Database" service and a "Windows SharePoint Services Web Application" service. But remember that the former is not itself a database, it is a service providing database access. Similarly, the latter is not a Web application. It is a service providing content publishing of Web applications.
Central Administration We saw earlier that the content of Central Administration is its own Web application so that it can have its own process and its own security policy. Now we find that the Web application is supported by its own Web service also. This service ordinarily runs on a front-end server only in a single server deployment. In other situations, it runs on one and only one application server.
Windows Services These services appear in the list of Services in the Control Panel of the server. Because these services have a presence in the UI and use the object model of Windows SharePoint Services, administrators and developers can start, stop, and manage the services without having to use the Control Panel.
Administration In a farm deployment, this special service is used by Windows SharePoint Services to perform privileged operations on behalf of the administrator on all front-end servers and application servers in the farm.
Timer This service enables administrators to set jobs to run at specified times. It runs on all front-end servers and application servers.
Search This service enables searching of the content in a Windows SharePoint Services deployment. On a multiserver farm, it runs on one or more application servers.
Database This is really a kind of wrapper around the already installed SQL Server Windows service. It enables the Windows SharePoint Services objects to access to the content and configuration databases. In a multiserver Windows SharePoint Services deployment, the server that is hosting a database is usually the only one that is running this service.
Windows SharePoint Services also provides three services that do not fit neatly into the categories of Windows service and Web service:
A Diagnostics service that runs on all front-end servers and application servers.
An Incoming e-mail service that typically runs on only one application server.
An Outgoing e-mail service that typically runs on only one application server.
These last three services mainly hold configuration settings.
You can create new Windows services and Web services. For example, a Windows service that scans documents for viruses would be a nice addition to a Windows SharePoint Services deployment. (For more information about Windows service development, see Services.)
A Windows SharePoint Services service is represented by a class that inherits from SPService. Eight such classes are already in the object model, and you can derive new classes from SPService and two of its children.
Figure 5. Services inheritance tree (solid borders indicate sealed classes)
.gif)
Aside from what it inherits from SPPersistedObject, SPService provides members that get information about the jobs the service is performing. Each of the derived types provides additional functionality relevant to its particular type.
Every SPService object has an Instances property that holds all the instances of the service that are running on various servers in the farm. No more than one instance of each service runs on any one server, but some services have multiple instances, each one running on a different server. Each instance is represented by an object of a class derived from SPServiceInstance.
The inheritance tree of SPServiceInstance is almost exactly parallel to the tree for SPService.
Figure 6. Service instance inheritance tree (solid borders indicate sealed classes)
.gif)
In addition to what it inherits from SPPersistedObject, SPServiceInstance provides members for starting and stopping the service on the server. Each of the derived types provides additional functionality relevant to its particular type. The SPLoadBalancerServiceInstance class is not used by the farm's load-balancing software or hardware. It is a base class that developers can use, along with SPWindowsService, to develop load-balanced document conversion services, such as a service that enables end users to view a PDF document as HTML.
Deployment Examples
Here are some concrete examples of Windows SharePoint Services 3.0 deployments. First, Figure 7 shows the major objects in the Windows SharePoint Services object model hierarchy immediately after Windows SharePoint Services 3.0 is installed on a single server.
Figure 7. Services, service instances, and Web applications on a new single server deployment
.gif)
Figure 8 shows the services and service instances on a hypothetical 10-server farm. Note the following things about this example:
The translucent rectangles represent services. These services are modeled in the Windows SharePoint Services object model with SP*Service classes.
The smaller, solid rectangles represent instances of services that are modeled in the Windows SharePoint Services object model with SP*ServiceInstance classes.
The Diagnostics Service does have instances running on all servers (except the dedicated database server), but the object model has no SPDiagnosticServiceInstance class (because there is no need for one in Windows SharePoint Services 3.0), so there are no sold rectangles for these instances.
The Administration, Timer, and Diagnostics services run on all servers (as they must), except the dedicated database server.
Only the five front-end servers run the Web Application Service.
This hypothetical farm has a moderate amount of content but intensive search needs, so one database server and three application servers run the Search Service. Each of the Search servers crawls and indexes a different subset of the farm's contents.
A fourth, multipurpose application server runs Central Administration and the e-mail services.
When the Windows SharePoint Services databases are on a dedicated server, as in this case, Windows SharePoint Services need not be installed on that server. The Database Service is just a wrapper for the SQL Server service running on the database server. Hence, Windows SharePoint Services code is not running on the dedicated database server. The service and its instance appears in the figure because it is represented in the object model with the SPDatabaseService and SPDatabaseServiceInstance classes.
Figure 8. Services and service instances on a typical 10-server farm
.gif)
Code Example
The following console application creates an itemization of the services, service instances, Web applications, content databases, site collections, and Web sites at a Windows SharePoint Services 3.0 deployment.
To use this code, create a console application project named "ComponentItemization" in Microsoft Visual Studio. Add a reference to Microsoft.SharePoint.dll. Then replace the contents of the default Program.cs file with the code below.
To run the executable, enter ComponentItemization > output.txt at a command prompt in the directory where you saved ComponentItemization.exe.
Open output.txt in any text viewer to see the output.
Note
This sample is written so that you can see references to each type of component in close proximity to references to its properties, its main child components, and its parent component. For that reason, this sample deliberately avoids encapsulating repetitive code into separate methods.
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
namespace ComponentItemization
{
class Program
{
static void Main(string[] args)
{
Console.WriteLine("The Farm is: {0}\n",
SPFarm.Local.DisplayName);
SPServiceCollection myServices = SPFarm.Local.Services;
Console.WriteLine("\tThe services in the farm:\n");
// Itemize the Windows Services
Console.WriteLine("\n\n\t\tThe Windows Services:");
foreach (SPService sps in myServices)
{
if (sps is SPWindowsService)
{
Console.WriteLine("\n\t\t\tService Type Name: {0}",
sps.TypeName);
Console.WriteLine("\t\t\tService Name: {0}\n",
sps.Name);
Console.WriteLine("\t\t\tThe instances of this service:\n");
Int16 serviceInstanceNumber = 1;
SPServiceInstanceDependencyCollection
winServiceIntCol = sps.Instances;
foreach (SPServiceInstance winSerInt
in winServiceIntCol)
{
Console.WriteLine("\t\t\t\tInstance {0}:",
serviceInstanceNumber);
Console.WriteLine("\t\t\t\tInstance
DisplayName: {0}", winSerInt.DisplayName);
Console.WriteLine("\t\t\t\tInstance Name: {0}",
winSerInt.Name);
Console.WriteLine("\t\t\t\tInstance Hosting Server: "
+ GetInstanceHostingServerName(winSerInt.Server)
+ "\n");
serviceInstanceNumber++;
}
}
}
// Itemize the Web Services
Console.WriteLine("\n\n\t\tThe Web Services:");
foreach (SPService sps in myServices)
{
if (sps is SPWebService)
{
Console.WriteLine("\n\t\t\tService Type name: {0}",
sps.TypeName);
Console.WriteLine("\t\t\tService Name: {0}\n",
sps.Name);
Console.WriteLine("\t\t\tThe instances of this service:\n");
Int16 serviceInstanceNumber = 1;
SPServiceInstanceDependencyCollection
webServiceIntCol = sps.Instances;
foreach (SPServiceInstance webSerInt
in webServiceIntCol)
{
Console.WriteLine("\t\t\t\tInstance {0}:",
serviceInstanceNumber);
Console.WriteLine("\t\t\t\tInstance DisplayName: {0}",
webSerInt.DisplayName);
Console.WriteLine("\t\t\t\tInstance Name: {0}",
webSerInt.Name);
Console.WriteLine("\t\t\t\tInstance Hosting Server: "
+ GetInstanceHostingServerName(webSerInt.Server)
+ "\n");
serviceInstanceNumber++;
}
Console.WriteLine("\n\t\t\tThe Web applications in this Web service:\n");
Int32 webAppNumber = 1;
SPWebService spws = (SPWebService)sps;
foreach (SPWebApplication spwebapp
in spws.WebApplications)
{
Console.WriteLine("\t\t\t\tWeb Application {0}",
webAppNumber);
Console.WriteLine("\t\t\t\tApplication Name: {0}",
spwebapp.Name);
Console.WriteLine("\t\t\t\tApplication Display Name: {0}\n",
spwebapp.DisplayName);
webAppNumber++;
Console.WriteLine("\n\t\t\t\tThe content databases in this Web application:\n");
Int32 contentDBNumber = 1;
foreach (SPContentDatabase db
in spwebapp.ContentDatabases)
{
Console.WriteLine("\n\t\t\t\t\tContent Database {0}",
contentDBNumber);
Console.WriteLine("\t\t\t\t\tDatabase Name: {0}",
db.DisplayName);
contentDBNumber++;
Console.WriteLine("\n\t\t\t\t\t\tThe site collections in this database:\n");
Int32 siteColNumber = 1;
foreach (SPSite site in db.Sites)
{
Console.WriteLine("\n\t\t\t\t\t\t\tSite Collection {0}",
siteColNumber);
Console.WriteLine("\t\t\t\t\t\t\tSite Collection RootWeb: {0}",
site.RootWeb);
Console.WriteLine("\t\t\t\t\t\t\tSite Collection Url: {0}",
site.Url);
siteColNumber++;
Console.WriteLine("\n\t\t\t\t\t\t\tThe Web sites in this site collection:");
SPWebCollection webs = site.AllWebs;
Int64 webSiteNumber = 1;
foreach (SPWeb web in webs)
{
Console.WriteLine("\t\t\t\t\t\t\t\tWeb site {0}: {1}",
webSiteNumber, web.Name);
webSiteNumber++;
}
}
}
}
}
}
// Itemize the other services
Console.WriteLine("\n\n\t\tOther Services:");
foreach (SPService sps in myServices)
{
if (!(sps is SPWebService)
&& !(sps is SPWindowsService))
{
Console.WriteLine("\n\t\t\tService Type Name: {0}",
sps.TypeName);
Console.WriteLine("\t\t\tService Name: {0}",
sps.Name);
Console.WriteLine("\t\t\tThe instances of this service:\n");
Int16 serviceInstanceNumber = 1;
SPServiceInstanceDependencyCollection
otherServiceIntCol = sps.Instances;
foreach (SPServiceInstance otherSerInt
in otherServiceIntCol)
{
Console.WriteLine("\t\t\t\tInstance {0}:",
serviceInstanceNumber);
Console.WriteLine("\t\t\t\tInstance DisplayName: {0}",
otherSerInt.DisplayName);
Console.WriteLine("\t\t\t\tInstance Name: {0}",
otherSerInt.Name);
Console.WriteLine("\t\t\t\tInstance Hosting Server: "
+ GetInstanceHostingServerName(otherSerInt.Server)
+ "\n");
serviceInstanceNumber++;
}
}
}
// To send output to the console, uncomment the following lines:
// Console.WriteLine("Press Enter to continue.");
// Console.ReadLine();
}//end Main
private static
String GetInstanceHostingServerName(SPServer instanceHostingServer)
{
String full = instanceHostingServer.ToString();
String concise = full.Substring(full.IndexOf("=") + 1,
full.IndexOf("Parent") - (full.IndexOf("=") + 1));
return concise;
}
}
}
Conclusion
The Windows SharePoint Services 3.0 object model provides a rich set of classes for automation of administrative tasks.
Additional Resources
Acknowledgements
Thank you to Corey Roussel, Les Smith, and A.J. May for their assistance.