Creating a Basic Web Part

This walkthrough provides the steps for creating a basic custom Web Part that you can add to your Web Part page. It is a simple HelloWorld Web Part demonstrating how to create a Web Part that derives from the ASP.NET 2.0 WebPart class for use in a SharePoint site.

Note:
For more information about ASP.NET Web Parts, see the following ASP.NET 2.0 documentation: ASP.NET Web Parts Quick Start and ASP.NET Web Parts Pages.

Prerequisites

Windows SharePoint Services 3.0

Visual Studio 2005

Step 1: Create an ASP.NET Web Part assembly

To create a simple Web Part, you start by developing an ASP.NET Web Part assembly. To start, you can create a class library project with a class that derives from the System.Web.UI.WebControls.WebParts.WebPart base class.

Create an ASP.NET Web Part Assembly

1. Start Visual Studio 2005.

2. Start a new C# class library project.

3. Type HelloWorldWebPart as the project name.

4. Add a reference to System.Web.

5. In your .cs file, copy and paste in the following code:

   C#

   Copy Code

   using System;
   using System.Text;
   using System.Web.UI.WebControls.WebParts;
   namespace MyWebPartLibrary
   
   {
    public class HelloWorldWebPart : WebPart
      {
       protected override void Render(System.Web.UI.HtmlTextWriter writer)
        {
           writer.Write("Hello, World!");
        }
      }
   }
   

6. Compile the solution. Now you have an assembly that contains your HelloWorldWebPart Web Part.

Step 2: Place your assembly in the bin or global assembly cache

Within a SharePoint site, you can deploy a Web Part assembly to one of two locations:

• bin directory: The bin directory is a folder stored in your Web application root directory. For more information, see How to: Find the Web Application Root.

  Note:
  If a bin directory does not exist you must add one. Web Parts cannot be stored in the _app_bin directory.

• global assembly cache: The global assembly cache enables you to share assemblies across numerous applications. The global assembly cache is automatically installed with the .NET runtime. Components are typically stored in C:\WINNT\Assembly.

Each location has advantages and disadvantages, as described in the following table.

Deployment Location	Advantages	Disadvantages
bin directory	A partial trust location. By default, code that runs from this directory has a low level of code access security (CAS) permissions. Because administrators must explicitly raise permissions granted to a Web Part so it can function properly, they can prefer that assemblies run in the bin directory with a known set of required CAS permissions. A bin directory is specific to a Web application. This makes it possible to isolate code to a particular Web application.	If you want your Web Part to run everywhere, you would need to deploy your bin assembly.
global assembly cache	A global location where signed assemblies can be deployed. Assemblies run with full trust by default. They are globally installed, so they will work in any Web application.	Generally no CAS restrictions on code installed to the global assembly cache; therefore, you lose the defense-in-depth security benefit.

For the purposes of this sample, we are placing the assembly in the bin directory.

Step 3: (Optional) If using the bin directory, set special security attributes

By default, code access security permissions for the bin directory are low; only pure execution is allowed. Although the sample in this walkthrough can run with the minimal trust level, in most cases you need to elevate these permissions to make your assembly run correctly, for example, if your Web Part requires access to the SharePoint object model.

There are two ways to elevate permissions:

• (Recommended) Create a new trust policy file, and point your web.config file at the new file. This option is more complicated but it gives you a precise attribution of permissions for your Web Parts.

  For more information about trust policy files, see Microsoft Windows SharePoint Services and Code Access Security.

• Raise the net trust level of the bin directory. In the web.config file in the Web application root, there is a tag called with a default attribute of level="WSS_Minimal". You can change this level to WSS_Medium. While this option is simpler, it grants arbitrary new permissions you might not need and is less secure than creating a new trust policy file.

To raise the trust level of the bin directory

1. Locate the web.config file in your application root and open it for editing.

2. Locate the trust level tag, . Change the trust level to WSS_Medium.

Step 4: Add your Web Part to the SafeControls List

A fundamental assumption of the Windows SharePoint Services technology is that untrusted users can upload and create ASPX pages within the system on which Windows SharePoint Services is running. To prevent these users from arbitrarily adding server-side code within ASPX pages, Windows SharePoint Services provides a SafeControls list, which is a list of approved controls that they can use.

The SafeControls list is a list of controls and Web Parts specific to your 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.

To add your Web Part to the Safe Controls list

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

2. Add a safe control entry for your custom assembly to the web.config file as follows:

   [xml]

Step 5: Create a .webpart file for your Web Part

Every Web Part should have a .webpart file, which is an XML file that describes the Web Part. The .webpart file also makes your Web Part appear in the Web Part gallery. This procedure describes the easiest way to create a .webpart file.

To Create a .webpart file for your Web Part

1. After you have deployed your Web Part and registered it in the Safe Control list, navigate to http://myserver/_layouts/newdwp.aspx, where myserver is the name of the server on which your SharePoint site is deployed.

2. Select the check box next to MyWebPartLibrary.HelloWorldWebPart.

3. Click Populate Gallery and the Web Part is added to the Team Site Gallery.

   Note:
   To create a .webpart file for your Web Part, you can select Edit for the Web Part in the Web Part Gallery, and then click Export. You are prompted to provide a location in which to put the .webpart file.

Step 6: Add your Web Part to a Page

In this step, you import the Web Part to a page in any SharePoint site. The following procedure explains the steps for adding the Web Part to a page.

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 HelloWorldWebPart, click Add a Web Part.

4. At the bottom of the Add Web Parts dialog box, click Advanced Web Part gallery and options.

5. Open the Team Site Gallery and drag the HelloWorldWebPart onto the page. The Web Part displays the SharePoint look and feel.