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 |