Description
A Windows "Side-by-Side" error occurs when a Windows application is unable to locate a dll file that the application depends on.
Side-by-Side assemblies and manifests
"Side-by-Side", also known as "WinSxS", "SxS" or "Fusion", is an extension to the Windows application model that allows software components to express dependency information. A Side-by-Side "assembly" contains a collection of resources - usually a group of dlls - that are always provided to applications together. These files are described in the assembly "manifest". The Microsoft Visual C++ run-time libraries are an example of an assembly that contains multiple dll files. Both Visual Studio 2005 and 2008 employ Side-by-Side when building a program, including an embedded binary manifest that records the C++ run-time version information. When that program runs, the Side-by-Side manager determines whether the application has a version dependence described in a manifest. (If there is no relevant manifest, the system loads the default version of the assembly).
Real-life example of a Side-by-Side error during OCR
An issue reported by some Clearwell users is that of all OCR failing with the "general" OCR error being reported in the OCR log file D:\CW\VXXX\logs\OCRConverter_output.log
:2016-09-09 15:27:36,381 INFO [OCRConverter] (10856:OCRConverter) Starting OCR conversion process
2016-09-09 15:27:36,394 ERROR [OCRConverter] (10856:OCRConverter) Conversion of D:\CW\V811R1\scratch\temp\esadb\dataStore_case_awda6d5rmj_20692977\cache02\AttHT
MLCache\daa\367\69a772c0858385d1d5ba46df9b\d00\1\1.JPG failed, error was: Err : Error code = 8004C40D API_ERROR_ERR: General error in the Engine.
One big difficulty when troubleshooting OCR issues is that the OCR software always reports this same "general" error message. However, if a Side-by-Side error has caused the OCR to fail, an additional error will be recorded in the Windows Application Event log (Figure 1).
Figure 1.
Here is the error shown in Figure 1:
Activation context generation failed for "D:\CW\V811R1\exe\ocr\WC_OPSteps.dlm". Dependent Assembly
Microsoft.VC80.MFC,processorArchitecture="x86",publicKeyToken="1fc8b3b9a1e18e3b",type="win32",version="8.0.50727.762" could not be found.
Please use sxstrace.exe for detailed diagnosis.
This error indicates that the OCR application was built with a dependency on version 8.0.50727.762
of the assembly Microsoft.VC80.MFC
. This assembly version number corresponds to the C++ run-time package Microsoft Visual C++ 2005 SP1 Redistributable Package (x86). The error shown above can therefore be resolved by installing the missing C++ run-time package.
The sxstrace.exe utility
The sxstrace.exe
utility (mentioned in the error in the Windows Event Log) can be used to determine the C++ run-time version that a program depends on. The following steps show how to capture a trace for an OCR that is run from the command-line (an excellent way to verify if OCR is working):
- Launch a command window and change to the directory
D:\CW\VXXX\exe\ocr
Note: It has been found that thesxstrace.exe
utility must be run from inside theD:\CW\VXXX\exe\ocr
directory in order to generate a full capture. - Start the capture with a specified output file name:
D:\CW\VXXX\exe\ocr>sxstrace.exe trace -logfile:D:\mytrace.etl
- Start a second command window and run the OCR command-line, specifying the input file and an output file name:
D:\CW\VXXX\exe\ocr>OCRConverter.exe -i d:\ocr_test\SAMPLE1.tif -o d:\ocr_test\out.txt
Note: When running an OCR test on the command-line like this, the command must be run from inside theD:\CW\VXXX\exe\ocr
directory.
Note: This example uses the same fileSAMPLE1.tif
that can be found in the Clearwell product directoryD:\CW\VXXX\exe\ocr
- In the command window that is running the capture, stop the capture by simply pressing <Enter>.
- Convert the capture file to text format:
D:\>sxstrace.exe parse -logfile:d:\mytrace.etl -outfile:d:\mytrace.txt
The trace confirms that the OCR file WM_OPSteps.dlm
has a dependency on Microsoft.VC80.MFC
version 8.0.50727.762
:=================
Begin Activation Context Generation.
Input Parameter:
Flags = 0
ProcessorArchitecture = Wow32
CultureFallBacks = en-US;en
ManifestPath = D:\CW\V82\exe\ocr\WM_OPSteps.dlm
AssemblyDirectory = D:\CW\V82\exe\ocr\
Application Config File =
-----------------
INFO: Parsing Manifest File D:\CW\V82\exe\ocr\WM_OPSteps.dlm.
INFO: Manifest Definition Identity is (null).
INFO: Reference: Microsoft.VC80.CRT,processorArchitecture="x86",publicKeyToken="1fc8b3b9a1e18e3b",type="win32",version="8.0.50727.762"
INFO: Reference: Microsoft.VC80.MFC,processorArchitecture="x86",publicKeyToken="1fc8b3b9a1e18e3b",type="win32",version="8.0.50727.762"
Note: This trace indicates that this particular component of the OCR software was built with a dependency on the C++ run-time package Microsoft Visual C++ 2005 SP1 Redistributable Package (x86), However, as we will see shortly, the Clearwell appliance does not actually need to have this exact same run-time package installed in order for the OCR to work.
Re-directed assembly versions
If we examine more of the sxstrace trace that we captured earlier, which was taken from a successful OCR, we see that the OCR application actually used version 8.0.50727.6195
of Microsoft.VC80.MFC
, and not version 8.0.50727.762
:
INFO: Resolving reference for ProcessorArchitecture x86.
INFO: Resolving reference for culture Neutral.
INFO: Applying Binding Policy.
INFO: Find publisher policy at C:\Windows\WinSxS\manifests\x86_policy.8.0.microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_49f31fd71413cdc6.manifest
INFO: Publisher Policy redirected assembly version.
INFO: Post policy assembly identity is Microsoft.VC80.MFC,processorArchitecture="x86",publicKeyToken="1fc8b3b9a1e18e3b",type="win32",version="8.0.50727.6195".
The version number 8.0.50727.6195
corresponds to the C++ run-time package Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package MFC Security Update. This is newer than Microsoft Visual C++ 2005 SP1 Redistributable Package (x86)
So why did our OCR work when version 8.0.50727.762
was not installed? The OCR worked because the C++ run-time version that was installed (8.0.50727.6195
) includes a policy file that re-directs users of 8.0.50727.762
to 8.0.50727.6195
. With version 8.0.50727.6195
installed, the policy file can be found here:
C:\Windows\WinSxS\Manifests\x86_policy.8.0.microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_49f31fd71413cdc6.manifest
This policy file includes some "assembly re-directions": <bindingRedirect oldVersion="8.0.41204.256-8.0.50608.0" newVersion="8.0.50727.6195"/>
<bindingRedirect oldVersion="8.0.50727.42-8.0.50727.6195" newVersion="8.0.50727.6195"/>
This is why the OCR works successfully even when 8.0.50727.762
is not installed.
Note: In order to resolve the Side-by-Side example error described in this article it is preferable to install the C++ run-time package Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package MFC Security Update.
The C:\Windows\WinSxS
directory
The directory C:\Windows\WinSxS
is the Side-by-Side store (also known as the "Windows component store"). It is conceptually the native equivalent of the .NET "Global Assembly Cache" (GAC). This directory contains the dll files and manifests associated with each Side-by-Side assembly. The size of this directory can grow to several GB in size as more applications are installed. As one might imagine however, uninstalling an application does not usually remove files from this directory, as the files could be needed by other applications. Note: Never modify the files in this directory.
Because the directory contains many files, a good way to search for relevant files is to specify the assembly name and the leading part of the assembly version number, for example:
C:\Windows\WinSxS>dir /s /b *Microsoft.VC80.MFC*50727*
C:\Windows\WinSxS\x86_microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_cbf5e994470a1a8f
C:\Windows\WinSxS\Manifests\x86_microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_cbf5e994470a1a8f.cat
C:\Windows\WinSxS\Manifests\x86_microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_cbf5e994470a1a8f.manifest
C:\Windows\WinSxS\Manifests\x86_policy.8.0.microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_49f31fd71413cdc6.cat
C:\Windows\WinSxS\Manifests\x86_policy.8.0.microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_49f31fd71413cdc6.manifest
If we list the files in directory C:\Windows\WinSxS\x86_microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_cbf5e994470a1a8f
we see all of the dll files in the assembly:
C:\>dir /b C:\Windows\WinSxS\x86_microsoft.vc80.mfc_1fc8b3b9a1e18e3b_8.0.50727.6195_none_cbf5e994470a1a8f
mfc80.dll
mfc80u.dll
mfcm80.dll
mfcm80u.dll
Note: Never modify the files in the C:\Windows\WinSxS
directory.