ChildProcessGuard

A cross-platform .NET library that makes child processes end with the process that started them: a kernel-level guarantee on Windows (Job Objects), process-tree signalling on Unix. What is covered on each platform differs.

Features

• Cross-Platform Support: Works on Windows, Linux, and macOS
• Automatic Cleanup: Child processes terminate when the parent exits; on Windows also when it is killed or crashes
• Windows Job Objects: Uses Job Objects for kernel-level process management on Windows
• Process Tree Termination: Terminates all descendant processes via native APIs
• Async/Await Support: Full asynchronous API with cancellation tokens
• Process Monitoring: Real-time statistics and lifecycle events
• Batch Processing: Start multiple processes with concurrency control
• Thread-Safe: Supports concurrent operations
• Graceful Shutdown: Two-stage termination with a configurable timeout and a pluggable close request
• Custom Logging: Pluggable log action delegate

Requirements

• .NET Standard 2.0+ / .NET Framework 4.6.1+ / .NET Core 2.0+ / .NET 5+

Supported Runtimes

Target Framework	Status
netstandard2.0	Supported
netstandard2.1	Supported
net10.0	Supported; trimming and Native AOT compatible (IsAotCompatible)

Installation

Package Manager

Install-Package ChildProcessGuard

.NET CLI

dotnet add package ChildProcessGuard

Quick Start

Basic Usage

using ChildProcessGuard;

// Simple usage with automatic cleanup
using var guardian = new ProcessGuardian();

var process = guardian.StartProcess("notepad.exe");
Console.WriteLine($"Started process with PID: {process.Id}");

// Process will be automatically terminated when guardian is disposed

Advanced Configuration

using ChildProcessGuard;

// Configure with builder pattern
using var guardian = ProcessGuardianBuilder.Debug()
    .WithKillTimeout(TimeSpan.FromSeconds(10))
    .WithMaxProcesses(50)
    .WithDetailedLogging(true)
    .WithAutoCleanup(true, TimeSpan.FromMinutes(1))
    .Build();

// Set up event handlers
guardian.ProcessError += (sender, e) =>
    Console.WriteLine($"Error: {e.Operation} - {e.Exception.Message}");

guardian.ProcessLifecycleEvent += (sender, e) =>
    Console.WriteLine($"Event: {e.EventType} - {e.ProcessInfo}");

var process = guardian.StartProcess("myapp.exe", "--verbose");

Usage Examples

Environment Variables and Working Directory

using var guardian = new ProcessGuardian();

var envVars = new Dictionary<string, string>
{
    { "DEBUG", "true" },
    { "CONFIG_PATH", "/etc/myapp/config.json" },
    { "LOG_LEVEL", "verbose" }
};

var process = guardian.StartProcess(
    "myapp.exe",
    "--config config.json",
    workingDirectory: "/path/to/working/dir",
    environmentVariables: envVars
);

Custom ProcessStartInfo

using var guardian = new ProcessGuardian();

var startInfo = new ProcessStartInfo
{
    FileName = "powershell.exe",
    Arguments = "-NoProfile -Command \"Get-Process\"",
    UseShellExecute = false,
    RedirectStandardOutput = true,
    CreateNoWindow = true
};

var process = guardian.StartProcessWithStartInfo(startInfo);
string output = process.StandardOutput.ReadToEnd();

Batch Processing

using var guardian = ProcessGuardianBuilder.HighPerformance().Build();

// Prepare multiple processes
var processInfos = Enumerable.Range(1, 5)
    .Select(i => new ProcessStartInfo("ping", "127.0.0.1 -n 3"))
    .ToList();

// Start all processes concurrently
var processes = await guardian.StartProcessesBatchAsync(processInfos, maxConcurrency: 3);

// Wait for all to complete
bool allCompleted = await guardian.WaitForAllProcessesAsync(TimeSpan.FromSeconds(30));
Console.WriteLine($"All processes completed: {allCompleted}");

Process Monitoring

using var guardian = new ProcessGuardian();

// Start processes
guardian.StartProcess("notepad.exe");
guardian.StartProcess("calc.exe");

// Get statistics
var stats = guardian.GetStatistics();
Console.WriteLine($"Total: {stats.TotalProcesses}, Running: {stats.RunningProcesses}");
Console.WriteLine($"Memory Usage: {stats.TotalMemoryUsage / 1024 / 1024:F1} MB");

// Get detailed process information
var runningProcesses = guardian.GetProcessesByStatus(ProcessStatus.Running);
foreach (var processInfo in runningProcesses)
{
    Console.WriteLine($"Process: {processInfo}");
    Console.WriteLine($"Runtime: {processInfo.GetRuntime():hh\\:mm\\:ss}");
}

Process Lifecycle and Ownership

using var guardian = new ProcessGuardian();

var process = guardian.StartProcess("worker.exe");

// The returned Process belongs to the caller: read its exit code, wait on it, dispose it.
// The guardian never disposes it for you. Dispose it only after it has exited: the exit
// notification that removes it from the managed list is not raised on a disposed instance,
// so an entry disposed early stays until the next periodic cleanup.
process.WaitForExit();
Console.WriteLine($"Exit code: {process.ExitCode}");
process.Dispose();

// A process leaves the managed list as soon as it exits; there is nothing to clean up.
// To stop guarding a process that is still running, remove it explicitly.
var detached = guardian.StartProcess("daemon.exe");
guardian.RemoveProcess(detached);       // by instance — works even if it was already disposed
guardian.RemoveProcess(detached.Id);    // or by process ID

Async Operations

using var guardian = new ProcessGuardian();
var cts = new CancellationTokenSource();

// Start process asynchronously
var process = await guardian.StartProcessAsync("myapp.exe", cancellationToken: cts.Token);

// Terminate one process (close request, wait, then force) — true once it has exited
bool exited = await guardian.TerminateProcessAsync(process, TimeSpan.FromSeconds(5));

// Terminate all processes
int terminated = await guardian.KillAllProcessesAsync(TimeSpan.FromSeconds(10));
Console.WriteLine($"Terminated {terminated} processes");

// Selective termination
int stopped = await guardian.TerminateProcessesWhere(
    p => p.GetRuntime() > TimeSpan.FromMinutes(5),
    TimeSpan.FromSeconds(5)
);

Custom Logging

// Route logs to your logging framework
using var guardian = new ProcessGuardianBuilder()
    .WithDetailedLogging(true)
    .WithLogAction(message => logger.LogInformation(message))
    .Build();

// Or use options directly
var options = new ProcessGuardianOptions
{
    EnableDetailedLogging = true,
    LogAction = message => Debug.WriteLine(message)
};
using var guardian = new ProcessGuardian(options);

Custom Close Request

The built-in graceful request is SIGTERM on Unix and a window close message on Windows, so a Windows console process — which has no window — is killed without being asked first. When you know how your child prefers to be asked to exit, supply that request:

using var guardian = new ProcessGuardianBuilder()
    .WithKillTimeout(TimeSpan.FromSeconds(10))
    .WithCloseRequest(info =>
    {
        // The child exits when its standard input ends (started with RedirectStandardInput = true)
        info.Process.StandardInput.Close();
        return true; // delivered: wait up to the kill timeout, then force
    })
    .Build();

Return false to fall back to the built-in request for that process. The callback should only deliver the request, not wait for the exit — the guardian does the waiting. See Termination Sequence.

Children That Outlive Their Owner

By default the children end with their owner, which is the point of the library. A launcher or updater that starts a long-lived child and then exits on purpose can opt out:

var guardian = new ProcessGuardianBuilder()
    .WithChildrenOutliveOwner()
    .Build();

var backend = guardian.StartProcess("backend", "--serve");
// ... hand over and exit: the backend keeps running

While the guardian lives it still tracks the children, and KillAllProcessesAsync and TerminateProcessAsync terminate them as usual. Dispose, the exit of the process and Ctrl+C release the children instead. On Windows the job object is created without JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE; on Unix nothing signals the children when the guardian is disposed. The guarantee that the children are cleaned up is gone for such a guardian: if the owner crashes or is killed, they keep running and the caller is responsible for them.

Stopping on SIGTERM (Unix)

SIGTERM is the signal systemd, Docker and Kubernetes send to stop a process, and .NET does not raise AppDomain.ProcessExit for it. A process stopped that way ends without the guardian's process-exit hook running, so its children keep running. In the net10.0 build a guardian can handle the signal itself:

using var guardian = new ProcessGuardianBuilder()
    .WithKillTimeout(TimeSpan.FromSeconds(10))
    .WithCleanupOnSigterm()
    .Build();

On SIGTERM the guardian is disposed exactly as it is when the process exits, and the process then ends the way it would have without the handler. This is off by default because it ends the children the moment the signal arrives: an application that keeps working after SIGTERM until it has drained, a generic host for example, should dispose the guardian from its own shutdown instead. The handler waits for the termination, which can take up to the kill timeout, so give the process a stop grace period longer than that. SIGKILL and a crash run no code in the process and still leave the children running on Unix.

Cross-Platform Example

using var guardian = new ProcessGuardian();

string executable, arguments;

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
    executable = "cmd.exe";
    arguments = "/c echo Hello from Windows";
}
else
{
    executable = "/bin/bash";
    arguments = "-c 'echo Hello from Unix'";
}

var process = guardian.StartProcess(executable, arguments);
await process.WaitForExitAsync();

Configuration Options

ProcessGuardianOptions

var options = new ProcessGuardianOptions
{
    ProcessKillTimeout = TimeSpan.FromSeconds(30),      // Graceful termination timeout
    EnableDetailedLogging = false,                      // Verbose logging
    ForceKillOnTimeout = true,                          // Force kill if timeout exceeded
    MaxManagedProcesses = 100,                          // Maximum concurrent processes
    AutoCleanupDisposedProcesses = true,                // Fallback sweep for exited processes
    CleanupInterval = TimeSpan.FromMinutes(5),          // Interval of the fallback sweep
    ThrowOnProcessOperationFailure = false,             // Exception handling behavior
    LogAction = msg => Console.WriteLine(msg),          // Custom log handler (optional)
    CloseRequest = null,                                // Custom graceful close request (optional)
    ChildrenOutliveOwner = false,                       // Leave the children running when the owner exits
    CleanupOnSigterm = false                            // Unix, net10.0 build only: end the children on SIGTERM
};

using var guardian = new ProcessGuardian(options);

Predefined Configurations

// High performance configuration
using var highPerf = ProcessGuardianBuilder.HighPerformance().Build();

// Debug configuration with detailed logging
using var debug = ProcessGuardianBuilder.Debug().Build();

// Custom configuration
using var custom = new ProcessGuardianBuilder()
    .WithKillTimeout(TimeSpan.FromSeconds(15))
    .WithMaxProcesses(200)
    .WithDetailedLogging(true)
    .WithLogAction(msg => myLogger.Log(msg))
    .Build();

Guarantees by platform

What happens to the children of the process that owns the guardian, by how that process ends:

The owner...	Windows	Linux / macOS
exits normally (Dispose, Environment.Exit, end of Main)	children end	children end (process-exit hook)
is stopped with Ctrl+C	children end	children end
receives SIGTERM, what systemd, Docker and Kubernetes send	not applicable	children keep running, unless CleanupOnSigterm is set (net10.0 build)
is killed (kill -9, the OOM killer, taskkill /f) or crashes	children end (Job Object)	children keep running

Termination by the guardian (Dispose, KillAllProcesses, TerminateProcessAsync) reaches the whole tree of a process on Windows, because the Job Object owns every descendant. On Unix it walks the tree from the process that is still running, so a descendant whose parent has already exited before the termination (a process that daemonizes itself, for example) is no longer reachable and is left running; Process.Kill(entireProcessTree: true) has the same limit. On Windows the guarantee holds for a process once it has been assigned to the Job Object (ManagedProcessInfo.IsJobAssigned); when that fails, ProcessError is raised with the operation AssignProcessToJobObject and the process is tracked without the guarantee.

How It Works

Windows Implementation

• Uses Windows Job Objects with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE flag
• Automatically terminates all child processes when the job handle is closed
• Kernel-level guarantee for process cleanup
• Per-process Job Object assignment tracking with graceful fallback

Unix Implementation (Linux/macOS)

• Tracks descendants by walking parent pids from one snapshot of the process table (/proc on Linux, libproc on macOS)
• Sends SIGTERM to the process and its descendants for graceful termination, then SIGKILL after the timeout
• Only signals a process the process table shows running as a child of the caller, and that child's descendants: a child that has already exited, or a pid that has been reaped and possibly reused, is never signalled
• Never signals process groups: children share the parent's group, so a group signal would reach the calling application

Termination Sequence

TerminateProcessAsync, TerminateProcessesWhere, KillAllProcesses and Dispose terminate each managed process in two stages; when several processes are terminated, they are terminated concurrently:

1. Graceful request. If CloseRequest is set, it is called first; when it returns true the request counts as delivered and the built-in request is not sent. Otherwise — no callback, or it returned false or threw (reported through ProcessError) — Unix: SIGTERM to the process and its descendants; Windows: a close message to the process's main window (CloseMainWindow). If no request can be delivered — a Windows console process has no window — this stage is skipped rather than waited on.
2. Wait, then force. If a request was delivered, the guardian waits up to ProcessKillTimeout (default 30 s) for the process to exit. If it is still running, or no request could be delivered, and ForceKillOnTimeout is true (default), the process tree is killed (SIGKILL on Unix, TerminateProcess on Windows). With ForceKillOnTimeout = false the process is left running after the graceful stage.

On Windows, processes assigned to the Job Object are additionally terminated by the kernel when the guardian's job handle closes, including on abnormal parent exit.

Cross-Platform Failsafes

• Hooks into AppDomain.ProcessExit and ConsoleCancelKeyPress events
• Falls back to basic process termination if advanced features fail
• Provides .NET 5+ features (e.g., WaitForExitAsync) for .NET Standard 2.0/2.1 compatibility

Best Practices

1. Always use using statements or call Dispose() explicitly
2. Dispose the Process instances you start — the guardian tracks them but does not own them
3. Configure appropriate timeouts based on process characteristics
4. Handle events for production applications to track errors
5. Use builder pattern for complex configurations
6. Use LogAction to route logs to your logging framework instead of relying on Console.WriteLine
7. Monitor statistics in long-running applications
8. Test cross-platform behavior when targeting multiple operating systems

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.