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 FilesCommon FilesMicrosoft SharedWeb Server Extensions60Bin.
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
|Figure 1. Get in the CAB: The contents of the CAB file are shown.
If the assembly contains the Web parts then it should have a
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
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
The next attribute
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
|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.
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.
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.
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.