How SharePoint Works

How SharePoint Works

A Technical Whitepaper for Software Developers and System Architects
Written by Ted Pattison

Over the last few years, Microsoft has made a significant investment in collaborative technologies, Windows SharePoint Services and SharePoint Portal Server are two flagship products positioned to dominate this space. This whitepaper is written to introduce SharePoint’s fundamental architecture and to discuss the opportunities that SharePoint provides to you as a software developer using the .NET Framework.
Windows SharePoint Services (WSS) is a free product that runs on the Windows Server 2003 operating system. WSS supplies a framework for building collaborative Web sites which make it possible for a company to share information and documents across the members of teams, departments and large organizations with unprecedented levels of ease and reliability. Any user can access a WSS Web site using a Web browser or through the new collaboration features built into Microsoft Office 2003 products such as Word and Excel.
WSS also provides the underlying infrastructure for generating user interfaces through the inclusion of Smart Page and Web Part technology. Smart Pages and Web Parts are a very powerful aspect of SharePoint because each WSS site provides a browser-based user interface that is extensible and fully customizable. Web Parts can also be used to store personalization information on a user-by-user basis. We will discuss Web Parts in greater detail later at the end of this whitepaper.
SharePoint Portal Server 2003 (SPS) is a product for building enterprise-level portal sites that is part of the Microsoft Office 2003 System. It is important to note that SPS is built on top of WSS. SPS compliments WSS by adding manageability features designed to assist users navigating through vast amounts of information and documents. SPS also supplies additional functionality to enhance portal sites using indexing, searching, audience targeting and single sign-on.
There is a fundamental difference in the roles played by WSS and SPS. These differences are shown in the table in figure 1. WSS is based on a collaboration theme in the sense that it’s designed to store and share list-based data and documents. SPS, on the other hand, is based on an aggregation theme. An SPS portal site is useful for aggregating information and documents from many different places. SPS adds value by providing users with a quick and easy way to find information and documents that are spread out around a private network or scattered throughout the Internet.

In essence, WSS gives you a place to put all your content while SPS provides the means to navigate and search through your content when you need it. These two roles are quite complimentary to one another. WSS allows an enterprise-level company to create and maintain tens of 1,000s of collaborative Web sites, while one or more SPS portal sites allows users to search through all this content and find what they're looking for.
You should understand that SPS depends upon WSS to provide many essential services. For example, WSS provides SPS with the capacity to track members and share lists and documents. Furthermore, SPS doesn’t supply any code for generating the user interface for a portal site. Instead, SPS leverages the WSS Smart Page and Web Part infrastructure to construct the user-interface for an SPS portal site.
Windows SharePoint Services Architecture
WSS is a free product to any individual or company that has purchased the Windows Server 2003 operating system. The WSS installation files can be downloaded using the Windows Update service or from the following URL:
http://www.microsoft.com/windowsserver2003/technologies/sharepoint/default.mspx.
The WSS framework is built on top of Windows Server 2003, IIS6 and ASP.NET. Figure 2 shows how the fundamental pieces of the WSS framework fit together. Note that before you can successfully install WSS on Windows Server 2003, you must first configure the host computer as an Application Server by enabling IIS6 and ASP.NET 1.1.


Learning about WSS is easier once you know a few facts about its history. WSS is part of the second generation of SharePoint products and technologies. The first generation was built on an earlier IIS-based framework named SharePoint Team Services (STS). The STS framework is similar to WSS in that it provides a collaborative framework for sharing list-based data and documents. However, STS was not built upon on the .NET Framework or ASP.NET. Instead, it was built using a proprietary ISAPI extension.
Customizing and extending STS Web sites has always been relatively difficult due to limited tool support. Site customization is much easier with WSS and the second generation of SharePoint because of WSS-compatible Web designers such as Microsoft Office FrontPage 2003. WSS also offers a much better extensibility model because you can write custom applications and Web Parts for WSS sites and SPS portal sites with Visual Studio .NET using either C# or Visual Basic .NET.
STS and the first generation of SharePoint products and technologies have also suffered from scalability problems. The scaling limitations of STS are due to an underlying architecture that runs a stateful design on front-end Web servers. This flaw makes it impossible to scale out STS Web sites using a Web Farm environment. When Microsoft engineers started to design WSS and the second generation of SharePoint products and technologies, they made it a primary design goal to fix the scaling problems of STS. Consequently, they designed their architecture to support WSS and SPS deployments with tens of 1000s of users and tens of 1000s of Web sites.
WSS architecture is based on stateless front-end Web servers. Their architecture is founded on an integrated storage strategy where all the list-based data and documents associated with a Web site are stored within a SQL Server database as shown in figure 3. A key objective of this integrated storage strategy is that it allows a deployment of WSS Web servers to effectively scale out in a Web farm environment.

WSS relies on two different kinds of SQL Server databases; configuration databases and content databases. As you might suspect, the configuration database holds deployment-specific configuration information for each physical Web server, IIS virtual server and WSS Web site. Content databases, on the other hand, hold data associated with WSS Web sites.
WSS requires exactly one configuration database for each deployment of WSS Web servers. A simple deployment can involve a single host computer running both the WSS front-end Web server components and SQL Server with the configuration database and a single content database. A more scalable WSS deployment involves a Web farm scenario with multiple front-end Web servers. A WSS deployment can also involve multiple back-end database servers. For example, in certain deployments it can offer scaling advantages to spread several content databases across multiple host computers running SQL Server. However, there is only one configuration database for each WSS deployment. The configuration database provides a central repository of information to coordinate all font-end servers and back-end servers.
Each content database stores the data for one or more WSS Web sites. WSS data that is stored on a site-by-site basis includes lists and documents as well as all information pertaining to site customization and personalization. This integrated storage strategy provides a definite improvement over STS where site-specific data was stored in the file system and in the registry in addition to the database. The fact that everything pertaining to a site is stored within a single SQL Server database makes it much significantly easier to backup and restore Web sites under WSS.
The ability to spread the content for different Web sites across multiple backend database servers provides a valuable scaling feature. For example, imagine your company’s marketing department needs several gigabytes of storage and lots of processing cycles because they are constantly storing and retrieving really large graphics files. You can create a WSS Web site for the marketing department which stores its content in a separate content database running on a dedicated host computer running SQL Server. You could then create a WSS Web site for your company's sales department that stores its content within this same content database, or you could store it in a different content database running on a separate database server. The purpose of content databases is to provide a point of scalability and management.
If you’re just getting started with WSS, you can install everything you need on a single computer running Windows Server 2003. Once you have installed Windows Server 2003, configure the computer as an Application Server by enabling IIS6 and ASP.NET 1.1. When you configure IIS and ASP.NET, be certain not to install the FrontPage Server Extensions because they are incompatible with WSS. After that you can install WSS by running the installation program STSV2.EXE.
For single-machine deployments, WSS doesn't require you to use the full-blown version of SQL Server. The WSS installation program can optionally install a special version of MSDE called Windows MSDE (WMSDE). WMSDE is unlike the standard version of MSDE because it doesn’t limit you to 2 GB of storage and 10 database connections. However, WMSDE is more restrictive than MSDE because it only supports table schemas signed by Microsoft. This means you cannot use WMSDE to create your own custom databases and tables.
If you would like to install SPS on a development workstation, the installation process is more complicated. First of all, there are several SPS features that require Active Directory. Therefore, you should prefer to install SPS on servers that are part of an Active Directory domain. Before installing SPS on a host computer running the Windows Server 2003 operating system, first add that machine to an existing Active Directory domain or configure it to be a domain controller. Once the Windows Server 2003 computer is in a domain, next configure it to be an Application Server by enabling IIS6 and ASP.NET 1.1. With SPS, we also recommend that you install SQL Server instead of relying on WMSDE to store the database for portal sites.
Once you have prepared a Windows Server 2003 computer with IIS6, ASP.NET 1.1 and SQL Server and added it to an Active Directory domain, you are ready to run the SharePoint Portal Server 2003 installation. The first thing the SPS installation program does is to install its own specialized version of WSS. The version of WSS used by SPS is required to add extra tables to the configuration database and to each content database that holds an SPS portal site. After the SPS installation program copies the required files to the host computer, it displays a wizard that steps you through the process of creating the configuration database and creating the initial portal site. In addition to adding extra tables to the configuration database and content database, the installation of SPS also creates a few other databases to track data for features such as search and audience targeting.
Before installing either WSS or SPS in a deployment with SQL Server (as opposed to WMSDE), you might be required to add a SQL Login for the Windows account that serves as the identity for the IIS Application Pools used by SharePoint. By default, WSS and SPS configure IIS Application Pools to run under the identity of the NT AUTHORITY\NETWORK SERVICE account. If you don't like this default setting, you can reconfigure any IIS Application pool to use a different Windows account. Whatever Windows account you use, however, needs a SQL login to log on to SQL Server.
Once you have added the a SQL login for the appropriate account within SQL Server, next you must add the account into the Server Roles of Security Administrators and Database Creators. If you don’t follow these steps, you will experience errors when installing or configuring either WSS or SPS. That’s because WSS and SPS by default use IIS application pools that run under the identity of the NT AUTHORITY\NETWORK SERVICE account which has no permissions to log onto SQL Server. You must configure SQL Server to grant this account the permissions to create databases and configure their security settings.
IIS Web Sites and Virtual Servers
WSS Web site configuration starts at the level of the IIS Web Site. A default installation of IIS creates an IIS Web Site named Default Web Site that is configured to listen for incoming HTTP requests across port 80. You can use the IIS Administrative tools to create additional IIS Web sites that listen for incoming HTTP requests on a different port or with a different host header. Figure 4 shows an example of an IIS Web server computer with two virtual servers configured for end-user access.

Note that the installation of WSS adds its own special IIS Web Site named SharePoint Central Administration. WSS uses this IIS Web site to run the SharePoint Central Administration HTML pages. The SharePoint Central Administration Web site is configured on a random port number during installation so that it is less likely to be accessed by an intruder.
In SharePoint terminology, an IIS Web Site is known as a virtual server. A virtual server must be extended with WSS in order to run WSS Web sites. When you install WSS with the default settings, it automatically extends the virtual server that is listening on port 80. You can extend WSS onto another virtual server by using the SharePoint Central Administration HTML pages or by using a WSS command-line administration tool named STSADM.EXE.
WSS is unlike ASP.NET in that it doesn't configure each Web site using an IIS virtual directory. Instead, WSS tracks all configuration information for WSS Web sites inside the configuration database and content databases. This means that once WSS has extended a virtual server and you start creating WSS Web sites that they will not appear in the IIS metabase. Instead an entry will be created in the configuration database and appropriate content database. In reality, IIS doesn't know whether a WSS-extended virtual server contains a single WSS Web site or 10,000 WSS Web sites. The fact that WSS doesn't need to configure an IIS virtual directory for each new WSS Web site offers benefits in scalability and improved maintenance.
When WSS extends itself onto a virtual server, it installs a custom ISAPI filter called the WSS filter (STSFLTR.DLL). The WSS filter intercepts each request routed to that virtual server and determines whether the request should be handled by WSS or IIS. To make this determination the WSS filter inspects the URL of the incoming request and consults the configuration database to determine who should process it. Keep in mind you may have a virtual server in which you plan to run WSS sites as well as other ASP and/or ASP.NET applications.
When WSS extends itself onto a virtual server, it adds a web.config file to the root directory of the hosting virtual server. This web.config file provides initial configuration settings for WSS and for all ASP.NET code that runs from inside that virtual server. By default, this web.config file contains fairly restrictive security settings. You will be required to modify sections of this web.config file when you want your code to run with elevated permissions or when you want to test or deploy a new custom Web Part.
In SharePoint terminology, an URL space is the set of all possible URLs that target a virtual server. WSS divides the URL space of an extended virtual server into managed paths. Paths that are managed by WSS are considered included paths while those that are not managed by WSS are considered excluded paths. When the WSS filter sees a incoming request with an URL that part of an excluded path, it knows to route the request back to IIS for standard ASP and/or ASP.NET processing.
What should you do when you want to host a standard ASP.NET within a virtual server that has been extended with WSS? For example, imagine you want to deploy as ASP.NET Web application at http://AcmeServer/webapp1 so that it's available alongside WSS sites in the same virtual directory. At this point you will need to understand and know how to configure included paths and excluded paths. In particular, you need to add an excluded path for the URL space used by the ASP.NET Web application. Figure 5 shows a screen shot of the user interface provided by the SharePoint Central Administration HTML pages for defining managed paths.

Take note that the screen capture in figure 5 shows the virtual server’s included path as well as its excluded paths. Some included paths such as \sites are defined as wildcard inclusions. The purpose of a wildcard inclusion is make URL parsing more efficient. WSS doesn’t allow the nesting of excluded paths within the URL space of a wildcard inclusion. Once the WSS filter sees the first part of the URL for an incoming request matches a wildcard inclusion such as http://AcmeServer/sites, it knows that the request should be directed to WSS for processing.
When the WSS filter determines the URL of an incoming request is inside an included path, it consults the configuration database to locate the target WSS site. WSS tracks each of its sites in the configuration database using the site's URL and an identifying GUID. There is additional information in the configuration database linking each site to a target content database.
Within a WSS deployment, it is often useful to extend more than one virtual server. The reason you might want to do this has to do with flexibility. Each virtual server can be configured using an IIS Application Pool to run its WSS Web sites in an isolated process. IIS also makes it possible to configure the security authentication requirements differently for each virtual server. One virtual server can be configured to require Basic Authentication while a second virtual server can be configured to require Integrated Windows authentication.
In some deployments, every WSS-extended virtual server will have its own separate content database. However, it's also possible to extend a virtual server so that it attaches to the same content database used by another virtual server. This allows a pair of virtual servers to provide two different access points to a common set of WSS sites. This is valuable because the security settings for each virtual server can be configured independently. For example, a virtual server used to provide public-facing Web sites to users on the Internet is typically configured to require SSL and Basic Authentication. A second virtual server providing access to users behind a corporate firewall can be configured to require Integrated Windows Authentication.
Site Collections, Sites and Workspaces
Within a virtual server, WSS sites are partitioned using site collections. A site collection is a set of one or more sites that constitutes a unit of ownership. Creating a new site collection requires you to supply a Windows login account and an email address for its owner. WSS tracks information about site collection owners so it can grant them administrative permissions and send them email notifications regarding site collection maintenance issues.
A site collection always includes a top-level site that has the same URL as the site collection itself. When you create a new site collection, the top-level site is created automatically. In addition to its top-level site, a site collection can optionally contain other secondary sites that are related to the top-level site through parent-child relationships as shown in figure 6. Every site must be created within a specific site collection and all the sites in the same site collection are stored in the same content database.


The site collection serves as a unit of backup and restore in WSS. The STSADM.EXE administrative tool provides easy-to-use commands for backing up and restoring a site collection. After backing up a site collection, you can later restore it on the same Web server or on a different Web server. You will find that WSS makes it far more difficult to back up and restore individual sites that exist within a site collection below the top-level site. If you are creating a site that you would like to backup and restore independently, you should create the site as a top-level site within a new site collection.
When performing day-to-day maintenance in a large WSS deployment with 100s or 1000s of site collections, it is not necessary to backup site collections individually. Instead, you can perform backups at the level of the content database. Backing up content databases will be easy for many companies because they can use the same maintenance procedures that they use to backup other SQL Server databases.
Now let's take a step back and ask a fundamental question; what is a WSS site?
First, a site is a container for storing content. Site contents are primarily stored in the form of lists, document libraries and child sites.
Secondly, a site is a securable entity whose content is accessible to a configurable set of users. A site can either define its own set of users or it can inherits the users of its parent site. Each site user maps to a Windows account defined within an Active Directory domain or a local Windows security accounts database. A site also contains a configurable set of groups and permissions that define the level of accessibility that various users have on the site's lists and document libraries.
Third, a site is a Web application with an extensible, fully-customizable user interface. A site owner or Web designer can customize the layout and appearance of a site's pages and modify the site's navigation structure using either the browser or Microsoft Office FrontPage 2003.
Finally, a site is the foundation for using Microsoft's Smart Page and Web Part technology. Site owners and Web designers can customize Smart Pages by adding and configuring shared Web Parts. A user can further personalize a Smart Page by modifying, adding and/or removing Web Parts. All the customization data and personalization data associated with the Web Parts on a Smart Page are automatically stored in the content database.
WSS supports a specialized type of site called a workspace. Technically speaking, a workspace is really just a standard WSS site. However, the purpose of a workspace is more narrowly defined than other types of WSS sites. Let's look at a simple example to illustrate this point. A Team Site is not a workspace because it typically contains several different lists, document libraries and child sites. A workspace, on the other hand, focuses on a single item. A document workspace is used to collaborate on a single document or document library. A meeting workspace is used to collaborate before, during and after a single meeting.
Every site is initially created from a site template. A site template is a blue print that defines an initial set of lists, document libraries, Smart Pages and Web Parts that exist within a new site. WSS ships with eight site templates including Team Site, Blank Site, Document Workspace, Basic Meeting Workspace, Blank Meeting Workspace, Decision Meeting Workspace, Social Meeting Workspace and Multipage Meeting Workspace. When a site is first accessed after being created, WSS prompts the user to select one of the available site templates using the HTML page shown in figure 7.
Figure 7:Each site is created based on a site template
WSS supports the creation and use of custom site templates. You can customize a site to your heart's content with Microsoft Office FrontPage 2003 and then save the site as a site template. Saving a site as a site template is accomplished with a few clicks in the browser. Once the custom site template has been created, it is then available for creating new sites within the same site collection. With some additional effort, a custom site template can be exported to other site collections and can also be used to create top-level sites.
SPS Architecture
SPS builds on top of the architectural layer provided by WSS. When you create a new SPS portal site, you are really creating a new physical WSS site collection. However, there are a few noteworthy restrictions about how SPS uses WSS. There can be only one portal site per virtual server. Furthermore, the site collection containing a portal site must always be created at the root URL of the hosting virtual server.
Once you have created a portal site at the root of a virtual server, you can then create additional standard WSS site collections within the same virtual server. If fact, that's exactly what SPS does when you execute the Create Site command from a portal site. That is, SPS creates a top-level site within a new site collection. When a portal site user creates a personal site by clicking the "My Site" link, SPS also creates this personal site as a top-level site within a new site collection. This strategy makes it easier to backup and restore shared sites and personal sites within an SPS deployment.
SPS extends the way in which WSS stores content by introducing areas and listings. Remember that SPS is a product designed around the theme of aggregation. Areas and listings are used by portal site content managers to aggregate content from other places. An area is a container of listings and nested subareas. Occasionally, a listing will contain HTML-based text. More often, a listening contains a link to non-portal content such as a document, Web page or WSS list across the network. The key point is that listings allow SPS to link users to non-portal content such as shared folders, Exchange public folders, WSS sites, public Web sites and Lotus Notes as shown in figure 8.
Figure 8: SPS provides Areas and Listing to aggregate information from around the network.
The areas within a portal site are structured in a hierarchy of parent-child relationships. Figure 9 shows a screen shot of the HTML-based interface that SPS provides for working with areas. This user interface makes it relatively simple for portal site content managers to add and delete areas and listings from within the areas hierarchy of a portal site. SPS also makes it simple using the browser to relocate an area or listing to a new location within the areas hierarchy.
Figure 9: Areas make it easy for users to navigate and search through content.
Areas and listings facilitate aggregation because they make it easy to navigate through content both within and external to a portal site. Areas and listings are also integrated with the SPS Search service. When you run an SPS search within the scope of an area, SPS searches through the content and links of that area's listings as well as the content and links of listings within the subareas nested below.
The SPS search service is complimented by the SPS indexing service. The indexing service is designed to build indices by crawling through the content links provided by areas and listings. The indexing service even knows how to crawl through Word documents and Excel spreadsheets and search for specific keywords. Once the set of indices has been built, the SPS search service is able to perform fast searches that allow user to find the content they are looking for.
The WSS and SPS Object Models
WSS and SPS each expose an object model for developers that are writing custom software. The WSS object model allows you to develop administrative applications that create and manage virtual servers, site collections, sites, workspaces and users. You can also design and implement end-user targeted applications using the WSS object model that manage lists and document libraries as well as the items they contain. The SPS object model allows you to programmatically manipulate areas and listings and to automate other features such as the SPS services for search and single sign on (SSO).
The WSS and SPS teams at Microsoft have exposed their object models to you through class library DLLs as well as through a built-in set of Web services. For example, you should add a reference to Microsoft.SharePoint.dll when you want to program against the WSS object model using the class library. If you want to program against the WSS object model using Web services, you should add a Web reference to one of the built-in Web services such as http://AcmeServer/_vti_bin/Lists.asmx.
How do you decide between using the class libraries and Web services? The class libraries are easier to use and they support more features. However, a custom application that uses one of the class library DLLs can only run on a server computer within a WSS or SPS deployment. Programming against the object model of WSS and SPS using the Web services doesn’t provide as much functionality and often requires you to program in terms of XML. However, a custom application built using Web services can be run on an administrator’s desktop computer or a user’s laptop computer. The whole point to using the built-in Web services is that a custom application can be written to communicate with a WSS or SPS deployment from across the network.
When developers begin to program against the WSS object model, there is often confusion surrounding different terminology used between WSS and its predecessor SharePoint Team Services (STS). For example, the new WSS term "Site Collection" is the equivalent of the old STS term "Site". The new WSS term "Site" is the equivalent of the old STS term "Web". The new WSS term "Top-level Site" is the equivalent of the old STS term "Root Web".
While the WSS team has been consistent using the new WSS terminology in their product documentation, the names of classes in the WSS object model are based on the old STS terms. For example, you program against a site collection using an SPSite object. You program against a site using a SPWeb object. An SPSite object provides a public property named RootWeb that returns an SPWeb object representing the site collection’s top-level site. Once you understand this potential point of confusion, the WSS object model becomes easier to learn.
The WSS object model exposed by the class library provides a top-level GlobalAdmin class that serves as an entry point into a WSS deployment. You can use a GlobalAdmin object to enumerate through the virtual servers, site collections and site within a WSS or SPS deployment as shown in figure 10. Within each site, you can then inspect its lists, document libraries, users and child sites.
// get GlobalAdmin object for current WSS deployment
SPGlobalAdmin globalAdmin = new SPGlobalAdmin();

// enumerate through IIS Virtual Servers
foreach(SPVirtualServer vServer in globalAdmin.VirtualServers)
{
// determine which IIS Virtual Servers are extended with WSS
if(vServer.State == SPVirtualServerState.Ready)
{
// enumerate through Site Collections of each Virtual Server
foreach(SPSite SiteCollection in vServer.Sites)
{
// enumeratre through Sites of each Site Collection
foreach(SPWeb Site in SiteCollection.AllWebs)
{
// enumerate through Lists of each Site
foreach(SPList List in Site.Lists)
{
Console.WriteLine(List.Title);
}
}
}
}
}
Figure 10: The WSS object model makes it possible to enumerate a site hierarchy.
This whitepaper is accompanied by two sample applications. The first sample application named the SharePoint Site Browser illustrates how to program against the WSS object model using the class library. We wrote this Windows Forms application to demonstrate techniques required to enumerate through virtual servers, site collections, sites, lists, document libraries and users. A screen shot of this application is shown in figure 11.
Figure 11: The SharePoint Site Browser is a sample application that uses the WSS object model
We wrote a second sample application named the Portal Area Browser that demonstrates how to program against the SPS object model. The code behind the application will show you how to program against the SPS class library DLLs to navigate through areas and inspect their listings. Both of these applications complete with full source code can be downloaded from http://Barracuda.net/downloads.aspx.
Web Part Architecture
The inclusion of Smart Page and Web Part technology is one of the most powerful and enabling aspects of WSS. Smart Pages provide each site with an extensible HTML-based user interface. A site owner or Web designer can customize a Smart Page by adding and configuring Web Parts. Users can further personalize Smart Pages by modifying existing Web Parts and adding new Web Parts. It is interesting to note that the Smart Page and Web Part technology created for WSS is being carried over as a major new feature in the Whidbey release of ASP.NET.
How is a Smart Page different from a standard ASP.NET page? A standard ASP.NET page is stored as a text file on the file system of the Web server. The pieces that make up a Smart Page, on the other hand, are stored in multiple tables inside the content database. WSS constructs Smart Page objects on the fly by retrieving data from these tables. It is this dimension of the Web Part architecture that makes it possible to customize and personalize sites.
Note that the HTML-based interface provided by WSS refers to a Smart Page as a Web Part Page. You can assume that a Smart Page and a Web Part Page are two different terms that mean the same thing. For the remainder of this whitepaper, we will use the term Web Part Page because that is what you will see when customizing WSS sites with the browser or with Microsoft Office FrontPage 2003.
Let's take a moment and examine a Web Part Page from the perspective of a Web Part consumer. If you are a site owner or you have Web designer permissions, you can view and modify a Web Part Page in either Shared View or Personal View. Using the browser, you can switch back and forth using the Modify Shared Page menu as shown in figure 12. Once you have switched over to your personal view, the menu caption in the upper right-hand corner of the Web Part Page changes to Modify My Page.
Figure 12: Web Part Pages can be modified in either shared view or personal view.
To customize the Web Parts on a Web Part Page, you should enable the Design this Page option. You can also add new Web Parts to a Web Part Page using the Add Web Parts menu. If you are working in a Web Part Page in shared view, the customizations you apply to Web Parts are seen by all users. If you switch from shared view to personal view, your modifications are only seen by you. WSS is smart enough to store the shared customization data and private personalization data separately in the content database.
You must be a site owner or have Web designer permissions to modify a Web Part Page in shared view. When a Web Part Page is generated for a user that is neither the site owner nor a Web designer, the page does not provide the ability to switch over to a shared view. Instead, the page only provides a Modify My Page menu. However, the user can still enable the Design this Page option and, consequently, add and customize Web Parts. Any modifications made by the user will be stored as personalized data as opposed to shared data.
A Web Part Page is laid out in terms of Web Part Zones as shown in figure 13. A Web Part is added to a Web Part Page by being placed within a Web Part Zone. WSS allows a site owner or Web designer to create new Web Part Pages using a pre-provided set of templates. With the browser, you can use one of these Web Part Page templates to create new Web Part Page with a pre-defined layout of zones. If you use Microsoft Office FrontPage 2003 to create and design Web Part Pages, you have even more flexibility. That's because you can add, remove and reposition zones on a Web Part Page using the FrontPage page designer.
Figure 13: The SharePoint handler object retrieves data from the content database to assemble and render a Web Part Page.
WSS provide a rendering engine for Web Part Pages by leveraging and extending the underlying ASP.NET infrastructure. WSS routes each Web Part Page request to a custom ASP.NET handler object created from the SharePointHandler class. This handler class is defined inside the Microsoft.SharePoint.dll assembly within the Microsoft.SharePoint.ApplicationRuntime namespace.
For each Web Part Page request, the SharePointHandler object is responsible for retrieving all the necessary data from the content database. This includes the Web Part Page document which defines a layout of Web Part Zones. The SharePointHandler object also must retrieve data from other tables within the content database to determine how Web Parts have been customized and personalized within specific zones. WSS provides the optimization of retrieving all the data it needs for a Web Part Page in a single roundtrip to SQL Server.
After retrieving the data associated with a Web Part Page, the SharePointHandler object is responsible for assembling the logic to generate an HTML page to return to the user. The SharePointHandler object creates an object for each Web Part and initializes it with the appropriate customization and personalization data. Finally, the SharePointHandler object enters the rendering phase where it steps through all the Web Part objects in sequence giving them an opportunity to contribute HTML to the output for the page.
Writing a Custom Web Part
With your newfound understanding of Web Part architecture, let's turn our attention to creating custom Web Parts with Visual Studio .NET. To get started with Web Part development, you should begin by downloading and installing the Web Part Templates for Visual Studio .NET. These templates are distributed in an MSI file that can be found at http://msdn.microsoft.com/sharepoint.
After you have installed the Web Part Templates, Visual Studio .NET will provide a new project template for creating a Web Part library DLL. Visual Studio .NET will also provide various other templates for creating files related to Web Part development such as a source file with the starting point for a Web Part class.
You create a Web Part by authoring a class that inherits from the WebPart class defined inside the Microsoft.SharePoint.dll assembly. The WebPart class exists within the Microsoft.SharePoint.WebPartPages namespace. You are required to override methods of the WebPart class to take advantage of many Web Part features. To create the traditional "Hello, World" Web Part class, you simply need to override a single method named RenderWebPart.

using Microsoft.SharePoint.WebPartPages;
using System.Web.UI;

namespace AcmeWebParts {
public class TedsWebPart : WebPart {
protected override
void RenderWebPart(HtmlTextWriter output) {
output.Write("Hello, World");
}
}
}
Figure 14 shows how custom Web Part classes fit into a larger inheritance hierarchy. As you can see, the WebPart class created by Microsoft's WSS team inherits from the Control class created by Microsoft's ASP.NET team. Therefore, a Web Part is really a specialized type of ASP.NET control. If you have experience developing ASP.NET Web applications or server-side controls, many of the programming techniques you already use can be readily applied when developing Web Parts.
Figure 14: A Web Part "IS AN" ASP.NET control.
When it comes to providing to code to render HTML, there's an important difference between developing ASP.NET controls and developing Web Parts. When you author an ASP.NET control, you render HTML by overriding the Render method. When you author a Web Part, you override the RenderWebPart method instead. Why is this?
The Render method defined in WebPart class contains generic code to generate the Web Part's title bar and borders. This is what is known in SharePoint terminology as the chrome around a Web Part. You should not override the Render method provided by the WebPart class because your resulting Web Part class will not render the standard Web Part chrome correctly. Instead, you should override the RenderWebPart method because this allows you to generate HTML that is displayed properly inside the chrome.
The RenderWebPart method provides the same HtmlTextWriter parameter as the Render method. That means you can generate HTML for a Web Part in the RenderWebPart method using the same techniques you use for a custom ASP.NET control in the Render method. For example, you can generate an HTML table by calling the RenderBeginTag method and the RenderEndTag method of the HtmlTextWriter parameter as shown in figure 15.
override void RenderWebPart(ByVal output As HtmlTextWriter) {

// create HTML table with custom attributes
output.AddAttribute(HtmlTextWriterAttribute.Cellpadding, "5");
output.AddAttribute(HtmlTextWriterAttribute.Border, "2");
output.RenderBeginTag(HtmlTextWriterTag.Table);

// create new row
output.RenderBeginTag(HtmlTextWriterTag.Tr);

// create new cell
output.RenderBeginTag(HtmlTextWriterTag.Td);
output.Write("Name:");
output.RenderEndTag(); //

// create new cell
output.RenderBeginTag(HtmlTextWriterTag.Td);
output.Write("Bob Smith");
output.RenderEndTag(); //

output.RenderEndTag(); //
output.RenderEndTag(); //
}
Figure 15: You use the HtmlTextWriter parameter within the RenderWebPart method to generate the HTML for a Web Part.
A Web Part, like other ASP.NET controls, can be designed to be a composite control containing child controls. If you leverage familiar ASP.NET server-side controls when developing custom Web Parts, you can create detailed views and polished data entry screens without getting bogged down in the details of generating DHTML and JavaScript. For example, you can create sophisticated-looking Web Parts in a hurry using ASP.NET controls such as the DataGrid control, the Calendar control and the ASP.NET validation controls.
You must override the CreateChildControls method to create a custom Web Part with child controls. Your implementation of CreateChildControls should create and initialize child control objects and then add them to the Web Part object's Controls collection. A simple example of creating a TextBox object and a Button object is shown in the class definition for JasonsWebPart in figure 16.
public class JasonsWebPart : WebPart {

// fields to hold child controls
protected TextBox txtName;
protected Button btnSubmit;

// create child control
protected override void CreateChildControls() {
txtName = new TextBox();
this.Controls.Add(txtName);
btnSubmit = new Button();
btnSubmit.Text = "Submit Name";
this.Controls.Add(btnSubmit);
}

// render HTML for Web Part
protected override
void RenderWebPart(ByVal output As HtmlTextWriter) {
txtName.RenderControl(output);
output.RenderBeginTag(HtmlTextWriterTag.Br);
btnSummit.RenderControl(output);
}
}
Figure 16: A custom Web Part class can create child ASP.NET controls.
Examine the implementation of the RenderWebPart method in the class JasonsWebPart and see how it calls the RenderControl method on each child control. When you call RenderControl on a child control and pass it the HtmlTextWriter parameter, the child control responds by writing its HTML into the output stream that will be returned to the user. This example illustrates how a Web Part's implementation of the RenderWebPart method is written to combine the HTML output of all the child controls into a single HTML element.
Web Part Customization and Personalization
One of the most powerful aspects of Microsoft's Web Part technology is its ability to track customization and personalization data. And while this feature is powerful, it's relatively easy to implement from the perspective of a Web Part developer. You simply add properties to a Web Part class and mark these properties with special attributes that have been defined by the WSS team. This strategy represents a great example of the power of declarative programming made possible by the .NET Framework. You are not required to write any code for storing or retrieving either customization data or personalization data. All this is handled by WSS behind the scenes.
Imagine a scenario where you are required to develop a custom Web Part that displays the user's local weather report. However, different users live in different locations. Therefore, your Web Part must be designed to track a personalized zip code for each user. You can design a Web part to track personalized zip codes by defining a ZipCode property with a special set of attributes provided by the WSS team at Microsoft. It's the presence of these attributes in your compiled code that tell WSS how you would like the property value to be customized and/or personalized.
Examine the WeatherReportWebPart class definition of the class in figure 17. This Web Part class defines a public ZipCode property together with a protected _ZipCode field to track the required personalization data. The ZipCode property definition contains the WebPartStorage attribute which has been parameterized for personal storage. The presence of the WebPartStorage attribute instructs WSS to automatically store and retrieve personalization data for this property.
[ XmlRoot(Namespace="AcmeWebParts") ]
public class WeatherReportWebPart : WebPart {

[ // Web Part property attributes
WebPartStorage(Storage.Personal),
DefaultValue(""),
Browsable(true),
FriendlyName("Zip Code"),
Category("User Info")
]
public string ZipCode {
get {
return _ZipCode;
}
set {
_ZipCode = value;
}
}

// field used as backing store for ZipCode property
protected string _ZipCode = string.Empty;

}
Figure 17: Web Part properties are defined with attributes that control how WSS persists its customization and personalization settings.
When the SharePointHandler object initializes a Web Part object from the WeatherReportWebPart class, it checks to see if there is any customization or personalization data for the Web Part in the content database. If WSS finds a pre-existing ZipCode property value, it assigns this value to the ZipCode property while it is initializing the Web Part object. Since the ZipCode property's set block assigns the personalized value to the _ZipCode field, the user's zip code is available to all other methods in the WeatherReportWebPart class throughout the lifetime of the Web Part object. This example demonstrates a common technique where a protected field is used to provide a backing store for the public property value.
When you define a persistent property like ZipCode in a Web Part class, how does a user actually customize or personalize its setting? This is easy because WSS automatically supplies user interface elements that allow users to customize or personalize property settings. When a user runs a menu command on a Web Part Page to modify a Web Part, WSS displays a Task Pane containing Tool Parts on the right-hand side of the browser window.
A Tool Part is a WSS user interface element that allows a user to examine and modify Web Part property values in the Task Pane. When in shared view, a Tool Part allows the user to work with customized values. When in personal view, a Tool Part allows the user to work with personalized values.
WSS provides standard Tool Parts that allow users to inspect and modify Web Part properties. If you don't like the generic user interface elements created by these standard Tool Parts, WSS makes it possible for you to create your own. If you choose to create a custom Tool Part, you can take over control of how the user interface is generated when a user wants to customize or personalize your custom Web Part properties. Authoring a Tool Part is similar to authoring a Web Part because you can build it as a composite control containing child ASP.NET controls.
You have just seen how Web Parts track customization data and personalization data. This is a feature that makes Web Part technology valuable to you as a software developer. Your sites can be customized and personalized by different users in different ways. All the while, you never have to write any code to manage user membership nor do you have to write any code to store and retrieve property values inside the content database. WSS does all this for you so you can spend more time writing other aspects of a Web Part such as your business logic.
Taking Advantage of Other Web Part Development Features
When you are writing code for a Web Part, you might want to program against the WSS object model to access the data for a list or a document library. You might also want to create a custom Web Part that allows a user to inspect or configure the various security settings for a site. However, it doesn’t usually make sense to use the GlobalAdmin object as the entry point into the WSS object model as was shown earlier. Instead, you should acquire an entry point using the SPControl class.
The SPControl class provides two static methods named GetContextSite and GetContextWeb. These two methods allow you to hook into the WSS object model within the context of the current request. The GetContextSite method returns an object that represents the current site collection. The GetContextWeb method returns an object that represents the current site. Both methods require you to pass the ASP.NET HttpContext object associated with the current request. Here’s an example of using the GetContextWeb method from within a custom Web Part to enumerate through the lists of the current site.

SPWeb CurrentSite = SPControl.GetContextWeb(this.Context);

// enumerate through the site’s lists
foreach(SPList List in CurrentSite.Lists) {
this.ListBox1.Items.Add(List.Title);
}
Another important aspect of developing Web Parts involves communicating across the network with Web services and other back-end systems. Web Part are often used to give SPS portal sites and standard WSS sites the ability to acts as gateways into an enterprise-level applications. Microsoft and other companies have already built Web Parts that act as adapters into popular line-of-business applications such as such as BizTalk, SAP and PeopleSoft. You can follow suit and build custom Web Parts that will allow your company's users to access any of your back-end systems.
Web Parts that are written to communicate with Web services and line-of-business applications typically require a set of security credentials to make the initial connection. Given this common requirement, SPS was designed with a Single Sign-On (SSO) service for storing and retrieving security credentials. The SSO service can cache security credentials on a user-by-user basis. It can alternatively store a common set of security credentials used by all the members of an Active Directory group. The SSO service does the work required to track the Windows security ID (SID) of current user when storing or retrieving a set of security credentials from the SSO database. The SSO service also employs the necessary encryption so that security credentials are never stored in the SSO database as clear text.
The Web Part infrastructure supports a feature known as Web Part connections. Web Part connections represent an extensible customization model where two or more Web Parts can be connected together in a provider/consumer relationship. A user can establish a connection between Web Parts using either the browser or Microsoft Office FrontPage 2003. This makes it possible to create Web Part Pages that display sophisticated views of data with master/detail relationships and parent/child relationships. As a developer, you create connectable Web Parts by implementing standard interfaces defined by the WSS team at Microsoft.
The WSS infrastructure for connecting Web Part is based on a loosely-coupled model. That means two Web Part do not require knowledge of each other to be connected together on a page. The loosely-coupled nature of this model provides the flexibility to connect Web Part created by different companies and different development teams. For example, you can create your own custom Web Parts and connect them to standard Web Parts that are distributed by teams within Microsoft.
Web Part Deployment and Distribution
You can deploy a Web Part library DLL on a Web server in one of two different places. First, you can deploy a Web Part library DLL inside a virtual server's \bin directory just like you would deploy assembly DLLs for a standard ASP.NET application. Secondly, you can deploy a Web Part library DLL in the Global Assembly Cache (GAC). A Web Part library DLL in the GAC can be loaded into any virtual server on the hosting Web server machine.
While you are developing and testing Web Parts, it's convenient to configure your Web Part library project to compile its output DLL directly into the \bin directory of the virtual server you will be using for your testing. With this approach, you can instantly test your Web Parts using the browser after you recompile the Web Part library project.
The fact that Web Part Pages are stored inside the content database poses a security risk. Imagine a scenario where some malicious individual is able to access the content database and modify the table that holds all the Web Part Page documents. What would happen if this malicious individual attempted to mount an attack by placing in-line code within the body of the Web Part Page? You should be able to see the potential problem here. Fortunately, WSS can defend itself against this kind of attack.
WSS protects itself by processing Web Part Pages in safe mode. When the SharePointHandler object processes the request for a Web Part Page, it will never execute any in-line code it finds within the body of the page. Furthermore, the SharePointHandler object will only load Web Parts and ASP.NET controls that have been explicitly configured as a safe control. You can configure Web Parts and ASP.NET controls using the section of the hosting virtual server's web.config file.
You will experience an error whenever you run a Web Part Page that attempts to load a Web Part or an ASP.NET control that has not been properly configured as a safe control. Clearly, there must be a set of standard Web Part and ASP.NET controls that WSS marks as safe by default. Whenever you extend a virtual server with WSS, the web.config file that is automatically copied to the root directory contains a element that includes a set of Microsoft's standard Web Parts and ASP.NET server-side controls.
When you deploy a custom Web Part library DLL onto a front-end Web server running WSS, you must modify the web.config file for each virtual server where you plan to run these Web Parts. The element of the web.config file should be modified to include a new element that look like this.





Namespace="AcmeWebParts"
TypeName="*"
Safe="True" />



Note that the preceding example of a element identifies an assembly using its friendly name (e.g. AcmeWebParts). When you deploy a strongly-named assembly DLL, you should not use the simple friendly name. Instead, you should use the fully-qualified, four-part assembly name. You will always be required to use the fully-qualified, four-part assembly name when you have deployed a Web Part library DLL in the GAC. That's because the GAC only allows strongly-named assembly DLLs.
The security layer provided by the Web Part architecture goes beyond requiring that Web Parts and ASP.NET controls are configured as safe controls. A Web Part library DLL running inside the \bin directory is further restricted in what actions it can perform by the element defined within the web.config file.







The element contains the level attribute. The value of the level attribute configures Code Access Security (CAS) permissions that restrict Web Part library DLLs from performing potentially dangerous actions such as connecting to a SQL Server database and accessing the local file system. The element's level attribute is set to WSS_Minimal by default which severely restricts what a Web Part library can do. This default setting often makes it hard or impossible to test and debug custom Web Parts during the development cycle.
You can adjust the elements level attribute setting to WSS_Medium to relax the CAS restrictions. A setting of WSS_Medium usually allows you to test and debug Web Part without security-related problems. In occasional scenarios you might have to adjust the trust level setting to a value of Full to completely disable all CAS-related security restrictions. Note that you should run the IISRESET.EXE command to restart after adjusting the element's level attribute setting inside a web.config file.
Keep in mind that a element's level attribute setting in a web.config file only affects Web Part library DLLs running within the \bin directory. It does affect Web Part library DLLs that have been installed in the GAC. Web Part library DLLs in the GAC are considered to be fully trusted and always run without any CAS restrictions. This can be a factor that influences your decision whether to deploy a Web Part library DLL in the \bin directory of the GAC.
Importing Web Parts
The final aspect Web Part deployment centers around importing description information about the Web Part into a Web Part gallery. WSS supports Web Part galleries at site collection level as well as the virtual server level. However, before you can import a Web Part's description information into a Web Part gallery, you must first create a Web Part description file.
A Web Part description file is an XML file with a .dwp extension. An example of a Web Part description file is shown in figure 18. The Title and Description elements provide friendly text that is displayed to Web Part consumers as they are browsing through the list of Web Parts that can be added to a Web Part Page. The Assembly and TypeName elements provide WSS with the information it needs to load the associated Web Part class at runtime. Remember to use the fully-qualified, four-part assembly name when creating a .dwp file for a Web Part library DLL with a strong name.





AcmeWebParts
AcmeWebParts.WeatherReportWebPart


98052


Figure 18: A Web Part description file is used to import a Web Part into a Web Part gallery.
A .dwp file can optionally contain initialization values for one or more Web Part properties. The .dwp file in figure 17 shows how to use a custom element to provide an initial default value for the Web Part's ZipCode property. The default zip code that's being used in this example is 98052 which is the zip code for Redmond, WA. That means that this Web Part will initially show the weather report for the Microsoft Campus after being placed on a Web Part Page. However, this initial ZipCode property value will be overwritten once it has been customized or personalized by a user.
Once you have created the Web Part description file, you can import the associated Web Part into WSS and use it on a Web Part Page. The simplest way to import a Web Part is choose the Import command from the Add Web Part menu while customizing or personalizing a Web Part Page within the browser. The Add Web Parts menu is available as a sub menu on the Modify Shared Page menu and the Modify My Page menu in the upper right-hand corner of the browser window.
You can also import a Web Part description file into the Web Part gallery of a site collection to make it available to all sites within that site collection. To do this, navigate to the Top-Level Site Administration page and scroll down to the Site Collection Galleries section. Next, click the link with the caption Manage Web Part Gallery. That will bring you to the site collection's Web Part Gallery page. This page provides the option of importing .dwp files.
In addition to importing a Web Part at the site collection level, you can also import a Web Part into the Web Part Gallery for a virtual server. However, the process for doing this is more complex because you must first build a Web Part Package. Once you have built the Web Part Package, you can install it using the STSADM.EXE administration tool.
A Web Part Package is a CAB file that contains a Web Part library DLL and all its associated .dwp files. You can easily build a Web Part Package with Visual Studio .NET by creating a new CAB project. When you create a Web Part Package, you must add a special header file named manifest.xml. The manifest.xml file is required because it contains essential deployment information that WSS needs to properly install and configure a Web Part library DLL.
An example of a manifest.xml file is shown in figure 19. As you can see, the manifest.xml file contains the file name of the Web Part library DLL and a list of .dwp files. It isn't necessary to add the fully-qualified, four-part assembly name of a Web part library DLL to a manifest.xml file. That's because STSADM.EXE administration utility is able to discover the assembly name at runtime when it loads the Web Part library DLL.















Figure 19: Each Web part package must include a manifest.xml file
Once you have built a Web Part Package that contains a manifest.xml file, the Web part library DLL and all the associated .dwp files, you can then install it using the STSADM.EXE administration tool. For example, if you have built a Web Part Package named AcmeWebPartsPack.cab, you can install it using the following command-line instruction.

STSADM.EXE -o AddWPPack -filename AcmeWebPartsPack.cab
When you run this command, WSS copies the Web Part library DLL into the \bin directory each virtual server within the current WSS deployment. You can add the -url parameter to the preceding command-line instruction if you would like to install the Web Part library into only one of the virtual servers within the current WSS deployment.
When you install a Web Part Package with the STSADM.EXE utility, WSS provides the convenience of adding the required elements to web.config files to configure each Web Part being installed as a safe control. This maintenance feature certainly eases large-scale deployment when you are rolling a new Web Part library DLL out into a Web farm environment.
When installing a Web Part Package with the STSADM.EXE utility, you have the option of installing Web Part library DLLs in the GAC. This can be accomplished by using the -globalInstall parameter.

STSADM.EXE -o AddWPPack -filename AcmeWebPartsPack.cab -globalInstall
Using this technique makes it possible to install a Web Part library DLL only once per machine no matter how many virtual servers use it. Also remember that Web Part library DLLs installed in the GAC are not restricted by the trust level defined inside the web.config file. Therefore, you should not install Web Part library DLLs into the GAC casually. You should only install a Web Part library DLL in the GAC when you know it has come from a trusted source and that it poses no security risk at all.
Summary
This whitepaper has provided an in-depth examination into the architecture of SharePoint products and technologies. WSS and SPS are two separate products that have been designed to work well together. WSS provides the foundation for creating collaborative Web site that support customization and personalization. SPS compliments WSS by playing the role of a content aggregator. You have also seen that SPS is fully dependant upon the underlying infrastructure of WSS. The more you know about WSS, the easier it will be to master SPS.
In one sense, SharePoint products and technologies lessen the need for custom software development. That's because WSS and SPS provide so much functionality right out of the box. However, WSS and SPS also provide valuable opportunities to write custom applications and Web Parts. This article has given you a roadmap to get started in the world of SharePoint development.

About the authors
Ted Pattison is a published author and an industry-leading trainer and consultant who specializes in building portal applications and collaborative solutions with SharePoint Products and Technologies. Ted has been recognized by Microsoft as an MVP with Windows SharePoint Services and Microsoft Office Portal Server 2003. He has delivered his advanced SharePoint training over 25 times since September of 2003 and has taught and consulted with developers and system administrators from companies such as Microsoft, Intel, Countrywide, Morgan Stanley, Mattel and Viacom. Ted is also a best-selling author of books focused on developing for the Windows platform and a columnist with MSDN Magazine. For more information, go to http://www.TedPattison.net.