ChildProcessGuard 1.2.0

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: Configurable timeout and fallback mechanisms
• Custom Logging: Pluggable log action delegate

Requirements

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

Supported Runtimes

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.
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 all processes
int terminated = await guardian.KillAllProcessesAsync(TimeSpan.FromSeconds(10));
Console.WriteLine($"Terminated {terminated} processes");

// Selective termination
int killed = 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);

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

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 (/proc on Linux)
• Sends SIGTERM to the process and its descendants for graceful termination, then SIGKILL after the timeout
• On .NET 8+ the forced kill uses Process.Kill(entireProcessTree: true); the .NET Standard builds walk /proc, so on macOS they terminate only the child itself
• Never signals process groups: children share the parent's group, so a group signal would reach the calling application

Termination Sequence

KillAllProcesses and Dispose terminate each managed process in two stages (TerminateProcessesWhere goes straight to the forced stage):

1. Graceful request. 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.