Home

Awesome

SharpShell

Build status codecov NuGet GuardRails badge

SharpShell makes it easy to create Windows Shell Extensions using the .NET Framework.

<!-- vim-markdown-toc GFM --> <!-- vim-markdown-toc -->

If you find this project useful, please consider Sponsoring!

Installation

Install SharpShell by searching for 'SharpShell' in the NuGet package manager, or using the Package Manager Console:

PM > Install-Package SharpShell

The latest official packages are listed below:

ComponentPackage
SharpShellSharpShell NuGet Package
SharpShellToolsSharpShellTools Nuget Package
ServerRegistrationManagerServerRegistrationManager NuGet Package

User Guide

All documentation is being moved to docs.

Some of the most useful guides are:

Supported Shell Extensions

The following extensions are supported by SharpShell.

Shell Context Menus

Shell Context Menus allow the context menus used in Windows Explorer to be customised.

Shell Context Menu Screenshot

Step by Step Tutorial on the CodeProject.

Icon Handlers

Shell Icon Handlers are DLLs that are registered in the system to customise the appearance of icons.

Shell Icon Handler Screenshot

Step by Step Tutorial on the CodeProject.

Info Tip Handlers

Shell Info Tip Handlers are DLLs that are registered in the system to customise tooltips for items in the shell.

Shell Info Tip Handler Screenshot

Step by Step Tutorial on the CodeProject.

Drop Handlers

Shell Drop Handlers are DLLs that are registered in the system to extend the drag and drop functionality in the Shell.

Shell Drop Handler Screenshot

Step by Step Tutorial on the CodeProject.

Preview Handlers

Shell PreviewHandlers are dlls that can be registered in the system to allow you to create visually rich previews for items that are displayed directly in Windows Explorer.

Shell Preview Handler Screenshot

Step by Step Tutorial on the CodeProject.

Icon Overlay Handlers

Shell Icon Overlay Handlers can be really useful. They let you display an icon overlay over shell objects to provide extra information. Programs like Dropbox use these overlays to show whether files are synchronised or not.

Shell Icon Overlay Handler Screenshot

Step by Step Tutorial on the CodeProject.

Thumbnail Handlers

Shell Thumbnail Handlers (or as they're sometimes known, Shell Thumbnail Providers) are COM servers that you can write to customise the appearance of the thumbnail icons in the Windows Shell.

Shell Thumbnail Handler Screenshot

Step by Step Tutorial on the CodeProject.

Property Sheet Extensions

These are extensions that add extra pages to the property sheets shown for shell items such as files, network shares, folders and so on.

Shell Thumbnail Handler Screenshot

Documentation.

Desk Band Extensions

These are extensions which add custom functionality to the Windows Desktop or Task Bar.

Shell Desk Band Screenshot

Documentation

Developer Guide

The repository made up the following components:

ComponentDescription
docs/Project Documentation
SharpShell/The core SharpShell assemblies.
SharpShellInstallerSample/An example of an installer for a SharpShell extension.
SharpShellNativeBridge/Interface to Win32 code needed for property sheets.
Tests/Regression test scripts and data.

Most developers will only need to work with the code in the SharpShell folder.

SharpShell is currently developed in Visual Studio 2017, and can be built using the Community Edition.

In order to maximize compatibility, we do not use the latest version of each SDK. The following components are needed:

Building & Testing

As long as the correct components have be installed for Visual Studio, you should be able to just open the main ./SharpShell/SharpShell.sln solution to build, test and run any of the code or samples.

To build using Powershell (which is what is done in the CI/CD process), first allow Powershell to execute scripts and then install Chololatey:

Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Now the following scripts to run the processes:

ScriptNotes
config.ps1Ensure your machine can run builds by installing necessary components such as nunit. Should only need to be run once.
build.ps1Build all solutions. Ensures that we build both 32/64 bit versions of native components.
test.ps1Run all tests, including those in samples.
coverage.ps1Create a coverage report for the main SharpShell project (samples are not included). Reports are written to ./artifacts/coverage

These scripts will generate various artifacts which may be useful to review:

artifacts\
  \build
    \SharpShell           # The SharpShell assembly.
  \tests                  # NUnit Test Reportsd
  \coverage               # Coverage Reports

Only assemblies and binaries which need to be copied into other projects are added to the artifacts/build folder. This makes chaining more complex dependencies manageable. The solution is fairly standard, but be aware that:

  1. SharpShell contains the SharpShellNativeBridge binaries. To update them, build the SharpShellNativeBridge solution from source and embed the new binaries.
  2. The SharpShell assembly is copied to artifacts/build/SharpShell folder after a successful build.
  3. The SharpShell assembly is embedded in the ServerRegistrationManager binary. The assembly is copied from artifacts/build/SharpShell prior to the server registration manager build.

All of the above steps are automated, and will run whether a build is trigger from Visual Studio, the build.ps1 script or msbuild.

Enabling Logging

A detailed guide explaining how to configure and use logging for SharpShell is at:

./docs/logging/logging.md

You can also use the SharpShell-Easy-Log tool to quickly enable/disable logging options and view the logs realtime:

SharpShell Easy Log

The tool is available at: github.com/ElektroStudios/SharpShell-Easy-Log

CI/CD

CI/CD is currently handled by AppVeyor. AppVeyor will:

  1. Build the project
  2. Run the tests
  3. Create the core SharpShell NuGet Package
  4. Publish the package to nuget.org if a version tag is pushed
  5. Create a GitHub release with the package if a version tag is pushed

Creating a Release

To create a release:

  1. Update the version number in SharedAssemblyInfo.cs
  2. Update the CHANGELOG.md
  3. Create a new version tag, then push

AppVeyor will build and publish a new NuGet package and as long as a new semver tag is pushed.

Compatibility

The goal is to maximize compatibility for platforms which are supported. For platforms which are no longer in support SharpShell may work, but is not tested.

Note: At the moment compatibility across platforms is being verified, this section of the documentation will be updated soon.

šŸŸ¢ - Fully Supported; tested and verified as part of the build process šŸŸ  - Partly Supported; potentially will work, but no longer formally supported or tested šŸ”“ - Not Supported; confirmed that this will not work, unless the code is modified

ComponentCompatibility
Windows
Windows 11šŸŸ¢ Fully Supported
Windows 10šŸŸ¢ Fully Supported
Windows 8.1šŸŸ  Partly Supported
Windows 8šŸŸ  Partly Supported
Windows 7šŸŸ  Partly Supported
Visual Studio
Visual Studio 2022šŸŸ¢ Fully Supported
Visual Studio 2019šŸŸ¢ Fully Supported
Visual Studio 2017šŸŸ  Partly Supported
Visual Studio 2015šŸŸ  Partly Supported
msbuild
msbuild 17.3šŸŸ¢ Fully Supported
msbuild 16.11šŸŸ¢ Fully Supported
msbuild 15.9šŸŸ  Partly Supported

Documentation

Documentation is still work in progress, and any contributions would be most welcome!

Contributor Guide

The project is maintained by the following group:

UserRole
dwmkerrProject creator, maintainer.
CountryenProject maintainer.

We have a Code of Conduct aimed at keeping the community welcoming and inclusive.

Testimonials

If you've used SharpShell and would like to add a testimonial, just send me a message!

CmisSync, our Dropbox-like client for Enterprise Content Management servers, just switched to SharpShell, and we are extremely pleased with this library. Our previous custom-built Windows Explorer integration was buggy, unreliable and hard to maintain, and SharpShell is really rock-solid in comparison. The best part: It only took 2 days to integrate SharpShell into our software, testing and installer included. Thanks SharpShell!

Nicolas Raoul - CmisSync.com

Projects that use SharpShell

Send me a message to add a project to this list:

Thanks

Many thanks to JetBrains for providing an Open Source License for their products!

JetBrains

License

SharpShell is licensed under the MIT License - the details are at LICENSE.md