Implement graceful shutdown for AppiumLocalService on Windows to prevent temp file accumulation

[Copilot]

List of changes

AppiumLocalService now sends CTRL+C to Node.js processes on Windows before forceful termination, allowing cleanup handlers to execute and preventing accumulation of temporary .response files.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change that adds functionality or value)
• Breaking change (fix or feature that would cause existing functionality not to work as expected)
• Test fix (non-breaking change that improves test stability or correctness)

Documentation

• Have you proposed a file change/ PR with Appium to update documentation?

This can be done by navigating to the documentation section on http://appium.io selecting the appropriate command/endpoint and clicking the 'Edit this doc' link to update documentation

Integration tests

• Have you provided integration tests for your changes? (required for Bugfix, New feature, or Test fix)

Existing integration tests for service start/stop cover this change. The graceful shutdown path is exercised by all tests that call service.Dispose().

Details

Problem

Process.Kill() on Windows acts as SIGKILL, preventing Node.js exit handlers from running. Result: temporary .response files accumulate indefinitely (300GB+ reported).

Solution

Added TryGracefulShutdownOnWindows() that:

• Uses P/Invoke to attach to process console
• Sends CTRL+C event (SIGINT equivalent)
• Waits 5 seconds for graceful exit
• Falls back to Kill() on failure or non-Windows platforms

Implementation

private void DestroyProcess()
{
    if (Service == null) return;
    
    try
    {
        // Graceful shutdown on Windows, fallback to Kill() if unsupported/fails
        if (!TryGracefulShutdownOnWindows(Service))
        {
            Service.Kill();
        }
    }
    catch { }
    finally
    {
        Service?.Close();
        SharedHttpClient.Dispose();
    }
}

Platform behavior:

• Windows: CTRL+C → wait 5s → Kill() if needed
• Linux/macOS: Existing behavior unchanged (already handles SIGTERM correctly)

P/Invoke APIs used: AttachConsole, GenerateConsoleCtrlEvent, FreeConsole, SetConsoleCtrlHandler

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feat]: Implement graceful shutdown (SIGINT/SIGTERM) for AppiumLocalService on Windows to prevent temp file accumulation</issue_title>
<issue_description>Problem Description
The AppiumLocalService in the .NET client currently uses Process.Kill() (or Dispose()) to stop the local Appium server instance. On Windows, this behaves as a SIGKILL (force termination).

Because the process is force-killed, the Appium Node.js server does not trigger its cleanup logic. As a result, temporary .response files (used for idempotency keys) generated during the session are not deleted. Over time, these files accumulate and can consume significant disk space (reports of >300GB).

Technical Context
Source Issue: appium/dotnet-client#625

Affected Platform: Windows (macOS/Linux handle SIGTERM correctly via Dispose).

Root Cause: The Kill() method does not allow the Node.js process to run its exit or SIGINT handlers.

Failed Attempts:

Process.CloseMainWindow(): Does not work if the server is started without a visible window (background process).

GenerateConsoleCtrlEvent: Unreliable for background processes started via AppiumLocalService.

Requirements
We need to implement a mechanism in AppiumLocalService that sends a graceful termination signal (equivalent to SIGINT or SIGTERM) to the Node.js process on Windows.

Potential Solutions to Explore
Window Management: Start the process with a visible window but immediately hide it via P/Invoke, allowing CloseMainWindow to function correctly later.

IPC/Signal: Use a dedicated mechanism or P/Invoke to send CTRL_C_EVENT specifically to the child Node process group.

Process Management: Review how other .NET wrappers for Node.js services handle graceful shutdowns on Windows.

Reproduction
Start an AppiumLocalService instance on Windows.

Run a test that generates session requests (creating .response temp files).

Call service.Dispose().

Observe that the Appium process dies immediately and .response files remain in the temp folder.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feat]: Implement graceful shutdown (SIGINT/SIGTERM) for AppiumLocalService on Windows to prevent temp file accumulation #171

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

Adds a Windows-specific graceful shutdown path for AppiumLocalService so Node/Appium can run its exit handlers (preventing accumulation of temporary .response files) before falling back to a forceful terminate.

Changes:

• Introduces a TryGracefulShutdownOnWindows helper that attempts to send a CTRL+C event to the Appium/Node process.
• Updates DestroyProcess() to prefer graceful shutdown on Windows, falling back to Process.Kill() if needed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

SetConsoleCtrlHandler(null, true) is not reliably reverted: if AttachConsole fails (or GenerateConsoleCtrlEvent returns false before the re-enable call), the method returns early with Ctrl-C handling still disabled for the current process. This can leave the host test runner ignoring Ctrl+C for the rest of its lifetime. Use a try/finally (with a flag) to always restore the handler state before any return, and ensure any console attachment is cleaned up as well.

[Copilot]

AttachConsole will fail with ERROR_ACCESS_DENIED if the current process is already attached to a console (common for dotnet test / CLI runs). Currently there is no FreeConsole() call before AttachConsole, so the graceful shutdown path will often never execute and will always fall back to Kill(). Consider calling FreeConsole() before AttachConsole (ignore failure if not attached), and restore the original console state in a finally.

[Copilot]

The Win32 APIs invoked via P/Invoke (AttachConsole, GenerateConsoleCtrlEvent, FreeConsole, SetConsoleCtrlHandler) return bool and will not throw Win32Exception by themselves. The catch (Win32Exception) blocks therefore won’t run, and the cleanup logic inside them is effectively dead. Prefer putting cleanup/restoration in a finally and (if needed) use Marshal.GetLastWin32Error() for diagnostics when a call returns false.

[Copilot]

GenerateConsoleCtrlEvent is asynchronous. Detaching from the console immediately after generating the event can make delivery unreliable. Consider keeping the console attached briefly (e.g., a short sleep) before FreeConsole(), or otherwise ensure the event has time to be delivered before detaching.

[Copilot]

using System.Threading; appears unused in this file as-is (no Thread/WaitHandle usages). If you don't end up needing it, remove it to avoid unnecessary usings/warnings.

Suggested change

using System.Threading.Tasks;

[Copilot]

Replace this call with a call to managed code if possible.

[Copilot]

Minimise the use of unmanaged code.

[Copilot]

Minimise the use of unmanaged code.

[Copilot]

Minimise the use of unmanaged code.

[Copilot]

Minimise the use of unmanaged code.