ChildProcessGuard

A cross-platform .NET library that ensures child processes automatically terminate when the parent process exits unexpectedly.

Features

• Cross-Platform Support: Works on Windows, Linux, and macOS
• Automatic Cleanup: Child processes terminate when the parent exits
• 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

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.

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)
};

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();

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.