com-server-associations.md

COM Server Associations

COM Server Associations are attributes that are applied to a SharpShell COM Server to specify what file types, classes or special objects the COM server should be associated with. A COM Server Association is specified on the COM Server class, just like the example below:

[COMServerAssociation(AssociationType.ClassOfExtension, ".dll")]
public class DllIconHandler : SharpIconHandler

In this example, the DllIconHandler COM server is associated with the class of *.dll files.

Each different association type is described below.

• Classes of Files
• Specific Classes
• File Extensions (Deprecated)
  • Predefined Shell Objects
  • All Files
  • Directories
  • Directory Background
  • Desktop Background
  • Drives
  • Unknown Files

Classes of Files

This is the most typical type of association that is made. In this case, we ask the system to register the server for a class, and rather than specifying the class, specify a file in it. For example, if we want to register for JPEG types, we could register for the class of *.jpg, which will resolve to jpgfile - meaning the server will register for *.jpg, *.jpeg and any other extensions that are classified as jpgfile.

Here are the examples:

// Associate the CustomIconHandler server with the class of jpg files.
[COMServerAssociation(AssociationType.ClassOfExtension, ".jpg")]
public class CustomIconHandler : SharpIconHandler

and:

// Associate the CustomIconHandler server with the class of jpg and png.
[COMServerAssociation(AssociationType.ClassOfExtension, ".jpg", ".png")]
public class CustomIconHandler : SharpIconHandler

If the file extension is not defined in the registry, SharpShell will create it.

Specific Classes

If you know the class you want to associate with it, you can use the 'Class' association, as in the example below.

[COMServerAssociation(AssociationType.Class, "dllfile")]
public class CustomIconHandler : SharpIconHandler

File Extensions (Deprecated)

You can associate a COM server with a specific file extension or set of file extensions only. Examples:

// Associate the CustomIconHandler server with batch files.
[COMServerAssociation(AssociationType.FileExtension, ".bat")]
public class CustomIconHandler : SharpIconHandler

and:

// Associate the CustomIconHandler server with jpeg files.
[COMServerAssociation(AssociationType.FileExtension, ".jpg". ".jpeg")]
public class CustomIconHandler : SharpIconHandler

Important Testing on Windows 7 and Windows 8 shows that the system does not normally respect such associations - they must be made on the class of an extension, rather than the extension itself.

Predefined Shell Objects

There are a number of predefined shell objects which you can register. These are documented below. If you need to use a predefined object and it is not available in SharpShell, just use the Class association type and manually specify the class. The types below are for convenience.

All Files

To associate a server with all files in the system, use the AllFiles association:

[COMServerAssociation(AssociationType.AllFiles)]
public class CustomIconHandler : SharpIconHandler

Directories

To associate a server with all folders in the system, use the Directory association:

[COMServerAssociation(AssociationType.Directory)]
public class CustomIconHandler : SharpIconHandler

Directory Background

To associate a server with the background of a folder, use the DirectoryBackground association:

[COMServerAssociation(AssociationType.DirectoryBackground)]
public class CustomIconHandler : SharpIconHandler

Desktop Background

To associate a server with the background of the desktop, use the DesktopBackground association:

[COMServerAssociation(AssociationType.DesktopBackground)]
public class CustomIconHandler : SharpIconHandler

Drives

To associate a server with all drives in the system, use the Drive association:

[COMServerAssociation(AssociationType.Drive)]
public class CustomIconHandler : SharpIconHandler

Unknown Files

To associate a server with all unknown file types, use the UnknownFiles association:

// Associate the CustomIconHandler server with the all unknown file types.
[COMServerAssociation(AssociationType.UnknownFiles)]
public class CustomIconHandler : SharpIconHandler