Related items

Shell Folders and Shell Items can have related items. Technically, Shell related items are exposed through Windows’ IRelatedItem interface and all derived interfaces.

ShellBoost supports that feature using special custom properties, not declared by Windows, but private to ShellBoost:

IIdentityName -> ShellBoost.Core.PropertyStore.CurrentItem

IDelegateItem -> ShellBoost.Core.PropertyStore.DelegateItem

IDisplayItem -> ShellBoost.Core.PropertyStore.DisplayItem

IIdentityName -> ShellBoost.Core.PropertyStore.IdentityName

IPreviewItem -> ShellBoost.Core.PropertyStore.PreviewItem

ITransferMediumItem -> ShellBoost.Core.PropertyStore.TransferMediumItem

IViewStateIdentityItem -> ShellBoost.Core.PropertyStore.ViewStateIdentityItem

Refer to each property documentation in the Windows SDK for the associated usage.

One common usage for these relations is to associate a virtual item (without a physical file) to a physical file, for example in on demand/lazy loading scenarios.

The following code demonstrates a virtual item, associated with a physical path. No file exists at the given physical path. The file is only created (or updated) when the Shell asks for it, through a related item (here, PreviewItem). Since the Shell asks for related item before it falls back to the item’s content, this gives an opportunity to the developer to write that file down before the final application that initiated the request accesses it.

public class VirtualAndPhysicalShellItem : ShellItem
{
    public VirtualAndPhysicalShellItem(ShellFolder parent, string name)
        : base(parent, new StringKeyShellItemId(name))
    {
        // this item is virtual, but we give it a file system path (with nothing in there)
        // so it's half virtual, half physical
        FileSystemPath = Path.Combine(Path.GetFullPath("Data"), VirtualAndPhysicalShellFolder.PhysicalStorageName, name + ".txt");
    }
 
    // Shell is asking for something
    protected override bool TryGetFileSystemValue(PropertyKey key, out object value)
    {
        if (key == PropertyStore.PreviewItem)
        {
            // make sure the directory exists
            IOUtilities.FileCreateDirectory(FileSystemPath);
 
            // write something in the file
            // we use a ShellBoost utility to avoid sharing violation errors
            IOUtilities.WrapSharingViolations(() =>
            {
                File.WriteAllText(FileSystemPath, "hello from " + DisplayName + " at " + DateTime.Now);
            });
        }
 
        return base.TryGetFileSystemValue(key, out value);
    }
}

In that type of scenario, sharing violations are common errors. ShellBoost has this WrapSharingViolations utility that helps the developer to deal with them more easily.