his isn't the article that I set out to write. While researching another article (coming soon) I soon realized there just isn't a lot of good material on how to troubleshoot Web part deployment, or even precisely how Web part deployment via STSADM even works. This article is designed to explain the moving parts of the deployment process and describe what can go wrong. Hopefully, it will help a few people get their implementations up and running more smoothly.

Why Deploy with STSADM?
Before getting too deeply involved in fixing STSADM Web part deployments, it's important to understand what STSADM is and why it's a good platform for troubleshooting Web part deployment.

STSADM is a 'utility knife' type of tool that ships as a part of Windows SharePoint Services. It does a wide range of things from site creation to Web part pack installation. If you have SharePoint Services, you already have this utility; it is typically found in C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\Bin.

Alternative tools such as WPPackager just add additional complexity to the process by wrapping the installation in a Windows Installer file. Worse, these tools don't really gain you anything. At their core they're still using the same installation process by running STSADM or calling the Windows SharePoint Services object model calls that roughly equate to the STSADM options.

But whether you choose to download one of these tools or stick with the somewhat plain but very functional STSADM, learning how STSADM deploys Web parts is very valuable.

Understanding the CAB File
In order to troubleshoot Web parts and deployment you must first understand how the process works. This means understanding what STSADM does to the CAB files that you create for it. The CAB files that STSADM wants are not special other than the fact that they contain a manifest.xml file which contains the instructions that STSADM needs to set up the Web part.

There are two basic sections to the manifest.xml file (see Figure 1). The first, which falls under the <Assemblies> tag, contains the DLLs, supporting files, and configuration entries that are made by STSADM. The second section, DWP Files, falls under the <DwpFiles> tag and contains all of the DWP files for the package. DWP files are what the user sees when adding a Web part to the site. They contain the title to display, the description for the hover text, the assembly to load and what the properties are that should be loaded into the Web part. They are the configuration part of a Web part, whereas the assembly is the code that is running.

Figure 1. Get in the CAB: The contents of the CAB file are shown.

In the <Assemblies> tag there is a set of <Assembly> tags. Each tag in the set has a FileName attribute that defines the name of the assembly being described. This file should be packaged inside the CAB file.

If the assembly contains the Web parts then it should have a <SafeControls> tag (note plural), which encloses one or more <SafeControl> tags (note singular), each of which has an attribute for Namespace and TypeName. The Namespace is the namespace that the type belongs in and the TypeName is the specific name of the type in the namespace to make safe (or a * to indicate that all types in the specified Namespace are good). These <SafeControl> tags are used to create the appropriate entries in the web.config file. The web.config file entries are nearly identical except they reference the full name of the assembly.

The <Assembly> tag may also contain a <ClassResources> tag (note plural), which itself encloses one or more <ClassResource> tags (note singular). The <ClassResource> tag has an attribute, FileName, which specifies the name of the file to include as a resource. These files should also be included in the CAB file. Class resources are things like images and JavaScript include files, which the Web part will need to operate correctly.

Assembly tags do not need any sections inside of them. If the tag doesn't have any references inside of it, the assembly is copied just like the other DLLs. This is important when you are referencing other DLLs from your Web part DLL. By adding a separate assembly tag for them you can ensure they get copied during installation so that your DLL can use the referenced DLLs during run time.

The next major section is the DWP Files section. The <DwpFiles> tag has one or more <DwpFile> tags in it. Each of the <DwpFile> tags has an attribute, FileName, which contains the name of the DWP file to install. DWP files themselves are XML files as well. They contain a <Title> tag, which holds the text to display in the Web Part menu when a user tries to add a Web part. The files also contain a <Description> tag that contains the text that will be displayed in a tool tip when the user hovers over the Web part in the Add Web Part pane.

The DWP file also contains information necessary to load the DLL, which is where the code for the Web part really is. It contains an <Assembly> tag that references the DLL that the Web part type is loaded from. If the DLL has been strong named, which I recommend, the assembly tag must provide a fully specified code base including the public key, which makes this tag particularly troublesome. It is easy to overlook this step since Visual Studio will create the DWP file without the strong named code base and you will be able to install the Web part to the site without warning, however, users won't be able to use the Web part.

The next attribute <TypeName> isn't as difficult, it just describes the fully qualified name of the Web part type including the namespace.

In addition, a DWP file may contain additional tags. A DWP file can contain tags for each of the public properties that are exposed by the Web part. If your Web part has a property named MyPublicProperty then a tag of <MyPublicProperty> in the DWP file will populate that property. This allows you to create multiple DWP files, appearing as multiple Web parts, which all use the same fundamental DLL and type but use different properties. You can even set the value of hidden properties that do not appear in the tool pane.

Figure 2. Charting it Out: Though the workflow is fairly simple, this process ends in errors fairly frequently. Knowing how STSADM works is your best defense against problems.

Understanding What STSADM Does
Sure, STSADM extracts the CAB file and installs the Web part—but how precisely does it do that? The answer is that it depends. It depends on whether you use the global install or not.

Basically, STSADM does three things:

• Copies the DLL files—If you're doing a non-global install the Assemblies are copied to the /bin directory of the IIS virtual server (Web site).If there's an associated PDB file it is copied to the /bin directory too. If you're installing globally then the DLL files are registered in the GAC rather than copied to the /bin directory. This, by the way, means that you won't be able to debug your application. You'll have to manually copy the PDB file into the GAC to make debugging work.
• Safe Controls—If there are safe control entries in the assembly tags of the manifest.xml file they are added to the web.config. These will contain the assembly's strong name, if there is one.
• The DWP files are copied to the /wpcatalog directory. If the DWP references an assembly with a strong name the DWP file will be renamed to the name of the assembly with an underscore followed by the version number, followed by another underscore, followed by the public key token, followed by yet another underscore, and finally the original DWP name.

Figure 2 walks you through the workflow for the STSADM.

If you read between the lines you'll realize that the safe controls in the web.config are updated. This in turn means that the ASP.NET worker process will reset itself because it is designed to reset when the web.config file is changed. Ultimately, you'll need to be careful about installing Web parts during the middle of the day, as they'll force a momentary interruption in service.

Common Problems
Now that you have a foundation for how things work, in the following sections I'll tear apart common errors and what their causes are.

Installation
Here are some of the problems that you can run into when trying to install a Web part pack:

• Can not connect to the configuration database—In this situation, though your SharePoint implementation is operational, when you run STSADM you get a message saying that it can't connect to the configuration database. Most of the time this is because the logged in user doesn't have access to the SQL Server. STSADM accesses its database directly so the user account must have access to the database. To solve this problem, use the RUNAS command to run a command prompt as the application pool's user identity. Run STSADM from that command prompt. If it works, you have a permissions problem. If not, you've got a mystery.
• Missing files referenced in manifest.xml—There are two basic problems that lead to this. First, you didn't change the reference in manifest.xml after changing the name of the assembly or the DWP file. If neither of these resolves the problem, you may have added another file but not added that file to the CAB file. The most common occurrence of this is adding a new DWP file to the project but failing to set its properties such that its Build Action is set to Content. Most people set up the CAB file to include the primary output and content files from the Web part project. If the build action property isn't set to Content then the new DWP file won't get picked up.

Running
One of the most frustrating things about SharePoint is not being able to determine what the problem is when a Web part can't be displayed. Generally you get the message that the Web part isn't registered as safe but you may get a handful of other messages including that the Web part has caused an error. Here are a few things to check:

• Wrap everything in a try/catch. Make sure that you don't allow exceptions to propagate back to SharePoint. Handling of exceptions propagated from a Web part isn't one of SharePoint's strengths. Make sure you're doing your own error handling in CreateChildControls, the constructor, and RenderWebPart, as well as other overridden methods that might throw an exception.
• Verify that the DWP is referencing the right assembly and type—verify this by going out to the /wpcatalog directory. Check the name of the file and make sure that it matches the reference internally in the file—and the way that you've created your assembly. This should include checking version number and public keys.
• Verify that all of the DLLs that the Web part assembly references are loadable. When in doubt put anything that the DLL needs in the GAC—at least temporarily to guarantee that they are loadable.
• Install the Web part itself into the GAC. It's possible that there's a security permission that's missing which is causing an issue. Put the assembly in the GAC at least temporarily to make sure that it isn't a security issue. One problem that sometimes happens is that the referenced DLL is in the GAC but the Web part itself is not. This requires that the referenced component have the attribute AllowPartiallyTrustedCallers so that non-trusted assemblies can be loaded.
• Set the Trust level in the web.config to Full; turning down security on the Web site may help make the Web part work—you can then work backward to determine what the security issue may be.
• If you have complex properties in your Web part, make them simple; SharePoint occasionally gets unhappy with serializing complex types. Comment out the property or change it to a simple type, like a string, and have the property setter do the conversion to the internal type.
• Try an IISRESET. Occasionally bad things happen.

SharePoint Web parts aren't the easiest things to troubleshoot, however, with a bit of knowledge and a bit of patience you can make them work.