LANGUAGES: VB.NET | C#
ASP.NET VERSIONS: 2.0
Through the Portal
Programming Custom ASP.NET Applications for Windows SharePoint Server 2007
By Gustavo Velez
Microsoft SharePoint Services is the collaborative portal application that belongs to the Microsoft Office family. The portal offers online publishing, approval workflow and versioning of documents, search facilities for internal and external content, a flexible hierarchy of content areas, services for authentication and authorization, and a plethora of additional functionality. The portal unifies unrelated information to facilitate collaboration on documents, projects, and other efforts, integrating different systems into one solution.
The portal application, called Microsoft Office SharePoint Server (MOSS), is based on the Microsoft Windows SharePoint Services (WSS) platform, a free component of Windows Server 2003. The predecessor of MOSS, SharePoint Portal Server and WSS have become very popular in the last few years and have helped businesses to create the needed infrastructure to effortlessly connect users, teams, and information. In this way, relevant information flows seamlessly across organizations, and members can work together more efficiently on documents, projects, and tasks.
Windows SharePoint Portal Server 2007 provides for organizations sharing tools that are straightforward and secure to use, manage, and maintain, and that can be scaled depending on the requirements of the enterprise. Using the Microsoft SQL Server relational database technology as the repository, significant advantages are created for IT professionals and developers, whereby they can adapt it to fit the needs and requirements of users.
One of the key concepts of SharePoint is the document library, which offers a central location for storing documents and ensures approval workflow and versioning to track changes. Additionally, it enables the infrastructure to create workspaces a place for collaborating on documents with others.
Programmability of WSS and MOSS
SharePoint 2007 has an extensive object model API to access and work with all the components of the server. The object model is fully compatible with Microsoft ASP.NET 2.0 (and 3.0), enabling developers to work within the Microsoft Visual Studio 2005 integrated development environment, and to program custom Web applications for use in conjunction with SPS. The object model offers wide-ranging access to document libraries, its documents, and the properties of each element.
This article demonstrates how to create a Web application in Visual Studio 2005 that operates inside the context of Windows SharePoint. The following example creates a tool for selecting one document library from a list of all available libraries in the portal and displays the documents in it. The purpose of the example is to show the possibilities of the object model in working with libraries and documents, although the power of the object model is far greater, reaching all aspects of SharePoint.
To program seamlessly with SharePoint, it is advisable to install the development environment in the same server as SharePoint. This applies only to development systems; in production systems, it is recommended to install the minimum amount of software to guarantee system stability. Having Visual Studio together with SharePoint simplifies reference settings and debugging. Another important point is that it is impossible to use the SPS object model remotely, which means the compiled assembly needs to be located in the same physical server(s) where SharePoint is running.
Namespaces, Classes, Methods, and Properties
The object model of WSS contains 42 namespaces, with approximately 350 classes; MOSS adds another 80 namespaces and 600 classes. There are other namespaces not supported; they are reserved for Microsoft s internal use. The namespaces and classes cover all aspects of SharePoint, such as administration and creation of all components in the system, authorization, management of users, and security across each element.
The object model is too extensive to be covered in this article. However, this article will address the namespaces, classes, and methods needed to work exclusively with document libraries:
- Microsoft.SharePoint.SPSite. This class represents a collection of sites on the virtual server, including the top-level site and all its sub-sites. SharePoint can host different applications; each of which is, in fact, a different portal that shares the deep-set infrastructure. Each application can have a number of collection sites.
- Microsoft.SharePoint.SPWeb. The SPWeb class stands for a SharePoint site. Each collection of sites, represented by the SPSite class, can contain one or more sites, represented by the SPWeb class. There is at least one site in each site collection, and its name is always the same as the name of the collection.
- Microsoft.SharePoint.WebControls.SPControl. The SPControl class provides methods for getting and/or setting up the context of the calls. The methods of this class can return the site collection and Web site that serves as the environment for the request.
- Microsoft.SharePoint.SPList. The SPList class denotes a list on a SharePoint Web Site. There are different types of lists; the document library is one of them. A list consists of items, and each of the items contains fields that hold the data and metadata. The methods and properties of this class allow for retrieval and management of all the documents in a document library.
- Microsoft.SharePoint.SPListCollection. This represents a collection of objects of the type SPList.
Setting up the Web Application Environment
SharePoint 2007 is an ASP.NET Web application that runs on top of IIS 6.0, which provides the first level of authentication by handling the base HTTP request. After that, SharePoint takes over, manipulating managed paths, inclusions, and exclusions.
The 2003 version of SharePoint had an Internet Server API (ISAPI) filter to intercept the traffic to IIS and redirect it to its own authorization mechanism. In the 2007 version this has been modified; SharePoint behaves like all Web applications under IIS.
The technique for creating Web applications with Visual Studio 2005 is radically different from that of Visual Studio .NET 2003. To make the construction of a Web application easier to deploy in SharePoint, it s possible to use the Visual Studio 2005 Web Application Projects extension, which makes ASP.NET projects behave similarly to the way they did in Visual Studio .NET 2003, and can be used as an alternative to the built-in Web Site Project (see http://msdn2.microsoft.com/en-us/asp.net/aa336618.aspx).
Create a new Virtual Directory with the Internet Information Services Manager (IIS), with the default options provided by the IIS wizard. Ensure that the Application name in the Properties window (under the Virtual Directory tab) of the new Virtual Directory has been created; otherwise, create it. At the same time, confirm that Execute permissions is set to Scripts only . This is necessary to prevent the error message Error while trying to run project: Unable to start debugging on the web server. The project is not configured to be debugged as you begin to run and debug the new project under Visual Studio. For more information, see the Microsoft Knowledge Base Article Q306156, PRB: The Project Is Not Configured to Be Debugged Error Message When You Debug ASP.NET Applications ; ensure the new application is running under the ASP.NET version 2.0.50727 (ASP.NET tab in the Properties window).
Creating the Web Application
Start Visual Studio 2005; create a new ASP.NET Web application project; assign the Name and path in Location. If everything is satisfactory, the new project will be created without error messages from IIS (see Figure 1).
Figure 1: Newly created project in Visual Studio 2005.
Rename the aspx page and add a Reference to Windows SharePoint Services (Microsoft.SharePoint.dll); because all the necessary functionality is present in the WSS namespaces, it is not necessary to set a Reference to the MOSS assembly, Microsoft Office SharePoint Server component (Microsoft.SharePoint.portal.dll). At the top of the code-behind page, add Imports statements to Microsoft.SharePoint and Microsoft.SharePoint.WebControls (with the using statement in C#).
Attempt to run the empty project for testing purposes. If you receive the error message Error while trying to run project... , ensure the Application name in the Properties window (under the Virtual Directory tab) of the new Virtual Directory has been created, as noted above.
If you are using the application directly from the physical server, you may also receive a Server Error in Application message after starting the aspx page; namely, Debugging is not supported under current trust level settings . Moreover, if you are using a remote connection, you may get a generic error in place of the above message.
This error occurs as a result of the Code Access Security policies of SharePoint. MOSS and WSS use code access security to help protect defined assets and operations by specifying the permissions necessary for them to run.
There are various ways to verify that the code has the right permissions to access the SharePoint object model, including:
- Installation of the assembly in the Global Assembly Cache (GAC). In this case, the assembly needs to be signed with a key and a safe name. To sign your assembly, use the infrastructure of Visual Studio ( Properties of the project, the Signing tab, and check the Sign the assembly checkbox, giving it a new name). After generating a key, it is necessary to install the assembly in the GAC and restart IIS. Assemblies installed in the GAC always have Full trust permissions.
- Create a custom security policy specified for your project. The trust levels are defined in the security policy files in the file system of the server. By default, SharePoint sets the trust level to WSS_Minimal , which provides a secure trust level in which assemblies operate with the minimal set of permissions. For more information about Code Access Security, see the MSDN article Microsoft Windows SharePoint Services and Code Access Security (http://msdn2.microsoft.com/en-us/library/ms916855.aspx).
- Raise the trust level for the Virtual Server to an acceptable level. Although this is the option that is most used, from a security standpoint it is the least safe. This is done by opening the web.config file of SharePoint Application, which is located (for a default installation) in the root of IIS ( ..\inetpub\wwwroot\wss\VirtualDirectories\80 ), and changing the line:
The example application consists principally of a DropDownList control to select a document library from all the libraries defined in the site and a DataGrid control to display the list of documents in the selected library.
Because you need a reference for the Site and Web objects throughout the entire application, the first step is to make a global instance of the objects:
Private _mySite As SPSite = Nothing
Private _myWeb As SPWeb = Nothing
And in the Load event, the objects can be referenced:
_mySite = SPControl.GetContextSite(Context)
_myWeb = _mySite.RootWeb
The SPControl.GetContextSite method returns the site collection that serves as the context for the request. The Context parameter is an object of the type System.Web.HttpContext, which encapsulates the specific context used by the server to process the request.
The RootWeb property of the SPSite class gets the first (default) Web site of the site collection. In the example, we ll employ the RootWeb property because we have chosen to use the document libraries of the portal. If you need to use other libraries, you must specify the URL as a parameter in the OpenWeb method of the SPSite, instead of the RootWeb property. The code line:
Dim myListCol As SPListCollection = _myWeb.Lists
gives back all the Lists present in the Web site.
The DropDownList is bonded to the values of the List collection using the values from the GetLibraries function:
Private Function GetLibraries(ByVal myWeb As SPWeb)
Dim myArrList As New ArrayList
Dim myLists As SPListCollection = myWeb.Lists
Dim myList As SPList
For Each myList In myLists
End Function 'GetLibraries
The Title property of each List is added to an ArrayList and is given back by the function to be bonded. In the SelectedIndexChanged event of the DropDownList is the code to bind the documents to the DataGrid:
Private Sub DropDownList1_SelectedIndexChanged( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
Dim myListCol As SPListCollection = _myWeb.Lists
Dim myList As SPList =
myListCol.IncludeRootFolder = True
DataGrid1.DataSource = GetDocuments(_myWeb, myList)
End Sub 'DropDownList1_SelectedIndexChanged
The IncludeRootFolder property of the SPListCollection class sets or gets a Boolean value that specifies whether the root folder of a list in the collection is returned. It is necessary to set this property before binding the DataGrid because we are using the object model to display remote Document Libraries. If it is not set, the compiler will generate the error message, To use the RootFolder property, set the IncludeRootFolder property on the SPListCollection object to true .
The list with documents from the selected document library is provided by the GetDocuments function:
Private Function GetDocuments(ByVal myWeb As SPWeb, _
ByVal myList As SPList) As ArrayList
Dim myArrList As New ArrayList
Dim myItem As SPListItem
For Each myItem In myList.Items
End Function GetDocuments
This function loops through each document found in the library and makes an HTTP hyperlink using the URL of the server (myWeb.Url), the title of the list (myList.Title), and the name of the document (myItem.File.Name).
Because the parameter myList contains all types of lists or libraries, the production code will need an error-handling statement in the For Each loop: not all lists have a File.Name method. Another option is to read the type of the list before the method can be employed, ensuring that the element is of the right type.
To install the application after compilation, copy the .dll to the bin directory of the IIS root from the application (normally, ..\inetpub\wwwroot\wss\VirtualDirectories\80 ). If the directory doesn t exist, simply create a new one. Then, copy the aspx file to the directory C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS , where SharePoint will recognize it as a new application that can run within its authorized context. The URL of the application will then be http[s]:\\ServerName\_layouts\AplicationName.aspx .
For test purposes, you can create a document library in the portal home with a few trial documents. The application is very straightforward: simply choose one of the lists presented in the DropDownList and the documents contained therein will be shown on the DataGrid (see Figure 2).
Figure 2: Application interface.
Clicking in the hyperlink of a document will open a new window with this document. In the case of Office documents, and, in the event the client computer has Office 2003 installed, Internet Explorer will start the viewer of the document with the Task Pane open. Office 2000 and XP can be used with SharePoint, but offer far less integration.
When you work on a document in Word 2003, Excel 2003, PowerPoint 2003, or Visio 2003, it is expedient to use the Shared Workspace Task Pane to take advantage of the SharePoint features. The Task Pane is also offered with partial functionality in OneNote 2003 and Project 2003.
If the document is already stored on a SharePoint list, the Shared Workspace Task Pane displays the status of the document, the members of the team (users with rights to utilize the document library), tasks, links, and related documents from that site (see Figure 3).
Figure 3: Word document in Internet Explorer with Shared Workspace Task Pane.
In Office 2007, the Shared Workspace has disappeared, and now it is possible to fill the SharePoint properties of the document from the document itself, as illustrated in Figure 4.
Figure 4: Office Word 2007 with the SharePoint document properties.
The integrated features between SharePoint, Office, and Internet Explorer include the ability to remotely open, edit, and save documents; creation and update of shared attachments; synchronization (if the documents are changed by other users); automatic collection of metadata for the documents; check-in/check-out; and version tracking.
SharePoint Portal s default has a rich and efficient interface that can be used directly from the box. That said, if it is necessary to create a customized interface to interact with, for example, a limited set of SharePoint features, you can use the object model to reach all the classes, methods, and properties you require. Although the SharePoint object model is hefty, it is well documented and covers all aspects of SPS.
The source code accompanying this article is available for download.
Gustavo Velez is an MCSD Senior Application Developer for Winvision (http://www.winvision.nl), a Microsoft Gold Partner in the Netherlands. He has had many years experience in developing Windows and Office applications, and more than four years of daily programming experience with SharePoint. His articles can be found in many of the leading trade magazines and he s pleased to be Webmaster of http://www.gavd.net/servers, the only Spanish-language site dedicated to SharePoint.