Creating a Basic Web Part

This programming task provides the steps for creating a basic custom Web Part that you can add to your Web Part Page. It is a very simple Web Part that allows you to change the Web Part‘s Title property. The Title property is a Web Part base class property that sets the text in the part‘s title bar.

Requirements

Microsoft Visual Studio .NET

Microsoft Windows SharePoint Services

Starting a Web Part project

Web Parts are based on ASP.NET Web Form Controls. You create Web Parts in C# or Visual Basic .NET by using the Web Part Library template in Visual Studio .NET. The Web Part templates can be downloaded from MSDN. After you download and install these templates, you can proceed with creating a Web Part using C# as described in this topic.

To create a new Web Part Library project  

• Start Visual Studio .NET.
• On the File menu, point to New, and then click Project.
• In the New Project dialog box, click Visual C# Projects, and then select the Web Part Library template.

  Note  If you want to create a Visual Basic .NET project, select the Web Part Library template from Visual Basic Projects instead.

• Type SimpleWebPart as the name and specify the location for the project files, and then click OK.

On the other hand, if you do not want to download the templates, you can choose to create a Web Part by starting with the ASP.NET Web Control Library template.

To create a new Web Control Library project  

• Start Visual Studio .NET.
• On the File menu, point to New, and then click Project.
• In the New Project dialog box, click Visual C# Projects, and then select the Web Control Library template.

  Note  If you want to create a Visual Basic .NET project, select the Web Control Library template from Visual Basic Projects instead.

• Type SimpleWebPart as the name and specify the location for the project files, and then click OK.
• To create a Web Part, you need to add a reference to the Microsoft.SharePoint assembly (Microsoft.SharePoint.dll) in your Web Control Library project. If you‘re working from Visual Studio .NET installed on a server running Microsoft Windows SharePoint Services, the Microsoft.SharePoint assembly will be registered and available from the Add Reference dialog box. If you want to develop Web Parts on another computer, you will need access to a server running Windows SharePoint Services. On the server computer, copy Microsoft.SharePoint.dll from the C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI folder to a folder on the computer where you will be developing Web Parts, and follow the steps in this topic to add a reference. You will also need to add a reference to System.Xml.dll to support the System.Xml.Serialization namespace which is used to define the XML namespace for serializing custom properties, as described later in this topic.
  
  To add a reference to Microsoft.SharePoint.dll to a project  

  If you are creating a Web Part on a computer that has Windows SharePoint Services or SharePoint Portal Server installed on it:

  • On the Project menu, click Add Reference.
  • On the .NET tab, double-click Windows SharePoint Services.
  • Click OK.

  If you are creating a Web Part on a computer that does not have Windows SharePoint Services or SharePoint Portal Server installed on it:

  • On the Project menu, click Add Reference.
  • On the .NET tab, click Browse, and then navigate to C:\inetpub\wwwroot\bin (or the folder to which you copied Microsoft.SharePoint.dll). Select Microsoft.SharePoint.dll, and click Open.
  • Click OK.
  To add a reference to System.Xml.dll to a project  

  The same steps apply regardless of whether you are creating a Web Part on a computer that has Windows SharePoint Services or SharePoint Portal Server installed on it:

  • On the Project menu, click Add Reference.
  • On the .NET tab, double-click System.Xml.dll.
  • Click OK.

Initial project settings

Before you start working with the code for a Web Part, you need to make the following changes to your project settings:

• Specify the build output path.
• Set the version number.
• Strongly name the assembly.

Specify the build output path

This task assumes that you are running Visual Studio .NET on a server running Windows SharePoint Services or SharePoint Portal Server. Setting the build output path to the C:\inetpub\wwwroot\bin folder will build your Web Part‘s assembly in the same location from which it will run on your server. If you are not running Visual Studio .NET on your computer, you can copy your Web Part‘s assembly to the folder C:\inetpub\wwwroot\bin folder on your server after building it.

Note  The C:\inetpub\wwwroot\bin folder is one of two default locations where the .NET common language runtime will look for .NET assemblies. The other location is the Global Assembly Cache (GAC), which is exposed in the Windows user interface as C:\windows\assembly. However, if you want to run your Web Part‘s assembly from the GAC, you should not specify C:\windows\assembly as the build output path in Visual Studio .NET. Instead, you should manually copy it using Windows Explorer (drag the file to C:\windows\assembly) or by using the gacutil.exe command-line utility which is located in C:\Program Files\Microsoft Visual Studio .NET\FrameworkSDK\bin. Be aware that the GAC requires you to strong name your assembly.

In addition to the two default locations, you can specify another folder (for example, \inetpub\wwwroot\mydir or \inetpub\wwwroot\mydir2\bin) by specifying those folders in the web.config file for your server by adding the following element block within the element:

To specify the build output path  

• In the Solution Explorer, right-click your project name (for example, SimpleWebPart), and then click Properties.
• Under Configuration Properties | Build | Outputs, set the Output Path to: C:\inetpub\wwwroot\bin.

Set the version number (only if using the Web Control Library template)

By default, the AssemblyVersion property of your project is set to increment each time you recompile your Web Part. A Web Part Page identifies a Web Part with the version number that is specified in the web.config file. (For details, see "Register the Web Part as a Safe Control" later in this topic.) With the AssemblyVersion property set to increment, if you recompile your Web Part after importing it into a Web Part Page, the Web Part Framework will look for the version number you specified in the web.config file. If the version number does not match, an error will occur. To prevent the version number of your Web Part from incrementing each time you recompile, you need to set the version number in AssemblyInfo.cs. These steps are not required if you use the Web Part Library template.

To set the version number  

• In the Solution Explorer, double-click AssemblyInfo.cs.
• Edit the line
  [assembly: AssemblyVersion("1.0.*")]
  so that it reads
  [assembly: AssemblyVersion("1.0.0.0")]

Strongly name the assembly

Web Parts are designed to be distributed over the Internet or an intranet. For security reasons when creating a custom Web Part, you must strongly name it to ensure that the part can be trusted by your users.

A strong name consists of the assembly‘s identity plus a public key and a digital signature. You can use the Strong Name tool (sn.exe) to manage keys, generate signatures, and verify signatures. This tool is installed with the .NET Framework SDK when you install Visual Studio .NET.

To strongly name the assembly  

• Create a file containing the key pair. From a command prompt on the drive where you installed Visual Studio .NET, type the following: cd \Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin\
• Type the following: sn.exe -k c:\keypair.snk

  Note  You can use any path, as long as you reference that path in the following steps.

• In the Solution Explorer, double-click AssemblyInfo.cs in your project and edit the line
  [assembly: AssemblyKeyFile("")]
  so that it reads
  [assembly: AssemblyKeyFile("c:\\keypair.snk")]

  Note  Although it is possible to create and use the same strong name key pair file (.snk) for all Web Part assemblies you build, for greater security we recommend that you create and use a different key pair file (.snk) for each assembly you create.

Modifying the default code file (only if using the Web Control Library template)

When you create a project using the Web Control Library template in Visual Studio .NET, a default C# source file called WebCustomControl1.cs is created. The following steps are basic additions and modifications that you make to that default code to create the class for a custom Web Part (these steps will not be required if you use the Web Part Library template):

• Adding namespace directives
• Defining toolbox data
• Inheriting from the WebPart class
• Defining the XML namespace
• Using the RenderWebPart method

To start modifying the default code file  

• In the Solution Explorer, double-click WebCustomControl1.cs.

Adding namespace directives

To make it easier to write a basic Web Part class, you should use the using directive to reference the following namespace in your code:

• The Microsoft.SharePoint.WebPartPages namespace provides the types for Web Part Pages, such as the WebPart class.
• The System.Xml.Serialization namespace provides the XmlRootAttribute and XmlElementAttribute classes that support the XmlRoot and XmlElement attributes used to declare the XML namespace that is used for the serialization of any custom properties implemented by your Web Part.

For the purposes of this sample, we‘re also adding a using directive for the System.Web.UI.HtmlControls namespace because we‘ll use two HtmlControls classes in the rendering of this Web Part.

To add namespace directives  

• Add the following using directives near the top of your code:
  using Microsoft.SharePoint.WebPartPages;
using System.Xml.Serialization;
using System.Web.UI.HtmlControls;

Defining Toolbox data

The ToolboxDataAttribute class specifies the default tag that is generated for a custom control when it is dragged from a toolbox in a tool such as Microsoft Visual Studio.

To define Toolbox data  

• Replace the following line
  [ToolboxData("<{0}:WebCustomControl1 runat=server>")]
  with this line
  [ToolboxData("<{0}:SimpleWebPart runat=server>")]

Inheriting from the WebPart class

A Web Part is compatible with ASP.NET server controls because the Microsoft.SharePoint.WebPartPages.WebPart base class inherits from the same parent class as server controls, the System.Web.UI.Control class. To create a Web Part, the implementation of your WebPart class must inherit from the WebPart base class.

To inherit from the WebPart base class  

• Replace this line of code
  public class WebCustomControl1 : System.Web.UI.WebControls.WebControl
  with this line
  public class SimpleWebPart : WebPart

Defining the XML namespace

To succesfully import your custom Web Part, you must define an XML namespace for all of the properties in your Web Part. You can do this globally by declaring the XmlRoot attribute at the top of your Web Part class definition, or by declaring an XmlElement attribute for each custom property in your class. The following steps describe using the XmlRoot attribute at the class level. For examples of using the XmlElement attribute, see Creating a Web Part with Custom Properties.

To define the XML namespace for an entire WebPart class  

• Add this line of code above declaration for your WebPart class
  [XmlRoot(Namespace="MyWebParts")]

Using the RenderWebPart method

The WebPart base class seals the Render method of System.Web.UI.Control because the Web Part infrastructure needs to control rendering the contents of a Web Part. For this reason, custom Web Parts must override the RenderWebPart method of the WebPart base class.

To implement the WebPart class RenderWebPart method  

• Replace this line of code
  protected override void Render(HtmlTextWriter output)
• with this line
  protected override void RenderWebPart(HtmlTextWriter output)

Modifying the Web Part‘s namespace (when using either the Web Control Library template or Web Part Library template)

If you are creating multiple Web Parts, you should generally use the same namespace across all of your Web Parts. By default, both the Web Control Library and Web Part Library templates assign the namespace the same name as your project. For this example, we‘re using the arbitrary namespace of MyWebParts for both the WebPart class and XML namespace for the Web Part‘s properties.

To modify the Web Part namespace  

• Replace this line of code
  namespace SimpleWebPart
• with this line
  namespace MyWebParts

To modify the XML namespace  

• Replace this line of code
  [XmlRoot(Namespace="SimpleWebPart")]
• with this line
  [XmlRoot(Namespace="MyWebParts")]

Defining the logic and rendering of your Web Part

After you have completed the previous steps, you can define the logic and rendering for your Web Part. For this part, we will write some basic ASP.NET code to create two HTML server controls: a text box, and a button that will set the Title property of the Web Part. The following code sample shows the complete SimpleWebPart.cs file with all of the modifications described in the previous steps. The additional code to define the Web Part‘s functionality is highlighted in bold text:

//--------------------------------------------------------------------// File: SimpleWebPart.cs//// Purpose: A sample Web Part that demonstrates how to create a basic// Web Part.//--------------------------------------------------------------------using System;using System.ComponentModel;using System.Runtime.InteropServices;using System.Web.UI;using System.Web.UI.WebControls;using System.Xml.Serialization;using Microsoft.SharePoint;using Microsoft.SharePoint.WebPartPages;using Microsoft.SharePoint.Utilities;using System.Web.UI.HtmlControls;namespace MyWebParts{    /// 
    /// This Web Part changes it‘s own title and implements a custom property.    /// 
    [XmlRoot(Namespace="MyWebParts")]    public class SimpleWebPart : WebPart    {        private const string defaultText = "hello";        private string text=defaultText;        // Declare variables for HtmlControls user interface elements.        HtmlButton _mybutton;        HtmlInputText _mytextbox;        // Event handler for _mybutton control that sets the        // Title property to the value in _mytextbox control.        public void _mybutton_click (object sender, EventArgs e)        {            this.Title = _mytextbox.Value;            try            {                this.SaveProperties=true;            }            catch            {                Caption = "Error... Could not save property.";            }        }        // Override the ASP.NET Web.UI.Controls.CreateChildControls        // method to create the objects for the Web Part‘s controls.        protected override void CreateChildControls ()        {            // Create _mytextbox control.            _mytextbox = new HtmlInputText();            _mytextbox.Value="";            Controls.Add(_mytextbox);            // Create _mybutton control and wire its event handler.            _mybutton = new HtmlButton();            _mybutton.InnerText = "Set Web Part Title";            _mybutton.ServerClick += new EventHandler (_mybutton_click);            Controls.Add (_mybutton);        }        [Browsable(true),Category("Miscellaneous"),        DefaultValue(defaultText),        WebPartStorage(Storage.Personal),        FriendlyName("Text"),Description("Text Property")]        public string Text        {            get            {                return text;            }            set            {                text = value;            }        }        protected override void RenderWebPart(HtmlTextWriter output)        {            RenderChildren(output);            // Securely write out HTML            output.Write("
Text Property: " + SPEncode.HtmlEncode(Text));        }    }}

After you‘ve added all of the preceding code, you can build your sample Web Part. Assuming that you are building your Web Part on your server, this will create an assembly for the part named SimpleWebPart.dll in the C:\inetpub\wwwroot\bin folder.

To build your Web Part  

• On the Build menu, click Build Solution.

By default, the trust level for this server is WSS_Minimal, which does not allow access to the SharePoint object model. In order for this Web Part to set the SaveProperties property, you must perform one of the following three actions:

• Create a custom policy file for your assembly.
• Install your assembly in the global assembly cache.
• Increase the trust level for the entire virtual server.

For more information about SharePoint permissions, see Code Access Security for Developers, or search on "SharePoint Permissions" on the Microsoft SharePoint Products and Technologies Developer Center on MSDN®.

Deploying your Web Part

In addition to copying your Web Part‘s assembly to the C:\inetpub\wwwroot\bin folder of your SharePoint server (or to the Global Assembly Cache folder C:\windows\assembly), you must perform three additional steps to deploy a Web Part:

• Register your Web Part as a safe control.
• Create a Web Part Definition file (.dwp).
• Import your Web Part into a Web Part Page.

Register your Web Part as a SafeControl

As a security measure, Windows SharePoint Services requires you (or a server administrator) to register the Web Part‘s assembly and namespace as a SafeControl in the web.config file of the server.

To register a Web Part assembly as a SafeControl  

• Open c:\inetpub\wwwroot\web.config in Visual Studio .NET or Notepad.
• Add the following lines in the block:

  Note  Replace the PublicKeyToken value (def148956c61a16b) with the actual value for your Web Part‘s assembly.To determine the correct PublicKeyToken value for the Assembly attribute of the tag for your Web Part, use the sn.exe command-line utility:
  sn.exe -T c:\inetpub\wwwroot\bin\SimpleWebPart.dll

  Note  You can also determine the correct PublicKeyToken value for your Web Part assembly, by performing the following workaround:

  • In Windows Explorer, open the C:\inetpub\wwwroot\bin folder.
  • In a separate window, open the C:\Windows\Assembly folder. (C:\Windows\Assembly exposes the contents of the GAC.)
  • Drag your Web Part assembly (your sample from these procedures should be named SimpleWebPart.dll) from the C:\inetpub\wwwroot\bin folder into the C:\Windows\Assembly folder.
  • In the C:\Windows\Assembly folder, right-click your assembly, and then click Properties.
  • Copy the PublicKeyToken value, and then paste it into the tag for your assembly.
  • In the C:\Windows\Assembly folder, right-click your assembly, and then click Delete.

Create a Web Part Definition file (.dwp)

A Web Part Definition file (.dwp) file is a simple XML file which contains property settings for a single Web Part. To import your Web Part into a Web Part Page, simply upload the .dwp file. After uploading the Web Part, you can display the Web Part by dragging it into one of the zones of the Web Part Page.

Two properties are required in the .dwp file: Assembly and TypeName. However, to display a default name and description for the Web Part after it is imported, you should also include the Title and Description properties. If you want to set other Web Part properties during import, you can also define them in a .dwp file. A .dwp file takes the following form:

   AssemblyName(with no .dll extension), Version=VersionNumber, Culture=Culture, PublicKeyToken=PublicKeyToken   WebPartNamespace.WebPartClassName      WebPartDescription

If you used the Web Part templates, a .dwp file will have been created for you automatically; just make sure that the after you change the name of the Web Part you also change the corresponding TypeName in the .dwp file. If you did not use the Web Part templates, to create a .dwp file for this sample Web Part from scratch, type the following lines in a new Notepad document and save it as SimpleWebPart.dwp in the C:\Inetpub\wwwroot\bin directory.

   SimpleWebPart, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=def148956c61a16b   MyWebParts.SimpleWebPart      A sample Web Part

Note   In the preceding example, replace the PublicKeyToken value (def148956c61a16b) with the actual value for your Web Part‘s assembly.

Import your Web Part into a Web Part Page

To use and test your Web Part, import it into a Web Part Page on a server running Windows SharePoint Services or SharePoint Portal Server.

To import your Web Part  

• Open a Web Part Page on your server.
• Click Modify My Page or Modify Shared Page (depending on whether you‘re in Personal View or Shared View) in the upper right corner of the page and click Add Web Parts from the menu.
• Click Import.
• Browse to the location of the SimpleWebPart.dwp file and click the Upload button. After uploading, the page will refresh and "My Simple Web Part" should be displayed under Imported Web Part.
• Drag the icon next to "My Simple Web Part" to a zone on the Web Part Page.
• Type some text in the text box, and then click Set Web Part Title to test the part.