Chapter 2
Introduction to the SharePoint Object Model

IN THIS CHAPTER

• First Look at the Object Model
• Development Scenarios and Sample Applications
• Setting Up Your Development Environment
• Creating Your First Object Model Application
• Deploying Your Application

Quite possibly one of the most important facts to remember about Microsoft Office SharePoint Server (MOSS) is that it is an application framework as much as it is an application on its own. As a result, both Windows SharePoint Services (WSS) and MOSS expose a rich and powerful managed application programming interface (API).

This chapter introduces you to the object model exposed by this API, shows you how to set up your development environment for working with this object model, and walks you through creating your first application targeting the SharePoint object model. You need a version of Visual Studio 2005 and network connectivity to a SharePoint server (either physical or on a Virtual PC) to compile and execute the code in this chapter and all subsequent chapters in the portion of the book dealing with the SharePoint object model.

First Look at the Object Model

SharePoint itself is functionally segmented by Windows SharePoint Services and Microsoft Office SharePoint Server. Within each of these separate but complementary products there are several namespaces that house the object model with which you’ll be working. MOSS is responsible for such things as farm-enabled search, Excel Services, the Business Data Catalog, Single Sign-On, and other centralized portal-style activities. Virtually all activity that takes place within the context of a team site (regardless of template) is the purview of WSS. WSS is technically part of Windows Server 2003 R2, whereas MOSS is a product that installs on top of that to add additional enterprise portal functionality. The Microsoft.Office.Server namespace is the root namespace of all Office Server objects and Microsoft.SharePoint is the root namespace for all WSS objects.

Figure 2.1 illustrates some of the key classes contained in each of these namespaces, as well as to which functional area they belong. The namespace of each group of classes is shown in parentheses next to the functional area. For example, all list-related functionality is handled within the Microsoft.SharePoint namespace.

Figure 2.1. Illustration of key classes in the SharePoint object model, segmented by functional area.

Don’t worry if you haven’t seen any of these class names before—the next several chapters in the book are devoted entirely to the functional areas shown in Figure 2.1. By the time you are done with these chapters, all this will have become second nature to you. The following is a list of the functional areas of the object model that are covered in the upcoming chapters:

• Features and Solutions—As you will see in Chapter 3, “Programming with Features and Solutions,” Features and Solutions allow you to create small, deployable packages of functionality that can be reused among multiple sites and site templates.
• Site administration and enumeration—Chapter 4, “Working with Sites and Webs,” shows you how to iterate through site collection hierarchies, create and edit existing sites, and manipulate site collections.
• List management—Of all the tasks a programmer can do with SharePoint, working with lists is probably the one most commonly performed task. It is so common, in fact, that there are three chapters (5, 6, and 7) dedicated to working with lists and handling list events.
• Document libraries—Document libraries are a special type of list designed to store documents. Chapter 8, “Working with Document Libraries and Files,” shows you how to work with document libraries, picture libraries, and files in general using the SharePoint object model.
• Meetings—Meeting workspaces are a special type of team collaboration site. Chapter 9, “Working with Meetings,” shows you how to programmatically manipulate meetings and meeting workspaces.
• Business Data Catalog—The Business Data Catalog is an extremely powerful and important new feature of MOSS 2007. Chapter 10, “Integrating Business Data,” shows you how to integrate enterprise data into SharePoint, and Chapter 11, “Creating Business Data Applications,” shows you how to create applications designed to expose their business data to SharePoint.
• User profiles—Chapter 12, “Working with User Profiles,” provides a detailed discussion of how to work with user profiles using the SharePoint API.

Development Scenarios and Sample Applications

Now that you have a general idea of what the object model looks like and how it is divided, you might be wondering why you would be using the object model instead of web services and what kinds of applications you might be able to create using the object model.

Developing Applications on the Server

You will see it stated over and over again throughout this book that SharePoint is much more than just an application, it is an application framework. That essentially means that SharePoint doesn’t truly shine until you begin extending its reach and influence and integrating it with other applications and solutions.

To use the SharePoint API, your code must reside on one of the machines in a SharePoint application server farm. Your code can still work with other sites in the farm from any other site in the farm, but you cannot, for example, work with the SharePoint API from a machine on which MOSS or WSS is not installed.

Because of the fact that SharePoint runs on Windows Server 2003 and is frequently deployed in a data center environment, applications written to run on SharePoint servers are almost always administrative in nature. It is a rare case when a user will find reason to be logged on to the console of a Windows Server 2003 machine to interact with a SharePoint API application for a nonadministrative purpose.

Some examples of tools that can be written using the SharePoint API that reside directly on SharePoint servers might include data migration applications, applications that operate on batches of information, scheduled maintenance applications, or even system monitoring tools that examine specific aspects of a large installation or farm.

Developing Web Parts

Another reason you might find yourself creating code that utilizes the SharePoint object model is if you are creating Web Parts. Web Parts are componentized, self-contained packages of user interface that can be dropped into place on SharePoint Web Part pages to provide discrete sets of functionality to users. Later in the book, an entire section is devoted to programming Web Parts. Unless the Web Part you are creating will be working entirely with information not contained within SharePoint, you will need to be familiar with the SharePoint API to create it. Later chapters in this book provide in-depth coverage of Web Part programming.

Developing Remote Applications

The other extremely common usage scenario for SharePoint is to consume SharePoint data and functionality remotely from a client application running outside the SharePoint farm. This can be done for any number of reasons such as storing lists on SharePoint that provide data for a public-facing ASP.NET application, creating a Windows Forms application for a technical support help desk that consumes data from a SharePoint site created with a Help Desk site template, or any of hundreds of other possibilities.

The only practical way to consume SharePoint data and functionality from a remote client is to use the SharePoint web services. These web services are discussed in chapters 20 through 30. Despite the rich functionality provided by the web services, you might still want to expose specific SharePoint functionality contained in the object model in your own custom web service so that clients can consume your custom service instead of the stock services that ship with SharePoint. The object model is not designed to support Remoting. If you need to expose a portion of the object model that you can’t easily access with one of the stock web services, you should create your own web service rather than attempting to use Remoting.

Setting Up Your Development Environment

Making sure you have a good development environment is essential to your ability to write easy-to-maintain, reliable, stable code for SharePoint.

The first tool you will need is Visual Studio 2005. If you are an MSDN subscriber, you should have access to multiple versions of Visual Studio 2005. If you don’t have access to any of the licensed versions of Visual Studio 2005 but you are still interested in writing SharePoint code, you can download Visual C# 2005 Express Edition for free from http://msdn.microsoft.com/vstudio/express/visualcsharp/download/.

After installing Visual Studio 2005 (or Visual C# 2005 Express Edition), you should be able to use Visual Studio to create standard Windows Forms and console applications.

SharePoint 2007 also makes extensive use of the Windows Workflow Foundation, which is part of the .NET Framework 3.0. If you want to whet your appetite for workflow programming, you can also download the .NET Framework 3.0 runtime components and the Visual Studio 2005 extensions for the Windows Workflow Foundation.

You have an option of installing your development environment directly on the SharePoint server or setting up the development environment on another workstation. There are pros and cons to each option that are discussed in their respective forthcoming sections.

Setting Up a Local Development Environment

The biggest advantage to the local development environment is the debugger. With Visual Studio 2005 installed directly on the Windows Server 2003 machine, it becomes extremely easy to write the code, build the code, and debug the code all in a single sweep without having to do any painstaking deployment.

Unfortunately, as programmers, we often find ourselves on the other side of Information Technology (IT) and/or security restrictions that prevent us from running compilers and other development tools on servers. It is for this reason that developers will often have their own Windows Server 2003 installations that are rough approximations of the target environment so that they can have the benefits of coding locally without running the risk of damaging a live production server.

Caution

Even if there are no IT restrictions or security policy restrictions in place telling you not to run Visual Studio 2005 on a live SharePoint server, pragmatism and some good common sense should tell you to avoid this scenario whenever possible. If the cost of using multiple servers for development and production is prohibitive, consider using Virtual PCs or Virtual Servers as development environments and keep production environments pristine.

After Visual Studio 2005 is installed, you need to be able to create applications that reference the appropriate SharePoint Assemblies.

Open Visual Studio and create a new console application called LocalDevelopmentSample. You can put it anywhere you want, but Visual Studio defaults to creating a new solution in your My  DocumentsVisual  StudioProjects folder.

Right-click the project and select Add Reference. Click the Browse tab and select the following directory:

C:program  filescommon  filesmicrosoft  sharedweb  server  extensions12isapi

Obviously, if you installed your copy of SharePoint in an alternate location or on a different disk/partition, this path will be slightly different for you.

Figure 2.2 shows the Add Reference dialog box pointing at this directory.

Figure 2.2. Adding a reference to a SharePoint Assembly.

Select the Microsoft.SharePoint.dll Assembly and add a reference to it. Make sure that the Copy  Local property is set to true (you do not want your application referencing the actual Assemblies used by the server).

At this point, you can skip to the “Creating Your First Object Model Application” section if you plan on developing locally with both Visual Studio and SharePoint in the same environment, or you can continue reading the next section, “Setting Up a Remote Development Environment.”

Setting Up a Remote Development Environment

A remote development environment, at least as far as SharePoint development is concerned, is a development environment that is not on a SharePoint server. The question, then, is how do you add a reference to the SharePoint Assemblies if your copy of Visual Studio 2005 isn’t on the SharePoint server?

The answer is simple: cheat. Well, maybe it’s not quite cheating, but it sounds more exciting than copy the files. You cannot run or test your application in your development environment, so you only need the bare minimum that will get your code to compile. To do that, you just copy the Assemblies from the following directory to a safe location somewhere on your development machine:

[drive]:program  filescommon  filesmicrosoft  shared
web  server  extensions12isapi

For this example, just copy the Microsoft.SharePoint.dll Assembly. As you progress through this section, you will learn which Assemblies are required for the various functional areas of the object model. After the file has been copied from your server, you can add a reference to it from your remote development machine, as shown in Figure 2.3.

Figure 2.3. Adding a reference to a SharePoint Assembly on a Windows XP development machine.

Now that you have a reference to a SharePoint Assembly in your application, you’re ready to write some code.

Creating Your First Object Model Application

The first thing that your code needs to do is establish site context. The site context is the link between your code and the SharePoint site collection hierarchy. This context is represented by the SPContext class. This class is the doorway through which all of your code must step to do anything with the SharePoint object model.

Establishing site context is done differently between Web Parts and console/WinForms applications. You will see how to establish site context in the upcoming Web Parts programming chapters (Chapters 14 through 19), so what is shown here is how to establish site context in a console or Windows Forms application (this also applies to a Windows Presentation Foundation application).

Add a few lines of code so that your Program.cs file contains the code shown in Listing 2.1. Throughout the book, you may see references to the server names of the lab environment of the authors (such as win2k3r2lab). As you enter the code for samples throughout the book, please change the name of the server and other relative URLs to match those of your development environment.

Listing 2.1. Program.cs to Test SharePoint Assembly Reference

The SPSite constructor used in the preceding code obtains a reference to the site collection contained at the given uniform resource locator (URL). You can access the web application to which a given site collection belongs using the WebApplication property, which is of type Microsoft.SharePoint.Administration.SPWebApplication.

If you are running your development environment directly on the SharePoint server, you can simply press F5 on your keyboard to run your application; you should see output similar to the following text (the URL of your server will probably be different than win2k3r2lab):

Root  collection  found  at  Url
http://win2k3r2lab  is  part  of  Web  Application  SharePoint  (80)

SharePoint  (80) is the default name of the web application that was created during the standalone (no farm) installation on that particular server.

If your code resides on a remote server, you’ll need to deploy your application before you can test it.

Deploying Your Application

For a Windows Forms or console application, deploying your application follows the standard deployment methods available to all .NET Framework applications. You can simply copy the application and its dependencies (you don’t need to copy the SharePoint dynamic link libraries [DLLs]) or you can create a ClickOnce deployment package.

Figure 2.4 shows one possible deployment progression from your development workstation to production that involves a separate build machine that might be the target of automated nightly builds. In addition, there is a staging machine, on which a QA team might perform testing against the most recent build, and a production machine, which is the target of the final, verified deployment.

Figure 2.4. Large deployment scenario involving both build and stage environments.

Figures 2.5 and 2.6 show progressively smaller deployment chains. Going directly from the development machine to production, as shown in Figure 2.6, is not recommended. The complex, highly integrated nature of SharePoint practically demands integration testing of every application or component deployed to a SharePoint server.

Figure 2.5. Deployment scenario involving a combined build/development machine and a staging server.

Figure 2.6. Impractical scenario involving deploying to production directly from a developer workstation.

Summary

The SharePoint API gives developers the ability to control virtually every aspect of SharePoint through managed code. It is an extensive object model that covers a wide variety of functionality from Features and Solutions to site administration and user profile management. The next several chapters provide you with in-depth coverage of these functional areas. Using the information in this chapter and your new SharePoint development environment, you should be able to follow along with the samples and start mastering the SharePoint API.