en-US/about_ManagingNtObjectLifetime.help.txt

TOPIC
    about_ManagingNtObjectLifetime

SHORT DESCRIPTION
    Various Cmdlets in this library return objects which hold references to system resources. Its
    common that resources will need to be left open while operating on them otherwise the kernel will
    delete them. It's also important to ensure these resources don't leak. The library provides a few
    techniques to manage the lifetime of a resource.

LONG DESCRIPTION
    Almost all the objects returns by the various cmdlets in this library hold open a reference to a
    system resource, typically a handle to a kernel object. Managing these resources are important, both
    to ensure a resource is accessible during its required lifetime as well cleaning up afterwards.

    When you create a named resource (e.g. New-NtDirectory \Some\Path) the name only lasts as long as the
    last handle to that resource exists. If you assign it to a script variable then it should persist,
    however if you don't then eventually the garbage collector will pick it up and finalize, removing the name.
    This makes it difficult to use pipelines to create a run of new objects. For that reason the majority of
    the New-Nt* commands takes the -CreateDirectories parameter. When this is specified the cmdlet will
    automatically create new object directories as appropriate to make the final object. These directories
    are returned in a list with the new object, the new object is at the head of the list. You now have
    all the objects necessary for as long as they're required.

    If you don't need to maintain a reference to a directory object (for example it already exists) then
    instead you can use the -CloseRoot parameter. This will close the -Root object (which is passed in
    the pipeline) once the new object has been created.

    The final lifetime management technique is by using Use-NtObject. This cmdlet takes an input object
    (which can be from the pipeline) and executes a ScriptBlock with that object. Once the ScriptBlock
    completes the input object will be disposed of. It can be used for NtObjects but also for anything
    which implements IDisposable such as FileStream instances. It will also dispose enumerations of
    IDisposable objects.

EXAMPLES
    Example 1: Create a new event with a nested directory.

    $ev = New-NtEvent \BaseNamedObjects\ABC\XYZ\EventName -CreateDirectories
    try {
      # Print out created event
      $ev[0] | Format-List
    } finally {
      # Dispose objects
      $ev.Dispose()
    }
    
    Example 2: Manage lifetime in a pipeline using -CloseRoot.
    $software_key = Get-NtKey \Registry\Machine\Software | New-NtKey MyKey -CloseRoot
    # Key object to \Registry\Machine\Software is automatically closed.

    Example 3: Using Use-NtObject to automatically close a list of processes
    $pinfo = Use-NtObject($ps = Get-NtProcess) { $ps | select Name, CommandLine }
    # $ps is now disposed of.

    Example 4: Same as 3 but not polluting the variable namespace
    $pinfo = Use-NtObject (Get-NtProcess) { param($ps); $ps | select Name, CommandLine }
    # $ps no longer in scope

KEYWORDS
    ObjectManager, Lifetime