Jaa

.NET Compact Framework Version 2 .CAB Files Explained

  • Artikkeli

Abstract

Just like other Windows CE applications, .Net Compact Framework V2 (NETCF V2) is distributed as a set of CAB files. This article describes these CABs and discusses potential installation problems as well as ways to solve these problems.

NETCF V2 CABs – which one is for which device?

NETCF V2 currently includes seven CAB files. Table below describes platforms and CPUs supported by each CAB. 

CAB name Supported Platform(s) Supported CPU(s)
NETCFv2.ppc.ARMV4.cab Pocket PC 2003

Pocket PC 2003 SE

 ARMV4
NETCFv2.wm.armv4i.cab Windows Mobile 5.0 Pocket PC

Windows Mobile 5.0 Smart Phone

 ARMV4I
NETCFv2.wce5.sh4.cab Windows CE 5.0 SH4
NETCFv2.wce5.mipsii.cab Windows CE 5.0 MIPS II

MIPS II FP
NETCFv2.wce5.mipsiv.cab Windows CE 5.0 MIPS IV

MIPS IV FP
NETCFv2.wce5.armv4i.cab Windows CE 5.0 ARMV4I
NETCFv2.wce5.x86.cab Windows CE 5.0 X86

 Note: “Pocket PC” also includes “Pocket PC Phone Edition”.

What is inside the CAB?

Each CAB file contains at least one native (CPU dependent) NETCF runtime, CPU independent managed libraries and setup DLL. In some cases CAB file contains more than one native runtimes, each optimized for particular CPU flavor. For example, NETCFv2.wce5.mipsii.cab contains two runtimes, one for MIPS II CPU and another one for MIPS II FP CPU (which has dedicated floating point unit). Correct runtime files are picked at installation time by setup DLL, unused files are discarded to save space.

Some files in runtime called shared files are special – they have the same names and install locations as similar files in NETCF V1. They are treated in a special way. That is needed to allow side by side installation of NETCF versions.

What happens upon NETCF V2 CAB installation?

NETCF V2 installation is handled by standard WCELOAD utility just like with any normal CAB. It would invoke setup DLL which performs following tasks:

-         Locating other installed NETCF versions.

-         Creates registry entries for installed version and removes entries for old one if found

-         Picks and deploys runtime for specific CPU flavor. Shared files are deployed based on files versions to avoid issues with incorrect time stamps.

-         Creates list of managed libraries and adds them to GAC.

-         Verifies versions of shared files to ensure correct installation.

All these steps along with some extra information like available memory and device type are logged to the file “Microsoft .NET CF 2.0.LOG.TXT” located in the root folder. In case of failure this log file can be used to figure out the failure reason and take appropriate steps to correct the situation. Failures are also reported to the end user via message box (unless installation runs in silent mode).

Installing NETCF V2 to storage card

While it is technically possible to redirect installation of NETCF onto storage card via standard Active Sync/WCELOD capabilities, it won’t save precious RAM on device. NETCF files have to be in \Windows folder in order for NETCF to function properly.

If NETCF is installed to storage card, NETCF files will be initially deployed to it. However, at some point they would moved to \Windows folder taking out exactly the same space as normal installation would.

In some cases attempt to use storage card would lead to installation failure due to some subtle storage card issues. Thus it’s not recommended to install NETCF V2 to storage card or embedded storage and there are no benefits of doing so.

Platform and CPU restriction in NETCF CAB files

NETCF V2 CAB files can be deployed via Active Sync by using standard CEAPPMGR.EXE and properly constructed INI file. Active Sync will pick the right CAB for connected device and install it.

To accomplish that, platform and CPU information from CAB file is used. That makes NETCF V2 CAB files somewhat restricted to specific platforms because WCELOAD also verifies this information upon installation and will refuse to install CAB file if it appears to be incompatible with the device.

Here’s information from each CAB:

CAB name OS version min OS version max CPU ID Supported platform Unsupported platforms
NETCFv2.ppc.ARMV4.cab 4.000 4.999 2577 PocketPC 3.000-3.999 SmartPhone
NETCFv2.wm.armv4i.cab 5.000 5.999 2577 n/a n/a
NETCFv2.wce5.sh4.cab 5.000 5.999 10005 n/a SmartPhone

PocketPC
NETCFv2.wce5.mipsii.cab 5.000 5.999 4000 n/a SmartPhone

PocketPC
NETCFv2.wce5.mipsiv.cab 5.000 5.999 5000 n/a SmartPhone

PocketPC
NETCFv2.wce5.armv4i.cab 5.000 5.999 n/a n/a SmartPhone

PocketPC
NETCFv2.wce5.x86.cab 5.000 5.999 n/a n/a SmartPhone

PocketPC

Note: All CAB files also have obsolete HPC and Jupiter in a list of unsupported platforms.

As you can see, ARMV4I and x86 Windows CE 5.0 CABs don’t have CPU ID information. That’s because multiple supported CPU IDs are possible. For example, x86 device can have CPU ID of 586 or 686. Since both are supported, but CAB file format only allows for no more than one CPU ID, we choose to remove CPU ID from such CAB files.

Another problem to notice, x86 and ARMV4I Windows CE CABs have exactly the same information in the CAB, so how does Active Sync distinguish them? To our regret, it does not. To resolve this situation x86 CAB was removed from CABs list in INF file and won’t be deployed by NETCF MSI. We hope it won’t be a problem since embedded x86 devices are rarely connected via Active Sync and software is unlikely to be installed by end user via NETCF MSI. That does not affect Visual Studio ability to deploy NETCF.

What exactly are those platform names and CPU ID CAB file has and how to retrieve them?

This information is specified by device’s OEM and can be obtained via Windows APIs. It is retrieved by Active Sync to pick the CAB and also by WCELOAD to see if CAB is compatible.

CPU ID information can be obtained by calling GetSystemInfo() function. It would be in dwProcessorType field of SYSTEM_INFO structure.

Details can be found here:

https://msdn.microsoft.com/library/default.asp?url=/library/en-us/wcesdkr/html/_wcesdk_win32_getsysteminfo.asp

Platform name and version can be retrieved by calling SystemParametersInfo() function with SPI_GETPLATFORMTYPE and SPI_GETPLATFORMVERSION arguments respectively.

Please see this for details:

https://msdn.microsoft.com/library/default.asp?url=/library/en-us/wceshellui5/html/wce50lrfSystemParametersInfo.asp

Installation failed. Now what?

Platform restriction issues.

In case WCELOAD believes CAB file does not match the device, it will refuse to proceed with installation. For example, attempt to install NETCFv2.ppc.ARMV4.cab on generic Windows CE 4.2 device will fail even though Pocket PC 2003 based on the same Windows CE version. This is unsupported platform, so failure is expected.

In some rare cases WCELOAD might refuse to install NETCF V2 CAB file on supported device due to issues with OS. For example, it’s not possible to install NETCF V2 CAB file on some early Pocket PC 2003 devices due to following issue:

https://support.microsoft.com/default.aspx?scid=kb;en-us;824409

There’s no workaround besides ROM upgrade. Check with your hardware manufacturer to see if there is a ROM update available.

Other potential issues with platform restriction can arise in custom built Windows CE images. It is important to make sure all OEM information is set correctly and calls to APIs described above returns expected results on custom Windows CE devices.

Installation time issues.

If CAB file was not rejected by WCELOAD right away as described in a previous section, failure might occur later on. Most common reasons for these failures are:

-         Newer version of NETCF is installed.

-         Device is not compatible with selected CAB file.

-         Low storage and/or program memory.

-         Device security settings prohibit installation (for Windows Mobile 5.0)

-         Managed application is running which prevents deployment of new files.

-         Failure to add managed files to GAC.

Since downgrade is not supported, if newer (not side by side) version is installed (e.g. future NETCF V2 release), installation will be terminated. That can be fixed by removing newer version.

In all other cases generic error message with error ID will be reported. These errors are:

ID Meaning Most likely reasons Way to fix it
1 CAB expansion failed Low memory

 

 Free up some memory.
2 Setup DLL failed to copy runtime files Managed application is running, preventing files from been overwritten. Terminate running managed applications.
3 CGACUTIL can not add managed libraries to GAC Low memory, attempt to install to HP 4700 file storage. Free up some memory, install to main memory only.
4 Shared files version is incorrect Incompatible device, security issues on WM 5.0 (installation prohibited by phone carrier). Use correct CAB file for this device. Try manual installation, answer “yes” to security prompt.

Note: “memory” in this table refers to normal storage memory (persistent storage on WM 5.0). Adding storage card won’t help in low memory condition.

Log file walk through

 

Log entry Description
10/10/2005 14:44:10: Entered Install_Init().

First Call: Yes

Previously Installed: No

Installation folder is: '\Program Files\.NET CF 2.0'.

 Installation started, CAB file is not unpacked yet. Information passed by WCELOAD to setup DLL is printed out.
10/10/2005 14:44:10: Build 2.0.5238.00 NETCF build number we’re installing.
10/10/2005 14:44:10: Device CPU: 'ARMV4', 05010000 (83951616)

10/10/2005 14:44:10: PocketPC 4.20

10/10/2005 14:44:10: Our trust level is: 2

10/10/2005 14:44:10: User LCID: 1033

10/10/2005 14:44:10: System LCID: 1033

 Device information which includes CPU type, platform name, OS version and device locale.
10/10/2005 14:44:10: Invoker's command line: '"\NETCFv2.ppc.ARMV4.cab"' WCELOAD’s command line.
10/10/2005 14:44:10: Memory status, K --------------------------

10/10/2005 14:44:10: Load : 31

10/10/2005 14:44:10: Physical : 31804

10/10/2005 14:44:10: Physical free : 22080

10/10/2005 14:44:10: Virtual : 32768

10/10/2005 14:44:10: Virtual free : 28864

10/10/2005 14:44:10: Storage status, K -------------------------

10/10/2005 14:44:10: Available to us: 23114

10/10/2005 14:44:10: Total storage : 31732

10/10/2005 14:44:10: Available total: 23114

10/10/2005 14:44:10: -------------------------------------------

 Memory status information prior to installation.

 
10/10/2005 14:44:10: About to process registry.

10/10/2005 14:44:10: Opened CF registry key OK.

10/10/2005 14:44:10: Looking for upgradeable installations for version '2.0.5238.00'

10/10/2005 14:44:10: Added new CF version value '2.0.5238.00'.

10/10/2005 14:44:10: CF registry key closed.

 Setup DLL would check for installed version by looking into NETCF registry entry. That entry would be removed if “upgradeable” version is found. Side by side version would remain unchanged. New entry would be added for version we’re installing.
10/10/2005 14:44:18: Entered Install_Exit().

Failed Dirs: 0

Failed Files: 0

Failed RegKeys: 0

Failed RegVals: 0

Failed Shortcuts: 0

 WCELOAD just expanded the CAB file, number of failed items shown.
10/10/2005 14:44:18: Memory status, K --------------------------

10/10/2005 14:44:18: Load : 31

10/10/2005 14:44:18: Physical : 31804

10/10/2005 14:44:18: Physical free : 22072

10/10/2005 14:44:18: Virtual : 32768

10/10/2005 14:44:18: Virtual free : 28864

10/10/2005 14:44:18: Storage status, K -------------------------

10/10/2005 14:44:18: Available to us: 23160

10/10/2005 14:44:18: Total storage : 31732

10/10/2005 14:44:18: Available total: 23160

10/10/2005 14:44:18: -------------------------------------------

 Memory status after CAB file was expanded.
10/10/2005 14:44:18: About to verify reference count.

10/10/2005 14:44:18: PocketPC 4.20

10/10/2005 14:44:18: CE 4 or below detected. Attempting to correct ref count.

10/10/2005 14:44:18: Counting CF installations.

10/10/2005 14:44:18: Found matching file 'MSCOREE2_0.dll'.

10/10/2005 14:44:18: Found 1 CF installation(s).

10/10/2005 14:44:18: Number of CF installations determined to be 1.

10/10/2005 14:44:18: Opened ref count registry key OK.

 Special process to work around shared files reference count on Window CE 4.2 based platforms. Reference count is responsible for keeping track of shared files to allow side by side installations.
10/10/2005 14:44:19: About to process alternative files. “Alternative files” are CPU specific NETCF runtime(s).
10/10/2005 14:44:19: PocketPC 4.20

10/10/2005 14:44:19: Processing alternative file: '\Program Files\.NET CF 2.0\cgacutil.exe.-410~-410~ARMV4'.

10/10/2005 14:44:19: Special file extension: '.-410~-410~ARMV4'.

10/10/2005 14:44:19: File is intended for OS: -410 to -410, CPU: ARMV4

10/10/2005 14:44:19: Device CPU: 'ARMV4', 05010000 (83951616)

10/10/2005 14:44:19: CPU matches.

10/10/2005 14:44:19: Version MIN ignored.

10/10/2005 14:44:19: Version MAX ignored.

 Setup DLL checks file’s information (encoded in file’s extension) and compares it with device information. In this case file matches the device.

 

If file does not match, it will be deleted. That means if device does not match the CAB, vital files won’t be deployed at all. That would be caught later on in shared file version verification.
10/10/2005 14:44:19: Querying version of file '\Program Files\.NET CF 2.0\cgacutil.exe.-410~-410~ARMV4'.

10/10/2005 14:44:19: Version determined to be: 2.0.5238.0.

10/10/2005 14:44:19: Get version completed.

10/10/2005 14:44:19: Querying version of file '\Windows\cgacutil.exe'.

10/10/2005 14:44:19: Version determined to be: 2.0.5238.0.

10/10/2005 14:44:19: Get version completed.

10/10/2005 14:44:19: Suggestion: overwrite.

 Setup DLL now queries version of the file already on device and version of a file to be installed. Older file won’t overwrite newer one to allow for side by side installations.
10/10/2005 14:44:19: Copy file from '\Program Files\.NET CF 2.0\cgacutil.exe.-410~-410~ARMV4' to '\Windows\cgacutil.exe': done. File is deployed OK.
10/10/2005 14:44:19: Delete file '\Program Files\.NET CF 2.0\cgacutil.exe.-410~-410~ARMV4': done. And original deleted to save space.
10/10/2005 14:44:19: Processing alternative file: '\Program Files\.NET CF 2.0\mscoree.dll.-410~-410~ARMV4'.

10/10/2005 14:44:19: Special file extension: '.-410~-410~ARMV4'.

10/10/2005 14:44:19: File is intended for OS: -410 to -410, CPU: ARMV4

10/10/2005 14:44:19: Device CPU: 'ARMV4', 05010000 (83951616)

10/10/2005 14:44:19: CPU matches.

10/10/2005 14:44:19: Version MIN ignored.

10/10/2005 14:44:19: Version MAX ignored.

10/10/2005 14:44:19: Querying version of file '\Program Files\.NET CF 2.0\mscoree.dll.-410~-410~ARMV4'.

10/10/2005 14:44:19: Version determined to be: 2.0.5238.0.

10/10/2005 14:44:19: Get version completed.

10/10/2005 14:44:19: Querying version of file '\Windows\mscoree.dll'.

10/10/2005 14:44:19: Version determined to be: 2.0.5238.0.

10/10/2005 14:44:19: Get version completed.

10/10/2005 14:44:19: Suggestion: overwrite.

10/10/2005 14:44:19: Copy file from '\Program Files\.NET CF 2.0\mscoree.dll.-410~-410~ARMV4' to '\Windows\mscoree.dll': done.

10/10/2005 14:44:19: Delete file '\Program Files\.NET CF 2.0\mscoree.dll.-410~-410~ARMV4': done.

 Process is repeated for other files we have.
10/10/2005 14:44:19: Attempting to remove old files from GAC.

10/10/2005 14:44:19: Delete GAC list file: failure

10/10/2005 14:44:20: Run: '\Windows\cgacutil.exe /silent /refresh ', error code: 0 (00000000), exit code: -1 (FFFFFFFF)

10/10/2005 14:44:20: Refreshed GAC.

 We’ll try to remove older version of NETCF V2 assemblies form GAC. That’s needed if update or reinstall is been performed.
10/10/2005 14:44:20: About to add files to the GAC.

10/10/2005 14:44:20: GAC list file opened.

10/10/2005 14:44:20: Writing UTF8 signature: done.

10/10/2005 14:44:20: Adding file 'mscorlib.dll': added.

10/10/2005 14:44:20: Adding file 'system.dll': added.

10/10/2005 14:44:20: Adding file 'system.drawing.dll': added.

10/10/2005 14:44:20: Adding file 'system.messaging.dll': added.

10/10/2005 14:44:20: Adding file 'system.web.services.dll': added.

10/10/2005 14:44:20: Adding file 'system.windows.forms.dll': added.

10/10/2005 14:44:20: Adding file 'system.windows.forms.datagrid.dll': added.

10/10/2005 14:44:20: Adding file 'system.xml.dll': added.

10/10/2005 14:44:20: Adding file 'system.net.irda.dll': added.

10/10/2005 14:44:20: Adding file 'system.data.dll': added.

10/10/2005 14:44:20: Adding file 'microsoft.visualbasic.dll': added.

10/10/2005 14:44:20: Adding file 'microsoft.windowsce.forms.dll': added.

10/10/2005 14:44:20: Adding file 'Microsoft.WindowsMobile.DirectX.dll': added.

10/10/2005 14:44:20: Adding file 'CustomMarshalers.dll': added.

10/10/2005 14:44:20: Closed list file.

 List of files to add to the GAC is created. It can not be hard coded as install location might vary on localized devices.
10/10/2005 14:44:28: Run: '\Windows\cgacutil.exe /silent /id \Windows\Microsoft .NET CF 2.0.GAC', error code: 0 (00000000), exit code: 0 (00000000)

10/10/2005 14:44:28: GACing: completed.

 CGACUTIL utility is invoked to add files to the GAC. None-zero exits code means failure.
10/10/2005 14:44:28: About to verify installation...

10/10/2005 14:44:28: Querying version of file '\Windows\cgacutil.exe'.

10/10/2005 14:44:28: Version determined to be: 2.0.5238.0.

10/10/2005 14:44:28: Get version completed.

10/10/2005 14:44:28: Querying version of file '\Windows\mscoree.dll'.

10/10/2005 14:44:28: Version determined to be: 2.0.5238.0.

10/10/2005 14:44:28: Get version completed.

10/10/2005 14:44:28: Shared files version verification: done.

 Shared files versions (and files presence) are compared against installing NETCF version. If versions are same or above, installation considered successful.
10/10/2005 14:44:28: Installation completed, no errors detected. We’re good to go.
10/10/2005 14:44:28: Memory status, K --------------------------

10/10/2005 14:44:28: Load : 31

10/10/2005 14:44:28: Physical : 31804

10/10/2005 14:44:28: Physical free : 22064

10/10/2005 14:44:28: Virtual : 32768

10/10/2005 14:44:28: Virtual free : 28864

10/10/2005 14:44:28: Storage status, K -------------------------

10/10/2005 14:44:28: Available to us: 23190

10/10/2005 14:44:28: Total storage : 31732

10/10/2005 14:44:28: Available total: 23190

10/10/2005 14:44:28: -------------------------------------------

 Memory status after installation is done.

Changes in CAB files since Beta 2.

 We’ve made some changes since beta 2.

-         Windows Mobile 5.0 CAB file was signed with test certificate in Beta 2, now we’re using official certificate. That would allow CAB to install without security prompt on production (locked) devices. However, NETCF certificate can be disabled by network carrier or device manufacturer. That would prevent installation of NETCF V2 (or cause a security prompt).

-         In Beta 2 NETCFv2.wce5.armv4i.cab has CPU ID of 2336. It was later removed since some OEM platforms were using other IDs for compatibility reasons.

-         Platform restriction was added to NETCFv2.ppc.ARMV4.cab to allow for Active Sync deployment.

 [Author: Ilya Tumanov]

Disclaimers:
This posting is provided "AS IS" with no warranties, and confers no rights.

Comments