en-US/about_ManagingNtObjectLifetime.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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