Subatomix.PowerShell.TaskHost.xml
|
<?xml version="1.0" encoding="utf-8"?> <doc> <assembly> <name>Subatomix.PowerShell.TaskHost</name> </assembly> <members> <member name="T:Subatomix.PowerShell.TaskHost.Extensions"> <summary> Extension methods. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.Extensions.Sanitize``1(``0[])"> <summary> Returns an array containing the non-<see langword="null" /> elements of the specified array. </summary> <typeparam name="T"> The type of elements in <paramref name="array" />. </typeparam> <param name="array"> The array to sanitize. </param> <returns> An array containing the non-<see langword="null" /> elements of <paramref name="array" />, if <paramref name="array" /> itself is not <see langword="null" />; otherwise, an empty array. </returns> </member> <member name="M:Subatomix.PowerShell.TaskHost.Extensions.ShouldBypass(System.Management.Automation.PSCmdlet)"> <summary> Gets whether the specified cmdlet should bypass any features of the TaskHost library/module. </summary> <param name="cmdlet"> The cmdlet to check. </param> <returns> <see langword="true" /> if the <paramref name="cmdlet" /> should bypass any features of the TaskHost library/module; <see langword="false" /> otherwise. </returns> <remarks> This method detects a bypass request when the PowerShell variable <c>$TaskHostBypass</c> has a value other than <c>$null</c> or <c>$false</c> in the context of the <paramref name="cmdlet" />. </remarks> <exception cref="T:System.ArgumentNullException"> <paramref name="cmdlet" /> is <see langword="null" />. </exception> </member> <member name="T:Subatomix.PowerShell.TaskHost.Invocation"> <summary> Utility to invoke PowerShell commands with TaskHost-related extensions and fixups. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.#ctor"> <summary> Initializes a new <see cref="T:Subatomix.PowerShell.TaskHost.Invocation" /> instance. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.UseTaskHost(System.Management.Automation.PSCmdlet,System.Boolean)"> <summary> Configures the invocation to use a <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> if possible and to redirect output to the specified cmdlet. </summary> <param name="cmdlet"> The cmdlet to which to redirect output from the invocation. </param> <param name="withElapsed"> <see langword="true" /> to report elapsed time; <see langword="false" /> otherwise. </param> <returns> The invocation instance, for method chaining. </returns> <remarks> <para> This method attempts to redirect the following streams from the invocation to the <paramref name="cmdlet" />: Output (success), Error, Warning, Information, Verbose, Debug, and Progress. </para> <para> ⚠ This method uses a PowerShell internal API. It is possible that some future version of PowerShell changes that API, breaking this method. In that case, this method takes care to fail gracefully, but some output stream redirection might not occur. </para> <para> If a PowerShell variable <c>$BypassTaskHost</c> exists in the scope of the <paramref name="cmdlet" /> and has a value other than <c>$null</c> or <c>$false</c>, this method has minimal effect: it does not override the host for the invocation and avoids using any internal PowerShell APIs. </para> If <see cref="P:Subatomix.PowerShell.TaskHost.TaskHost.Current" /> is not <see langword="null" />, this method reuses host and does not create a new see cref="TaskHost"/> instance. <para> </para> <para> <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> requires the underlying host of the <paramref name="cmdlet" /> to provide a <see cref="T:System.Management.Automation.Host.PSHostUserInterface" /> implementation. Some hosts do not, such as the host used inside <c>ForEach-Object -Parallel</c>. If this method detects such a host, this method avoids avoids wrapping it with a <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> (which would throw an exception) and instead causes the <paramref name="cmdlet" /> to write a warning message. </para> </remarks> <exception cref="T:System.ArgumentNullException"> <paramref name="cmdlet" /> is <see langword="null" />. </exception> <exception cref="T:System.InvalidOperationException"> The <see cref="M:Subatomix.PowerShell.TaskHost.Invocation.UseTaskHost(System.Management.Automation.PSCmdlet,System.Boolean)" /> or <see cref="M:Subatomix.PowerShell.TaskHost.Invocation.UseTask(System.Management.Automation.PSCmdlet,System.String)" /> has been invoked already. </exception> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.UseTask(System.Management.Automation.PSCmdlet,System.String)"> <summary> Configures the invocation to run as a task (<see cref="T:Subatomix.PowerShell.TaskHost.TaskInfo" />) and to redirect output to the specified cmdlet. </summary> <param name="cmdlet"> The cmdlet to which to redirect output from the invocation. </param> <param name="name"> The name of the task, or <see langword="null" /> to generate a default name. </param> <returns> The invocation instance, for method chaining. </returns> <remarks> <para> This method attempts to redirect the following streams from the invocation to the <paramref name="cmdlet" />: Output (success), Error, Warning, Information, Verbose, Debug, and Progress. </para> <para> ⚠ This method uses a PowerShell internal API. It is possible that some future version of PowerShell changes that API, breaking this method. In that case, this method takes care to fail gracefully, but some output stream redirection might not occur. </para> <para> If a PowerShell variable <c>$BypassTaskHost</c> exists in the scope of the <paramref name="cmdlet" /> and has a value other than <c>$null</c> or <c>$false</c>, this method has minimal effect: it does create a <see cref="T:Subatomix.PowerShell.TaskHost.TaskInfo" /> and avoids using any internal PowerShell APIs. </para> </remarks> <exception cref="T:System.ArgumentNullException"> <paramref name="cmdlet" /> is <see langword="null" />. </exception> <exception cref="T:System.InvalidOperationException"> The <see cref="M:Subatomix.PowerShell.TaskHost.Invocation.UseTaskHost(System.Management.Automation.PSCmdlet,System.Boolean)" /> or <see cref="M:Subatomix.PowerShell.TaskHost.Invocation.UseTask(System.Management.Automation.PSCmdlet,System.String)" /> has been invoked already. </exception> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.AddScript(System.Management.Automation.ScriptBlock)"> <summary> Adds a script block to be invoked. </summary> <param name="script"> The script block to invoke. </param> <returns> The invocation instance, for method chaining. </returns> <exception cref="T:System.ArgumentNullException"> <paramref name="script" /> is <see langword="null" />. </exception> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.AddReinvocation(System.Management.Automation.InvocationInfo)"> <summary> Adds a reinvocation of the specified invocation. </summary> <param name="invocation"> The invocation to be reinvoked. </param> <returns> The invocation instance, for method chaining. </returns> <exception cref="T:System.ArgumentNullException"> <paramref name="invocation" /> is <see langword="null" />. </exception> <remarks> ⚠ To prevent a stack overflow, the reinvoked command must be able to detect when it is reinvoked and avoid reinvoking itself infinitely. </remarks> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.Invoke"> <summary> Executes the invocation. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.DeferDisposal(System.IDisposable)"> <summary> Adds the specifiedc object to the deferred disposal collection. </summary> <param name="obj"> The object to be disposed. </param> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.Dispose"> <summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.</summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.Invocation.Dispose(System.Boolean)"> <summary>Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.</summary> </member> <member name="T:Subatomix.PowerShell.TaskHost.TaskHost"> <summary> A wrapper for <see cref="T:System.Management.Automation.Host.PSHost" /> to improve the clarity of output from long-running, potentially parallel tasks. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.#ctor(System.Management.Automation.Host.PSHost,System.Diagnostics.Stopwatch)"> <summary> Initializes a new <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> instance wrapping the specified host, optionally reporting elapsed time from the specified stopwatch. </summary> <param name="host"> The host to wrap. </param> <param name="stopwatch"> A stopwatch from which to report elapsed time, or <see langword="null" /> to not report elapsed time. </param> <exception cref="T:System.ArgumentNullException"> <paramref name="host" />, its <see cref="P:System.Management.Automation.Host.PSHost.UI" />, and/or its <see cref="P:System.Management.Automation.Host.PSHostUserInterface.RawUI" /> is <see langword="null" />. </exception> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.#ctor(System.Management.Automation.Host.PSHost,System.Boolean)"> <summary> Initializes a new <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> instance wrapping the specified host, optionally reporting elapsed time since construction. </summary> <param name="host"> The host to wrap. </param> <param name="withElapsed"> <see langword="true" /> to report elapsed time since construction; <see langword="false" /> otherwise. </param> <exception cref="T:System.ArgumentNullException"> <paramref name="host" />, its <see cref="P:System.Management.Automation.Host.PSHost.UI" />, and/or its <see cref="P:System.Management.Automation.Host.PSHostUserInterface.RawUI" /> is <see langword="null" />. </exception> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.Current"> <summary> Gets the global current instance, or <see langword="null" /> if there is no current instance. </summary> <remarks> Use this property to detect and reuse an existing instance and thus avoid unnecessary nesting of <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> instances. Nesting <i>works</i>, but the resulting duplication of output line headers is unlikely to be what a user wants. </remarks> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.InstanceId"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.Name"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.Version"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.UI"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.CurrentCulture"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.CurrentUICulture"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.PrivateData"> <inheritdoc /> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskHost.DebuggerEnabled"> <inheritdoc /> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.GetOrSetCurrent(Subatomix.PowerShell.TaskHost.TaskHost@)"> <summary> Gets the current instance, if any; otherwise, sets the specified instance as the current instance. </summary> <param name="host"> <para> An instance to become current if there is no current instance. </para> <para> On return, this parameter is set to the actual current instance. </para> </param> <returns> A disposable scope object. The developer should dispose this object when the a current <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" /> is no longer needed. </returns> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.EnterNestedPrompt"> <inheritdoc /> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.ExitNestedPrompt"> <inheritdoc /> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.NotifyBeginApplication"> <inheritdoc /> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.NotifyEndApplication"> <inheritdoc /> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskHost.SetShouldExit(System.Int32)"> <inheritdoc /> </member> <member name="T:Subatomix.PowerShell.TaskHost.TaskInfo"> <summary> Information about a task provided to <see cref="T:Subatomix.PowerShell.TaskHost.TaskHost" />. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskInfo.#ctor(System.String)"> <summary> Initializes a new <see cref="T:Subatomix.PowerShell.TaskHost.TaskInfo" /> instance. </summary> <param name="name"> The name of the task, or <see langword="null" /> to generate a default name. </param> <remarks> <para> The <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current" /> task becomes the <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Parent" /> of the new instance. </para> <para> The new instance has a <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.RetainCount" /> of <c>1</c> and is accessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" /> until the retain count transitions to <c>0</c>. Use <see cref="T:Subatomix.PowerShell.TaskHost.TaskScope" />, <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Retain" />, and/or <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Release" /> to manage the retain count. </para> </remarks> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current"> <summary> Gets or sets the current task, or <see langword="null" /> to indicate no current task. </summary> <remarks> This property is local to the current thread or asynchronous flow. </remarks> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.All"> <summary> Gets a read-only dictionary containing all retained tasks, keyed by <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Id" />. </summary> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.Parent"> <summary> Gets the parent task, or <see langword="null" /> if the task has no parent. </summary> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.Id"> <summary> Gets a unique identifier for the task. </summary> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.Name"> <summary> Gets or sets the name of the task. Cannot be <see langword="null" />. </summary> <exception cref="T:System.ArgumentNullException"> Attempted to set the property to <see langword="null" />. </exception> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.FullName"> <summary> Gets the fully-qualified name of the task, consisting of the task's <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Name" /> prefixed by the fully-qualified name of the task's <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Parent" />. </summary> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskInfo.RetainCount"> <summary> Gets the retain count of the task. </summary> <remarks> The initial retain count of a task is <c>1</c>. The task remains accessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" /> until the retain count transitions to <c>0</c>. Use <see cref="T:Subatomix.PowerShell.TaskHost.TaskScope" />, <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Retain" />, and/or <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Release" /> to manage the retain count. </remarks> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)"> <summary> Gets the task with the specified unique identifier, or <see langword="null" /> if no such task exists. </summary> <param name="id"> The unique identifier of the task to get. </param> <returns> The task whose <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Id" /> is <paramref name="id" />, or <see langword="null" /> if no such task exists. </returns> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskInfo.Retain"> <summary> Increments the retain count of the task. </summary> <remarks> The initial retain count of a task is <c>1</c>. The task remains accessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" /> until the retain count transitions to <c>0</c>. </remarks> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskInfo.Release"> <summary> Decrements the retain count of the task. </summary> <remarks> <para> The initial retain count of a task is <c>1</c>. The task remains accessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" /> until the retain count transitions to <c>0</c>. </para> <para> If the retain count is already <c>0</c>, this method has no effect. </para> </remarks> </member> <member name="T:Subatomix.PowerShell.TaskHost.TaskOutput"> <summary> A pair consisting of a task associated with an output object. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskOutput.#ctor(Subatomix.PowerShell.TaskHost.TaskInfo,System.Object)"> <summary> Initializes a new <see cref="T:Subatomix.PowerShell.TaskHost.TaskOutput" /> instance with the specified task and object. </summary> <param name="task"> The task associated with <paramref name="obj" />. </param> <param name="obj"> The output object. </param> <exception cref="T:System.ArgumentNullException"> <paramref name="task" /> is <see langword="null" />. </exception> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskOutput.Task"> <summary> Gets the task associated with <see cref="P:Subatomix.PowerShell.TaskHost.TaskOutput.Object" />. </summary> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskOutput.Object"> <summary> Gets the output object. </summary> </member> <member name="T:Subatomix.PowerShell.TaskHost.TaskScope"> <summary> A scope in which a particular task is the current task. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskScope.Begin(System.String)"> <summary> Begins a new task. </summary> <param name="name"> The name of the task, or <see langword="null" /> to generate a default name. </param> <returns> A scope referencing the new task. When all scopes referencing a task are disposed, the task becomes inaccessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" />. </returns> <remarks> This method sets <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current" /> to the new task. When the returned scope is disposed, <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current" /> reverts to its previous value. When all scopes referencing a task are disposed, the task becomes inaccessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" />. </remarks> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskScope.#ctor(Subatomix.PowerShell.TaskHost.TaskInfo)"> <summary> Initializes a new <see cref="T:Subatomix.PowerShell.TaskHost.TaskScope" /> instance referencing the specified task. </summary> <param name="task"> The task to reference. </param> <remarks> This constructor sets <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current" /> to the specified <paramref name="task" />. When the scope is disposed, <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current" /> reverts to its previous value. When all scopes referencing the task are disposed, the task becomes inaccessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" />. </remarks> <exception cref="T:System.ArgumentNullException"> <paramref name="task" /> is <see langword="null" />. </exception> </member> <member name="P:Subatomix.PowerShell.TaskHost.TaskScope.Task"> <summary> Gets the task referenced by the scope. </summary> </member> <member name="M:Subatomix.PowerShell.TaskHost.TaskScope.Dispose"> <summary> Disposes the scope. </summary> <remarks> <para> This method restores the previous value of <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.Current" />. When all scopes referencing a task are disposed, the task becomes inaccessible via <see cref="P:Subatomix.PowerShell.TaskHost.TaskInfo.All" /> and <see cref="M:Subatomix.PowerShell.TaskHost.TaskInfo.Get(System.Int64)" />. </para> <para> A nested scope must be disposed before its containing scope. Scopes may be disposed only once. </para> </remarks> <exception cref="T:System.InvalidOperationException"> A nested scope has not been disposed. </exception> </member> </members> </doc> |