Troubleshooting Smart Documents Error Messages

Article
09/18/2009

Siew Moi Khor
Octavian Timofte
Microsoft Corporation

December 2003

Applies to:
Microsoft® Office Word 2003
Microsoft Office Excel 2003

Summary: Read a step-by-step guide on how to troubleshoot smart documents error messages. (13 printed pages)

Introduction
Error Due to an External Issue
Manifest Validation Error
Processing Error--Cannot Download Components
Loading Error
More Debugging Tips
Update Processing Error
Conclusion

Introduction

The smart document technology in Microsoft® Office Excel 2003 and Microsoft Office Word 2003 enables the creation of XML-based applications that provide users with contextual content by using the task pane. With smart documents, users benefit from the ability to deliver relevant information and actions through the use of an intuitive task pane that synchronizes content based on the user's current location within the document.

You can create smart documents using Microsoft Visual Basic® 6.0, Microsoft Visual Basic® .NET, Microsoft C® .NET, or Microsoft Visual C++®. The code manipulates the document directly or interacts with server-side processes, such as retrieving data or routing the document (or its contents) to a back-end system to complete the solution.

This article provides a step-by-step guide on how to troubleshoot error messages in smart documents. This article assumes that you know how to create smart documents and resolve Office security checks on an XML Expansion Pack manifest file.

For more information about creating smart documents, see The Definitive "Hello World" Managed Smart Document Tutorial.
For more information about how to resolve Office security checks on XML Expansion Pack manifest files, see the Smart Documents Development Overview

This article does not provide a complete list of error messages but rather provides a guide to understanding the error messages for the purpose of narrowing down possible issues and to provide guidance.

Error Due to an External Issue

Figure 1. An external error unrelated to the smart document

Figure 1 shows the first error you may encounter if your XML expansion pack manifest file passes the security check. Generally, this error is caused by an external error. Possible reasons:

Your manifest is not well-formed. You can check whether your manifest is well formed or not by using Microsoft Internet Explorer. If it isn't well-formed, if you try to open it in Internet Explorer, it fails to render successfully.
You cannot access the manifest file. Reasons include:
- Inappropriate permissions. You do not have the appropriate permissions to the server where the manifest resides. Check this by trying to open the manifest in Notepad. If you don't have permission, you cannot open the manifest file.
- Server unavailable. The server is unavailable. Try accessing the server without trying to access the manifest file. If the server is still unavailable, then the issue is with the server, not the manifest file.

Manifest Validation Error

Figure 2. An error due to validation problems with the manifest

Figure 2 shows a validation error. This error is thrown if the manifest is invalid because it didn't adhere to certain rules related to the manifest elements usage.

Note The order of elements in the manifest is not important provided they follow the parent-child rule. To reiterate, this error is because the manifest itself is invalid. When this error occurs, the location of the supporting files is not important, nor is the error related to mismatched spelling of name of files on the manifest and the actual file, and so forth. The smart document is only validating the xml of the manifest file.

Examples of possible manifest validation errors:

Wrong casing for the elements. The manifest elements are case sensitive; they must be camel case.

Two files of type "schema" in the solution of type "schema". This causes the manifest to be invalid as shown in the following example:

[Incorrect]

<manifest xmlns="http://schemas.microsoft.com/office/xmlexpansionpacks/2003">   
<version>1.0</version>
   <uri>urn:schemas-microsoft-com.office2003demos.test</uri>
   <solution>
      <solutionID>Solution_id</solutionID>
      <alias>Solution_alias</alias>
      <type>schema</type>
      <file>
         <type>schema</type>
         <version>1.0</version>
         <filePath>schema1.xsd</filePath>
      </file>         
      <file>
         <type>schema</type>
         <version>1.0</version>
         <filePath>schema2.xsd</filePath>
      </file>         

   </solution>
</manifest>

Schema file in the wrong element. The schema file must be located only in a solution of type "schema." In other words, in the solution type (specified in the <type> element) to which you associate your schema file in the manifest must be schema or your solution fails. The following is an example of a correct solution:

[Correct]
```
<solution>
      <solutionID>Solution_ID</solutionID>
      <alias>Solution_alias</alias>
      <type>schema</type>
      <file>
         <type>schema</type>
   <filePath>\\Server_name\Share_name\SmartDocs\Schema.xsd</filePath>
         <version>1.0</version>
      </file>
   </solution>
```

Unsupported type for the registry value. The current supported values are REG_SZ, REG_DWORD and REG_EXPAND_SZ. The following example shows an unsupported type which causes the manifest to be invalid:

[Incorrect]

   <solution>
      <solutionID>Solution_ID</solutionID>
      <alias>Solution_alias</alias>
      <type>other</type>
      <file>
         <type>other</type>
         <version>1.0</version>
         <filePath>File_name.xml</filePath>
         <registry>
            <registryKey>
   <keyName>HKEY_CURRENT_USER\Software\CustomKey</keyName>

               <keyValue>
                  <valueType>REG_MULTI_SZ</valueType>
                  <valueName>CustomvalueName</valueName>
                  <value>Custom Value Content</value>
               </keyValue>
                        </registryKey>

          </registry>
      </file>         
   </solution>

The CLSID tag is used with the managed tag. If the smart document .DLL file is in managed code, then you should use the CLSNAME tag as shown in the following example.

[Correct]

<solution>
      <solutionID>Solution_ID</solutionID>
      <alias>Solution_alias</alias>
      <type>SmartDocument</type>
      <file>
          <type>solutionActionHandler</type>
        <version>1.0</version>
        <filePath>\\Server_name\Share_name\SmartDocs\File_name.dll</filePath>
        <CLSNAME>My_namespace.My_class_name</CLSNAME>
        <managed>True</managed>
      </file>
      <file>
          <type>installPackage</type>
        <version>1.0</version>
  <filePath>\\Server_name\Share_name\SmartDocs\CASPOLSetSecurity.bat</filePath>
      </file>

   </solution>

Inappropriate use of the CLSID element. Using the CLSID element for anything other than type solutionActionHandler, ActionHandler, Recognizer, SolutionRecognizer, and SolutionActionAndRecognizer, causes a validation error. The following example shows the correct usage:

[Correct]

<solution>
      <solutionID>{704768D2-A6E9-4ecb-8057-882D86A8C742}
   </solutionID>
      <type>smartDocument</type>
      <alias lcid="1033">Proposal Generator</alias>
      <file>
         <type>solutionActionHandler</type>
         <version>1.0</version>
         <filePath>wdSmartDoc.dll</filePath>
         <CLSID>{CCC9DC4F-8FED-4642-9677-43A5AA130505}</CLSID>
         <regsvr32>True</regsvr32>
         <runFromServer>True</runFromServer>
      </file>
   </solution>

The runFromServer element and installPath element in the same file. You use the runFromServer element and set it to True while also using the installPath element. When you use the runFromServer element, do not use the installPath element because you do not need to download the file locally. The following segment shows this error:

[Incorrect]

      <solutionID>Solution_ID</solutionID>
      <alias>Solution_alias</alias>
      <type>schema</type>
      <file>
         <type>schema</type>
   <filePath>\\Server_name\Share_name\SmartDocs\Schema.xsd</filePath>
   <installPath>My_Schema.xsd</installPath>
   <runFromServer>True</runFromServer>
         <version>1.0</version>
      </file>         
   </solution>

Element is in the wrong context. For example, the tag context is allowed only in a solution of type transform, the tags PROGID and application are allowed only inside a file of type COMAddIn.
SolutionID element set to None. This causes a validation error as None is a reserved word.
Version element set to 0.0. Setting the version element of the XML expansion pack to 0.0 causes the manifest to be invalid. It should be in the format of major_number.minor_number and both numbers must be greater or equal to zero. Also the version tag should have the format major.minor.
Incorrect XML expansion pack namespace. The correct XML expansion pack namespace is as follows:
```
http://schemas.microsoft.com/office/xmlexpansionpacks/2003
```
Carriage returns or line feeds. If required or optional XML elements contain carriage returns or line feeds, it causes a validation error.

Processing Error--Cannot Download Components

The following section provides examples of processing errors.

Figure 3. Failing to download all components (click picture to see larger image)

Figure 4. Failing to download some components (click picture to see larger image)

Figures 3 and 4 show processing errors. These errors are thrown when the smart document cannot process the information contained in the manifest file. Examples are as follows:

Paths to the supporting files are wrong. Verify the paths are correct.
Paths to the supporting files are correct, but spelling of file names are wrong and therefore does not match the actual files. Verify the spelling is correct.
Web server is not trusted. For example in the case where the supporting files are located on a Web server. Verify the Web server address is trusted by using your Web browser.
Web server is unavailable. This could have several causes: The supporting files are stored on a different server than the manifest file which explains why you did not get the error shown in Figure 1 ("The XML expansion pack is invalid or cannot be loaded. Contact your system administrator for assistance."). Or, the server becomes unavailable after loading the manifest file. Lastly, the manifest moves after successfully loading the smart document solution. For example, if you move the manifest file and change the file path to your manifest but the manifestLocation information saved in your smart document still refers to the previous location.

To resolve outdated manifestLocation information:

Do one of the following:

When prompted to download the components, click No.
Verify the document property "Solution URL" points to your updated manifest location; if it doesn't change it.
Then, save your smart documents, close and reopen.

-or-
When prompted to download the components, click No.
Then, manually attach the manifest. To do this, point to Tools, click Templates and Add-ins. Next, click XML Expansion Packs, and then click Add. Browse to the manifest file, click the name of the manifest file, and then click Attach.

**Note **These solutions assume that the XML expansion pack is not installed on the current machine or it was installed using the manifest from the updated location.

To view the manifestLocation information:

Save your smart document as an .xml file.
Open the file in a text editor such as Notepad and search for the following string:

sl:manifestLocation

The smart document solution searches for this piece of information in the document first and then the solutionURL.

Loading Error

Figure 5. An error caused by loading of components problems

Figure 5 shows an error when the smart document solution encounters a problem loading one or more components. Examples of this error are as follows:

If it is a managed code smart document:

You have Microsoft Windows® .NET Framework 1.0 and Microsoft Windows® .NET Framework 1.1 installed on your computer. However, you accidentally configured the code access security policy using version 1.0 of the .NET Framework instead of 1.1. Correct this by using the .NET Framework 1.1 to grant Full Trust permissions to the assemblies. Remember to delete the previous settings.
You use the runFromServer tag (that is, set runFromServer to True) and you use location-based evidence for your .NET security policy. However you set your .NET security policy to give Full Trust permission to the local user file location and not the server, for example:
```
%WINDIR%\Microsoft.NET\Framework\v1.1.4322\caspol -pp off -ag 1.1 -url "%UserProfile%\Local
 Settings\Application Data\Microsoft\Schemas\ManagedSample\*" FullTrust -n SDSample_Project
%WINDIR%\Microsoft.NET\Framework\v1.1.4322\caspol -pp on
Pause
```
In this example, your assembly has no permission to run. You can debug this by doing the following: In Visual Studio .NET 2003, attach the Office application you want to use to debug the solution. In Visual Studio, click Debug, and then click Exceptions. In the Exceptions dialog box, click Common Language Runtime Exceptions. In the When the exception is thrown list, click Break into the debugger. Next, press F5.

Two exceptions related to msosec occur. If you have more than one managed smart documents installed, you may get more than two msosec related exceptions. These exceptions are expected and can be safely ignored. Click Continue. The msosec log should show the following:
```
A first chance exception of type 'System.IO.FileNotFoundException' occurred in
 WRDomainSetup Additional information: File or assembly name msosec, or one of its dependencies, was not found. 
A first chance exception of type 'System.IO.FileNotFoundException' occurred in
 WRDomainSetup Additional information: File or assembly name msosec, or one of its dependencies, was not found. 
```
You can safely ignore this message. Verify whether the managed smart document assembly is loaded. If permissions are the issue, the following policy exceptions occur:
```
A first chance exception of type 'System.Security.Policy.PolicyException' occurred in
 mscorlib.dll Additional information: Execution permission cannot be acquired. 
A first chance exception of type 'System.Security.Policy.PolicyException' occurred in
 Unknown Module. Additional information: Execution permission cannot be acquired. 
A first chance exception of type 'System.Security.Policy.PolicyException' occurred in
 Unknown Module. Additional information: Execution permission cannot be acquired. 
A first chance exception of type 'System.Security.Policy.PolicyException' occurred in
 Unknown Module. Additional information: Execution permission cannot be acquired. 
```
You can also debug permission issues by reviewing a combination of call stacks, modules, outputs, and so forth. For example, instead of clicking Continue, click Break, then Ok. Next, click Debug, point to Windows, and then click Call Stack or Module and so on to analyze the output. After breaking, when you want to continue, press F5. To break, click Break at the exception point you want to analyze.
You have to use an interop assembly (IA) because a primary interop assembly (PIA) isn't available or your smart document calls into some dependent assemblies. However, you did not set up .NET security policy to grant those IAs and dependent assemblies Full Trust permissions to run. Note that IAs and dependent assemblies also require Full Trust permissions to run, otherwise they fail to load.
Your smart documents use IA or dependent assemblies and you don't want to run from server. However you didn't specify for these assemblies to be downloaded to the local computer. Your smart documents fail with the above error message because it is missing required components.
The .NET security policy was incorrectly set. You can check this by running the following command:
```
CD %windir%\microsoft.net\framework\v1.1.4322
caspol -all -lg 
Pause
For each assembly that you use in your solution run the following:
CD %windir%\microsoft.net\framework\v1.1.4322
caspol -rsg <assembly_name>
Pause 
```
Note The <assembly_name> element should include the path to the specified assembly. For more information about the code access security policy command line options see Code Access Security Policy Tool (Caspol.exe).

The caspol -all –lg command(which is the same as caspol -all –listgroups) provides a list of all the code groups. The caspol -rsg <assembly_name> command (which is the same as caspol -resolvegroup <assembly_name>) provides a list of the code groups that the assembly belongs to, thereby showing how the evidence of the assembly actually maps to those rules. The output indicates whether or not you have set up the policy correctly and whether or not that particular assembly matches the code group you think it should match. You can then verify whether you set up the code groups incorrectly or not and whether your assembly has permission to run or not.
You failed to restart Excel or Word (and Microsoft Office Outlook 2003 if using Word as an e-mail editor) when setting .NET security policy. Word and Excel use a cached copy of the policy. To resolve this issue, restart Word or Excel. Also check Task Manager to make sure there are no hidden instances of Word, Excel or Outlook applications running.
Your registered managed smart documents Namespace.ClassName doesn't match the actual assembly Namespace.ClassName. Therefore, your smart document assembly cannot load. Verify the registered name matches the actual name specified in the CLSNAME tag in the manifest.
There is a problem with your code or your assembly is damaged or corrupted. You should review your code for logic errors and make sure that have built an intact assembly.

If it is an unmanaged code smart document.

Your smart document DLL is unsigned and your Office security level is at High or Very High with Trust all installed add-ins and templates unchecked. To run unsigned DLLs, set your security at one of the following:
- Medium with Trust all installed add-ins and templates unchecked.
- High with Trust all installed add-ins and templates checked.
  
  Remember to reset your security level to the previous level after testing. For more information about security guidelines, see the Microsoft Office Smart Document 2003 SDK.
Your CLSID for the registered smart document DLL doesn't match the actual CLSID. Therefore, your smart document assembly fails to load. Verify the registered CLSID matches the actual CLSID. The CLSID value can be found in the registry in the normal way. For more information, see COM Class Objects and CLSIDs
There is a problem with your code or your DLL is damaged or corrupted.

General

You failed to define at least one action for the URI specified in the manifest or the smart documents namespace "http://schemas.microsoft.com/office/smartdocuments/2003"

For example if you have a URI element value of the following:
```
<uri>urn:schemas-microsoft-com.office2003demos.test</uri>
```
The value for your SmartDocXmlTypeName property must include either or both the URI value or the smart document namespace as shown in the following example:

Note The following example includes extra paragraph marks to enable this example to display correctly. To use this example in working code, remove the extra paragraph marks.
```
Private Property Get ISmartDocument_SmartDocXmlTypeName(ByVal SmartDocID As Long) As String

   Select SmartDocID
     case 1
        ISmartDocument_SmartDocXmlTypeName = "urn:schemas-microsoft-com.office2003demostesttag1"
     case 2
        ISmartDocument_SmartDocXmlTypeName http://schemas.microsoft.com/office/smartdocuments
/2003default
End Select
End Sub
```
The code fails when running the SmartDocInitialize method. Therefore, the smart document solution fails to implement the ISmartDocument interface. It is good practice to add code to trap and capture exceptions in the SmartDocInitialize method.
If you run a managed smart document, and there is a delay between attaching the smart document and the error, the smartdocument class may fail to initialize properly. Most likely this indicates a problem in your code. Possible issues include:
- You didn't implement the right interface
- You didn't return matching namespace
- Your code threw an exception

If there is no delay between when you attach the smart document and the appearance of the error, then your managed class probably failed to initialize for a different reason. Make sure you specified the correct DLL name, configured the permissions correctly, and other items mentioned in this document.

More Debugging Tips

The following is a list of other tips when debugging smart document errors.

Set the debugger to trap all managed exceptions. Some exceptions such as dependency failures may occur outside of your Try...Catch statement but should be trapped by Word. You never see them unless you set the debugger to stop first.
Logging is useful. For example, System.Diagnostics.Debugger.Break() is a useful method you can call in your code. This statement can be helpful if you are having problems attaching your solution to the debugger in Visual Studio .NET 2003.
If the manifest does not include the <runFromServer> element, then this is the same as setting the <runFromServer> element to False. When this is set to False, the smart document DLL is copied locally to the following location whether its managed or unmanaged:

Drive:\Documents and settings\User_name\Local Settings\Application Data\

If you debug using this configuration, you fail to hit your breakpoint since the smart document DLL being run is the copy and not the one from the original location. To run the smart document DLL from the original location, add and set the <runFromServer> element to True in the manifest file. If your solution is managed code, you must modify the .NET security policy to trust this directory location, assuming you specify Trust level based on location while in development and not based on publisher or strong name key.

For more information about attaching to a debugger and logging exceptions, see the Microsoft Visual Studio 6 and Microsoft Visual Studio .NET documentation.

Update Processing Error

Figure 6. An error encountered while processing an update

Figure 6 shows a processing error. This error sometimes occurs when you click Update on the XML Expansion Packs dialog box or the updateFrequency time lapses.

It also occurs when you do not to use runFromServer (set to True). This means you download new files locally and overwrite existing ones. This causes an error if the smart document is currently in use, as it cannot be overwritten. To resolve this, close Excel or Word (and Microsoft Office Outlook 2003 if using Word as the e-mail editor). Also check the Task Manager to make sure there are no hidden instances of Word, Excel or Outlook running. Then restart the application.

Conclusion

When debugging smart documents error messages, it is important to identify the stage at which each of the errors is thrown. For example identifying something as a loading error means you don't waste time troubleshooting it as a manifest issue. Knowing the stage at which each of these error messages are thrown helps you narrow down issues and troubleshoot more effectively and in less time.

Acknowledgement

Thanks to Peter Torr from the Microsoft Visual Studio Tools for the Microsoft Office System team for his contributions and guidance on troubleshooting .NET security policy and permissions issues, and Matthew Blain of Serriform, LLC, for his contributions to the "Loading Error" troubleshooting tips.

Troubleshooting Smart Documents Error Messages

Contents

Introduction

Error Due to an External Issue

Manifest Validation Error

Processing Error--Cannot Download Components

To resolve outdated manifestLocation information:

To view the manifestLocation information:

Loading Error

If it is a managed code smart document:

If it is an unmanaged code smart document.

General

More Debugging Tips

Update Processing Error

Conclusion

Acknowledgement

Additional resources