Technical Briefing Series

Creating a SharePoint Web Part: A

Step-by-step Tutorial to Creating,
Deploying and Configuring a
Simple Web Part

David A. Scheele
Senior Consultant
May 2006
Table of Contents
TABLE OF CONTENTS .................................................................................................................................... 2
TABLE OF FIGURES ........................................................................................................................................ 3
EXECUTIVE OVERVIEW: MANAGING IDENTITY DATA ON AN ENTERPRISE LEVEL .................................... 4
1. PART 1 — INITIAL DEVELOPMENT ...................................................................................................... 5
1.1 HIGH LEVEL REQUIREMENTS .................................................................................................. 5
1.2 APPROACH .............................................................................................................................. 5
1.3 PREREQUISITES........................................................................................................................ 5
2. PHASE 1 — CREATING AND DEPLOYING THE WEB PART "SHELL" .................................................. 6
2.1 CREATE THE PROJECT.............................................................................................................. 6
2.2 SIGN THE ASSEMBLY ............................................................................................................... 7
2.3 UPDATE THE ASSEMBLY NAME ............................................................................................... 8
2.4 CREATE THE DEPLOYMENT PROJECT ..................................................................................... 10
2.5 DEPLOY THE WEB PART ........................................................................................................ 13
2.6 TEST THE WEB PART ............................................................................................................. 14
3. PHASE 2 — ADDING FUNCTIONALITY TO THE WEB PART "SHELL" ............................................... 16
CONCLUSION ................................................................................................................................................ 21

2
Table of Figures
NEW PROJECT SCREEN SHOT — SELECTING C# PROJECTS.............................................................. 6
SOLUTION EXPLORER SCREEN SHOT — SAMPLE WEB PARTS........................................................ 7
COMMAND WINDOW SCREEN SHOT — ASSIGNING A NAME .......................................................... 7
SOLUTION EXPLORER HIGHLIGHTING KEY FILE............................................................................... 8
COMMAND WINDOW SCREEN SHOT — PUBLIC KEY TOKEN .......................................................... 9
NOTEPAD SCREEN SHOT — PUBLIC KEY TOKEN ............................................................................... 9
NEW PROJECT SCREEN SHOT — SELECTING SETUP AND DEPLOYMENT PROJECTS ............... 10
ADD PROJECT OUTPUT GROUP SCREEN SHOT —SELECTING PRIMARY OUTPUT .................... 11
ADD PROJECT OUTPUT GROUP SCREEN SHOT —SELECTING CONTENT FILES......................... 12
SOLUTION EXPLORER SCREEN SHOT — SELECTING SAMPLEWEBPARTSDEPLOYMENT...... 12
OUTPUTS SCREEN SHOT — CONFIRMING CONTENT FILES ........................................................... 13
COMMAND WINDOW SCREEN SHOT — CHANGING DIRECTORIES TO SHAREPOINT BIN
DIRECTORY...................................................................................................................................... 14
BROWSER SCREEN SHOTS — TESTING YOUR WEB PART............................................................... 15
COMMAND WINDOW SCREEN SHOT — PERFORMING IISRESET COMMAND ............................ 19
BROWSER SCREEN SHOT — SETTING MISCELLANEOUS PROPERTIES ....................................... 20

3
Executive Overview: Creating a SharePoint Web Part
While SharePoint Web parts are not a new technology, many learning developers run into problems with
either the development process or deployment, not because of a lack of information, but rather because of
the scattered nature of the information available.

This guide provides a good step-by-step tutorial for creating, deploying, and configuring a simple Web
part. Starting from an empty Visual Studio project, this tutorial shows developers how to create a simple
Web part assembly, create a deployment file, deploy the Web part, drop it onto a portal page, and
demonstrate that it works.

4
1. Part 1 — Initial Development
1.1 High Level Requirements

First, you need to determine the function of the Web part you’re creating. In this tutorial, you’ll be creating
a Web part that can:

• Display user-specified text within the content area of the Web part.
• Allow the user to specify the background color of the content frame by selecting from a list.

1.2 Approach

The big difficulty when writing Web parts always seems to be the deployment process. Once over that
hurdle, the rest is just straightforward code writing. Consequently, this tutorial will involve two phases:

• Create and deploy the "minimal" or "empty" Web part created by the Visual Studio project
template.
• Add actual functionality to the Web part.

1.3 Prerequisites
In order to complete this tutorial, make sure you meet the following prerequisites:

• You have access to a development or test SharePoint installation on which you have permissions
to install and configure Web parts.
• You have access to a development machine running Visual Studio .NET 2003.
• You have installed the Web Part Templates for Visual Studio .NET on the development machine.

5
2. Phase 1 — Creating and Deploying the Web Part
"Shell"
First, you need to create a new Web part using the Web part template for VS.NET. Then you will create a
public/private key pair and sign the assembly. Finally, you will create a CAB deployment project and build
the entire solution. Using the command line utility stsadm, you will install the Web part, then drop it onto
a portal page and confirm that it works.

2.1 Create the Project

Start by launching Visual Studio .NET 2003 and selecting “New Project.” From the "New Project" dialog,
select your project type (in this example Visual C# Projects) and select the "Web Part Library" template
type. Assign a name to your project (in this example “SampleWebParts”) and a location in the file system.
Create a separate directory for the solution, since you will be adding a deployment project later, and this
keeps things nicely organized. Here is an example of what the dialog will look like:

NEW PROJECT SCREEN SHOT — SELECTING C# PROJECTS

When you click the OK button, the template creates a “shell” Web part for you. The Web part has one
property, labeled “Text,” which can be configured in the SharePoint tool pane, and this text is displayed in
the body of the Web part. This gets you part way towards your functionality goal, but there’s more to do
first.

Before moving on to the next step, your Solution Explorer should look like this:

6
SOLUTION EXPLORER SCREEN SHOT — SAMPLE WEB PARTS

2.2 Sign the Assembly

Since you will be deploying this assembly to the GAC, you need to assign a strong name to the assembly.
So get that detail out of the way first. Bring up the Visual Studio .Net command prompt (typically at All
Programs | Microsoft Visual Studio .NET | Visual Studio .NET Tools | Visual Studio .NET 2003 Command
Prompt) and enter the following command:

sn -k C:\Dev\SampleWebParts\SampleWebParts\SampleWebParts.snk

The directory path specified is the directory containing the project file SampleWebParts.csproj.

Don't close your command window after this step, as you will need it again in a few minutes.

Here is what your command window will look like:

COMMAND WINDOW SCREEN SHOT — ASSIGNING A NAME

From the Solution Explorer, click the "Show All Files" button, locate the key pair file and include it in the
project. This isn't strictly necessary, but I like to have it as part of the project so I can explicitly track it.

Your Solution Explorer should now look like this:

7
SOLUTION EXPLORER HIGHLIGHTING KEY FILE

Now go to your AssemblyInfo.cs file and update the AssemblyKeyFile attribute as follows:

[assembly: AssemblyKeyFile( @"..\..\SampleWebParts.snk" )]

Rebuild the solution and confirm that everything compiles OK. If you get a "Cryptographic failure while
signing assembly" error, it means the relative path specified in the AssemblyKeyFile attribute is wrong.
The path must point to the key file, relative to the location of the assembly DLL in the file system. Just
count the number of hops up from the DLL to the project directory and that will tell you how many ..\
you need in the path.

2.3 Update the Assembly Name

This step is critical.

The DWP file in the project is the Web part description file. Each Web part in a project has a DWP file, an
XML file containing information about the Web part, such as its title, description, the assembly it lives in,
and the qualified type name. The assembly attribute was initially correct when the project was created, but
it is now out of date because you assigned a strong name to the assembly. If you don't update this value,
SharePoint will refuse to render the Web part because the actual assembly name and the stated assembly
name differ. So you need to update that value now.

Currently, the value is:

<Assembly>SampleWebParts</Assembly>

The new value will be a strong name, which includes the version, culture, and public key token. The
version number will come from the AssemblyInfo.cs file. It is, in this case:

[assembly: AssemblyVersion("1.0.0.0")]

Make sure to always explicitly set all components of the version number. Don't let Visual Studio assign
numbers for each compilation, as that will cause rendering problems too.

The culture will be "neutral."

8
Now, you simply need the public key token from the assembly. One way to get it is to use the sn.exe utility
again. Go back to your command window and enter the following command:

sn -T C:\Dev\SampleWebParts\SampleWebParts\bin\Debug\SampleWebParts.dll
> C:\Dev\SampleWebParts\SampleWebParts\PublicKey
Token.txt

This will emit the public key token for the assembly to the PublicKeyToken.txt in the Web part project
directory. Here is what your command window should look like:

COMMAND WINDOW SCREEN SHOT — PUBLIC KEY TOKEN

Open the PublicKeyToken.txt file and you should see something like:

NOTEPAD SCREEN SHOT — PUBLIC KEY TOKEN

Select the 16 hexadecimal-digit public key token and copy it to the clipboard. In the Web part description
(DWP) file, change the assembly attribute to read:

<Assembly>SampleWebParts, Version=1.0.0.0, Culture=neutral,

PublicKeyToken=674462f7ad64de18</Assembly>

Of course, your public key token will be different from mine, so your actual assembly attribute value will
be a bit different from the example above.

OK, now recompile and confirm that everything is OK.

9
2.4 Create the Deployment Project

At this point, everything is hooked up in such a way that the Web part can be deployed to the GAC and
should render correctly in the SharePoint user interface. Now you have to create a CAB deployment for the
Web part.

To start, in the Solution Explorer, right click on the “Solution,” select “Add menu,” then the “New Project”
menu. From the "Add New Project" dialog, select the "Setup and Deployment Projects" project type and
choose "CAB Project" as the template. Assign a meaningful name to the project, such as
"SampleWebPartsDeployment" for this example.

Your screen should now look like this:

NEW PROJECT SCREEN SHOT — SELECTING SETUP AND DEPLOYMENT PROJECTS

When you click the “OK” button, a new project will be added to the Solution Explorer.

Now, right click the new project in the Solution Explorer and select “Add | Project Output.” This will bring
up the "Add Project Output Group" dialog box. Select the "Primary Output" item from the list, which will
include the EXE or DLL in the resulting CAB file. Your dialog box should now look like this:

10
ADD PROJECT OUTPUT GROUP SCREEN SHOT —SELECTING PRIMARY OUTPUT

Click the “OK” button to add the output.

Now, right click the new project in the Solution Explorer and select “Add | Project Output.” This will bring
up the "Add Project Output Group" dialog box. Select the "Content Files" item from the list, which will
include any project files with the compile action of "Content." Your dialog box should now look like this:

11
ADD PROJECT OUTPUT GROUP SCREEN SHOT —SELECTING CONTENT FILES

Click the “OK” button to add the output.

Your Solution Explorer should now look like this:

SOLUTION EXPLORER SCREEN SHOT — SELECTING SAMPLEWEBPARTSDEPLOYMENT

As a final step, you should confirm that your content files are present in the content output. Right-click the
“Content Files” output under your deployment project and select “Outputs” command to bring up the
outputs dialog box. All DWP files plus the Manifest.xml must be in the content output. If anything is

12
missing, select the missing file in the Solution Explorer, bring up the properties for that file, and set the
“Build Action” to "Content."

Here is what that dialog should look like:

OUTPUTS SCREEN SHOT — CONFIRMING CONTENT FILES

Build your entire solution to compile the Web part and create the CAB file.

2.5 Deploy the Web Part

OK, now you are all set to deploy and test the Web part. Of course, it doesn't do much yet, but remember
that this initial phase seems to be the troublemaker for new Web part developers. Once you get the initial
deployment working, then you can concentrate on the actual functionality.

To deploy the Web part, you have to use the SharePoint administration command-line tool nstsadm.exe.
You will need to run it specifying the command option to install a Web part pack and giving the file name
of the CAB file you just created.

Open a command shell and execute the following command to change directories to the SharePoint bin
directory:

cd \program files\common files\microsoft shared\web server

extensions\60\bin

Now execute the following command to install the Web part assembly:

stsadm -o addwppack -filename

"C:\Dev\SampleWebParts\SampleWebPartsDeployment\Debug\SampleWebPartsDep
loyment.CAB" -force globalinstall

Of course, use the actual path in your file system when specifying the "filename" switch value.

Your command window should look like this:

13
COMMAND WINDOW SCREEN SHOT — CHANGING DIRECTORIES TO SHAREPOINT BIN
DIRECTORY

2.6 Test the Web Part

Now you are ready to see the results of your effort. If you have done everything correctly, you will now be
able to drop the Web part onto a portal page from the Web part gallery and have it render correctly.

Point your browser to a test page on your portal site. Switch the page into edit mode and select the “Add
Web Parts | Browse” menu from the “Modify Shared Page” menu. Select the “Virtual Server Gallery” and
page down until you see “WebPart1” in the gallery. Drag and drop it onto a Web part zone and the Web
part should render as you see below.

14
BROWSER SCREEN SHOTS — TESTING YOUR WEB PART

If you get an error message indicating that the Web part is not safe to render, then you probably got the
pubic key token wrong in the <assembly> attribute of the DWP file. Double check the full assembly name
and be sure the version, culture, and public key token are correct for your project. If you followed the
directions here, you shouldn't have any problems.

The next step is to add real functionality to the Web part.

15
3. Phase 2 — Adding Functionality to the Web Part
"Shell"
Now that you have successfully created and deployed the "shell" Web part, you have passed the major pain
point in Web part development. With that tackled, you can now move on to the "easy" stuff — adding real
functionality. The word "easy" is in quotes because I am fully aware that real production Web parts may
have complex functionality and thus be hard to write. But in this example, the functionality is simple and
easy to implement.

Recall that your requirement is to permit the user to specify text to be displayed in the Web part, as well as
the background color of the Web part. In this example, you'll be adding another requirement here to allow
the user to specify the padding between the Web part border and the text. The general approach used here
will be to emit HTML and use the bgcolor attribute to specify the background color. Although this element
is deprecated in favor of specifying color using style sheets, we'll keep this example simple and use it
anyway. There are only a few elements that officially support bgcolor: <body>, <table>, <tr>, <th>, and
<td>. It looks like you'll need to emit an HTML table to support our background color requirement, and this
will nicely support your padding requirement, too.

First, you need to expose two additional public properties to support the background color and padding
specification. The text property is already handled by the following code:

private const string defaultText = "";

private string text = defaultText;

[Browsable(true),
Category("Miscellaneous"),
DefaultValue(defaultText),
WebPartStorage(Storage.Personal),
FriendlyName("Text"),
Description("Text Property")]
public string Text
{
get
{
return text;
}

set
{
text = value;
}
}

You can see that there is a constant defined specifying the default text. There is also a private field
responsible for holding the specified text. The public text property allows the text to be retrieved and set,
and is decorated with several attributes which control how the property is rendered by the SharePoint user
interface. The SharePoint UI will iterate over all the public properties defined in the Web part and render
those with attribute Browsable equal to True. SharePoint will use the declared type of the property to
decide what type of control to render and the attributes specify the label to use for the control, the tool tip
description, and the default value.

16
For the background color, we would like the user to be able to select from a drop-down list if possible. The
.NET Framework conveniently defined an enumeration of colors called “KnownColor” in the
System.Drawing namespace. The SharePoint user interface is smart enough to detect when the data type of
a public property is an enumeration and automatically renders the field as a drop-down list containing the
values of the enumeration. So all you have to do is to declare a property having the KnownColor type, and
SharePoint takes care of the rest.

First add a reference to the System.Drawing namespace at the top of the class file:

using System.Drawing;

Now, add the following code after the text property code:

private const KnownColor defaultColor = KnownColor.White;

private KnownColor backColor = defaultColor;

[Browsable(true),
Category("Miscellaneous"),
DefaultValue(defaultColor),
WebPartStorage(Storage.Personal),
FriendlyName("Background Color"),
Description("Background color for the web part")]
public KnownColor BackColor
{
get
{
return backColor;
}

set
{
backColor = value;
}
}

Next, you’ll have to add another property to allow the user to specify a padding. This will be of integer
type. Add the following code after the BackColor property code:

private const int defaultPadding = 0;

private int padding = defaultPadding;

[Browsable(true),
Category("Miscellaneous"),
DefaultValue(defaultPadding),
WebPartStorage(Storage.Personal),
FriendlyName("Padding"),
Description("Padding between the web part border and the text")]
public int Padding
{
get
{

17
 return padding;
}

set
{
padding = value;
}
}

As a final step, change the WebPartStorage from “Personal” to “Shared” on each of the three properties.
They each should read:

WebPartStorage(Storage.Shared)

So at this point, if compiled and deployed to the GAC, the Web part would accept property settings from
the user for background color and padding, but wouldn't do anything with them. You can correct that by
updating the rendering code.

As you can see, the rendering code just takes the value of the text property and spits it out into the HTML
output stream:

protected override void RenderWebPart(HtmlTextWriter output)

{
output.Write(SPEncode.HtmlEncode(Text));
}

You will need to update the body of this function to render an HTML table with a single row and single
column. The column will contain the text and have a background color set to the specified value. The table
will have a cell padding set to the value specified by the user.

Here is the updated code:

protected override void RenderWebPart(HtmlTextWriter output)

{
// Emit the <table> element
output.AddAttribute( HtmlTextWriterAttribute.Cellspacing, "0" );
output.AddAttribute( HtmlTextWriterAttribute.Cellpadding,
Padding.ToString( ) );
output.AddAttribute( HtmlTextWriterAttribute.Width, "100%" );
output.AddAttribute( HtmlTextWriterAttribute.Border, "0" );
output.RenderBeginTag( HtmlTextWriterTag.Table );

// Emit the <tr> element

output.RenderBeginTag( HtmlTextWriterTag.Tr );

// Emit the <td> element

output.AddAttribute( HtmlTextWriterAttribute.Bgcolor,
BackColor.ToString( ) );
output.RenderBeginTag( HtmlTextWriterTag.Td );

// Emit the text

output.Write(SPEncode.HtmlEncode(Text));

18
 // Emit the closing tags
output.RenderEndTag( ); // td
output.RenderEndTag( ); // tr
output.RenderEndTag( ); // table
}

Notice we are using the stack-based Render__ methods to emit HTML, rather than the .Write method or
.Write__ methods. This is a best practice when working with the HtmlTextWriter class.

You can now conclude by rebuilding the solution and confirming that all is well. If there are compile
errors, go back and correct the code according the directions given above.

Now, you’ll need to redeploy the assembly and test the changes. You do not need to use the stsadm.exe tool
again, because the Web part is already registered with SharePoint — all that is needed is to replace the
assembly in the GAC. To do that, use the gacutil.exe utility. Bring up the Visual Studio .Net command
prompt (typically at All Programs | Microsoft Visual Studio .NET | Visual Studio .NET Tools | Visual
Studio .NET 2003 Command Prompt) and enter the following command:

gacutil /i
C:\Dev\SampleWebParts\SampleWebParts\bin\Debug\SampleWebParts.dll /f

Then do an iisreset command to ensure the new DLL gets loaded on the next page request.

Be sure to specify the actual path to the Web part assembly for the value of the /i switch. Your command
window should look like:

COMMAND WINDOW SCREEN SHOT — PERFORMING IISRESET COMMAND

Point your browser to the test portal page on which you dropped your Web part from Part 1. Bring up the
tool window and set the “Miscellaneous” properties, and observe the effects in the user interface of the
Web part.

Here is what the result will look like, along with the corresponding property settings:

19
BROWSER SCREEN SHOT — SETTING MISCELLANEOUS PROPERTIES

Note: One "gotcha" that I have encountered has to do with serializing/de-serializing the Web part to/from
the database. Give thought to your public property data types before you implement, because if you change
the data type of a property after you have already deployed, you will probably run into de-serialization
problems as SharePoint tries to de-serialize old configuration data into the new schema. Also, be sure you
get the data types of your defaults right. Typically, to create a new public property you will copy and paste
the code from another property, and it is easy to overlook something when changing the pasted code. If you
don't get the data type right, you will experience de-serialization errors.

20
Conclusion
While this tutorial is not a conclusive guide for creating Web parts, it provides all the basics and should
serve as an excellent, step-by-step guide for new programmers learning to create, deploy, and configure a
simple Web part.

About the author:

David A. Scheele, Senior Consultant, is a software architect with over ten year’s experience designing and
developing software systems. His areas of expertise include object-oriented analysis and design; data modeling
and databases; user interaction and interface design; and Microsoft .NET. He is a strong advocate of model-based
design driven by careful requirements analysis and communicated using UML. David has been involved in
numerous projects in a variety of roles, with strong skills as business analyst, software architect, designer, and
developer. Familiar with several platforms and environments, David specializes in Microsoft tools and
technologies, having designed systems with architectures based on both .NET and Windows DNA.

About PointBridge:
PointBridge (www.pointbridge.com) leverages Microsoft technologies to enable collaborative work
environments that improve business performance. Focused on strategy, portals and content management,
messaging, infrastructure and security, and collaboration; PointBridge delivers business value to the most
complex work workplaces. Based in Chicago, PointBridge is a Microsoft Gold Certified Partner in Advanced
Infrastructure, Information Worker and Security Solutions. PointBridge was named the worldwide Microsoft
Partner of the Year for Advanced Infrastructure Solutions and won the Microsoft Exchange Solution of the Year
award in 2005.

Copyright © 2006 PointBridge. All rights reserved. All information contained herein is the property of PointBridge
and shall not be copied, photocopied, translated, or reduced to any electronic or machine-readable form, either in
whole or in part, without prior written approval from PointBridge. PointBridge reserves the right to modify or revise
all or part of this document, without notice, and/or change product features or specifications. PointBridge shall not be
responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials.
Active Directory, legacyExchangeDN, AD 2000 and 2003, Exchange 2000 and 2003, AD Application Mode, the
Identity Integration Feature Pack for Windows Server 2003 and MS Identity Integration Server 2003 are either
registered trademarks or trademarks of Microsoft Corporation. Other brand and product names mentioned herein may
be the trademarks of their respective companies.

PointBridge, LLC, One North Franklin, Suite 2470, Chicago, Illinois 60606

www.pointbridge.com

21