KeyboardHook: кроссплатформенный глобальный перехват клавиатуры и мыши для .NET

Проблема: ни один готовый пакет не подошёл

Первые несколько пакетов, которые я попробовал, работали исключительно на Windows и молчали на macOS. Другие просто вешали приложение при первом нажатии клавиши. Я искал кроссплатформенное решение, «только Windows» меня не устраивало.

Если чего-то нет, что делать? Конечно, писать самому. По началу всё было написано даже без вынесения в отдельную библиотеку, но чуть позже, когда данный код понадобился и в других моих проектах, подумал написать библиотеку с нуля. Самое главное чего я хотел добиться: без лишних зависимостей, кроссплатформенность, возможность кочевать между pet-проектами. По ходу решил сделать ее open source, чтобы неминуемо улучшать и совершенствовать данное решение.

KeyboardHook - кроссплатформенный глобальный хук клавиатуры и мыши для .NET Standard 2.0.

Что умеет библиотека

• Глобальный перехват нажатий и отпусканий клавиш — работает даже когда ваше приложение не в фокусе

• Глобальный перехват событий мыши (Left, Right, Middle)

• Программная эмуляция нажатий клавиш и кнопок мыши

• Поддержка комбинаций клавиш (Ctrl+C, Alt+F4 и любых других)

• Три платформы: Windows x86/x64, macOS Arm64, Linux x64 (X11)

• Нет внешних зависимостей — только стандартный .NET и P/Invoke к системным библиотекам

Установка одной строкой:

dotnet add package KeyboardHook

Архитектура: один интерфейс, три реализации

Ключевое решение — полное разделение публичного API и платформенного кода. Снаружи пользователь видит только два интерфейса:

public interface IKeyboardHook
{
    event Action<KeyboardKey> KeyDown;
    event Action<KeyboardKey> KeyUp;

    void SendKey(KeyboardKey key);
    void SendKeyCombo(params KeyboardKey[] keys);
}

public interface IMouseHook : IDisposable
{
    event Action<MouseButton> ButtonDown;
    event Action<MouseButton> ButtonUp;

    void SendButton(MouseButton button);
    void SendButtonCombo(params MouseButton[] buttons);
}

Получить нужную реализацию — одна строка, платформа определяется в рантайме:

IKeyboardHook keyboard = KeyboardHookFactory.Create();
IMouseHook mouse = MouseHookFactory.Create();

Фабрика внутри выглядит так:

public static class KeyboardHookFactory
{
    public static IKeyboardHook Create()
    {
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
            return new WindowsKeyboardHook();
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
            return new LinuxKeyboardHook();
        if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
            return new MacKeyboardHook();

        throw new PlatformNotSupportedException("Unsupported platform");
    }
}

Маппинг клавиш: атрибуты вместо switch-портянок

Каждая платформа использует свои коды клавиш. На Windows это Virtual Key Codes, на Linux — X11 keycodes, на macOS — Virtual Key коды CoreGraphics. Вместо трёх гигантских switch-выражений я решил хранить коды прямо в enum через кастомные атрибуты:

public enum KeyboardKey
{
    [WindowsCode(0x41)]
    [LinuxCode(38)]
    [MacosCode(0)]
    A,

    [WindowsCode(0x1B)]
    [LinuxCode(9)]
    [MacosCode(53)]
    Escape,

    [WindowsCode(0x70)]
    [LinuxCode(67)]
    [MacosCode(122)]
    F1,

    // ... 150+ клавиш
}

Атрибуты минималистичны:

[AttributeUsage(AttributeTargets.Field)]
public class WindowsCodeAttribute : Attribute
{
    public int Code { get; }
    public WindowsCodeAttribute(int code) => Code = code;
}

Конвертация в обе стороны через рефлексию:

internal static int ToPlatformCode(this KeyboardKey key)
{
    var field = typeof(KeyboardKey).GetField(key.ToString());

    if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        return field?.GetCustomAttribute<WindowsCodeAttribute>()?.Code ?? 0;
    if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        return field?.GetCustomAttribute<LinuxCodeAttribute>()?.Code ?? 0;
    if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
        return field?.GetCustomAttribute<MacosCodeAttribute>()?.Code ?? 0;

    return 0;
}

internal static KeyboardKey FromPlatformCode(int platformCode)
{
    foreach (var field in typeof(KeyboardKey).GetFields())
    {
        if (field.FieldType != typeof(KeyboardKey)) continue;

        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        {
            var attr = field.GetCustomAttribute<WindowsCodeAttribute>();
            if (attr?.Code == platformCode)
                return (KeyboardKey)field.GetValue(null);
        }
        // ... аналогично для Linux и macOS
    }
    return KeyboardKey.None;
}

Добавить новую клавишу теперь значит добавить одну запись в enum с тремя атрибутами — и больше ничего трогать не нужно.

Windows: WH_KEYBOARD_LL

На Windows реализация опирается на низкоуровневый хук WH_KEYBOARD_LL — это стандартный механизм Win32 для перехвата клавиш на уровне системы:

internal class WindowsKeyboardHook : IKeyboardHook, IDisposable
{
    private delegate IntPtr LowLevelKeyboardProc(int nCode, IntPtr wParam, IntPtr lParam);

    private const int WH_KEYBOARD_LL = 13;
    private const int WM_KEYDOWN    = 0x0100;
    private const int WM_KEYUP      = 0x0101;
    private const int WM_SYSKEYDOWN = 0x0104;
    private const int WM_SYSKEYUP   = 0x0105;

    private readonly HashSet<KeyboardKey> _pressedKeys = new HashSet<KeyboardKey>();

    public event Action<KeyboardKey> KeyDown;
    public event Action<KeyboardKey> KeyUp;

    public WindowsKeyboardHook()
    {
        _proc = HookCallback;
        _hookId = SetHook(_proc);
    }

    private IntPtr HookCallback(int nCode, IntPtr wParam, IntPtr lParam)
    {
        if (nCode >= 0)
        {
            var kb = Marshal.PtrToStructure<KBDLLHOOKSTRUCT>(lParam);
            var key = KeyboardKeyExtensions.FromPlatformCode(kb.vkCode);

            if (wParam == (IntPtr)WM_KEYDOWN || wParam == (IntPtr)WM_SYSKEYDOWN)
            {
                _pressedKeys.Add(key);
                KeyDown?.Invoke(key);
            }
            else if (wParam == (IntPtr)WM_KEYUP || wParam == (IntPtr)WM_SYSKEYUP)
            {
                _pressedKeys.Remove(key);
                KeyUp?.Invoke(key);
            }
        }
        return CallNextHookEx(_hookId, nCode, wParam, lParam);
    }

    public void SendKey(KeyboardKey key)
    {
        var code = (byte)KeyboardKeyExtensions.ToPlatformCode(key);
        keybd_event(code, 0, 0, UIntPtr.Zero);
        keybd_event(code, 0, KEYEVENTF_KEYUP, UIntPtr.Zero);
    }

    public void SendKeyCombo(params KeyboardKey[] keys)
    {
        foreach (var k in keys)
            keybd_event((byte)KeyboardKeyExtensions.ToPlatformCode(k), 0, 0, UIntPtr.Zero);

        for (int i = keys.Length - 1; i >= 0; i--)
            keybd_event((byte)KeyboardKeyExtensions.ToPlatformCode(keys[i]), 0, KEYEVENTF_KEYUP, UIntPtr.Zero);
    }

    [DllImport("user32.dll")] private static extern IntPtr SetWindowsHookEx(...);
    [DllImport("user32.dll")] private static extern IntPtr CallNextHookEx(...);
    [DllImport("user32.dll")] private static extern void keybd_event(...);
    // ...
}

Важная деталь: SYSKEYDOWN/SYSKEYUP — это отдельные сообщения для клавиш, нажатых вместе с Alt (или если окно не в фокусе). Без них пропустите половину системных сочетаний.

macOS: CGEventTap + CoreFoundation RunLoop

На macOS всё интереснее. Системный механизм — CGEventTap из фреймворка CoreGraphics. Он создаёт «точку перехвата» в потоке событий сессии и требует разрешений Accessibility (иначе CGEventTapCreate вернёт NULL):

internal class MacKeyboardHook : IKeyboardHook, IDisposable
{
    private const int kCGEventKeyDown        = 10;
    private const int kCGEventKeyUp          = 11;
    private const int kCGKeyboardEventKeycode = 9;
    private const int kCGSessionEventTap     = 1;

    private CGEventTapCallBack _callbackKeepAlive; // удерживаем делегат от GC!
    private IntPtr _eventTap;
    private IntPtr _runLoop;

    private void InitializeEventTap()
    {
        _callbackKeepAlive = EventCallback;

        var eventMask = (1UL << kCGEventKeyDown) | (1UL << kCGEventKeyUp);
        _eventTap = CGEventTapCreate(
            kCGSessionEventTap,
            place:   1,   // HeadInsert
            options: 1,   // Default
            eventsOfInterest: eventMask,
            callback: _callbackKeepAlive,
            userInfo: IntPtr.Zero
        );

        if (_eventTap == IntPtr.Zero)
            throw new UnauthorizedAccessException(
                "Accessibility permissions are required to intercept keys.");

        _runLoopSource = CFMachPortCreateRunLoopSource(IntPtr.Zero, _eventTap, 0);
        CGEventTapEnable(_eventTap, true);
        StartRunLoop();
    }

    private void StartRunLoop()
    {
        var thread = new Thread(() =>
        {
            _runLoop = CFRunLoopGetCurrent();
            IntPtr modes = GetCFRunLoopCommonModes(); // через dlopen/dlsym
            CFRunLoopAddSource(_runLoop, _runLoopSource, modes);
            CFRunLoopRun(); // блокирует поток, обрабатывая события
        })
        {
            IsBackground = true,
            Name = "MacKeyboardHook Loop"
        };
        thread.Start();
    }

    private IntPtr EventCallback(IntPtr proxy, int type, IntPtr eventRef, IntPtr userInfo)
    {
        if (type == kCGEventKeyDown || type == kCGEventKeyUp)
        {
            long macKeyCode = CGEventGetIntegerValueField(eventRef, kCGKeyboardEventKeycode);
            var key = KeyboardKeyExtensions.FromPlatformCode((int)macKeyCode);

            if (type == kCGEventKeyDown) KeyDown?.Invoke(key);
            else                         KeyUp?.Invoke(key);
        }
        return eventRef;
    }
}

Одна нетривиальная вещь: kCFRunLoopCommonModes — это не константа, а указатель на глобальную переменную во фреймворке. Получить его значение можно только через dlopen/dlsym:

private static IntPtr GetCFRunLoopCommonModes()
{
    IntPtr handle = dlopen(
        "/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation", 2);
    IntPtr symbol = dlsym(handle, "kCFRunLoopCommonModes");
    return Marshal.ReadIntPtr(symbol);
}

Без этого хук перестанет работать в некоторых режимах runloop.

Linux: опрос XQueryKeymap на 60 FPS

На Linux с X11 нет глобального хука в классическом понимании. Зато есть XQueryKeymap — функция, возвращающая битовую карту из 256 бит (32 байта), где каждый бит соответствует состоянию одной клавиши. Опрашиваем её в фоновом потоке ~60 раз в секунду и сравниваем с предыдущим состоянием:

internal class LinuxKeyboardHook : IKeyboardHook, IDisposable
{
    private byte[] _previousKeys = new byte[32];

    [DllImport("libX11.so.6")]
    private static extern bool XQueryKeymap(IntPtr display, byte[] keys);

    [DllImport("libXtst.so.6")]
    private static extern int XTestFakeKeyEvent(IntPtr display, uint keycode, bool press, uint delay);

    private void KeymapPollingLoop()
    {
        while (_running)
        {
            byte[] currentKeys = new byte[32];
            if (XQueryKeymap(_display, currentKeys))
                ProcessKeymapChanges(currentKeys);

            Thread.Sleep(16); // ~60 FPS
        }
    }

    private void ProcessKeymapChanges(byte[] currentKeys)
    {
        for (int i = 0; i < 32; i++)
        {
            byte current  = currentKeys[i];
            byte previous = _previousKeys[i];

            if (current == previous) continue;

            for (int bit = 0; bit < 8; bit++)
            {
                bool wasPressed = (previous & (1 << bit)) != 0;
                bool isPressed  = (current  & (1 << bit)) != 0;
                int keyCode = i * 8 + bit;

                if (isPressed && !wasPressed)
                    KeyDown?.Invoke(KeyboardKeyExtensions.FromPlatformCode(keyCode));
                else if (!isPressed && wasPressed)
                    KeyUp?.Invoke(KeyboardKeyExtensions.FromPlatformCode(keyCode));
            }
        }
        Array.Copy(currentKeys, _previousKeys, 32);
    }

    public void SendKey(KeyboardKey key)
    {
        XTestFakeKeyEvent(_display, (uint)KeyboardKeyExtensions.ToPlatformCode(key), true, 0);
        XTestFakeKeyEvent(_display, (uint)KeyboardKeyExtensions.ToPlatformCode(key), false, 0);
        XFlush(_display);
    }
}

Подход с опросом означает теоретическую задержку до 16 мс, зато он работает без дополнительных прав и поддерживается во всех дистрибутивах с X11.

Важно: Wayland не поддерживается — там нет эквивалента XQueryKeymap, доступного из пользовательского процесса без привилегий.

Использование: всё укладывается в несколько строк

Подписка на глобальные события:

var hook = KeyboardHookFactory.Create();

hook.KeyDown += key => Console.WriteLine($"Нажата: {key}");
hook.KeyUp   += key => Console.WriteLine($"Отпущена: {key}");

Эмуляция одиночного нажатия:

hook.SendKey(KeyboardKey.A);

Отправка комбинации (клавиши нажимаются по порядку, отпускаются в обратном):

hook.SendKeyCombo(KeyboardKey.LControl, KeyboardKey.C); // Ctrl+C
hook.SendKeyCombo(KeyboardKey.LControl, KeyboardKey.LShift, KeyboardKey.Escape); // Диспетчер задач

Мышь:

var mouse = MouseHookFactory.Create();

mouse.ButtonDown += btn => Console.WriteLine($"Кнопка мыши: {btn}");
mouse.SendButton(MouseButton.Left); // клик левой

Освобождение ресурсов:

if (hook is IDisposable d) d.Dispose();

Интеграция с Avalonia

public class MainWindowViewModel : ViewModelBase
{
    private readonly IKeyboardHook _hook;

    public MainWindowViewModel()
    {
        _hook = KeyboardHookFactory.Create();
        _hook.KeyDown += OnGlobalKeyDown;
    }

    private void OnGlobalKeyDown(KeyboardKey key)
    {
        // Выполняем в UI-потоке, если нужно обновить биндинги
        Dispatcher.UIThread.Post(() =>
        {
            LastKey = key.ToString();
        });
    }

    public string LastKey { get; private set; }
}

Хук работает даже когда окно свёрнуто.

Что дальше

Библиотека живёт на GitHub под лицензией MIT. Пакет опубликован на NuGet.

Если вам нужен лёгкий, прозрачный перехватчик ввода без тяжёлых зависимостей — попробуйте, и не стесняйтесь открывать issues и делать форки.

Буду рад комментариям — особенно от тех, кто решал похожую задачу на Wayland.