Troubleshooting

Following are helpful resources for troubleshooting issues with CBFS Shell.

Issue 1: The CBFS Shell Namespace Extension is not visible

If the Namespace Extension is not visible, this is usually a registration issue. Registration occurs during installation of the native proxy DLL and serves two purposes: (1) to register the CBFS Shell native proxy as a COM object, and (2) to register the CBFS Shell native proxy as a Shell Namespace Extension.
Check the CBShellBoost.Attributes property. For example, setting the SFGAO_HIDDEN attribute will, as the name suggests, hide your extension. You only change these for valid reasons and do so only if you know exactly what you are doing. The default attributes are as follows: SFGAO_STORAGE, SFGAO_DROPTARGET, SFGAO_STREAM, SFGAO_STORAGEANCESTOR, SFGAO_FOLDER, and SFGAO_HASSUBFOLDER.
The Shell/Explorer keeps many things (e.g., icons, names) in a private cache, so sometimes, you'll have to reset it. You can kill all of the explorer.exe processes (make sure they are all gone using a tool such as the Task Manager, Details tab) or use the hidden "Exit Explorer" menu trick described here https://www.howtogeek.com/198815/use-this-secret-trick-to-close-and-restart-explorer.exe-in-windows/ . Note: This trick can keep some rogue explorer.exe instances running, so always check explorer.exe running using the Windows Task Manager. Sometimes, you will have to restart your session or even reboot, but that should be the exception.
End users (or a testing developer) may use the Explorer UI to delete a Shell Namespace Extension, for example, using the DELETE key. In this case, the extension will no longer appear. To check this, you can verify that there is no key at HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\CLSID\<Your Folder Class Id> or HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\CLSID\<Your Folder Class Id>. Your Folder Class Id is available through the callback.ShellBoost.Core.ShellFolderServer.FolderId static property (valid only after the ShellFolderServer is started).
Make sure your Namespace Extension is not Disallowed. To check this, you verify that there is no <Your Folder Class Id> value in the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed registry key.
If you installed the shell folder object for all users, you need to check these two registry keys:
- HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed
- (if you have an x64 system) HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed
Make sure your Namespace Extension is not Blocked. To check this, verify that there is no <Your Folder Class Id> value in the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked registry key. If you have an x64 system, you need to check HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked registry key as well.
Shell extension handlers, such as the CBFS Shell native proxy, run in the Shell process. Because this is a system process, the administrator of a system can limit Shell extension handlers to those on an approved list by setting the EnforceShellExtensionSecurity value of the Explorer key to 1. If this is the case, ensure that your Namespace Extension is Approved. To check this, verify that there is a <Your Folder Class Id> value in the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved registry key. See the official Microsoft documentation at Registering Shell Extension Handlers for more information.

Issue 2: The CBFS Shell Namespace Extension is visible but does not respond to Shell requests

This problem could be a UAC (User Account Control) issue. If your .NET server runs at a different UAC level than the Explorer or a third-party application hosting Common Controls, then communication may not work. For example, if you run your .NET server as administrator and Explorer is run as normal (not as administrator), then you may experience this problem.

This also could be a disabled UAC (User Account Control) issue. See the Microsoft articles here: Merged View of HKEY_CLASSES_ROOT and Application Compatibility: UAC: COM Per-User Configuration. "If an application is run with administrator rights and User Account Control is disabled, the COM runtime ignores per-user COM configuration and accesses only per-machine COM configuration. Applications that require administrator rights should register dependent COM objects during installation to the per-machine COM configuration store". This typically is the case when running on default Windows server or in some Windows sandbox configurations.

To address the problem, try installing the proxy DLL for the machine, not for the user. For this, set the PerUserInstallation property to false.

Another reason of this issue is the incomplete deployment of the proxy DLLs to the target system. To x64 systems, be sure to deploy both {id}.x64.dll and {id}.x86.dll as x64 Windows have both 64-bit and 32-bit shells. To ARM systems, deploy all of {id}.x64.dll, {id}.x86.dll, and {id}.arm64.dll.

Issue 3: The CBFS Shell Namespace Extension is not visible in Common Dialogs

Unfortunately, there are not always solutions to this problem. Ultimately, applications host the Common Dialog and the loading process is the application's process, not explorer.exe. Therefore, they can customize it the way they want and thus may prevent any Namespace Extension from running.
Another common example of this issue occurs when an application restricts the Common Dialog views to just filesystem Shell items. Applications may do this with the IFileDialog::SetOptions method: https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-ifiledialog-setoptions using the FOS_FORCEFILESYSTEM flag. In this case, your extension will be shown only if it is declared as a filesystem extension using its project characteristics. All folders under the root also have to be filesystem-compatible. If you own the application using the Common Dialog, you can adapt your code to ensure that a custom Namespace Extension is shown.
Even if your extension is fully filesystem-compliant (i.e., exposes what CBFS Shell calls "physical items"), some applications may still fail for various reasons, depending on the way they are implemented.
You will have to test your extension with applications that you explicitly plan to target (e.g., Office applications, Notepad, Adobe Reader) because they can behave differently. Some applications hook (as in "Windows hook") Common Dialogs to deeply change their behavior or even implement custom dialog boxes with custom shell-like controls in them. In such cases, the custom dialog boxes most likely will not support Namespace Extensions.
In general, Drag & Drop and Copy/Paste operations are better alternatives to the Common Dialogs "Save As" operation because they use a standard clipboard protocol. Drag & Drop from an Outlook message or an attachment from a message are examples of this behavior. See the Physical Overview sample for a code example that demonstrates this functionality.

Some applications are compiled as 32-bit binaries and therefore use Common Dialogs in 32-bit as well. If the native proxy DLL for 32-bit architecture is not included in your application, the Common Dialog will not be able to reach your Shell folder server application (even if it is compiled as "Any CPU") and will not display its items. See the "32- and 64-bit support" chapter for more information.

Issue 4: Preview images (from preview handlers) are not displayed for items in a CBFS Shell Namespace Extension

Preview images are supported through the Shell's native IPreviewHandler COM interface. Some preview handlers are provided by Windows (e.g., image, simple text), whereas others are provided by third-party binaries (e.g., PDF files). Handlers also should implement one of the three native COM interfaces: IInitializeWithStream (strongly preferred and recommended by Microsoft), IInitializeWithFile, or IInitializeWithItem.
Unfortunately, some handlers are not capable of loading Shell items that are not physical files because they simply do not implement IInitializeWithStream (which uses a stream that can come from anywhere) but IInitializeWithFile (which uses a physical file), which is the legacy interface.
For these legacy handlers, you have to provide physical Shell items for the handler to work.
To check if your Namespace Extension works properly with a preview handler, you can install and test the official Microsoft "Recipe Preview Handler Sample" https://docs.microsoft.com/en-us/windows/win32/shell/samples-recipepreviewhandler. Just add a .recipe file (or a virtual file) corresponding to the expected format into a folder within your Namespace Extension. Then test that this item has the correct preview image.

Issue 5: What is displayed in the Namespace Extension is not expected, the icons are incorrect, or Drag & Drop does not work properly (shows stop icon)

If you are in the process of developing your application, and you stop to restart your .NET server repeatedly while keeping Explorer views open with your Shell folder, things may get out of hand. Some discrepancy may occur between what your .NET server gives back (notably PIDLs) and what these Explorer views expect, or what they remember or keep in memory/cache. To avoid this situation, close the Explorer views that are connected to your server and then reopen them. The F5 (Refresh) key pressed in Explorer views also should reset memory, but this may not always happen.

Issue 6: You see too many calls to your .NET implementation

Most of the calls you can see from CBFS Shell are initiated by the Shell and are proxied back to your code. The number and the order of calls are not defined; they may change depending on Windows version, machine setup, and other reasons beyond our control.

Any third party (e.g., other Shell extensions, context menu extensions) may call into your extension indirectly by using the Shell API.

In general, do not assume that you can match end-user operations with what occurs on the process level. For example, the context menu is asked and used to determine the result of a double-click on a Shell item, even though no context menu is shown to an end user upon the double-click.

Depending on your context, caching techniques often are used between the Shell call and your final code being executed.

If you think there are too many calls to the ShellFolder's EnumItems method, make sure that you have overridden the two GetItems methods, as explained in the Items enumeration chapter.

CBFS Shell 2022 .NET Edition Website Download Support Questions / Feedback?
	Troubleshooting Following are helpful resources for troubleshooting issues with CBFS Shell. Issue 1: The CBFS Shell Namespace Extension is not visible If the Namespace Extension is not visible, this is usually a registration issue. Registration occurs during installation of the native proxy DLL and serves two purposes: (1) to register the CBFS Shell native proxy as a COM object, and (2) to register the CBFS Shell native proxy as a Shell Namespace Extension. Check the CBShellBoost.Attributes property. For example, setting the SFGAO_HIDDEN attribute will, as the name suggests, hide your extension. You only change these for valid reasons and do so only if you know exactly what you are doing. The default attributes are as follows: SFGAO_STORAGE, SFGAO_DROPTARGET, SFGAO_STREAM, SFGAO_STORAGEANCESTOR, SFGAO_FOLDER, and SFGAO_HASSUBFOLDER. The Shell/Explorer keeps many things (e.g., icons, names) in a private cache, so sometimes, you'll have to reset it. You can kill all of the explorer.exe processes (make sure they are all gone using a tool such as the Task Manager, Details tab) or use the hidden "Exit Explorer" menu trick described here https://www.howtogeek.com/198815/use-this-secret-trick-to-close-and-restart-explorer.exe-in-windows/ . Note: This trick can keep some rogue explorer.exe instances running, so always check explorer.exe running using the Windows Task Manager. Sometimes, you will have to restart your session or even reboot, but that should be the exception. End users (or a testing developer) may use the Explorer UI to delete a Shell Namespace Extension, for example, using the DELETE key. In this case, the extension will no longer appear. To check this, you can verify that there is no key at HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\CLSID\<Your Folder Class Id> or HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\CLSID\<Your Folder Class Id>. Your Folder Class Id is available through the callback.ShellBoost.Core.ShellFolderServer.FolderId static property (valid only after the ShellFolderServer is started). Make sure your Namespace Extension is not Disallowed. To check this, you verify that there is no <Your Folder Class Id> value in the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed registry key. If you installed the shell folder object for all users, you need to check these two registry keys: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed (if you have an x64 system) HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed Make sure your Namespace Extension is not Blocked. To check this, verify that there is no <Your Folder Class Id> value in the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked registry key. If you have an x64 system, you need to check HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked registry key as well. Shell extension handlers, such as the CBFS Shell native proxy, run in the Shell process. Because this is a system process, the administrator of a system can limit Shell extension handlers to those on an approved list by setting the EnforceShellExtensionSecurity value of the Explorer key to 1. If this is the case, ensure that your Namespace Extension is Approved. To check this, verify that there is a <Your Folder Class Id> value in the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved registry key. See the official Microsoft documentation at Registering Shell Extension Handlers for more information. Issue 2: The CBFS Shell Namespace Extension is visible but does not respond to Shell requests This problem could be a UAC (User Account Control) issue. If your .NET server runs at a different UAC level than the Explorer or a third-party application hosting Common Controls, then communication may not work. For example, if you run your .NET server as administrator and Explorer is run as normal (not as administrator), then you may experience this problem. This also could be a disabled UAC (User Account Control) issue. See the Microsoft articles here: Merged View of HKEY_CLASSES_ROOT and Application Compatibility: UAC: COM Per-User Configuration. "If an application is run with administrator rights and User Account Control is disabled, the COM runtime ignores per-user COM configuration and accesses only per-machine COM configuration. Applications that require administrator rights should register dependent COM objects during installation to the per-machine COM configuration store". This typically is the case when running on default Windows server or in some Windows sandbox configurations. To address the problem, try installing the proxy DLL for the machine, not for the user. For this, set the PerUserInstallation property to `false`. Another reason of this issue is the incomplete deployment of the proxy DLLs to the target system. To x64 systems, be sure to deploy both {id}.x64.dll and {id}.x86.dll as x64 Windows have both 64-bit and 32-bit shells. To ARM systems, deploy all of {id}.x64.dll, {id}.x86.dll, and {id}.arm64.dll. Issue 3: The CBFS Shell Namespace Extension is not visible in Common Dialogs Unfortunately, there are not always solutions to this problem. Ultimately, applications host the Common Dialog and the loading process is the application's process, not explorer.exe. Therefore, they can customize it the way they want and thus may prevent any Namespace Extension from running. Another common example of this issue occurs when an application restricts the Common Dialog views to just filesystem Shell items. Applications may do this with the IFileDialog::SetOptions method: https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-ifiledialog-setoptions using the FOS_FORCEFILESYSTEM flag. In this case, your extension will be shown only if it is declared as a filesystem extension using its project characteristics. All folders under the root also have to be filesystem-compatible. If you own the application using the Common Dialog, you can adapt your code to ensure that a custom Namespace Extension is shown. Even if your extension is fully filesystem-compliant (i.e., exposes what CBFS Shell calls "physical items"), some applications may still fail for various reasons, depending on the way they are implemented. You will have to test your extension with applications that you explicitly plan to target (e.g., Office applications, Notepad, Adobe Reader) because they can behave differently. Some applications hook (as in "Windows hook") Common Dialogs to deeply change their behavior or even implement custom dialog boxes with custom shell-like controls in them. In such cases, the custom dialog boxes most likely will not support Namespace Extensions. In general, Drag & Drop and Copy/Paste operations are better alternatives to the Common Dialogs "Save As" operation because they use a standard clipboard protocol. Drag & Drop from an Outlook message or an attachment from a message are examples of this behavior. See the Physical Overview sample for a code example that demonstrates this functionality. Some applications are compiled as 32-bit binaries and therefore use Common Dialogs in 32-bit as well. If the native proxy DLL for 32-bit architecture is not included in your application, the Common Dialog will not be able to reach your Shell folder server application (even if it is compiled as "Any CPU") and will not display its items. See the "32- and 64-bit support" chapter for more information. Issue 4: Preview images (from preview handlers) are not displayed for items in a CBFS Shell Namespace Extension Preview images are supported through the Shell's native IPreviewHandler COM interface. Some preview handlers are provided by Windows (e.g., image, simple text), whereas others are provided by third-party binaries (e.g., PDF files). Handlers also should implement one of the three native COM interfaces: IInitializeWithStream (strongly preferred and recommended by Microsoft), IInitializeWithFile, or IInitializeWithItem. Unfortunately, some handlers are not capable of loading Shell items that are not physical files because they simply do not implement IInitializeWithStream (which uses a stream that can come from anywhere) but IInitializeWithFile (which uses a physical file), which is the legacy interface. For these legacy handlers, you have to provide physical Shell items for the handler to work. To check if your Namespace Extension works properly with a preview handler, you can install and test the official Microsoft "Recipe Preview Handler Sample" https://docs.microsoft.com/en-us/windows/win32/shell/samples-recipepreviewhandler. Just add a .recipe file (or a virtual file) corresponding to the expected format into a folder within your Namespace Extension. Then test that this item has the correct preview image. Issue 5: What is displayed in the Namespace Extension is not expected, the icons are incorrect, or Drag & Drop does not work properly (shows stop icon) If you are in the process of developing your application, and you stop to restart your .NET server repeatedly while keeping Explorer views open with your Shell folder, things may get out of hand. Some discrepancy may occur between what your .NET server gives back (notably PIDLs) and what these Explorer views expect, or what they remember or keep in memory/cache. To avoid this situation, close the Explorer views that are connected to your server and then reopen them. The F5 (Refresh) key pressed in Explorer views also should reset memory, but this may not always happen. Issue 6: You see too many calls to your .NET implementation Most of the calls you can see from CBFS Shell are initiated by the Shell and are proxied back to your code. The number and the order of calls are not defined; they may change depending on Windows version, machine setup, and other reasons beyond our control. Any third party (e.g., other Shell extensions, context menu extensions) may call into your extension indirectly by using the Shell API. In general, do not assume that you can match end-user operations with what occurs on the process level. For example, the context menu is asked and used to determine the result of a double-click on a Shell item, even though no context menu is shown to an end user upon the double-click. Depending on your context, caching techniques often are used between the Shell call and your final code being executed. If you think there are too many calls to the ShellFolder's EnumItems method, make sure that you have overridden the two GetItems methods, as explained in the Items enumeration chapter.
Copyright (c) 2022 Callback Technologies, Inc. - All rights reserved. CBFS Shell 2022 .NET Edition - Version 22.0 [Build 8367]

CBFS Shell 2022 .NET Edition

Troubleshooting