Developing WebParts for MS Sharepoint Services Using Vulcan.NET

By the time you read this article Vulcan.NET will be released and we will see the first applications entering the .NET market which are written in Vulcan.NET. This article will show how to use the new environment to add extra value to your SharePoint portal by developing web parts in Vulcan.NET. See how easy it is to develop data concentric web parts which seamlessly integrate into the infrastructure of a SharePoint server.

What are Microsofts Sharepoint Services?

Windows SharePoint Services (WSS) are offering different ways to share and manage data and documents. With WSS you can manage projects and coordinate team members which are working in different places. Microsoft offers an entire library of Web parts that do all sorts of different things. For example, there is a document library Web part, a calendar Web part, etc. All the project leader has to do is to tell SharePoint which Web parts to use, set a few permissions for the team, and they are in business.

What do you need to run a WSS web site?

First of all, you need a server which is running Windows Server 2003, ASP.NET and IIS 6. More specifically, your server must be running the World Wide Web service, the SMTP Service, and the Common Files components of IIS. Then you have to download and install WSS. WSS is an additional component for Windows Server 2003 and can be downloaded from Microsoft’s Web-Site for free.

Do I need a special education to manage the site?

No. The server and the different sites - you can have more than one - are managed through a couple of  web sites running on your server. Every site can have its own set of permissions and access rights.

Can I customize the appearance of the sites?

Of course! While you have a lot of predefined templates in different shapes, you can highly configure the appearance of your site. If you’ve FrontPage 2003 in your tool portfolio, you even can edit existing sites to customize them to your needs. There are a lot of companies and services available where you can buy additional templates, web parts and other stuff which is WSS related.

A real advantage of WSS is the fact that they integrate seamlessly into Microsoft Office 2003. The big brother of WSS is the Microsoft’s SharePoint Portal Server which adds a complete portal solution to your company. In contrast to the WSS the WSPS is a product you have to buy.

What do I need to consume WSS?

What do I need to consume WSS?

Nothing more than a browser. It might be very likely that you already used a web site which is driven by using WSS or its big brother. If you want to go further than using WSS as an interactive front end, you have different ways to use the WSS services.

Windows SharePoint Services was being designed and developed during the time when Microsoft was beginning to heavily push Web services. It should be no surprise, then, to find out that you can get at the data in SharePoint through Web services. In fact, there's not just one Web service involved; there are 16.

To manage WSS programmatically you can make use of its object model. If you want to extend the WSS functionality you can use web parts to bring this additional potential to your server. There’s a complete model available in the .NET framework which allows us to build new web parts very easily which integrate seamlessly in the WSS infrastructure.

Usually the WSS holds its data in an instance of the MSDE, the desktop engine of Microsoft’s SQL Server. If you have a full blown SQL Server running on your server (or on your network) you can customize the installation of WSS to use this SQL instance instead of installing a local one. Being able to customize a WSS site by own components and the ability to access the data of a WSS very easily through SQL makes it extremely interesting to use the WSS and build even more than collaboration sites.

What is a Web Part?

Actually this question should better read: what is the web part infrastructure of a WSS site? There are several things involved:

• Web part pages are arranged in so called web part zones. This arrangement
  determines the appearance of a web part page inside of WSS products and applications.
• A web part page can hold one or more web part zones, which provide the layout of the page holding the web parts.
• Web parts are the building blocks used to build web part pages inside WSS. Every web part is specialized in a specific functionality, e.g. announcements, calendar, images, etc.

These three different blocks and their interfaces make up what is called the web part infrastructure.

This paper concentrates on the task to demonstrate how to build web parts using Vulcan.NET that can be added to WSS web part pages to customize their behavior.

As already mentioned, SharePoint Services provides a .NET object model for us to program against, in much the same fashion as does the standard .NET Framework. In fact, the web part infrastructure extends many of the ASP.NET classes. One of the classes the SharePoint Framework contains is the WebPart class, located in the Microsoft.SharePoint.WebPartPages namespace. This is the base class that your Web Parts inherits from.

A new Web Part using Vulcan.NET

In this chapter I’ll describe how to build a new web part from scratch using Visual Studio 2005 and Vulcan.NET.
First of all you need to create a new project. What we are going to build is a class library, to be precise a library with one single class in it, the web part, and compile this one to a DLL. Fortunately Vulcan.NET comes with a full integration into VS 2005, so creating a new project is as simple as a button click. So open your Visual Studio and choose File->New->Project…

Fig. 1: Create a new project (class library)

Under the project types mark Vulcan.NET and expand the treeview item. Then mark the Basic item and watch the template listview. There you’ll find a template for a class library (and others as well , so highlight this and fill the single lines at the bottom of this dialog. The solution name might be different form the library name. A solution is a collection of different projects which are representing a solution to a problem. There can be different sub-projects to achieve the goal, e.g. in our case we need to build the DLL and a CAB-file to be able to install the DLL easily on our server. Both projects (DLL and CAB) are handled in one solution, so one has everything in one place available. In the sample screenshots you’ll find ‘DevFest2006’ as solution name while ‘WPVulcan’ is the name of the class library.

Customizing the Project

If you look at the solution explorer, you’ll find a couple of entries already in place.

VS has automatically created a node for the WPVulcan project and inserted some predefined nodes:          

• References: Here you will add every namespace (assembly) from which you are going to use classes, attributes, collections, enumerations, etc.  The one you will always need is the System namespace and therefore it’s already there.
• AssemblyInfo.prg: Will hold several attributes that describe the assembly and holds some meta-data.
• Library.prg: A default file which is going to hold the source code for the class library. It has already some sample source code in it, which are we going to override.

I don’t like the default naming of the prg file so this is the first thing we are going to change. I usually name the prg identical to the class I am going to implement (and there’s usually only one class per prg, agreeing to our coding conventions). So go ahead, click on library.prg and then change the name to WPVulcan.PRG in the property window right beneath the solution explorer. To save the changes, please press the save all button now.

Before we start modifying the generated source code, we will add some additional references we need. Right click the reference item and choose ‘Add Reference…’.

Mark the entries for ‘System.Web’ as well as ‘Windows Sharepoint Services’ and click Add and OK. Now you’ll find the chosen references under the references node in your solution explorer.

If you don’t use Windows Server 2003 as development platform (which is a good idea when you want to develop for Sharepoint), you need to get a copy of the Microsoft.Sharepoint.DLL. To use the namespace inside this DLL you have use the Browse-tab on the Add References dialog. Browse to the DLL and add it as reference too.

Just for clarification about what happens later on with these references … they are passed on to the compiler as a command line parameter. Meanwhile it is sufficient to know that after adding these references, we are able to use the classes from the namespace of these references.

So the next step is to change the generated source code. To do so, double click on the WPVulcan.PRG node in the solution explorer; it takes you automatically to the editor window where you find this code:

// Library.prg

CLASS foo

CONSTRUCTOR() CLASS foo
   RETURN

METHOD Hello() AS VOID CLASS foo
   ? "Hello from Vulcan"
RETURN

It reminds us of the structure of a class definition, but makes no sense at all. Let’s start making life a little bit more comfortable by adding some using statements at the beginning of our source code:

using System
using System.ComponentModel
using System.Web.UI
using System.Web.UI.WebControls
using System.Xml.Serialization
using Microsoft.SharePoint
using Microsoft.SharePoint.Utilities
using Microsoft.SharePoint.WebPartPages

With these using directives we are allowed to use class names (datatypes) out of these namespaces without the full qualified name. E.g. we are allowed to write WebPart instead of Microsoft.SharePoint.WebPartPages.Webpart. This saves us  a lot of typing. As we already mentioned, a web part must inherit from the WebPart class, so naturally this is the next thing to do:

CLASS WPVulcan inherit WebPart

Fortunately we don’t have to deal with VO legacy code here, so we use the new stuff inside Vulcan.NET to become a good .NET citizen. For that reason we don’t use an init method, we use a constructor instead:

CONSTRUCTOR() CLASS WPVulcan
  SUPER()
  RETURN

The Web Part class itself is not meant to used directly, it simply implements no functionality. So we have to add a little functionality, just to bring something on the screen. Without knowing how these famous ASP.NET controls work it is fairly hard to do such thing. We start with something very simple: we use a text-control which displays some pretty useless information. Before a web part is asked for rendering its content to HTML, the sharepoint runtime calls a method named CreateChildControls() on it. In this method one will usually register all controls that should be used inside this web part. Due to the static behavior of a text-control, we’re going to use this.

METHOD CreateChildControls() AS VOID CLASS WPVulcan
  local oControl as LiteralControl
  oControl := LiteralControl{"Hi DevFest2006"}
  self:Controls:Add(oControl)
RETURN

LiteralControl is similar to a FixedText in Visual Objects with the difference, that it will render its content to HTML. So what we are doing here is instantiate a LiteralControl and add it to the controls collection of the web part.

Now we’re prepared to build the DLL, so choose Build->Build the solution from the menu of VS. If everything has gone well, you should see something like

----- Build started:
  Project: WPVulcan, Configuration: Debug .NET -----
===== Build: 1 succeeded or up-to-date,
  0 failed, 0 skipped =====

right under the source code editor window.

Now the fun part starts

Completing the project / solution

Now the fun part starts. Unlike applications made with Visual Objects, we need to do some additional things, before we are able to test our new web part. In VO or other Win32 programming environments we would have copied our DLL somewhere, hook it into the hosting application anyhow and there we are. In .NET everything is different, at least in environments like ASP.NET and SharePoint, where security plays an important role. We have to keep in mind that our web part might be delivered to other web sites as well and therefore one need some mechanism to ensure the web part is safe and unchanged since it left it’s publishing source. This is also needed to install such a DLL in the global assembly cache (GAC). The solution to this is a so called strong name. The .NET environment includes a tool which is able to generate the needed information so that we can sign our component with this strong name. Open up a command line environment with the path pointing to the .NET environment (usually there’s an menu entry in your system). Change to the directory were you’ve generated the DLL (look for debug/release). I am using the directory C:\PROJEKTE\DevFest2006\WPVulcan\Release for this. Now enter

sn -k key.snk

The tool is generating a file named key.snk which holds pairs of generated keys which can be used to sign the DLL. Switch back to VS and open the properties of the WPVulcan-project by right-clicking its node in the solution explorer (leave the command prompt open, we’ll need it again in a moment). Search for the signing section and enter the complete path to the generated key.snk file into the key file field (including the filename).

Now rebuild the DLL. Due to the new entry in the project property VS will now sign the DLL after the build. To verify the signing process and to obtain the public key token, go back to the command prompt and enter

sn -T WPVulcan.dll

The tool should response with something like:

Microsoft (R) .NET Framework Strong Name Utility
  Version 2.0.50727.42
Copyright (c) Microsoft Corporation.
All rights reserved.

Public key token is e8ace06f126e6ee4

Write down the token, we’ll need this in a second.

Now we are ready to publish the web part on our server.  Due to fact that we’re lazy we don’t want to do the necessary modifications on the SharePoint server manually (this can be a real nightmare). We’re planning to install the package through a little tool named stsadm.exe which is available on every SharePoint installation. To install a web part this way, we need to build a CAB-file with all needed stuff. VS 2005 can help us to build such a file. In fact, this is very easy to achieve. Select the root node in the solution explorer which represents the solution itself. Right click and choose Add->New project ….

Expand the node ‘Other Project Types’ and choose ‘CAB Project’ there, enter a project name, e.g. WPVulcanSetup, and click the OK-button. You’ll see there’s a new node in your solution explorer which represents this CAB file project. Next we need to add some output to it. So right click the CAB file project and choose Add->Project Output…

Choose ‘Built’ and ‘ContentFiles’ and add them to the CAB file project. Now rebuild the complete solution. After that process (if everything went well), you’ll find a CAB file in the CAB project release directory, which can be used to do the installation on the SharePoint server.

Installing the Web Part on the SharePoint Server

There are different ways to do this, I am just going to show you one way. Copy the just generated CAB file to your target server, the one with Windows SharePoint services running on it. Open a command line and make sure your environment path is pointing to the directory where the SharePoint binaries are installed. On my machine this is C:\Programme\Gemeinsame Dateien\Microsoft Shared\web server extensions\60\BIN.

Now issue the following command:

STSADM –o addwppack –filename wpvulcansetup.cab

Usually the STSADM.EXE will install your web part and respond with a successful installation. In our case not, because there’s something missing.

wpvulcansetup.cab: The file manifest.xml does not exist
  in the CAB file. The Web Part deployment failed.

As the admin complains, we need to add a manifest.xml to our cab-file. Well we add it to our WPVulcan project as the home of our source files and then to the cab project. Here’s the content of the mainifest.xml we need:

   "http://schemas.microsoft.com/WebPart/v2/Manifest">
 
   
     
     
           
       
     
      -->
     
                  Namespace="WPVulcan"
          PublicKeyToken="e8ace06f126e6ee4"
          TypeName="*"
        />
     
   
 
 
   
 

The Manifest file, a configuration file that describes the structure and contents of the .CAB file, is the only required component for the .CAB file. The STSADM.exe tool uses this file to deploy the remaining content of the .CAB file.

While we’re adding files to our WPVulcan project, we just add another one, the so called DWP-file. This file is use by the Sharepoint Server to register the web part in its galleries and internal lists. As you can see in manifest.xml this file is already referenced there. So let’s add both to our WPVulcan project. Right click the project node in the solution explorer and choose Add->New Item… In the upcoming dialog choose Web on the left side and the NewXMLPage on the right side and enter Manifest in the name edit control, and click OK. Now you’ll find a new node in the solution explorer, double click on it to activate the source code editor and insert the source code above into the editor. Having done that with manifest.xml do the same with the dwp-file. Pay attention to the filename extension. Here’s what you have to put in there :

  xmlns="http://schemas.microsoft.com/WebPart/v2" >
 
 
   This webpart is MSM's first try to write a web part
   using Vulcan.NET
 
  WPVulcan
  WPVulcan
 

After adding them to the WPVulcan project, mark the CAB file project, right click the project and chosse Add->File… Then go the the WPVulcan project directory (release) and chose manifest.xml and wpvulcan.dwp, then click OK. Having done that, rebuild the solution and try to run the stsadm.exe again.

stsadm -o addwppack -filename wpvulcansetup.cab

Usually, if done nothing wrong, the call should result into (depending on the server):

wpvulcansetup.cab: Deploying to http://vm2003/.
Operation completed successfully.

Congratulations ! You’ve done the first web part using Vulcan.NET as development platform.

Testing the Web Part

The last task we have to talk about is testing the newly created web part. This is straight forward and differs not from the way you would use other, predefined and installed, web parts. Navigate to one of your Sharepoint sites which runs on the server you’ve recently installed your web part on (my advice would be to setup a testpage).

In the upper right corner, you’ll find a small drop down menu ‘Modify Shared Page’, click on it and choose Add Web Parts->Browse.

You recently switched the page in edit mode and you can drag and drop a specific web part into one of the web part zones. You will find our web part if you choose the Virtual Server Gallery, that’s where STSADM installed our web part. Grap the little icon and drag it to the web part zone where you want it to display its result. Here’s a more sophisticated web part in action:

Here’s the corresponding Vulcan.NET code for this web part:

METHOD RenderWebPart(output as HtmlTextWriter) ;
    AS VOID CLASS WPVulcan
  local ht   as ;
    System.Collections.Specialized.NameValueCollection
  local arr  as System.String[]
  local i    as int
  local link as System.Web.UI.WebControls.HyperLink
 
  output:RenderBeginTag("div")
  ht := ;
    System.Collections.Specialized.NameValueCollection{}
  ht:Add("http://.../ODC_office01012004.asp",;
         "Developing ... XML Toolbox")
  ...
  ht:Add("http://...odc_XMLLists.asp",;
        "Importing XML Maps, ... in Excel 2003")
        
  arr:=ht:AllKeys
  for i:=1 upto arr:GetUpperBound(0)
    link := HyperLink{}
    link:NavigateUrl:=arr[i]:ToString()
    link:Text:= ;
      ht:GetValues(arr[i]:ToString())[1]:ToString()
    output:RenderBeginTag("p")
    link:RenderControl(output)
    output:RenderEndTag()
  next
  output:RenderEndTag()

return

As you see there’s no big secret here. Every control that inherits from System.Web.UI.Control has to implement a Render* method. In case of a web part this is a method named RenderWebPart. Here’s where the included controls are asked to render themselves and where we encapsulate the HTML output in our own needed HTML tags (like the DIV tag at the beginning of the method).

Conclusion

Time to look back. We’ve seen that Vulcan.NET is a full NET citizen and equal of level compared to other .NET programming languages like C#, VB.NET and others. What we experienced during the session is what we have to expect in the future. Due to the good knowledge of Visual Objects it should be absolutely no problem to do the coding itself. The biggest challenge is to learn the data types and classes available in the .NET framework. Another challenge is to learn how all these wonderful technologies based on .NET are working together and can be used by our own applications.