When trying to search for the “Custom Protocol Handler” phrase in Google, we will most probably find some articles on how to allow running a local application from a website. It’s quite interesting. Normally a website doesn’t have access to execute commands or applications on a local (client) computer. But there is an ability to call a protocol. For example, when trying to execute mailto:abc@abc.com (either from WinKey+R or as a link in Web Browser) and have Microsoft Office installed, a new Outlook window pops up with an email to abc@abc.com. This way a local application (so potentially any local command) can be launched from a website.
To run the application of our choice, for example, PowerShell, we can add our own custom protocol handler, like “test:” which in effect will launch a PowerShell process with commands of our choice. It has the ability to accept parameters derived from an URL.
Precisely speaking, by registering our own protocol we tell the operating systems which application should process the provided URL, so the entire URL is passed. But, in PowerShell, it’s fairly easy to parse the URL and retrieve parameters from it.
For an example existing on most personal computers, we can look at “mailto:”. In my case it calls Outlook.exe with some arguments, dynamically passing the entire URL to the application:
The “Custom Protocol Handler” is rather a community term than the official name of the OS feature. Some say it’s a URL Protocol or a registered URL Scheme. The last term is the most official one (if we can say so). It’s described by Internet Engineering Task Force (IETF) here: link.
The URI scheme is the thing that we can register. It is not the same as the protocol itself, it’s just a scheme to use a protocol. It’s “custom” because there are some officially registered or provisioned URL schemes (see the IETF guidelines). But, if we don’t have a need to officially register ours, we can just create a custom / private one. It will exist only on computers we have access to. In an enterprise scenario, think of using a GPO to register the URL protocol. It’s still not official and we don’t have a guarantee that another software will try to use the same. However, when implemented carefully it might be a great extension of an internal tool.
The commonly mentioned registry location for the custom protocol handler (I’ll use this name going forward) is HKEY_CLASSES_ROOT. It is a special place in the Registry for file name extension associations and COM class registration. What’s interesting, this key exists in the registry for compatibility with the old 16-bit version of the system. In fact, it’s a kind of view aggregating other keys. Information about protocol handlers is stored in HKEY_LOCAL_MACHINE\Software\Classes and respectively for CURRENT_USER. See here for more details.
Based on documentation from Microsoft, the custom protocol handler is related to COM class registration. This registry key contains information about COM classes, telling the operating system how to interact with applications using the COM standard. That includes DLL registration for components. The custom protocol handler is simpler – it doesn’t require DLL registration, it’s enough to specify that it’s an “URL Protocol”.
We can think about the custom protocol handler as a program that can be interacted with via COM. Or, in other words, a declaration of how an application can be called via COM. This ability is defined in a class of a programmatic identifier (ProgID) type. Going down, the path and file name of the application is provided in the ‘shell’ subkey.
To sum up, the thing we really do when creating the ‘custom protocol handler’ is the registration of the COM component with the “URL Protocol” flag, instructing other programs how to interact with our program using an URL. Look here for more details.
The “URL Protocol” flag is just a “URL protocol” entry in the root key of the class:
Once we have that created, we need to create the “shell\open\command” subkey. The format of the command is “path %1”. The command value is just the Windows Command Shell. “%1” is the representation of the first argument passed to the command. In the custom protocol handler it contains the entire URL. When we use it, we pass it as an argument to the application. With that knowledge we can run Powershell.exe with a default argument for running commands for example this way:
"powershell.exe" "Write-Output 'Hello %1 %w'; Read-Host"
Now we can call it either via a link, by typing it in the address bar of a web browser, using Win+R, or even within PowerShell with “Start-Process test:abc”.
As a result, we see the entire URL (reflecting %1). I added the current working directory (%w) to show that we can use other parameter variables as well.
With the above knowledge, we can do whatever is possible with PowerShell – and that’s quite a lot. In this blog post, I focused more on explaining what a custom protocol handler is. In the next part, I’ll focus on what we can achieve when combining the above knowledge with the possibilities of PowerShell.
If you have something to add to this topic, please share it in the comments!
Contact Me!
- Use PowerShell to integrate OpenAI GPT with context menu - October 25, 2023
- Let OpenAI improve and correct your PowerShell code - October 11, 2023
- Create Web Link with PowerShell in Intune - September 27, 2023
Pingback: Custom Protocol Handler and PowerShell (Part 2) - IT Constructors