Print Story

As portals gain in popularity, both as consumer-focused information portals and corporate collaboration tools, developers are increasingly being told to integrate customized portal features. In this article, I'll take a look at the solutions Microsoft offers for creating Web portals and how you can extend these portals by building custom modules.

The Microsoft Web Portal Landscape
Microsoft currently offers three levels of portal creation technologies as shown in Figure 1. The first and lowest level is ASP.NET 2.0's Web Parts framework. This framework includes the core infrastructure needed to build a basic Web portal such as base Web Part classes and Web Part management classes. Although the framework lets you build a basic Web portal, it doesn't include any pre-build Web parts or information repository capabilities.

The next level is Windows SharePoint Services 3.0 or WSS. This free component of Windows Server 2003 leverages the ASP.NET Web Parts framework and offers the entire infrastructure needed to create a basic Web portal including pre-build functionality for user management, document collaboration, and workflow.

Finally, you can use Microsoft Office SharePoint Server 2007, or MOSS. This product builds on WSS and offers much tighter integration with Microsoft Office, including better document management and search features, wikis, and blogs.

A list of the feature set differences between WSS and MOSS can be found at http://office.microsoft.com/en-us/sharepointtechnologyFX101758691033.aspx.

From a development perspective though, the great thing about all of these solutions is that they are built on the same core, the ASP.NET Web Parts Framework. This means that, for the most part, you can build a custom Web part using a single base class and leverage that Web part in any one of these portal solutions. It's only when you explicitly decide that you require specific WSS or MOSS platform features that you have to choose whether you want to base your Web parts off of the ASP.NET Frameworks base WebPart class, or the SharePoint base WebPart class (which itself is simply derived from ASP.NET's WebPart base class!). If you need help deciding which base class to use, the Microsoft MSDN article "Working with ASP.NET 2.0 Web Parts and Windows SharePoint Services 3.0" offers advice. See http://msdn2.microsoft.com/en-us/library/bb153523.aspx.

Building a Basic ASP.NET Web Part
Building a basic ASP.NET-based Web part is actually quite easy. To get started, create a new Class Library project and add a new Web Custom Control file to the project. This Visual Studio template provides most of the basic infrastructure you'll need to start creating the Web part.

Once your project is set, there are a few small changes you need to make to the Web Custom Control. First, to be able to reference the objects needed to create the Web part, you need to add the WebParts namespace to the class

using System.Web.UI.WebControls.WebParts;

And now that the class knows about the WebParts namespace, you need to change the base class that the Web part derives from. By default a custom Web control derives from the WebControl class, but since this is a Web part, you want it to derive from the WebPart class, which is in the WebParts namespace you added in the first step:

public class SimpleWebPartSample : WebPart

That's it! You now have a fully functioning Web part, though admittedly it doesn't provide much functionally, simply writing out the value of the Text property. You can test out the Web part by creating a Web Parts Page. As an example, you can use the Web Parts Page created by the great "Creating an ASP.NET Web Parts Page" walk-through, available on MSDN at http://msdn2.microsoft.com/en-us/library/kswx7h7e.aspx.

To test out the custom Web part, simply replace the linksPart Label with the custom Web part control as shown in Listing 1.

Deriving from the WebPart base class lets ASP.NET know that it should treat this control as a WebPart rather than a standard Web control. This means that ASP.NET will automatically add the base features of a WebPart such as the ability to change the location of the WebPart from one WebPartZont to another, adding the default control chrome, including the title and the action menu, and including this control in the PageCatelogPart. Additionally, by deriving from the WebPart base class, you now have a bunch of extra properties that you can use to control all of the basic chrome features. For example, if you didn't want to allow your Web part to be closed by the user, you could simply set the WebParts default AllowClose property to False:

<cc1:SimpleWebPartSample ID="SimpleWebPartSample1" Title="Sample Web Part" Text="This is my custom Web Part"
runat="server" AllowClose="False" />

Another great Web part feature that you get for free is the ability to let your users move parts around to different WebPartZones on your page. To see this simply add another WebPartZone control to your Web page. When you put the page in Edit mode, you can grab the custom Web parts title and drag it to the new WebPartZone.

To learn more about how this is done, see "Changing Display Modes on a Web Parts Page" at - http://msdn2.microsoft.com/en-us/library/bw5tctbb.aspx

Now that the basic Web part is in place, you can use the standard ASP.NET custom server control techniques to add functionality to the part. For example, you could create a more complex Web part that uses the Reuters news services RSS feeds to display a list of the top news stories. To do that you can modify the RenderContents method and add additional rendering logic. In this case, the method grabs the RSS feed and loops through all of the news items, generating new content for each item as shown in Listing 2.

Once the RenderContent is changed the Web part is now rendered as a more complex controls as shown in Figure 2.

Keep in mind that although this sample uses RenderContents to add the additional rendering logic using the HtmlTextWriter, as with custom WebControl creation practices, there are several means to an end. Instead of manually writing out HTML tags and attributes, you could instantiate instances of other ASP.NET controls like Label and Button, and add them to the WebParts Controls collection. In that case you'd probably want to override the Web part's CreateChildControls method and add the ASP.NET controls there.

    protected override void CreateChildControls()
    {
       base.CreateChildControls();

       Label label = new Label();
       label.Text = "Enter Search Phrase: ";

       TextBox textbox = new TextBox();

       Button button = new Button();
       button.Text = "Search";

       this.Controls.Add(label);
       this.Controls.Add(textbox);
       this.Controls.Add(button);
    }

Using this method, you can leverage pre-existing ASP.NET controls within a custom Web part.

That's all it takes to create custom ASP.NET Web parts. But what if you wanted to take this part and host it inside of the ASP.NET WebPart Framework's big brother, WSS?

Deploying an ASP.NET Web Part to WSS
Deploying your custom Web part into a WSS environment is quite simple and in fact is identical for both environments. First you have to decide where you want your Web parts assembly to be kept. As with all .NET applications you can choose either the Sharepoint applications Bin directory or the Global Assembly Cache (GAC).

Note that if you choose to keep the Web parts assembly in the Bin directory, you have to add the AllowPartiallyTrustedCallers attribute to the assembly's AssemblyInfo file. This is because the Bin directory isn't a full trust location, so you need to tell .NET to allow your assembly additional rights.

[assembly: AllowPartiallyTrustedCallers()]

Once your assembly is in place, you need to tell WSS that it's safe to load the Web parts in the assembly. WSS works on an opt-in model, only loading Web parts from assemblies that are explicitly listed as safe. To do this, all you have to do is add an entry to the SafeControls section of the WSS application's Web.config file. If you're using the default root instance of WSS, then the application root should be: C:\Inetpub\wwwroot\wss\VirtualDirectories\80

Once you've found the Web.config, open it and locate the <SafeControls> config section and add the following entry, substituting your assembly name and namespace in:

The final step in adding the custom Web part to WSS is create a .Webpart file, which is a small XML file that describes your Web part to WSS. WSS can create it for you automatically. Simply navigate to http://MyServer/_layouts/newdwp.aspx and you should see the Web part you added to the Bin directory listed. Simply check the checkbox located next to the Web Part type and click the Populate Gallery button. You should now see your custom Web part listed in the Web Part Gallery, and the part is now available for use by your WSS users.

Figure 3 demonstrates the same Web part used in a SharePoint portal Web site. You can see that it appears identical to its use in the ASP.NET portal framework. And, because it's being used in the SharePoint site, it inherits all of the normal SharePoint WebPart behavior.

Adding WSS-Specific Functionality
Now that you've seen how easy it is to create a basic Web part you can use in any of the Microsoft Web portals, let's take a look at how you can integrate SharePoint-specific features into the Web part. SharePoint includes a rich set of APIs that you can use in your Web part simply by adding a project reference to the Microsoft.Sharepoint.dll assembly.

Note: The Microsoft.Sharepoint.dll assembly is installed with WSS so to add it as a project reference you either need to be developing on a machine that has WSS installed or you can copy the assembly to your development machine from your WSS server.

The Windows SharePoint Services SDK includes a help library that offers documentation for the public SharePoint APIs. See Click Here!.

Once you've added the assembly reference to your project, you can add the necessary using statements to your Webpart class:

using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using Microsoft.SharePoint.WebPartPages;

Now you can begin to add Sharepoint-specific features to the Web part. For example, you could customize the previous sample to include a greeting for the currently logged in user:

SPSite site = SPControl.GetContextSite(Context);
SPWeb Web = site.OpenWeb();

output.RenderBeginTag(HtmlTextWriterTag.P);
output.Write("{0}'s Top Stories", Web.CurrentUser.Name);
output.RenderEndTag();

In this case, you can use the SPSite and SPWeb objects to get a reference to the currently open SharePoint Web site. From there the sample adds a caption to the Web part that includes the current users Name.

Using the SharePoint APIs can add significant power to your custom Web parts, from creating new SharePoint Sites and Users to retrieving list and document information, they let you create powerful and flexible Web parts.

Deriving from the SharePoint WebPart Base Class
Although Microsoft recommends that you create ASP.NET 2.0 Web parts whenever possible, there are certain situations where you need to integrate specific types of SharePoint functionality into your Web parts that require you to derive from Microsoft.SharePoint.WebPartPages.WebPart. The SharePoint SDK documentation lists the four reasons you'd want to derive from the SharePoint WebPart base class as:
  •   You need to use cross-page connections
  •   You need connections between Web parts that are outside of a Web part zone
  •   You need client-side connections (Web Part Page Services Component)
  •   You want to leverage the data caching infrastructure that allows caching to the content database

If you want to use any of these features you need to make sure your Web Part class derived from Microsoft.SharePoint.WebPartPages.WebPart.

Embedding Client-Side Script in a Web Part
Since SharePoint is a Web-based technology, you may eventually need to write a Web part with JavaScript-based client-side functionality. In older versions of SharePoint dealing with this was quite painful, but beginning with WSS 3.0, you can simply change the script files Build Action property to "Embedded Resource" and use ASP.NET's WebResource assembly attribute.

[assembly: WebResource("Infragistics.Guidance.Sharepoint.SimpleWebPartSample.js", "text/javascript")]

Now in your Web Part class you can register the JavaScript resource in the Web Parts OnPreRender event:

protected override void OnPreRender(EventArgs e)
{
base.OnPreRender(e);

Page.ClientScript.RegisterClientScriptResource(this.GetType(),
"Infragistics.Guidance.Sharepoint.SimpleWebPartSample.js");
}

This sample shows the use of ASP.NET's RegisterClientScriptResource method, which is used to register the JavaScript resource with the Web page.

Wrap Up
Portals continue to grow as a popular way to create Web sites that let end users create customized content aggregators and facilitate collaboration. And Microsoft ASP.NET WebParts Framework and SharePoint products offer great solutions for building portal applications. The flexible and powerful Web parts architecture lets you extend your portal with custom Web parts using the same basic control development techniques you're already familiar with, while at the same time leveraging the power and infrastructure Microsoft provides in its APIs.

How To Design, Build, and Deploy Custom Web Parts