148

How do I register a custom protocol with Windows so that when clicking a link in an email or on a web page my application is opened and the parameters from the URL are passed to it?

2

6 Answers 6

144
  1. Go to Start and then in Find, type *regedit. It should open the Registry editor

  2. Right-click on HKEY_CLASSES_ROOT and then `New* → Key

    Enter image description here

  3. In the Key, enter the lowercase name by which you want URLs to be called (in my case, it will be testus://sdfsdfsdf). Then right-click on testus. Then NewString Value and add URL Protocol without value.

    Enter image description here

  4. Then add more entries like you did with protocol (Right-click NewKey) and create a hierarchy like testusshellopencommand. Inside command, change (Default) to the path where the .exe file you want to launch is. If you want to pass parameters to your EXE file, then wrap the path to the EXE file in "" and add "%1" to make it look like: "c:\testing\test.exe" "%1"

    Enter image description here

  5. To test if it works, go to Internet Explorer (not Chrome or Firefox) and enter testus:have_you_seen_this_man. This should fire your .exe (it gives you some prompts that you want to do this; say Yes) and pass testus://have_you_seen_this_man into arguments.

Here's a sample console application to test:

using System;

namespace Testing
{
    class Program
    {
        static void Main(string[] args)
        {
            if (args!= null && args.Length > 0)
            Console.WriteLine(args[0]);
            Console.ReadKey();
        }
    }
}
13
  • 3
    Wow this thing works. And not only on IE but also on Chrome! Aug 8, 2019 at 21:28
  • 1
    Any way to do this in C#? Like an installer...? Jul 19, 2021 at 19:59
  • @MatasVaitkevicius can I specify "working directory for the application to run from" in registry(within custom URL protocol entry). Ex. for triggering a Batch file if I create a custom Url registry entry, the batch file runs from system32 when launched from browser irrespective of the location of the batch file, whereas if I run the batch file by double clicking it, then the working directory remains its current directory. Jul 30, 2021 at 5:45
  • @user1066231 superuser.com/questions/396394/… ? Aug 4, 2021 at 10:17
  • 2
    @MatasVaitkevicius Thanks. yeah found the answer. posting here-may be usefull for someone else. stackoverflow.com/questions/68577785/… Aug 4, 2021 at 12:34
23

[Obsolete - the MSDN information has been replaced by a new page which does address the security concerns]

The MSDN link is nice, but the security information there isn't complete. The handler registration should contain "%1", not %1. This is a security measure, because some URL sources incorrectly decode %20 before invoking your custom protocol handler.

PS. You'll get the entire URL, not just the URL parameters. But the URL might be subject to some mistreatment, besides the already mentioned %20->space conversion. It helps to be conservative in your URL syntax design. Don't throw in random // or you'll get into the mess that file:// is.

7
  • What do you exactly mean by "mess that the file://" is?
    – Maleev
    Apr 29, 2009 at 12:15
  • 7
    There's no formal mapping of file: URLs to local paths. There's not even a consensus on the use of two or three leading slashes, or the use of forward versus backward slashes when the path refers to a Windows directory.
    – MSalters
    May 1, 2009 at 12:51
  • Late comment, I know. But is it also possible to somehow access the URL parameters only, without the protocol handler? May 12, 2010 at 11:10
  • 2
    That sounds like a separate question. Please do get your terms straight, though. The protocol handler is the program that receives the URL. "Without the protocol handler" there's nobody to parse the URL and access the URL parameters.
    – MSalters
    May 14, 2010 at 8:01
  • 1
    @WiiLF: Correct, the registry treats it as just a REG_SZ. And internally, Windows doesn't parse command lines so spaces are preserved as well. But any language runtime that parses a command line (such as C's argv[]parsing) will break on an unquoted space.
    – MSalters
    Dec 20, 2021 at 9:10
15

If anyone wants a .reg file for creating the association, see below:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\duck]
"URL Protocol"=""
[HKEY_CLASSES_ROOT\duck\shell]
[HKEY_CLASSES_ROOT\duck\shell\open]
[HKEY_CLASSES_ROOT\duck\shell\open\command] 
@="\"C:\\Users\\duck\\source\\repos\\ConsoleApp1\\ConsoleApp1\\bin\\Debug\\net6.0\\ConsoleApp1.exe\" \"%1\""

Pasted that into notepad, the file -> save as -> duck.reg, and then run it. After running it, when you type duck://arg-here into chrome, ConsoleApp1.exe will run with "arg-here" as an argument. Double slashes are required for the path to the exe and double quotes must be escaped.

Tested and working on Windows 11 with Edge (the chrome version) and Chrome

2
  • what happens if the registration already exists? does this reg override it? Apr 22 at 23:34
  • @NitinSawant Yes, if it already exists it will override it.
    – duck
    Apr 26 at 7:39
8

There is an npm module for this purpose.

link :https://www.npmjs.com/package/protocol-registry

So to do this in nodejs you just need to run the code below:

First Install it

npm i protocol-registry

Then use the code below to register you entry file.

const path = require('path');

const ProtocolRegistry = require('protocol-registry');

console.log('Registering...');
// Registers the Protocol
ProtocolRegistry.register({
    protocol: 'testproto', // sets protocol for your command , testproto://**
    command: `node ${path.join(__dirname, './index.js')} $_URL_`, // $_URL_ will the replaces by the url used to initiate it
    override: true, // Use this with caution as it will destroy all previous Registrations on this protocol
    terminal: true, // Use this to run your command inside a terminal
    script: false
}).then(async () => {
    console.log('Successfully registered');
});

Then suppose someone opens testproto://test then a new terminal will be launched executing :

node yourapp/index.js testproto://test

It also supports all other operating system.

2
  • Is there a cross-platform tool like this available as a C++ library? Jun 8, 2022 at 16:37
  • Hi there is a cli version of this available as "protocol-registry-cli" You can use it and run it through c++ Aug 2, 2022 at 18:47
0

To further the existing answers a bit more, the application invoked to handle the protocol does not have to be a compiled application. It can also be a script file.

For example, you could create a Windows batch file - such as that below to - handle the call. Let us assume you save that script to c:\temp\testprotocol-handler.bat.

REM just echo the passed argument
echo off
echo Hello from the custom protocol handling script.
echo script name: %0
echo script arg : %1
pause

Use the following registry configuration to map the script to the protocol testprotocol.

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\testprotocol]
"URL Protocol"=""
[HKEY_CLASSES_ROOT\testprotocol\shell]
[HKEY_CLASSES_ROOT\testprotocol\shell\open]
[HKEY_CLASSES_ROOT\testprotocol\shell\open\command] 
@="\"C:\\temp\\testprotocol-handler.bat\" \"%1\""

When the OS encounters the protocol it will execute the script - opening a command window and displaying the content of the echo statements in the script.

sample script executing

-1
@echo off

setlocal

set "protocol_name=sugamprotocol"
set "application_path=C:\Users\%USERNAME%\Downloads\ping_execute.exe"

set "key_path=HKCU\SOFTWARE\Classes\%protocol_name%"
set "command_path=%key_path%\shell\open\command"

REM Create the registry key for the custom protocol handler
reg add "%key_path%" /ve /d "URL:Custom Protocol" /f > nul
reg add "%key_path%" /v "URL Protocol" /d "" /f > nul

REM Create the command key to specify the application to run
reg add "%command_path%" /ve /d "\"%application_path%\" \"%%1\"" /f > nul

echo Custom protocol handler registered successfully!

endlocal
  1. To create the .bat file, open a text editor, copy the above code, and save the file with a .bat extension (e.g., register_protocol.bat). Make sure to adjust the protocol_name and application_path variables according to your requirements.

    When you run the .bat file, it will register the custom protocol handler by modifying the Windows registry. You should see the "Custom protocol handler registered successfully!" message if the registration is successful.

    Please note that modifying the Windows registry requires administrative privileges. Make sure to run the .bat file as an administrator.

2
  • 1
    Many of your answers here, including several which you've made Community Wikis for some reason, appear likely to have been entirely or partially written by AI (e.g., ChatGPT). Please be aware that posting AI-generated content is not allowed here. If you used an AI tool to assist with any answer, I would encourage you to delete it. Jul 3 at 0:27
  • 1
    Readers should review this answer carefully and critically, as AI-generated information often contains fundamental errors and misinformation. If you observe quality issues and/or have reason to believe that this answer was generated by AI, please leave feedback accordingly. The moderation team can use your help to identify quality issues. Jul 3 at 0:28

Not the answer you're looking for? Browse other questions tagged or ask your own question.