Walkthrough: Creating a Basic Web Part

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This walkthrough provides the steps for creating a basic custom Web Part that can be added to your Web Part Pages. It is a simple Web Part that allows the user to define a custom message to be displayed inside the Web Part. This Web Part will derive from the ASP.NET 2.0 Web Part class, which is the recommended practice for Windows SharePoint Services. Note that this walkthrough describes how to create a Web Part without the Visual Studio Extensions for Windows SharePoint Services.

For more information about ASP.NET Web Parts, see the following ASP.NET documentation: ASP.NET QuickStart Tutorials and ASP.NET Web Parts Controls.

Note

You can also develop your Web Parts by using the Visual Studio Extensions for Windows SharePoint Services. By using these extensions, you can greatly reduce the work involved in creating and deploying your Web Parts. The extensions require development in a server environment, and offer the following benefits: Automatic generation of your solution package Automatic generation of the WebPart XML file Ability to deploy Web Parts directly from inside Visual Studio to your Web site For guidance on using the extensions or to download extensions for Visual Studio 2005 or Visual Studio 2008, see Windows SharePoint Services 3.0 Tools: Visual Studio 2005 Extensions User Guide, Version 1.1 Windows SharePoint Services 3.0 Tools: Visual Studio Extensions, Version 1.1 Windows SharePoint Services 3.0 Tools: Visual Studio Extensions, Version 1.2

Prerequisites

Windows SharePoint Services 3.0

Visual Studio 2005

Step 1: Create an ASP.NET Web Part assembly

To create a Web Part, you start by creating a class library project that derives from the WebPart base class.

To create an ASP.NET Web Part Assembly

1. Start Visual Studio 2005

2. On the File menu, point to New, and then click Project.

3. In Project Types, under Visual Basic or C#, select Windows.

4. In the Templates pane, select Class Library.

5. Type Sample.DisplayMessage as the project name.

Step 2: Rename the base class and add required namespaces

After you create the project, a blank class file is displayed. You can change the default class name of Class1 to easily identify your new Web Part. In a class library, only a few namespaces are included. You must add two required namespaces and references to their assemblies. You must also derive the base class from WebPart.

To add namespace references and rebase your Web Part

1. Rename the default class by selecting Class1 in Solution Explorer, right-click, click Rename, and type DisplayMessageWebPart as the file name.

2. On the Project menu, click Add Reference.

3. In the Add Reference dialog on the .NET tab, select System.Web and click OK.

4. In the references area of the class file, add a reference to System.Web.UI.WebControls.WebParts and rebase your class to inherit from WebPart, as shown in the following code sample.

   using System;
   using System.Collections.Generic;
   using System.Text;
   using System.Web;
   using System.Web.UI.WebControls.WebParts;
   
   namespace Sample.DisplayMessage
   {
       public class DisplayMessageWebPart : WebPart
       {
       }
   }
   

   Imports System
   Imports System.Collections.Generic
   Imports System.Text
   Imports System.Web
   Imports System.Web.UI.WebControls.WebParts
   
   Public Class DisplayMessage
       Inherits WebPart
   
   End Class
   

5. You have now created a basic structure for the Web Part.

Step 3: Add a user-customizable Web Part property

After configuring the new class to act as a Web Part, add a customizable property for the Web Part.

The Web Part property determines the text that is rendered inside the Web Part. This is customized on the basis of the individual user.

Note

For more information about customization and personalization, see Web Parts Personalization.

For Web Parts based on the ASP.NET Web Parts Pages base class, the tags that are used for the customizable properties are named differently than Web Parts that are based on the WebPart base class. The following list describes each of those properties:

• The WebBrowsableAttribute class attribute ensures that your custom property renders in the editing tool pane in Windows SharePoint Services.

• The WebDescriptionAttribute class attribute displays a tooltip to help guide users when editing your custom property.

• The WebDisplayNameAttribute class attribute shows a display name for your custom property.

• The PersonalizableAttribute class attribute determines if changes to your custom property affects all users or on a per-user basis.

To create the Web Part property

1. In the DisplayMessageWebPart file, copy and paste the following code to create a basic customizable property.

   private string customMessage = “Hello, world!”;
   
   public string DisplayMessage
   {
       get { return customMessage; }
       set { customMessage = value; }
   }
   

   Private customMessage As String = “Hello, world!”
   
   Public Property DisplayMessage() as String
       Get
           Return customMessage
       End Get
       Set(ByVal value as String)
           customMessage = value
       End Set
   End Property
   

2. Then, add the following tags above the public declaration to allow changes on a per-user basis:

   [WebBrowsable(true),
   WebDescription("Displays a custom message"),
   WebDisplayName("Display Message"),
   Personalizable(PersonalizationScope.User)]
   

   <WebBrowsable(True), _
   WebDescription("Displays a custom message"), _
   WebDisplayName("Display Message"), _
   Personalizable(PersonalizationScope.User)> _
   

3. Now you have created a customizable Web Part property.

Step 4: Override the Render method and build your Web Part

Now you must add functionality to your Web Part. By overriding the Control.Render Method, you can tell the Web Part what operations to perform when the page is visited. In this example, the Web Part will render the user-defined text.

To override the Render method and compile the assembly

1. In the DisplayMessageWebPart file, copy and paste the following code to override the Render method.

   protected override void Render(System.Web.UI.HtmlTextWriter writer)
   {
       writer.Write(DisplayMessage);
   }
   

   Protected Overrides Sub Render(ByVal writer As System.Web.UI.HtmlTextWriter)
       writer.Write(DisplayMessage)
   End Sub
   

2. Compile the solution. Now you have an assembly that contains your DisplayMessageWebPart Web Part.

Step 5: Place your assembly in the bin directory or global assembly cache

Within a SharePoint site, you can deploy a Web Part assembly to one of two locations listed below. Note that the recommended practice is to deploy assemblies to the bin directory.

• bin directory — The bin directory is a folder stored in your Web application root directory. For most installations, this is located in the %SYSTEMDRIVE%\inetpub\wwwroot\wss\VirtualDirectories\<port number>\bin directory, but if you need more information, see How to: Find the Web Application Root.

• Global Assembly Cache (GAC) — The GAC enables you to share assemblies across numerous applications. The GAC is automatically installed with the .NET framework runtime. Components are typically installed in the %SYSTEMDRIVE%\WINDOWS\Assembly directory.

For more information about choosing the correct deployment location, see Deploying Web Parts in Windows SharePoint Services.

For the following example, place the assembly in the bin directory.

Step 6: Add your Web Part to the SafeControls list

Windows SharePoint Services provides a SafeControls list to prevent users from arbitrarily adding server-side code within ASPX pages. The SafeControls list is a list of approved controls and Web Parts that are specific to the SharePoint site that you have designated as safe for invocation on any ASPX page within your site. This list is contained in the web.config file in your Web application root. The local path contains the physical location of the web.config file.

Note

The web.config file is located in the folder where the virtual directory for the Web site is located. This is normally c:\inetpub\wwwroot\wss\VirtualDirectories&lt;port number>, but your administrator may have set up your directory differently and this may not be the location of the file. You can find the location of your web.config file with the Internet Information Services (IIS) snap-in. The IIS snap-in is an administration tool for IIS that has been integrated with other administrative functions. To launch the IIS snap-in and locate the web.config file: Click Start, point to Programs, point to Administrative Tools, and click Internet Information Services (IIS) Manager. Expand the node that is the name of your computer, and expand the Web Sites item in the tree Locate the Web site that is running your Windows SharePoint Services installation (often it is Default Web Site). Right-click and select Properties. Select the Home Directory tab.

To add your Web Part to the SafeControls list

1. Open the web.config file in the application root.

2. In the SafeControls section of your web.config file, add a SafeControls entry for your custom assembly in the web.config file as follows.

   <SafeControl Assembly="Sample.DisplayMessage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" Namespace="Sample.DisplayMessage" TypeName="DisplayMessageWebPart" Safe="True" />
   

Step 7: Add your Web Part to the Web Part gallery

In order to add your Web Part to a Web Part page, you must add it to the gallery.

To add your Web Part to the Web Part Gallery

1. Navigate to the page on your SharePoint site where you want the Web Part to be accessible.

2. In the Web Part page, click Site Actions, and select Site Settings.

3. On the Site Settings page, click Web Parts under the Galleries heading.

4. On the toolbar in the Web Part gallery, click New.

5. In the New Web Parts list, check the box next to Sample.DisplayMessage.DisplayMessageWebPart and click Populate Gallery.

6. Your Web Part can now be added to any Web Part page.

Step 8: Add your Web Part to a Web Part Page

In this step, you import the Web Part to a page in any SharePoint site and test the custom property you added to the Web Part. The following procedure explains the steps for adding the Web Part to a page and changing the Display Message custom property.

To add and test your Web Part

1. Navigate to the Web Part page on your SharePoint site where you want to add the Web Part.

2. In the Web Part page, click Site Actions, and select Edit Page.

3. In the Web Part zone where you want to add the DisplayMessageWebPart, click Add a Web Part.

4. On the Add Web Parts dialog, find the Miscellaneous category under All Web Parts and check the box next to DisplayMessageWebPart. Click Add.

5. To modify the text displayed on the Web Part, choose Modify Shared Web Part from the chrome drop-down list.

6. In the DisplayMessageWebPart properties pane, expand the Miscellaneous category and change the Display Message value. Click Apply.

7. Now the Web Part is displaying the user-defined value inside the Web Part.

See Also

Tasks

Walkthrough: Creating a Basic SharePoint Web Part