OK, so SharePoint web parts are not a brand new technology. There are lots of articles on the Web talking about web part development, web part deployment, web part troubleshooting, and so forth. So why write yet another article on this topic?
I am writing this post because literally every developer I’ve encountered who has just started developing web parts has run into problems with either the development process or deployment. In each case the problem was rooted not in a lack of information about web part development, but in the scattered nature of it. There didn’t seem to be a good step-by-step tutorial for creating a simple web part — and those references that came close seemed to bite off too much at one time, thus complicating and obfuscating the central concepts.
What I present here is the step-by-step process for creating, deploying, and configuring a simple web part. I have used this example several times in developer demonstrations and have received good feedback on it. Starting from an empty Visual Studio project, we will create a simple web part assembly, create a deployment file, deploy the web part, drop it onto a portal page, and demonstrate it working.
High Level Requirements
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 writing of code. Consequently, our approach is going to involve two phases:
Create and deploy the "minimal" or "empty" web part created by the Visual Studio project template. This phase is covered in this article.
Add actual functionality to the web part. This phase is covered in the article Creating a SharePoint Web Part – Step by Step: Part 2 – Build Functionality.
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.
Phase 1 – Creating and Deploying the Web Part "Shell"
We will start by creating a new web part using the web part template for VS.NET. We will then create a public/private key pair and sign the assembly. Finally, we will create a CAB deployment project and build the entire solution. Using the command line utility stsadm, we will install the web part, then drop it onto a portal page and confirm it works.
1. Create the project
Let us 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 we will be adding a deployment project later, and this keeps things nicely organized. Here is an example of what the dialog will look like:
When you click the OK button, a "shell" web part is created for you by the template. The web part has one property "Text" that can be configured in the SharePoint tool pane, and this text is displayed in the body of the web part. This gets us part way towards our functionality goal, but we have more to do first.
Before moving on to the next step, your Solution Explorer should look like this:
2. Sign the assembly
Since we will be deploying this assembly to the GAC, we need to assign a strong name to the assembly. Let’s 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:DevSampleWebPartsSampleWebPartsSampleWebParts.snk
The directory path specified is the directory containing the project file SampleWebParts.csproj.
Don’t close your command window after this step, as we will need it again in a few minutes.
Here is what your command window will look like:
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:
Now go to your AssemblyInfo.cs file and update the AssemblyKeyFile attribute as follows:
[assembly: AssemblyKeyFile( @"….SampleWebParts.snk" )]
Rebuild the solution and confirm the 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.
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 we created the project, but it is now out of date because we assigned a strong name to the assembly. If we 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 let’s 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 we get from the AssemblyInfo.cs file. It is, in our 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".
We just 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:DevSampleWebPartsSampleWebPartsbinDebugSampleWebParts.dll > C:DevSampleWebPartsSampleWebPartsPublicKey
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:
Open the PublicKeyToken.txt file and you should see something like:
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 everything is OK.
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 we 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 look like this:
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 look like this:
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 look like this:
Click the OK button to add the output.
Your Solution Explorer should now look like this:
As a final step, let’s confirm that our 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 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:
Build your entire solution to compile the web part and create the CAB file.
5. Deploy the web part
OK we 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 we get the initial deployment working, then we can concentrate on the actual functionality.
To deploy the web part, we have to use the SharePoint administration command-line tool nstsadm.exe. We will run it specifying the command option to install a web part pack and giving the file name of the CAB file we just created.
Open a command shell and execute the following command to change directories to the SharePoint bin directory:
cd program filescommon filesmicrosoft sharedweb server extensions60bin
Now execute the following command to install the web part assembly:
stsadm -o addwppack -filename "C:DevSampleWebPartsSampleWebPartsDeploymentDebugSampleWebPartsDeployment.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:
6. Test the web part
Now we are ready to see the results of our effort. If we have done everything correctly, you will be able to drop the web part onto a portal page from 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.
If you get an error message indicating 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. We cover this in a companion article, Creating a SharePoint Web Part – Step by Step: Part 2 – Build Functionality.
