Using C# and PowerShell Scripts to Register and Use Custom Protocols

In this lesson, you will learn how to use both the C# and PowerShell versions of a script to register a custom protocol and handle specific actions based on protocol URLs. Custom protocols allow you to link external applications to your software, enabling functionalities like launching a game directly from a URL.

Lesson Overview

What is a Custom Protocol?
Using the C# Script
Using the PowerShell Script
Testing Your Custom Protocol

1. What is a Custom Protocol?

A custom protocol enables you to create a specialized URL scheme (e.g., atavism://) that links to your application. For example, clicking on a URL like atavism://launch can launch a game or execute specific functionality in your application.

2. Using the C# Script

The C# script registers a custom protocol and processes the protocol URLs. Follow these steps to use it:

Step 1: Copy the C# Code

Save the following C# code in a file named CustomProtocolHandler.cs:

using Microsoft.Win32;
using System;

public static class CustomProtocol
{
    public static void RegisterCustomProtocol()
    {
        string protocolName = "atavism";
        string applicationPath = System.Reflection.Assembly.GetExecutingAssembly().Location;

        RegistryKey key = Registry.ClassesRoot.CreateSubKey(protocolName);
        key.SetValue("", "URL:Atavism Protocol");
        key.SetValue("URL Protocol", "");

        RegistryKey defaultIcon = key.CreateSubKey("DefaultIcon");
        defaultIcon.SetValue("", $"\"{applicationPath}\",1");

        RegistryKey commandKey = key.CreateSubKey(@"shell\open\command");
        commandKey.SetValue("", $"\"{applicationPath}\" \"%1\"");

        key.Close();
    }

    public static void LaunchGame()
    {
        string gamePath = @"C:\Path\To\AtavismGame.exe"; // Replace with your game's executable path
        try
        {
            System.Diagnostics.Process.Start(gamePath);
            Console.WriteLine("Game launched successfully!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error launching game: {ex.Message}");
        }
    }
}

class Program
{
    static void Main(string[] args)
    {
        if (args.Length > 0)
        {
            string protocolUrl = args[0];
            Console.WriteLine($"Protocol URL received: {protocolUrl}");

            if (protocolUrl.StartsWith("atavismlauncher://launch"))
            {
                CustomProtocol.LaunchGame();
            }
            else
            {
                Console.WriteLine("Unknown command.");
            }
        }
        else
        {
            CustomProtocol.RegisterCustomProtocol();
            Console.WriteLine("Custom protocol registered successfully.");
        }
    }
}

Step 2: Compile and Run the Script

Compile the script using a C# compiler or Visual Studio.
Run the executable:
- Without arguments: Registers the custom protocol.
- With a protocol URL: Processes the URL, e.g., atavismlauncher://launch.

3. Using the PowerShell Script

The PowerShell script is an alternative that achieves the same result without requiring compilation.

Step 1: Copy the PowerShell Code

Save the following PowerShell script as CustomProtocolHandler.ps1:

function Register-CustomProtocol {
    $protocolName = "atavism"
    $applicationPath = (Get-Process -Id $PID).Path

    $protocolKeyPath = "HKCR:\$protocolName"
    New-Item -Path $protocolKeyPath -Force | Out-Null
    Set-ItemProperty -Path $protocolKeyPath -Name "(default)" -Value "URL:Atavism Protocol"
    Set-ItemProperty -Path $protocolKeyPath -Name "URL Protocol" -Value ""

    $defaultIconPath = "$protocolKeyPath\DefaultIcon"
    New-Item -Path $defaultIconPath -Force | Out-Null
    Set-ItemProperty -Path $defaultIconPath -Name "(default)" -Value "`"$applicationPath`",1"

    $commandKeyPath = "$protocolKeyPath\shell\open\command"
    New-Item -Path $commandKeyPath -Force | Out-Null
    Set-ItemProperty -Path $commandKeyPath -Name "(default)" -Value "`"$applicationPath`" `"%1`""

    Write-Host "Custom protocol registered successfully!"
}

function Launch-Game {
    $gamePath = "C:\Path\To\AtavismGame.exe"  # Replace with your game's executable path
    Start-Process -FilePath $gamePath
    Write-Host "Game launched successfully!"
}

param ([string]$ProtocolUrl)

if ($ProtocolUrl) {
    Write-Host "Protocol URL received: $ProtocolUrl"
    if ($ProtocolUrl -like "atavismlauncher://launch*") {
        Launch-Game
    } else {
        Write-Host "Unknown command."
    }
} else {
    Register-CustomProtocol
}

Step 2: Run the Script

Open PowerShell as Administrator.
Run the script:
- Without arguments: Registers the custom protocol:
  
  .\CustomProtocolHandler.ps1
- With a protocol URL: Processes the URL:
  
  .\CustomProtocolHandler.ps1 -ProtocolUrl "atavismlauncher://launch"

4. Testing Your Custom Protocol

Register the custom protocol using either the C# or PowerShell script.
Open a browser or run the following in PowerShell to test the protocol:

start "atavismlauncher://launch"
Verify that the game launches or the appropriate message is displayed.

Conclusion

Now you know how to use C# and PowerShell to register and handle custom protocols. Choose the method that best fits your development environment, and enjoy seamless application integration!

Atavism Tips and Tricks

Curriculum