PSUsing

1.0.0

en-US/PSUsing.dll-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh">
  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <command:details>
      <command:name>Use-Object</command:name>
      <command:verb>Use</command:verb>
      <command:noun>Object</command:noun>
      <maml:description>
        <maml:para>A C# `using` statement like cmdlet with extended features.</maml:para>
      </maml:description>
    </command:details>
    <maml:description>
      <maml:para>`Use-Object` cmdlet offers an easy way to invoke a script block that can span different __Input processing methods__ (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods#input-processing-methods)and automatically clean-up resources when completed. Resource cleanup is enforced for the same scenarios as the ones detailed in [`clean` block](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods#clean) :</maml:para>
      <maml:para>- When the pipeline execution finishes normally without terminating error.</maml:para>
      <maml:para>- When the pipeline execution is interrupted due to terminating error.</maml:para>
      <maml:para>- When the pipeline is halted by `Select-Object -First`.</maml:para>
      <maml:para>- When the pipeline is being stopped by &lt;kbd&gt;CTRL + C&lt;/kbd&gt; or `StopProcessing()`.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Use-Object</maml:name>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none">
          <maml:name>Disposable</maml:name>
          <maml:description>
            <maml:para>An object implementing the `IDisposable` interface to be disposed after completing the invocation.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">IDisposable</command:parameterValue>
          <dev:type>
            <maml:name>IDisposable</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="sb">
          <maml:name>ScriptBlock</maml:name>
          <maml:description>
            <maml:para>Specifies the operation that is performed on each input object. This script block is run for every object in the pipeline.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue>
          <dev:type>
            <maml:name>ScriptBlock</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none">
          <maml:name>InputObject</maml:name>
          <maml:description>
            <maml:para>Specifies the input objects to be processed in the ScriptBlock.</maml:para>
            <maml:para>&gt; [!NOTE] &gt; &gt; This parameter is intended to be bound from pipeline.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
          <dev:type>
            <maml:name>Object</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ls">
          <maml:name>UseLocalScope</maml:name>
          <maml:description>
            <maml:para>By default the script block is invoked in a child scope (`&amp;`), this switch enables the cmdlet to run in the current scope (`.`).</maml:para>
            <maml:para>&gt; [!TIP] &gt; For more information see: &gt; &gt; - Dot sourcing operator `.` (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-)&gt; - Call operator `&amp;` (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-)</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ct, ts">
          <maml:name>CancellationTimeout</maml:name>
          <maml:description>
            <maml:para>Specifies a timeout in seconds for the Cancellation Token.</maml:para>
            <maml:para>&gt; [!NOTE] &gt; The default timeout is `-1`, meaning no timeout. In this case the token source is cancelled only on `StopProcessing()` (i.e.: &lt;kbd&gt;CTRL + C&lt;/kbd&gt;).</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
          <dev:type>
            <maml:name>Int32</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none">
        <maml:name>Disposable</maml:name>
        <maml:description>
          <maml:para>An object implementing the `IDisposable` interface to be disposed after completing the invocation.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">IDisposable</command:parameterValue>
        <dev:type>
          <maml:name>IDisposable</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none">
        <maml:name>InputObject</maml:name>
        <maml:description>
          <maml:para>Specifies the input objects to be processed in the ScriptBlock.</maml:para>
          <maml:para>&gt; [!NOTE] &gt; &gt; This parameter is intended to be bound from pipeline.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
        <dev:type>
          <maml:name>Object</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="sb">
        <maml:name>ScriptBlock</maml:name>
        <maml:description>
          <maml:para>Specifies the operation that is performed on each input object. This script block is run for every object in the pipeline.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue>
        <dev:type>
          <maml:name>ScriptBlock</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ls">
        <maml:name>UseLocalScope</maml:name>
        <maml:description>
          <maml:para>By default the script block is invoked in a child scope (`&amp;`), this switch enables the cmdlet to run in the current scope (`.`).</maml:para>
          <maml:para>&gt; [!TIP] &gt; For more information see: &gt; &gt; - Dot sourcing operator `.` (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-)&gt; - Call operator `&amp;` (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-)</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ct, ts">
        <maml:name>CancellationTimeout</maml:name>
        <maml:description>
          <maml:para>Specifies a timeout in seconds for the Cancellation Token.</maml:para>
          <maml:para>&gt; [!NOTE] &gt; The default timeout is `-1`, meaning no timeout. In this case the token source is cancelled only on `StopProcessing()` (i.e.: &lt;kbd&gt;CTRL + C&lt;/kbd&gt;).</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue>
        <dev:type>
          <maml:name>Int32</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes>
      <command:inputType>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
        <maml:description>
          <maml:para></maml:para>
        </maml:description>
      </command:inputType>
    </command:inputTypes>
    <command:returnValues>
      <command:returnValue>
        <dev:type>
          <maml:name>System.Object</maml:name>
        </dev:type>
        <maml:description>
          <maml:para></maml:para>
        </maml:description>
      </command:returnValue>
    </command:returnValues>
    <maml:alertSet>
      <maml:alert>
        <maml:para></maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>-------------- Example 1: Use a disposable object --------------</maml:title>
        <dev:code>use ($myobj = [DisposableObject]::new()) {
   # do stuff with:
   $myObj
}</dev:code>
        <dev:remarks>
          <maml:para></maml:para>
        </dev:remarks>
      </command:example>
      <command:example>
        <maml:title>-- Example 2: Use a disposable object while processing input --</maml:title>
        <dev:code>0..10 | use ($myobj = [DisposableObject]::new()) {
   $myObj.DoStuff($_)
}</dev:code>
        <dev:remarks>
          <maml:para></maml:para>
        </dev:remarks>
      </command:example>
      <command:example>
        <maml:title>--------- Example 3: Span different processing methods ---------</maml:title>
        <dev:code>0..10 | use ($myobj = [DisposableObject]::new()) {
   begin { 'begin' }
   process { $myObj.DoStuff($_) }
   end { 'end' }
}</dev:code>
        <dev:remarks>
          <maml:para></maml:para>
        </dev:remarks>
      </command:example>
      <command:example>
        <maml:title>-------- Example 4: Invoke using a `CancellationToken` --------</maml:title>
        <dev:code># can CTRL+C out of this
use -sb {
   param($token)
    
   [System.Threading.Tasks.Task]::Delay(-1, $token).Wait()
}
 
# can stop this
$job = Start-Job {
   use -sb {
      param($token)
 
      [System.Threading.Tasks.Task]::Delay(-1, $token).Wait()
   }
}
 
Start-Sleep 1
$job | Stop-Job</dev:code>
        <dev:remarks>
          <maml:para>A `CancellationToken` (https://learn.microsoft.com/en-us/dotnet/api/system.threading.cancellationtoken)is available for .NET methods that support it. The cancellation source is tied to the cmdlet's `StopProcessing()` method (https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.cmdlet.stopprocessing).</maml:para>
        </dev:remarks>
      </command:example>
    </command:examples>
    <command:relatedLinks />
  </command:command>
</helpItems>