Section 8.2. Creating a Web Part Project

8.2. Creating a Web Part Project

Before you can start writing code for a web part, you need to set a few things up so that you can debug and test the component from within SharePoint:

1. Create a test page in SharePoint.

2. Create and configure a new project.

3. Build and sign the assembly; then extract the token.

4. Register the web part Web.config .

5. Add the web part to the test page to verify that everything works.

The following sections describe these tasks in more detail.

8.2.1. Creating a Test Page

Since web part projects are class libraries, they require a context within which to run. It is a good idea to create a document library of web part pages on your development server for debugging and/or testing purposes. Using a document library helps organize the test pages and makes it easier to create/modify them.

To create a test web part page library:

1. From SharePoint on the development server, choose Create Document Library. SharePoint displays the New Document Library page.

2. Choose New Document to create a new, empty web part page named Test1 .

3. Write down the address of the new page. You'll use that address when configuring the project.

8.2.2. Configuring a New Project

To create and configure a new web part project in Visual Studio:

1. From Visual Studio, choose File New Project, select the Web Part Library template from the Visual Basic .NET or Visual C# project type, and choose OK. Visual Studio creates a new web part project.

2. Properties Configuration Properties Debugging.

3. Select Enable ASP.NET debugging.

4. Choose Configuration Properties Build.

6. Choose File Save All to save the project settings.

8.2.3. Building and Signing the Assembly

Since you haven't written any code yet, this step might seem out of place. However, SharePoint requires that assemblies be signed with strong names before you can run, test, and debug them. You need to set up signing using the .NET Strong Name utility ( sn.exe ); build the assembly once; then extract the strong name token before you can register the web part with SharePoint. To sign and build the assembly:

1. From the server Start menu, choose All Programs Accessories Command Prompt. Windows opens command prompt window.

2. vsvars32.bat.

3. Enter sn -k " key.snk " to create a strong name key to use for signing the assembly.

4. From Visual Studio, open AssemblyInfo.vb or AssemblyInfo.cs and add an AssemblyKeyFile attribute referencing the key file. In Visual Basic it would look like this:

    <Assembly: AssemblyKeyFile("C:\WebParts\key.snk")> 

   
   

5. Choose Build Build Solution. Visual Studio builds and signs the web part assembly.

6. Record the public key token returned by sn.exe for use registering the web part next .

8.2.4. Registering the Web Part

You must register web part assemblies in the server's Web.config file to tell SharePoint that the assembly is safe to load. To register the web part:

1. From the server's \InetPub\ wwwroot folder, open Web.config .

2. Add a SafeControl element to the SafeControls section. The values for each attribute come from the locations in Table 8-3.

3. Save Web.config .

The following element shows a typical SafeControl element. Each project will have its own unique settings. Table 8-3 describes the attribute settings and where you find them.

 <SafeControls>       <SafeControl Assembly="WebPartLibrary1,        Version=1.0.0.0, Culture=neutral,        PublicKeyToken=b03f5f7f11d50a3a"        Namespace="WebPartLibrary1"        TypeName="*" Safe="True" />        ...      </SafeControls> 

Table 8-3. SafeControl attributes

Attribute	Used to	Settings come from/notes
Assembly	Describe the web part assembly.	The assembly file name, minus the .DLL extension.
Version	Identify the version.	Assembly: AssemblyVersion attribute. Projects must have a static version number.
Culture	Identify the culture.	Assembly: AssemblyCulture attribute or neutral if none specified.
PublicKeyToken	Uniquely identify the assembly.	Output from sn.exe -T .
Namespace	Provide the root namespace for the web parts .	Project root namespace (top-level name in Solution Explorer).
TypeName	Include one or all types from the project.	The class name of the web part or * for all classes in the project.
Safe	Flag the web part as safe or unsafe.	Set to False to disable a web part.

8.2.5. Adding the Web Part to a Page

If you've completed the preceding tasks correctly, you should now be able to add the web part to a page, set a breakpoint, and step through the code in debug mode to verify that everything works. It's a good idea to do this check before adding code to the project, since debugging code and configuration problems at the same time can be very hard. To add the web part to a test page:

1. Load the Web Part project in Visual Studio and set a breakpoint on the output.Write line in the RenderWebPart procedure.

2. Choose Debug Start or press F5. Visual Studio builds the assembly and displays the Test1.aspx page in the browser.

3. From the Test1 page in SharePoint, choose Modify Shared Page Add Web Parts Import. SharePoint displays the Import task pane.

4. Drag the web part from the task pane to a web part zone as shown in Figure 8-1. Control switches to Visual Studio at the breakpoint.

5. Clear the breakpoint in Visual Studio and press F5 to continue. Control returns to the browser and SharePoint display the web part on the page.

SharePoint saves the changes to Test1.aspx , so the web part is included on the page the next time you run the project. To see how that works, stop debugging and change the _defaultText constant as shown here:

 Private Const _defaultText As String = "New test string" 

Press F5 to run the project and the new string appears in the control (Figure 8-2).

You don't have to run the project to see the change. Just rebuild it and refresh the page in the browser.

animal 8-1. Adding a web part to a test page

animal 8-2. Changing properties in the assembly changes the web part appearance

8.2.6. Troubleshooting

If there is a problem with your web part, you'll usually see an error after dragging the part onto the web part page. Check the SafeControl settings in Web.config . These settings need to match the AssemblyInfo and public key token exactly, specifically :

• Errors loading the web part (Figure 8-3) are generally caused by a problem with the signature on the assembly. Verify that the PublicKeyToken attribute matches the value returned by running sn.exe -T on the assembly.

• Errors finding the web part (Figure 8-4) are generally caused by typos in the Namespace or TypeName attributes. Check that those match the entries in the AssemblyInfo file.