Web Part Tech Briefing

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 1.2 1.3

2.

PHASE 1 — CREATING AND DEPLOYING THE WEB PART "SHELL" .................................................. 6 2.1 2.2 2.3 2.4 2.5 2.6

3.

HIGH LEVEL REQUIREMENTS .................................................................................................. 5 APPROACH .............................................................................................................................. 5 PREREQUISITES........................................................................................................................ 5

CREATE THE PROJECT.............................................................................................................. 6 SIGN THE ASSEMBLY ............................................................................................................... 7 UPDATE THE ASSEMBLY NAME ............................................................................................... 8 CREATE THE DEPLOYMENT PROJECT ..................................................................................... 10 DEPLOY THE WEB PART ........................................................................................................ 13 TEST THE WEB PART ............................................................................................................. 14

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: • •

1.2

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.

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: • •

1.3

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

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: SampleWebParts 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: SampleWebParts, Version=1.0.0.0, Culture=neutral, PublicKeyToken=674462f7ad64de18 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 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: , , ,

, and

. 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 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 element output.RenderBeginTag( HtmlTextWriterTag.Tr ); // Emit the 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 Related Documents Web Part Tech Briefing June 2020 2 Web Tech November 2019 3 Web Tech October 2019 14 Web Tech Xii April 2020 3 Web-part May 2020 2 Briefing November 2019 40 Copyright © 2024 PDFCOKE.