Development Tools and Techniques for Working with Code in Windows SharePoint Services 3.0 (Part 1 of 2)

Summary: Learn the skills you need to develop for Windows SharePoint Services 3.0, about the differences from traditional ASP.NET development, about the required development environment, and the steps to build a Windows SharePoint Services solution with Visual Studio 2005 Extensions for Windows SharePoint Services 3.0. This article is part 1 of 2. (33 printed pages)

Patrick Tisseghem, U2U

June 2007

Applies to: Windows SharePoint Services 3.0, Visual Studio 2005 Extensions for Windows SharePoint Services 3.0

Contents

  • Introduction to Developing with Windows SharePoint Services Technology

  • Required Development Skills

  • ASP.NET Applications vs. SharePoint Sites

  • What You Develop for Windows SharePoint Services

  • The Development Environment

  • Visual Studio 2005 Extensions for Windows SharePoint Services 3.0

  • A Closer Look at Windows SharePoint Services Solutions

  • About the Author

  • Additional Resources

Introduction to Developing with Windows SharePoint Services Technology

Many developers are eager to leverage Windows SharePoint Services 3.0 as a development platform for increasing collaboration and building document management solutions for information workers. This article provides insight into the skills you need to develop for Windows SharePoint Services, the differences from traditional ASP.NET development, the development environment that is required, and the steps you must take to build a Windows SharePoint Services solution with Visual Studio 2005 Extensions for Windows SharePoint Services 3.0. The second part of the article explores the concept of Windows SharePoint Services solutions, addressing the architecture of a solution, and the techniques for creating, deploying, maintaining, and upgrading Windows SharePoint Services solutions. This article also includes walkthroughs that show the different approaches developers and administrators can take.

We start by understanding what SharePoint development actually entails before discussing the different techniques for building, packaging, deploying, and maintaining Windows SharePoint Services solutions.

Required Development Skills

People often ask what it takes to be a skilled SharePoint developer, and are surprised to discover that the developer must master many skills.

Following is the list of areas in which to gain expertise that we have identified as being helpful when starting with SharePoint development.

ASP.NET 2.0

The latest version of Windows SharePoint Services and Microsoft Office SharePoint Server (MOSS) 2007 rely completely on Microsoft ASP.NET 2.0 as the foundation. Therefore, being skilled in ASP.NET 2.0 concepts, terminologies, and development is the top priority for a Windows SharePoint Services developer. In addition to understanding the flow of an ASP.NET request, its different stages, and its internal architecture and extensibility options, a developer must be experienced in developing and using master pages, content pages, ASP.NET server and user controls, templates in ASP.NET, ASP.NET Web Parts and their infrastructure, and the ASP.NET provider model. (Many resources are available to you if you need to come up to speed in any of these areas, however, these are beyond the scope of this article.)

Windows Workflow Foundation

When working on Windows SharePoint Services solutions for information workers, you often must build custom workflows. The built-in workflows that are delivered with MOSS 2007 answer—to a certain extent—the demands of the business, but developers are often asked to build custom workflows using the extensions for both Windows Workflow Foundation (WF) and the project templates for building SharePoint-specific workflows. To succeed, the developer needs a good understanding of WF, including the process of building the workflow, building custom activities, interacting with the SharePoint environment within the workflow, and more.

XML Technologies

Windows SharePoint Services technologies rely heavily on XML technologies. These are the foundation for the many schema definitions that drive the provisioning engine. There are schema definitions for sites, lists, document libraries, fields, content types, and more. The Collaborative Application Markup Language (CAML) is used in most of these schema definitions. In addition, developers must also know about the related XML technologies such as XSLT and XPath because in their development on Windows SharePoint Services, they will encounter those technologies as well.

Windows SharePoint Services 3.0 and MOSS 2007 APIs

A Windows SharePoint Services developer must understand the APIs that are exposed by both Windows SharePoint Services 3.0 and MOSS 2007. Building solutions with Windows SharePoint Services requires a deep understanding of many of the classes that are exposed within the object models. In addition, if the applications target smart clients working remotely with SharePoint technologies, knowledge of the XML Web services delivered with Windows SharePoint Services and MOSS is also necessary.

Finally, all of the solutions must be deployed and made available within the SharePoint server farm scoped to a certain level (for example, a site collection). You must understand how to package the different components that make up a solution, and how to install and activate the features that make the solutions available on new and existing sites. This article provides more information and guidelines on how to do this.

ASP.NET Applications vs. SharePoint Sites

Windows SharePoint Services development and traditional ASP.NET development differ in many ways. To help you understand the differences, we can compare ASP.NET applications with Windows SharePoint Services applications.

Figure 1 displays the different components and the interaction flow of a mainstream ASP.NET application.

Figure 1. Components and flow of a mainstream ASP.NET application

Users send requests to the server running Internet Information Services (IIS) for specific resources. These requests are accepted by IIS and delegated to an ISAPI extension DLL for further processing. Typically, resources are retrieved from the file system, such as .config files, .aspx pages, cascading style sheets, custom-built .NET assemblies, and user controls. All of these can act on the final response that is delivered to the user in his or her browser. In many applications, an interaction with a data store is also needed to store and retrieve data that is used to process the request and generate the response.

So, what is different when we compare Figure 1 with Figure 2, which represents the components and flow for a site based on Windows SharePoint Services?

Figure 2. Components and flow of a Windows SharePoint Services site

As you can see in Figure 2, Windows SharePoint Services abstracts developers from many of the details of hosting highly scalable, template-driven sites. In many cases, SharePoint administrators and experienced users do not even touch that low-level infrastructure. However, an understanding of it is helpful.

Windows SharePoint Services is a site-provisioning engine that relies heavily on schema definitions for templates of many types of artifacts that are important to its environment. There are definitions for site templates; for infrastructure pages such as the default.aspx, which make up the home page of a team site; for lists and libraries; and for helper pages that enable the interaction among the content that is stored in these different containers.

When starting a request for a Windows SharePoint Services page, there is interaction with the configuration database and the content database that retrieves the details of the request. This includes accessing the many XML files that contain the schema definitions, and accessing building blocks (Web Parts) that each have to execute their code that is encapsulated in a .NET assembly made available via either the global assembly cache or the local bin folder. The Windows SharePoint Services provisioning engine joins all these processes.

When we look at the traditional ASP.NET application again, what happens there if you need more than one application, maybe two, five, or even dozens? Figure 1 starts to look complex because there the same infrastructure is repeated for each additional application. Developers following the best practices and patterns can produce many re-usable building blocks, but much of the infrastructure must still be re-created each time.

By comparison, many Windows SharePoint Services sites—dozens, hundreds, even thousands of collaboration sites—can be delivered with one common provisioning engine. This is the power of using Windows SharePoint Services compared to using ASP.NET applications.

What You Develop for Windows SharePoint Services

Windows SharePoint Services is a solutions platform, which means that it is extensible and ready to run custom solutions. The following sections discuss the solution types that Windows SharePoint Services developers can build.

Assembly-Based Solutions

We can refer to these solutions as code-based solutions. Assembly-based solutions are developed with managed code (a .NET Framework language such as Microsoft Visual C# or Microsoft Visual Basic 2005) and compiled as a .NET assembly (a DLL). You can build different types of these solutions as well. The following table describes only some of the possible assembly-based solutions.

Table 1. Types of assembly-based solutions

Solution Type

Description

Web Parts

Building blocks for a SharePoint Web Part Page that deliver specific functionality to the visitor of the site. Web Parts can deliver data from stores that are not based on Windows SharePoint Services (such as Microsoft SQL Server and Oracle stores); capture data to drive business processes; aggregate or roll up information that is available in the SharePoint sites, or perform many other functions. Many Web Parts are available by default with both Windows SharePoint Services 3.0 and MOSS 2007.

Event handlers

A .NET assembly containing one or more classes that encapsulate code that is executed when certain events (such as adding an item to a list, creating a column for a document library, deleting a site, and so on) occur in SharePoint sites.

Information management policies

A rich policy framework in MOSS that developers can use to build custom policies that enforce certain behavior for content stored and managed in SharePoint sites.

Workflow Activities and templates

A workflow is a collection of activities Windows SharePoint Services or the information workers involved in the workflow must take. Numerous activities are available; however, you can create custom activities compiled in a .NET assembly and deploy them so that experienced users creating workflows in Microsoft Office SharePoint Designer 2007 can use them. Developers can also create workflow templates by using the workflow extensions for Visual Studio 2005 and deploy these as .NET assemblies to the SharePoint servers.

Timer Jobs

Assemblies containing code that can be scheduled and executed by the SharePoint Timer Service. An example is a job scheduled to create a report every evening for the administrator about documents that have been checked out for more than a week.

ASP.NET Resources

Figure 2 showed the infrastructure that Windows SharePoint Services uses to deliver the sites. This infrastructure contains many ASP.NET resources that are directly available and help deliver the simplified development experience you have with Windows SharePoint Services. As a developer, you can create and integrate your own resources. Table 2 describes the possible types of resources you can create.

Table 2. Types of ASP.NET resources

Resource

Description

Site page

An ASP.NET page that is stored in a document library in the site collection itself (and is thus stored in the content database). Can be used to deliver custom functionality (such as reporting or dashboard pages) to the user. Site pages can be dynamically created and offer much flexibility. However, because they are stored in the content database, Windows SharePoint Services applies a strict security policy to these pages, and no inline code is allowed. Additionally, these pages are run in no-compile mode.

Application page

A physical ASP.NET page stored in the \12\Template\Layouts folder. This folder is commonly shared by all Windows SharePoint Services sites that are hosted on the Web server. Application pages are ideal for creating additional administration features for SharePoint sites. Because they are not part of the database, inline code is allowed.

Style sheets and master pages

Together, these define the look and feel of a site, as well as the common functionality that is used by all the pages of a site.

Navigation control

ASP.NET-based navigation controls that deliver an experience based on the ASP.NET provider model. Windows SharePoint Services provides many default ASP.NET-based navigation controls. Custom navigation controls are typically required when delivering public (Internet) facing sites with Windows SharePoint Services.

User control

ASP.NET user control (.ascx file) that can deliver common functionality to the pages in SharePoint sites. Windows SharePoint Services provides several controls in the \12\Template\ControlTemplates folder. Create additional custom user controls, and for example, visualize them within the master pages. User controls can deliver a particular editing experience to the user, such as custom information management policies or custom fields.

Schemas

Schemas are XML-based solutions that use the Collaborative Application Markup Language (CAML). Table 3 describes the features whose delivery you can drive by using schemas.

Table 3. Types of features delivered with schemas

Feature

Description

Site definition

A custom template for sites that are deployed in the \12\Template\SiteTemplate folder. The core file for a custom site definition is Onet.xml, which contains the global definitions for the site along with the possible configurations.

Features

Introduced in Windows SharePoint Services 3.0, a modular approach for delivering custom schemas and functionality to SharePoint sites. Features can activate what you build and deploy. Many of the previously mentioned types of solutions are made available by using Feature definitions. You can find the list of deployed Feature definitions in the \12\Template\Features folder

Custom Lists

The schemas for custom lists and document libraries are also defined via CAML-based files, many times as part of a Feature definition. However, they can also be part of a custom site definition.

Site Columns and Content Types

Schema for re-usable packaged definitions of content that can be stored and managed in SharePoint containers (lists and document libraries). Site columns and content types are delivered through Feature definitions most of the time.

Custom Field Definitions

These CAML-based files, together with a .NET assembly that contains the code-behind, deliver additional field types that users can select from when creating custom metadata in a document library, for example.

Data Manipulation

All of the content that is stored and managed in SharePoint sites, together with all the configuration data, is kept in SQL Server databases that you do not need to interact with directly. Windows SharePoint Services and MOSS have very rich object models that are delivered by a number of .NET assemblies, of which the Microsoft.SharePoint.dll and the Microsoft.Office.Server.dll are the most important.

The server object model is accessible only when the application is deployed to one of the computers that is part of the server farm. If the application accessing Windows SharePoint Services is remotely deployed, use the Web Services APIs instead.

Solutions that directly interact with the SharePoint classes must have access to the SharePoint context of the sites (either the collaboration sites or the administration sites, depending on the type of the solution). Examples are Windows–based applications that are deployed to a server running Windows SharePoint Services, Web Parts that run in the context of Windows SharePoint Services, custom Web services that expose data in a customized way, Windows services that run on the SharePoint server, and more.

Numerous Web services are available in Windows SharePoint Services that expose most of the necessary data manipulation operations. However, when in need of custom functionality, you can always create custom Web services and have Windows SharePoint Services host and integrate them with the built-in Web services.

There is also an HTTP-based protocol, the FrontPage Server Extensions Remote Procedure Call (RPC) protocol, which is used by remote clients to manipulate documents that are stored in document libraries in Windows SharePoint Services. Microsoft Office system clients are examples of smart clients that use this protocol.

The Development Environment

Developers can use two environments to build SharePoint solutions. Your choice depends on varying factors, including network infrastructure, licensing, size of the team, and the type of solution you want to build. In this article, we suggest one that we consider a best practice.

Working Remotely

In the setup we describe, developers are working locally on a non-server operating system with Microsoft Visual Studio 2005 installed. They build the solutions, and then go through the steps of deploying these solutions to a central server running Windows SharePoint Services 3.0 and possibly MOSS. Figure 3 displays the setup.

Figure 3. Setup for working remotely

Depending on the type of solution, specific .NET assemblies (for example, the Microsoft.SharePoint.dll) must be copied to the local development environment.

There are many advantages to working this way. The first important advantage is that developers do not have to install server software on their local development computers. This impacts licensing, and also eases the installation burden for developers who are already doing a lot of development on their local computers. The second advantage is that you can set up a centrally managed source-code control system, and the backup can also be centrally managed by the administrators.

However, there are many difficulties that developers experience when working this way. First, debugging the code remotely is challenging. For example, when building a Web Part in which the developer needs to debug the code, you need to consider many environment variables such as the following:

  • The developer requires powerful privileges on the server while debugging the solution for a site.

  • The developer also blocks all of the other developers who are working on solutions for the same site.

  • Every time testing must be done, developers must package the code and go through the deployment steps to the server before being able to see their code in action. This can be good, because from the start, developers have to take care of the proper packaging, but it is often going to be counter-productive when working this way.

    Note

    Many assembly-based solutions require an IISRESET on the server running Windows SharePoint Services to activate the updated version.

Working Locally

Alternatively, you can configure the development environment so that all of the SharePoint development work can be done locally. Figure 4 shows this setup.

Figure 4. Setup for working locally

We recommend this configuration for a number of reasons:

  • In the long run, the developer’s productivity benefits from being able to build, test, and debug the solution locally. This typically is the case when building assembly-based solutions.

  • Testing the solution does not impede the work of colleagues. However, working locally requires more discipline from the developers. Setting up an efficient back-up and source-control system, for example, is more challenging in this situation.

  • The local development environment can either be a native installation of Windows Server 2003 with Windows SharePoint Services 3.0 and possibly MOSS installed. However, as mentioned previously, this can be quite a burden for the developer who has other development work to do on the same computer. A configured Microsoft Virtual PC development environment is a good choice if you do not want to do a native installation, although it does require more memory and hard-disk space to use this approach.

Visual Studio 2005 Extensions for Windows SharePoint Services 3.0

Visual Studio 2005 Extensions for Windows SharePoint Services 3.0 can improve your productivity in a number of development tasks. It provides the following:

  • Project templates for building Web Parts, team sites, blank site definitions, and list definitions.

  • Individual item templates for adding Web Part classes, custom field controls, and modules to an existing project, as well as list definitions, and content types (both with an optional event receiver).

  • An external Windows application called the SharePoint Solution Generator that can pick up a provisioned team site, reverse-engineer it, and provide you with all of the individual pieces assembled together in a Visual Studio 2005 project.

It is important to remember that Visual Studio 2005 Extensions are meant to support the developer in the development process, and through the testing and debugging phases. As you use the walkthroughs in this article, the extensions can enable you to focus on the code, start writing it without the requirement of first setting the project infrastructure, have the code compiled and packaged in a Windows SharePoint Services solution, and deployed without hassle to one of your site collections—ready to be tested and debugged.

However, you can use a few configuration options to deviate from the default way the solution is packaged and deployed. The different scenarios where you will have to take control of, package, and deploy the solutions in a manual way are described later in this article.

Following are a few walkthroughs that show some of the development tasks you can undertake with the Visual Studio Extensions for Windows SharePoint Services 3.0.

Walkthrough: Building a Web Part Project

If you are familiar with the Visual Studio Extensions for Windows SharePoint Services 3.0 and with using it to build Web Parts, you might want to proceed to the next section. For the readers who are not familiar with the extensions, this short walkthrough describes the different steps for creating a project with one Web Part showing the world famous Hello World string. (Don’t worry! It is going to get more exciting.)

To create a project with one Web Part that shows the Hello World string

  1. Open Visual Studio 2005, and then create a new Web Part project as shown in Figure 5.

    Figure 5. Creating a Web Part project

    In Solution Explorer, notice that you have a reference to the Microsoft.SharePoint.dll and the System.Web.dll. The last reference is important because there is a WebPart1.cs file that contains a class that is inherited from the ASP.NET 2.0 WebPart class. This is the new "flavor" of Web Part classes that you build in Windows SharePoint Services 3.0.

  2. Write only the minimal code shown here to output a small string as the body of the Web Part. The final code looks like the following.

    using System;
    using System.Runtime.InteropServices;
    using System.Web.UI;
    using System.Web.UI.WebControls.WebParts;
    using System.Xml.Serialization;
    
    using Microsoft.SharePoint;
    using Microsoft.SharePoint.WebControls;
    using Microsoft.SharePoint.WebPartPages;
    
    namespace MSDN
    {
        [Guid("28c3eefe-2c03-4791-9f69-4405c80e1d92")]
        public class HelloWorldWebPart : System.Web.UI.WebControls.WebParts.WebPart
        {
            protected override void Render(HtmlTextWriter writer)
            {
                writer.Write("Hello Readers!");
            }
        }
    }
    
  3. Before testing the Web Part, perform the following configuration tasks. As displayed in Figure 6, open the properties of the project in Solution Explorer, and then click the SharePoint Solution tab.

    We explain the concepts of Features and solutions later in this article, but in brief, certain elements of the XML files involved are exposed here, as follows:

    • A solution node with the name and ID of the solution.

    • A node for the feature.xml file where the name of the folder to be created in the \12\Template\Features path can be changed. In addition, this node shows the title, the description, and the scope (by default, set to the level of the site collection).

    • A node for the manifest file (elements.xml) where you can set the title and the description of the Web Part itself.

      Note

      The dimmed attributes cannot be changed. For a Web Part project, for example, there is no way to change the feature.xml file and register an event handler. Later, I describe a workaround to this problem.

    Figure 6. SharePoint Solution tab in Project Properties

  4. In Visual Studio 2005, press F5 to install the SharePoint solution and deploy it to one of your extended IIS Web applications. Use the Debug tab to specify to Visual Studio where you want to list the Web Part as an activated feature.

    Later in the article, I explain what goes on behind the scenes in more detail. In short, the code is packaged into a SharePoint solution, added to the solution store at the level of the server farm, and deployed to the site collection. At this moment, you should be able to add the Web Part to a page on the targeted site, as shown in Figure 7.

    Figure 7. Web Part built and deployed by using F5

Walkthrough: Creating a Custom Field Type

The Visual Studio 2005 Extensions for Windows SharePoint Services 3.0 also supports you in developing other types of SharePoint solutions. For example, you can create an empty project and then add individual item templates. Following are the steps to create a simple field type, and to deploy and activate it quickly and easily within your Windows SharePoint Services development environment.

To create, deploy, and activate a simple field type

  1. Open Visual Studio 2005, and then create a new SharePoint project.

    This time, there is basically nothing created for you. Of course! You picked an empty project! But what you can do now is add a new item based on the Field Control template, as shown in Figure 8. The one I create is a simple field that captures, stores, and makes a project reference number available. (There is a small amount of validation logic encapsulated in this process that forces you to create a three-digit number.)

    Figure 8. Adding a Field Control item template

  2. When you proceed, two classes are added: one for the custom field and one that can be used to render a control for capturing the value of the field in a customized way. The only piece of code to add is in the ProjectReferenceNumberField class. Within this class, add the following methods.

            public override string GetValidatedString(object value)
            {
                if (value.ToString().Length != 3)
                {
                    throw new SPFieldValidationException
                             ("Only 3 characters allowed!");
                }
                else
                {
                    return value.ToString();
                }
            }
    
  3. Before pressing F5, use the properties of the project to configure the way the custom field type is made available. This time, there are no feature.xml files but there is another XML file created with the prefix fldtypes that is placed in the \12\TEMPLATE\XML folder. You can set values for the TypeDisplayName and the TypeShortDescription. Again, use the Debug tab to specify what site the browser should navigate to when pressing F5 (Figure 9).

    Figure 9. Preparing the build and deployment of the custom field type

  4. Press F5. Figure 10 shows how the new field becomes part of the list of possible field types. Figure 11 shows the validation code that checks the length of the field value and returns an error message to the user.

    Figure 10. Creating a column using the new field type

    Figure 11. Custom validation of the length of the field value

Walkthrough: Reverse Engineering a Team Site

The next example demonstrates how to use the SharePoint Solution Generator to reverse-engineer an existing (and possibly customized) SharePoint team site with the Visual Studio 2005 Extensions for Windows SharePoint Services 3.0. The walkthrough shows you how to reverse-engineer one of the 40 templates that are available for download from the MSDN site. Many of these are delivered as .stp files (the result of the Save As Template command in the browser).

Note

You can download the templates from Application Templates for Windows SharePoint Services 3.0.

In this walkthrough, we give the Sports League template to the SharePoint Solution Generator, and generate a .NET project that contains the individual components of a site definition and the Features that are involved.

To use the SharePoint Solution Generator to reverse-engineer a SharePoint team site

  1. Download the Sports League template, install it and upload it in a Site Template gallery of one of your site collections.

  2. Create a site that is based on this newly available template. Figure 12 shows the result of these actions.

    Figure 12. Site based on the Sports League site template

  3. Before you start with the SharePoint Solution Generator, remove the Web Part with the Windows SharePoint Services image from the page.

  4. Open the SharePoint Solution Generator (Figure 13), click Site Definition, and proceed to the next step.

    Figure 13. Starting with the SharePoint Solution Generator

  5. Type the URL to the site you want to reverse-engineer, or navigate to it by using the tree view. Specify where to create the Visual Studio 2005 project.

  6. Click the Start button to start the Solution Generator.

  7. When the Solution Generator is finished, you can open the Visual Studio 2005 project. Figure 14 shows the outcome.

    Figure 14. Site definition in Visual Studio 2005

    Many pieces make up the project, and discussing all of them is beyond the scope of this article. However, you can see the schema definitions of the lists and libraries and the site definition itself.

  8. Press F5 again to make everything available on your development computer. You can configure many of the details of the different features that represent each of the individual pieces of the site, as well as the site definition itself by using the SharePoint Solution tab.

A Closer Look at Windows SharePoint Services Solutions

One of the benefits of using the Visual Studio 2005 Extensions for Windows SharePoint Services 3.0 is that the outcome of your development work is packaged in a SharePoint solution. This is great for a developer who quickly wants to test out the code on his or her development computer, however, remember that there is a lack of flexibility in changing the configuration parameters that are used for the packaging and deployment of the solution.

Solution is the official term we use now to refer to the distribution package that delivers your custom Windows SharePoint Services development work to the front-end Web servers, and possibly to the application servers in your server farm. Figure 15 shows an overview of the various components that can be packaged in a SharePoint solution. These components include:

  • .NET assemblies that wrap up the code that drive the solution.

  • Deployment files such as resource files, images, or other helper files.

  • Many solutions involve the delivery of new templates and definitions for sites, lists, libraries, fields, content types, and more. These definitions are in the form of CAML-based XML files.

  • And finally, configurations that have to be performed at the level of the front-end Web server (for example in the web.config files for the registration of Web Parts) can be included.

Figure 15. Anatomy of a SharePoint solution

In addition to all of this, you must include a very important file—the manifest file—to assist Windows SharePoint Services in the deployment process of the solution. The manifest file is an XML file, which I describe in more detail later. But in short, the manifest file contains the listing of all assets involved in a solution, along with target locations for these assets and the various configurations in which they must occur.

Anatomy of a Manifest File

What can be included in the manifest file? A lot—and what follows is a brief explanation of each type of item. Before starting, it is interesting to mention that the schema definition for the manifest file is included in the Wss.xsd file that is available in the WSS system folder.

Note

You can find the WSS system folder in the path C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12.

So you might want to add this to your Visual Studio 2005 environment to get IntelliSense support. Figure 16 shows the main XML elements for a manifest file.

Figure 16. Main XML elements in a solution manifest file

Solution Element

The Solution element is the root element of the manifest file. The SolutionId attribute is an important element of the file. SolutionId identifies the solution in the solution store (which is part of the configuration database, discussed later in this article). You identify a solution with a GUID.

<Solution SolutionId="1de3b0fc-78e9-4fe6-ae63-51ea50109982" xmlns="http://schemas.microsoft.com/sharepoint/" >
</Solution>

DeploymentServerType and ResetWebServer are optional attributes. DeploymentServerType can have two possible values: ApplicationServer or WebFrontEnd. Typically, most of your solutions target the front-end Web servers in your server farm. Examples of solutions that target application servers (for example, index servers, servers running Excel Services, document conversion servers, and so on) are custom configurations or additional custom converters. The IISReset attribute can be used to start a reset of Internet Information Services (IIS) when the solution is deployed to a specific IIS Web application.

FeatureManifest Element

Features play an important role in many Windows SharePoint Services solutions because they represent the individual pieces of the solution (such as a field type, a Web Part, a workflow, and so on). You must represent every Feature that is included in the solution with a FeatureManifest element. The following code example contains the Feature that advertises a Web Part in a SharePoint site.

<Solution SolutionId="dda6427b-b880-46c0-a428-10c4bac0ce91" xmlns="http://schemas.microsoft.com/sharepoint/" >
  <FeatureManifests>
    <FeatureManifest Location="HelloWorldWebPart_28c3eefe-2c03-4791-9f69-4405c80e1d92\feature.xml" />
  </FeatureManifests>
  …
</Solution>

When you deploy the solution to a front-end Web server, all of the Feature-related files are copied to the location specified here.

Assembly Element

Most of the SharePoint solutions involve one or more .NET assemblies. The Assembly element is used in the manifest file to make the DLL available on the destination server. Following is an example.

<Solution SolutionId="dda6427b-b880-46c0-a428-10c4bac0ce91" xmlns="http://schemas.microsoft.com/sharepoint/" >
…
  <Assemblies>
    <Assembly Location="HelloWorldWebPart.dll" DeploymentTarget="GlobalAssemblyCache" >
      <SafeControls>
        <SafeControl Assembly="HelloWorldWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" Namespace="MSDN" TypeName="HelloWorldWebPart" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>
</Solution>

The first attribute for the Assembly element is Location, which stores the relative path of the DLL in the solution file. Next, there is the DeploymentTarget attribute, which has two possible values: GlobalAssemblyCache or WebApplication. GlobalAssemblyCache indicates that the assembly should be deployed in the global assembly cache; WebApplication tells Windows SharePoint Services to drop the assembly in the private application folder of the IIS Web application. As discussed later, WebApplication implies that the solution that is used depends on the trust level that the administrator sets in the web.config file that is associated with the IIS Web application. Deploying the assembly in the global assembly cache, which is a fully trusted location, means that as a developer, you do not have to worry about setting this trust level.

The Web Parts in the solution must be registered as safe controls in the web.config file. The Assembly element can contain one or more SafeControl elements (grouped together in a SafeControls element). Each SafeControl element describes the configuration that must be done in the web.config file.

Another possible set of child elements of the Assembly element are the ClassResource elements (grouped together in a ClassResources element). Each represents a possible resource that is needed by the deployed assembly. Examples are resource files, XML files, or pictures.

ApplicationResourceFile Element

The manifest files can contain one or more ApplicationResourceFile elements with a relative path to a resource file that must be deployed. At the time of deployment, the resource files are copied to the private application resource folder of the IIS Web Application, as shown in the following code.

<Solution SolutionId="8f37f0a7-ec35-4a63-9c3d-91205d9a2ac6" 
          xmlns="http://schemas.microsoft.com/sharepoint/" >
…
    <ApplicationResourceFiles>
        <ApplicationResourceFile Location="hellowp.resx"/>
         <ApplicationResourceFile Location="hellowp.en-us.resx"/>
    </ApplicationResourceFiles>
</Solution>

CodeAccessSecurity Element

The CodeAccessSecurity important element is important to include in the manifest file when you want to grant specific permissions to your code. Later in the article, there is a more detailed discussion about this. In short, the CodeAccessSecurity element has one or more PolicyItem child elements that each define the specifics regarding the code access security policy to apply for the solution. There are two parts for a policy item: the listing of the permissions that are part of it and the assemblies for which these permissions should play a role.

The list of permissions, each represented in an IPermission element, is collected in a PermissionSet element that is the child of the PolicyItem element. The IPermission elements each define a code access security permission that is required for the assembly to run correctly. This is discussed in more detail, later in the article.

One or more Assembly elements can play a role in code access security. You must define them one by one, identifying each by name, version, and full public key.

DwpFile Element

Web Parts must be made available in the Web Part gallery before they can be dropped on the Web Part Pages. XML files, with either a .dwp extension or a .webpart extension, store the metadata information that is necessary to make the Web Parts available. The solution manifest file can contain one or more DwpFile elements that are collected together in the DwpFiles element, with each pointing to one of these files.

   <DwpFiles>
      <DwpFile FileName="hellowebpart.webpart" Location="hellowebpart.webpart"/>
   </DwpFiles>

Resource Element

You can drop resource files in the folder that contains your Feature, and use it from that location. A Resource element represents such a resource in the solution manifest file. The only attribute to set is the relative path in the package to the resource file.

SiteDefinitionManifest Element

You use this element when you are deploying a custom site definition. The SiteDefinitionManifest element has a Location attribute that picks up all the files in the specified folder and creates the needed folder in the \12\Template\SiteTemplates folder. The WebTempFile child element deploys the webtemp*.xml file to make the template known to Windows SharePoint Services.

  <SiteDefinitionManifests>
    <SiteDefinitionManifest Location="LitwareSiteTemplate">
      <WebTempFile Location="1033\xml\webtempLitware.xml" />
    </SiteDefinitionManifest>
  </SiteDefinitionManifests> 

RootFile Element

Solution files can be copied to a specified folder directly under the \12 folder during deployment by inserting a RootFile element in the solution manifest file.

TemplateFile Element

The TemplateFile element can be used to define the template files that must be deployed under the \12\Template folder. An example of the type of file you can deploy in this way is the fldtypes*.xml file, which defines the details of a custom field type. Use the Location attribute to specify the relative path to the file.

Windows SharePoint Services Solution Samples

Earlier in the article, three walkthroughs guided you through the steps of creating and deploying a Web Part, a custom field type, and a custom site definition. Let’s inspect each of the solutions and the different files that are included with them.

Web Part Solution File

Let’s first take a look at the SharePoint solution that was generated for the simple Web Part created earlier in the article. In the \bin\debug folder of the project, you find the .wsp file together with a subfolder called solution, which contains all of the solution pieces that are packaged in the .wsp file. Figure 17 summarizes all of the components in a Web Part solution.

Figure 17. Components that make up a Web Part solution

There is the folder that contains the three files in the Feature that make the Web Part available to the users: feature.xml, elementManifest.xml, and HelloWebPart.webpart. There is the assembly with the code and the manifest file.

The manifest file looks like the following code.

<Solution SolutionId="219eec47-aeae-4ec2-9a2d-b7774a7e92d1" xmlns="http://schemas.microsoft.com/sharepoint/" >
  <FeatureManifests>
    <FeatureManifest Location="HelloWebPart_6ad212bb-5425-4d30-aa62-6acc23d04146\feature.xml" />
  </FeatureManifests>
  <Assemblies>
    <Assembly Location="HelloWebPart.dll" DeploymentTarget="GlobalAssemblyCache" >
      <SafeControls>
        <SafeControl Assembly="HelloWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" Namespace="MSDN" TypeName="HelloWebPart" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>
</Solution>

The code contains two main blocks. The first, represented by the FeatureManifests element, tells Windows SharePoint Services to copy the Feature to the \12\Template\Features folder on the server where the solution is deployed. The second, represented by the Assemblies element, has two roles: to deploy the assembly in the global assembly cache, and to define the necessary modifications to the web.config file with the SafeControl registration.

Custom Field Type Solution

The second type of solution that was created in the walkthroughs was a custom field type. Navigating to the solution folder again, you find an assembly and a manifest file at the root, but instead of a Feature folder, there is a folder named XML, that contains the template file that must be deployed.

The manifest file looks like the following code.

<Solution SolutionId="d5fdc38c-1892-4700-a7e0-723d02d6dfc0" xmlns="http://schemas.microsoft.com/sharepoint/" >
  <TemplateFiles>
    <TemplateFile Location="xml\fldtypes_50896c5a-bcfe-47b9-a4da-5aa78d3c0d3e.xml" />
  </TemplateFiles>
  <Assemblies>
    <Assembly Location="SimpleFieldTypeDemo.dll" DeploymentTarget="GlobalAssemblyCache" >
      <SafeControls>
        <SafeControl Assembly="SimpleFieldTypeDemo, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" Namespace="ProjectReferenceNumber" TypeName="ProjectReferenceNumberField" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>
</Solution>

Again, there are two important parts to this code: one deploys the template file to its proper location, and the second deploys the assembly. The SafeControl entry is not strictly needed unless the field type is used as a custom field control in publishing pages.

Custom Site Definition Solution

The last type of solution to discuss is the Windows SharePoint Services site exported with the SharePoint Solution Generator, by using a sports league as an example. Figure 18 displays the many components that are generated and collected in a .NET project.

Figure 18. Components of a custom site definition solution

First, you see the core schemas for the site definition including the important files, onet.xml and the webtemp*.xml. An assembly can contain code that can be executed at the time of provisioning a site. For the rest of the schemas, you see plenty of Feature definitions in the project—for the site, the provisioning code, and for the lists and document libraries that must be included in the provisioned site. The manifest file looks like the following XML.

<Solution SolutionId="c2f14355-caea-4e02-b2fb-be198b71a99f" xmlns="http://schemas.microsoft.com/sharepoint/" >
  <FeatureManifests>
    <FeatureManifest Location="LeagueCalendar_2a46379a-0cc6-4f0f-b901-d69c688270d5\feature.xml" />
    <FeatureManifest Location="PlayersList_63daf9b3-2d56-4b80-b235-c064b9b14d38\feature.xml" />
    <FeatureManifest Location="SharedDocuments_3dc03f6a-7abe-4cc7-8995-7d799bf1fa55\feature.xml" />
    <FeatureManifest Location="Teams_254d82e9-f759-4e29-86f0-7a5870fc7a7d\feature.xml" />
    <FeatureManifest Location="MSDNLeagueSiteTemplate_af2531ff-18bf-45f9-b47c-f9e820f570d3\feature.xml" />
    <FeatureManifest Location="MSDNLeagueSiteTemplate_d8e211da-abed-4556-87c9-0ceb6fa1220f\feature.xml" />
  </FeatureManifests>
  <Assemblies>
    <Assembly Location="MSDNLeagueSiteTemplate.dll" DeploymentTarget="GlobalAssemblyCache" >
      <SafeControls>
        <SafeControl Assembly="MSDNLeagueSiteTemplate, Version=1.0.0.0, Culture=neutral, PublicKeyToken=a203fc97bcb29c46" Namespace="MSDNLeagueSiteTemplate" TypeName="MSDNLeagueSiteTemplate" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>
  <SiteDefinitionManifests>
    <SiteDefinitionManifest Location="MSDNLeagueSiteTemplate_072c8ac2-012e-405d-b436-a4809fcb6c1f">
      <WebTempFile Location="1033\xml\webtempMSDNLeagueSiteTemplate_ee077f02-b4a0-45ba-829c-8eeb1991cf90.xml" />
    </SiteDefinitionManifest>
  </SiteDefinitionManifests>
</Solution> 

The section of code that differs from the previous examples is the last part with the SiteDefinitionManifests element. The SiteDefinitionManifest element deploys the site definition in the \12\Template\SiteTemplates folder, and the WebTempFile element does the same for the webtemp*.xml file.

Custom List Definition

A final example is the definition of a custom list. This is shown with a short walkthrough that demonstrates how the Visual Studio 2005 Extensions for Windows SharePoint Services 3.0 can help you in the initial stages.

To create a custom list definition

  1. Navigate to one of your sites and create a list based on the custom list template.

  2. Name the list Employees, and then add the following columns: First Name, Last Name (changing the Title column), Department, and Telephone Number.

    You can now use the SharePoint Solution Generator to generate the bulk of the custom list definition.

  3. Open the SharePoint Solution Generator, and on the first page, select List Definition.

  4. Enter the URL of your site and select the list instance created at the beginning of this walkthrough.

  5. Provide the location where you want to create the Visual Studio project, and then click Finish to start the generation process.

  6. Let’s now construct the Feature for this new list template. Create a folder on your file system in a location you choose, with a Features folder as a subfolder.

  7. Under the Features folder, create another subfolder named EmployeesList. Copy the Employees folder from the .NET project folder into it.

  8. At the level of the EmployeesList folder, create a feature.xml file containing the following XML.

    <Feature Id="{489C77F1-B064-408e-9B85-029A33BDF9D7}" 
        Title="Employees"
        Description="This feature provides support for creating an Employee List."
        Version="1.0.0.0"
        Scope="Web"
        Hidden="FALSE"
        xmlns="http://schemas.microsoft.com/sharepoint/">
        <ElementManifests>
            <ElementManifest Location="ListTemplates\Employees.xml"/>
            <ElementFile Location="Employees\allitems.aspx" />
            <ElementFile Location="Employees\dispform.aspx" />
            <ElementFile Location="Employees\editform.aspx" />
            <ElementFile Location="Employees\newform.aspx" />
            <ElementFile Location="Employees\schema.xml" />
        </ElementManifests>
    </Feature>
    
  9. Create a ListTemplates folder under the EmployeesList folder, and then create the Employees.xml in it containing the CAML for the list template.

    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <ListTemplate 
              Name="Employees" 
              Type="10100" 
              BaseType="0" 
              OnQuickLaunch="TRUE" 
              SecurityBits="11" 
              DisplayName="Employees" 
              Description="Employees List Type" 
              Image="/_layouts/images/CHNGCOL.GIF"/>
    </Elements>
    
  10. Open the schema.xml in the Employees folder, and make sure that the Type attribute for the root element matches the number you used in the Timesheets.xml for the type (in the example, 10100). Also open each of the .aspx pages, and then remove the first line containing the comment.

You now have the Feature ready. Next, you must package all of this into a SharePoint solution.

To package the Feature into a SharePoint solution

  1. Create a manifest file at the root level of the folders you created earlier. It is a simple task because there is no code involved.

    <Solution SolutionId="{B2BE6294-D62F-4f14-9266-7C37AD2B9DBA}" 
              xmlns="http://schemas.microsoft.com/sharepoint/" >
        <FeatureManifests>
            <FeatureManifest Location="EmployeesList\feature.xml" />
        </FeatureManifests>
    </Solution>
    
  2. Create a .ddf file at the same level as the manifest file to package everything into a solution file.

    ;
    ; *** .ddf file for generating SharePoint solution
    ;
    .OPTION EXPLICIT     ; Generate errors 
    .Set CabinetNameTemplate=Employees.wsp     
    .set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory
    .Set CompressionType=MSZIP;** All files are compressed in cabinet files
    .Set UniqueFiles="ON"
    .Set Cabinet=on
    .Set DiskDirectory1=Package
    
    ; *** the manifest file
    manifest.xml manifest.xml
    
    ; *** the feature files
    Features\EmployeesList\feature.xml EmployeesList\feature.xml
    Features\EmployeesList\ListTemplates\Employees.xml EmployeesList\ListTemplates\Employees.xml
    Features\EmployeesList\Employees\AllItems.aspx EmployeesList\Employees\AllItems.aspx
    Features\EmployeesList\Employees\DispForm.aspx EmployeesList\Employees\DispForm.aspx
    Features\EmployeesList\Employees\EditForm.aspx EmployeesList\Employees\EditForm.aspx
    Features\EmployeesList\Employees\NewForm.aspx EmployeesList\Employees\NewForm.aspx
    Features\EmployeesList\Employees\schema.xml EmployeesList\Employees\schema.xml
    
  3. Package everything into the .wsp file, add the solution to the solution store, and then deploy it globally by using the following Stsadm calls (typically contained within a batch file).

    set MakeCabTool=c:\Program Files\Microsoft Visual Studio 8\SmartDevices\SDK\SDKTools\makecab.exe 
    set SPAdminTool=%CommonProgramFiles%\Microsoft Shared\web server extensions\12\BIN\stsadm.exe
    
    "%MakeCabTool%" /f wsp_structure.ddf
    "%SPAdminTool%" -o addsolution -filename package\MSDNTimesheet.wsp
    "%SPAdminTool%" -o deploysolution -name MSDNTimesheet.wsp -immediate
    

You can now try out your work by activating the Feature from the Site Features page in one of your sites, and create a new list instance based on the new template. I work with this solution later in the article when discussing retracting and upgrading solutions.

Next step: Development Tools and Techniques for Working with Code in Windows SharePoint Services 3.0 (Part 2 of 2).

About the Author

Patrick Tisseghem is a Microsoft Office SharePoint Server MVP, and is highly focused on Windows SharePoint Services 3.0 and Office SharePoint Server 2007. He created and delivered the ISV-focused early adopter material for Microsoft Redmond for the latest version of SharePoint and has toured many countries with his developer-focused workshops. He is a frequent speaker at major Microsoft conferences such as TechEd and SharePoint Connections, and is the author of numerous white papers published on MSDN. He is also the author of a book titled Inside MOSS 2007, published by Microsoft Press. More information about Patrick can be found at his blog.

Additional Resources

For more information, see the following resources: