Deployment

ShellBoost does not mandate any deployment system and does not provide a specific one either. All what’s needed to deploy a namespace extension written with ShellBoost is:

1) copy these files:

The ShellBoost proxy native assembly (32-bit or 64-bit or both)

The ShellBoost Core .NET assembly

Your binaries

2) register the native proxy assembly as a COM object. You can do that using the ShellFolderServer.RegisterNativeDll method provided by ShellBoost, or with standard COM registration tools as explained below.

COM manual registration in HKEY_CURRENT_USER

If you decide to use a COM registration tool such as regsvr32 to register the native proxy (32 or 64-bit), instead of ShellBoost API, here are the command lines to use. Regsvr32 does not need to run with specific permissions, as this will register/unregister only for the current user.

Register 32-bit command line

%windir%\System32\regsvr32 /n /i:user ShellBoost.<id>.x86.dll

Unregister 32-bit command line

%windir%\System32\regsvr32 /u /n /i:user ShellBoost.<id>.x86.dll

Register 32-bit command line on a 64-bit machine

%windir%\SysWOW64\regsvr32 /n /i:user ShellBoost.<id>.x86.dll

Unregister 32-bit command line on a 64-bit machine

%windir%\SysWOW64\regsvr32 /u /n /i:user ShellBoost.<id>.x86.dll

Register 64-bit command line

%windir%\System\regsvr32 /n /i:user ShellBoost.<id>.x64.dll

Unregister 64-bit command line

%windir%\System32\regsvr32 /u /n /i:user ShellBoost.<id>.x64.dll

COM manual registration in HKEY_LOCAL_MACHINE

If you decide to use a COM registration tool such as regsvr32 to register the native proxy (32 or 64-bit), instead of ShellBoost API, here are the command lines to use. Regsvr32 must run with enough permissions (to write to HKEY_LOCAL_MACHINE), and this will register/unregister for all users.

Register 32-bit command line

%windir%\System32\regsvr32 ShellBoost.<id>.x86.dll

Unregister 32-bit command line

%windir%\System32\regsvr32 /u ShellBoost.<id>.x86.dll

Register 32-bit command line on a 64-bit machine

%windir%\SysWOW64\regsvr32 ShellBoost.<id>.x86.dll

Unregister 32-bit command line on a 64-bit machine

%windir%\SysWOW64\regsvr32 /u ShellBoost.<id>.x86.dll

Register 64-bit command line

%windir%\System32\regsvr32 ShellBoost.<id>.x64.dll

Unregister 64-bit command line

%windir%\System32\regsvr32 /u ShellBoost.<id>.x64.dll

Server Start

The native proxy can be configured to start the .NET server when it detects it cannot communicate with, for example, when it has stopped for some reason.

Here is an example code to register the command line to execute in this case:

ShellFolderServer.RegisterNativeDll(new ShellFolderRegistration(RegistrationMode.User) { ServerStart = new ServerStart { CommandLine = @"c:\Program Files\MyProgram\MyProgram.exe" } });

And are the keys that you can add if you want to set the RPC endpoint manually in HKCU:

HKEY_CURRENT_USER\Software\Classes\CLSID\{Shell Folder Id CLSID}
Value Name: ServerStartCommandLine (REG_SZ)
Value Name: ServerStartOperation (REG_SZ)
Value Name: ServerStartParameters (REG_SZ)
Value Name: ServerStartDirectory (REG_SZ)
Value Name: ServerStartShowCommand (REG_DWORD) // corresponds to values of type ShellBoost.Core.WindowsShell.SW
Value Name: ServerStartWait (REG_DWORD) defines an optional time to wait before retrying RPC connection

Or in HKLM:

HKEY_LOCAL_MACHINE\Software\Classes\CLSID\{Shell Folder Id CLSID}
Value Name: ServerStartCommandLine (REG_SZ)
Value Name: ServerStartOperation (REG_SZ)
Value Name: ServerStartParameters (REG_SZ)
Value Name: ServerStartDirectory (REG_SZ)
Value Name: ServerStartShowCommand (REG_DWORD) //corresponds to values of type ShellBoost.Core.WindowsShell.SW
Value Name: ServerStartWait (REG_DWORD) defines an optional time to wait before retrying RPC connection

The native proxy will use the Windows ShellExecute API to execute the command.

RPC endpoint

The ShellBoost native proxy (“client”) and the ShellBoost .NET server (“server”) communicate using the local-only RPC “ncalrpc“ protocol. This RPC channel uses an endpoint common on both sides but specific to the current user desktop.

It means communication is by default only possible between a “client” and the “server” in the same desktop.

If you want to deploy the “server” as a Windows Service (or as a program common to multiple “clients”), you must define a fixed or stable endpoint, and use that endpoint, instead of the default one. The “client” endpoint can only be set at registration time, either using ShellFolderServer registration API, or manually setting a key in the registry.

This is an example code to register the RPC endpoint as “MyFixedEndPoint”:

ShellFolderServer.RegisterNativeDll(new ShellFolderRegistration(RegistrationMode.User) { IpcFormat = "MyFixedEndPoint" })

And here is the key that you must add if you want to set the RPC endpoint manually in HKCU:

HKEY_CURRENT_USER\Software\Classes\CLSID\{Shell Folder Id CLSID}
Value Name: IpcFormat (REG_SZ)

Or in HKLM:

HKEY_LOCAL_MACHINE\Software\Classes\CLSID\{Shell Folder Id CLSID}
Value Name: IpcFormat (REG_SZ)

For example:

Note: you can use environment variables in the value if you define its type to be REG_EXPAND_SZ.

This defines the “client” endpoint. Now, to make sure the “server” answers to the same endpoint, you must configure it at startup with a .NET code like this for example:

using (var server = new OverviewShellFolderServer())
{
    var config = new ShellFolderConfiguration();
    config.IpcFormat = "MyFixedEndPoint";
    if (register)
    {
        config.NativeDllRegistration = RegistrationMode.User;
    }
    ...
    server.Start(config);
    ...
}

Multi-User Per-Machine scenarios

If you want to support multiple users per machine, there are two possibilities.

The first one is the default one, explained in the following picture:

Key points:

This scenario requires ShellBoost version 1.4.1.0 or higher.

Each user runs his own ShellBoost .NET server process, in the same Windows desktop that hosts his Explorer or other Windows apps that may open Common Dialogs.

The ShellBoost .NET server binary location can be the same for all users (it can be installed in Program Files for example), or in user’s local directories (such as %localappdata%), but each user will have to create the process somehow, for example at login time.

There’s nothing to configure for this scenario.

The second possibility is explained in the following picture:

Key points

You must start a common ShellBoost .NET server process, independently from users logging in or logging out. In general, it will probably be a Windows Service. See the Security Considerations chapter for more on this.

You must configure a common RPC endpoint. See the previous “RPC Endpoint” chapter for more on that.

Custom UI is not supported in this mode.