Build-Time Dependencies

Note

This topic generally does not apply when you are building an application manifest or performing an automatic build. The text is written with the assumption that you have a problem with building an assembly. Nevertheless, the techniques described here are also helpful if you isolated an application and it does not work.

What are build time dependencies

When building assemblies, Manifest Maker does not know what other COM objects or DLLs will be available on the target machine when the assembly is actually used. To avoid creating hidden dependencies that will make the assembly not work, Manifest Maker hides all COM objects from the DLLs included in the assembly. When the assembly DLLs are then loaded by Manifest Maker they may fail to initialize because of missing DLLs or COM objects that they need to load.

To accommodate this Manifest Maker allows you to define what resources should be made available during the assembly build.

Most common errors are:

Error 0x80040154: Class not registered

This indicates that the DLL needs a COM object that was not defined to Manifest Maker. Add appropriate DLL or assembly (shared or private if in an immediate subdirectory) to the Build Time Dependencies list.

Error 126: The specified module could not be found

A DLL is needed, normally a non-COM DLL. Use Microsoft Dependency Viewer (depends.exe) to see if there are unresolved static dependencies. Use the technique described below to see what dynamic dependencies are unresolved.

Error 127: The specified procedure could not be found.

There is an appropriate DLL but it does not contain a required procedure export. The DLL is probably too old, use a newer version.

How to find out what is required

The first place to look is the installation procedure for the product in question. Just look at the list of files installed by the standard setup and check if all DLLs are available to the DLLs being packaged in this assembly. If they are not in the Manifest Files list (top) and not in the Build-Time Dependencies (bottom list), they are not available.

If the DLL or the application for which this DLL is intended is build by in-house developers - talk to them, they should know.

If all else fails - investigate yourself...

Most common dependencies

Some DLLs are used very frequently. So frequently, that some users of Manifest Maker always add them to the Build-Time Dependencies list.

ATL.dll

ATL helper and registrar.

MSVBVM60.dll

Visual Basic 6 runtime.

Using Dependency Viewer

Microsoft Dependency Walker now has its own home at http://dependencywalker.com/. This is an indispensable tool for finding missing DLL dependencies required by somebody else's code. When you are the developer of the code being packaged, you know what DLLs and COM objects are required. Not necessarily so with third party software. Use Dependency Walker.

The moment you open a DLL or an executable in Dependency Viewer, it recursively scans import tables and locates all imported DLLs and exported and imported entry points. The first thing you should do is ignore all missing delay-load imports and, in most cases, all error messages pertaining to Windows DLLs.

Look for yellow marks at all non-system DLLs. These are all required to load the DLLs.

If there are no more missing DLLs in the UI, there may be DLLs loaded dynamically at runtime - proceed to round two.

Dependency Viewer - Round Two

You may need to actually run the program or load the DLL inside depends.exe to allow the program check run-time load requests. If you need to find missing DLLs for an executable - run that program with appropriate parameters. If you are investigating a DLL (for a shared or private assembly, for example) run REGSVR32.EXE <your DLL path>.

The log window displays in red failing DLL loads and entry point lookup calls - study the list. Every failing LoadLibrary* loading a DLL with no path can be fixed - just add the DLL to run-time dependencies or the manifest, whichever is appropriate. Any DLLs loaded with an explicit path must be in that explicitly named directory - no manifest will help here.

Missing COM Classes

Dependency Viewer is a great tool for finding missing DLLs, but it does not help much with missing COM objects. The most common error you will see is Class not registered. This means that the code being executed requested a COM object and COM could not find the object definition.

As we said elsewhere Windows will look for a class first in the activation context (the sum of all loaded manifests) then in the registry. If you see Windows look for any class in the registry - that class is not in the manifest.

The tool to use here is Process Monitor (Procmon.exe) from Microsoft TechNet's SysInternals.

This is an outstanding tool for monitoring registry usage by applications.

The procedure is:

• Run procmon.exe.
• Click the Build button in Manifest Maker.
• Stop capturing in Process Monitor as soon as Manifest Maker displays the error message.
• Examine Process Monitor log, look for failed attempts to open subkeys of HKCR\CLSID.

The identifiers in curly braces that look somewhat like this {0CD7A5C0-9F37-11CE-AE65-08002B2E1262} are class IDs. A failed attempt to open one of these will generate the above Class not registered error.

Other Useful Tools

Procmon.exe

From Microsoft TechNet's SysInternals. Monitors not only registry activity as described above but also file operations. Very helpful when investigating what files is the application trying to access. Use Procmon to find out how your program looks for assembly manifests or DLLs. Supplements the Dependency Viewer runtime log when pinpointing loaded DLLs.

filemon.exe, regmon.exe

Older tools from Mark Russinovich currently replaced by Process Monitor.

WinDBG.exe

Windows debugger, a part of Debugging Tools for Windows available for free from Microsoft. Particularly interesting is the LOGEXTS extension. It allows you to log all or selected API calls made by the program along with results and parameter lists. Use !load logexts command to load it then type !help to get command help. Typical sequence of commands may be:

!load logexts
!help
!logc e *
!logo e v
!loge
g

AtlTraceTool.exe

ATL and MFC program tracing tool that comes with Microsoft Visual Studio. Release-built programs normally do not contain trace statements. In reality surprisingly many do.

oleview.exe

COM/OLE object registration viewer (comes with multiple MS products including Visual Studio). Allows you to examine existing OLE/COM registrations in an organized, graphical UI. It is much more effective for this purpose then REGEDIT.