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.
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.
Understanding What STSADM Does
|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.|
Sure, STSADM extracts the CAB file and installs the Web partbut 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 filesIf 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 ControlsIf 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.