This project is read-only.

Troubleshooting SharpShell Servers

Creating Shell Extension Servers can be extremely difficult, as diagnosing issues is very hard. The most common problem encountered is that a server seems to work with the ServerManager tool, but simply doesn't show up at all in Windows Explorer. This page pulls together a detailed guide of how to troubleshoot servers.

My Server Doesn't Show Up in Windows Explorer

Perhaps the most common issue. Here are the things to try, in order.

  1. Make sure that your server class has the [ComVisbile(true)] attribute.
  2. Make sure that your assembly is COM Visible (Project Properties > Application > Assembly Information... 'Make assembly COM-visible'.
  3. If you are on Windows 32 bit, make sure you register the server with the x86 version of regasm:
  4. If you are on Windows 64 bit, make sure you register the server with the x64 version of regasm:
  5. If you are registering a server that is NOT installed in the GAC, make sure you use the '/codebase' flag for regasm.
    regasm MyServer.dll /register /codebase
  6. Important: For most SharpShell servers to work on anything other than a development machine, they MUST be built in Release Mode against the Release Mode SharpShell binary. This binary uses an unmanaged C++ component that has a dependency to MSVCRTD100.dll in debug mode - this will NOT be present on none-development machines.

Shell Thumbnail Handlers

Shell thumbnail handlers have some specific things to be aware of:

  1. Do NOT use 'ClassOfExtension' COM server associations - you must register to a file extension.
  2. The Server Manager tool doesn't seem to respect alpha channels, but the system does.

Shell Icon Overlay Handlers

If you are not seeing your Shell Icon Overlay handlers after registering, double check which other icon handlers are registered, if you have more than a few then yours may not show up - the system only supports about ten.

On 32 bit systems, it normally takes a restart if explorer.exe for the icon to be loaded. Apparently, this can actually be done programatically via SHChangeNotify.

If you see a cross icon instead of your icon, make sure the build action for the icon is set to "Resource". If this doesn't work, try copying it to the resource folder manually. (See

Shell Property Sheet Extensions

For property sheet extensions to work, make sure that the destination machine has the Visual C++ 2012 Redistributables installed (vcredist_x86 or vcredist_x64).

It seems that under some circumstances, Tab Controls in property sheet extensions can lead to unpredictable behaviour and crashes - currently I recommend against using them until the route cause of this issue is identified. More detail on this issue and the one above can be found here:

Context Menu Extensions

It seems that sometimes creating the [ComServerAssociation] is not enough. When you add the registry key for the given extension, the context menu may be got from a different part of the registry for the users preference. For example, for 'png', uou can determine this by checking the user choice:


This will give you the progid gives you the keyname to associate with the server. In this case, it might be WindowsLive.PhotoGallery.png.16.4.

I did this manually and hey presto it works.

Preview Handlers

If you find your preview handler for Directories is not working on a client machine, trying installing and registering it both both x86 and x64. Thanks Umut Ozel!

The File Type Verifier

The File Type Verifier tool from Microsoft can also be used to get some diagnostic reports on Shell Extensions associated with file types. Details are here:

Last edited Mar 31, 2015 at 11:24 AM by dwmkerr, version 10


peterch May 28, 2015 at 3:09 PM 
The SharpShell API and codeproject examples were very well written, no mistake about that. Only the deployment is indeed much more difficult.

While testing registration with srm.exe, ServerManager.exe and REGASM for each hardware (x86 and x64) version of Windows 7 and 8, I've got very different results for 2 Thumbnail Handlers (x86 and x64) - compiled on VS2013 with the same source code !

Q. What is the difference in registration between srm.exe and ServerManager.exe ?

aramAzhari May 6, 2014 at 10:46 AM 
In the context menu extensions, what do you mean by:
"This will give you the progid gives you the keyname to associate with the server. In this case, it might be WindowsLive.PhotoGallery.png.16.4.

I did this manually and hey presto it works" ?

What did you do regarding the shell extension ?