Document PSInvocationSettings.Timeout and PowerShell.Stop(TimeSpan) hosting API additions #12852
Description
Prerequisites
- I searched for existing issues and this is not a duplicate.
- I wrote a descriptive title.
Summary
PowerShell/PowerShell#27027 adds two new public API members to the hosting API that allow C# host applications to enforce timeouts on script invocation and pipeline stop operations:
PSInvocationSettings.Timeout (System.TimeSpan, default Timeout.InfiniteTimeSpan)
When set to a finite value, PowerShell.Invoke() throws TimeoutException if the script does not complete within the deadline. The default preserves existing behavior.
PowerShell.Stop(TimeSpan timeout)
Stops the running pipeline and throws TimeoutException if the pipeline does not stop within the specified duration. Safe to call after Dispose().
Example usage:
var settings = new PSInvocationSettings
{
Timeout = TimeSpan.FromSeconds(10)
};
try
{
ps.Invoke(null, settings);
}
catch (TimeoutException)
{
// Runspace is still usable after timeout
}Additionally, all internal waits (Close(), StopPipelines(), Dispose()) are now bounded to 30 seconds to prevent indefinite hangs during cleanup.
Details
The change also adds a Stop(TimeSpan) overload to PowerShell that provides bounded stop with a TimeoutException on expiry. The original parameterless Stop() is unchanged.
When Timeout is finite, Invoke() dispatches to an MTA thread via Task.Run. Scripts that depend on STA COM apartment state should use the default InfiniteTimeSpan.
Articles
PSInvocationSettingsclass reference — addTimeoutproperty documentationPowerShellclass reference — addStop(TimeSpan)overload documentationreference/docs-conceptual/developer/hosting/— consider adding a section on timeout patterns for hosting applications