en-US/about_PSeudo_Administrator_Scope.help.txt
|
TOPIC
about_PSeudo_Administrator_Scope SHORT DESCRIPTION Describes the functions and aliases available inside of the Invoke-AsAdministrator environment. LONG DESCRIPTION PSeudo works by assembling a large string containing a PowerShell program and passing it to the Administrator process as an encoded command. By doing this, it exposes a number of functions and variables to the user. Some of them are incidental and "private" but accessible. Others are intended to be called by the user - PSeudo defines a number of aliases which shadow common output functions to call these functions. In an ideal world, the user shouldn't have to know about any of these functions or aliases, private public or otherwise. That said, for those of you deep in the weeds, these docs are for you. ALIASES The following aliases are defined inside of the Administrator scope: Get-Output -> Write-Output Get-Error -> Write-Error Get-Debug -> Write-Debug Get-Verbose -> Write-Verbose Get-Warning -> Write-Warning Get-Host -> Write-Host Get-Progress -> Write-Progress All of these functions are also defined inside of the scope. PUBLIC FUNCTIONS The following functions are intended to be called by the user, largely through aliases: Send-Output ------------ .Synopsis Sends the specified object through a named pipe from the Administrator process to the host process as output. .Description The Send-Output function sends the specified object through a named pipe from the Administrator process to the host process such that it is passed down the pipeline to the next command. It attempts to expose the same interface as Write-Output such that it can be aliased to shadow the real Write-Output inside script blocks and commands executed by Invoke-AsAdministrator. It implements NoEnumerate by calling the real Write-Output with this switch before sending its output through the pipe. This means that NoEnumerate's behavior depends on the version of PowerShell running in the Administrator process. Note that this behavior is also poorly tested. Send-Error ---------- .Synopsis Sends the specified object through a named pipe from the Administrator process to the host process as an error. .Description The Send-Error function declares a non-terminating error and then sends it through a named pipe from the Administrator process to the host process such that it is emitted on the error stream. It attempts to expose the same interface as Write-Error such that it can be aliased to shadow the real Write-Error inside script blocks and commands executed by Invoke-AsAdministrator. It should be noted, however, that the actual interface to Write-Error is complicated and that there might be bugs. Internally, it constructs an ErrorRecord before sending it to the pipe. This simplifies the payload structure but may cause slightly different behavior than the real Write-Error depending on how it is called. Send-Debug ---------- .Synopsis Sends a debug message through a named pipe from the Administrator process to the host process. .Description The Send-Debug function sends a message through a named pipe from the Administrator process to the host process such that it can be emitted as a debug message on the host. It attempts to expose the same interface as Write-Debug such that it can be aliased to shadow the real Write-Debug inside script blocks and commands executed by Invoke-AsAdministrator. Send-Verbose ------------ .Synopsis Sends text through a named pipe from the Administrator process to the host process such that it can be written to the verbose message stream. .Description The Send-Verbose function sends text through a named pipe from the Administrator process to the host process such that it can be emitted on the verbose message stream on the host. It attempts to expose the same interface as Write-Verbose such that it can be aliased to shadow the real Write-Verbose inside script blocks and commands executed by Invoke-AsAdministrator. Send-Warning ------------ .Synopsis Sends a warning through a named pipe from the Administrator process to the host process. .Description The Send-Warning function sends warning messages through a named pipe from the Administrator process to the host process such that they can be emitted as warnings on the host. It attempts to expose the same interface as Write-Warning such that it can be aliased to shadow the real Write-Warning inside script blocks and commands executed by Invoke-AsAdministrator. Send-Information ---------------- .Synopsis Sends information stream data through a named pipe from the Administrator process to the host process. .Description The Send-Information function sends message data and tags through a named pipe from the Administrator process to the host process such that it can be handled by the Write-Information cmdlet on the host. It attempts to expose the same interface as Write-Information such that it can be aliased to shadow the real Write-Information inside script blocks and commands executed by Invoke-AsAdministrator. Send-Host --------- .Synopsis Sends customized output through a named pipe from the Administrator process to the host process. .Description The Send-Host function sends objects and parameters through a named pipe from the Administrator process to the host process such that it can be printed to the host's screen using Write-Host. It attempts to expose the same interface as Write-Host such that it can be aliased to shadow the real Write-Host inside script blocks and commands executed by Invoke-AsAdministrator. Send-Progress ------------- .Synopsis Sends progress information through a named pipe from the Administrator process to the host process so that it can be displayed in progress bars. .Description The Send-Progress function sends progress information through a named pipe from the Administrator process to the host process such that it can be displayed in progress bars on the host. It attempts to expose the same interface as Write-Progress such that it can be aliased to shadow the real Write-Progress inside script blocks and commands executed by Invoke-AsAdministrator. PRIVATE FUNCTIONS The following functions are exposed inside of the Administrator process scope but are not intended to be called by the user: ConvertFrom-Representation -------------------------- .Description The ConvertFrom-Representation function converts a deserializable base64 object representation into an object, using .NET's serialization framework. This is used inside of the Administrator process to re-hydrate objects sent to it as command arguments from the host process. .Parameter Representation A base64 representation of an object. .Outputs Object. A fully function PowerShell object. Test-Serializable ----------------- .Description The Test-Serializable function tests an object to see if it's serializable with .NET's serialization framework. It does this by attempting to serialize the object into a MemoryStream. This means that an object may be serialized twice - once to test that it's serializable and then a second time to "do it for real" - but it seems to be the most straightforward and accurate way of ascertaining this property in PowerShell. .Parameter InputObject An object to test for serializability. .Outputs boolean. True if the object is serializable and false if not. New-SerializableObject ---------------------- .Description The New-SerializableObject function takes an arbitrary object and returns one which is guaranteed to be serialiable with .NET's serialization framework. When the object is already support serialization it's returned as-is and serialization is fully reversible; in other cases, we create a new PSObject with the same top-level properties (unless they're non-serializable, in which case they are stubbed with a string representation). This means that an object representation, though one with a significant loss of fidelity, can still be deserialized later. .Parameter InputObject An object to convert into a serializable object. .Outputs Object. This object is guaranteed to be serializable. Send-Message ------------ .Description The Send-Message function sends a message from the Administrator process to the host process over a named pipe using .NET's serialization framework. It handles non-serializable objects by converting them into PSObjects with the same keys and with serializable values where possible and string stubs otherwise. .Parameter Type The type of message. This is used by the host to decide which output function to call. Expected to be one of: Output, Error, Fatal, Debug, Verbose, Warning, Information, Host, Progress. .Outputs None. Send-ToPipe ------------ .Synopsis Sends data from the output stgream of the executed command to the host process as output. .Description The Send-ToPipe filter sends objects through a named pipe from the Administrator process to the host process such that it is interpreted as output. It handles both the output stream and a second stream, based on the -CapturedStream argument - by default this is the error stream but it can also handle streams 3-6. When intercepting the other stream it checks the type of the data and if it's the appropriate record type (ErrorStream, VerboseStream, InformationStream, etc.) it will forward it to the appropriate stream. This behavior is intended for capturing errors (and other streams of data) that are written to the error stream using $PSObject.WriteError, which can't be intercepted by aliasing Write-Error to Send-Error (or Write-Verbose/Send-Verbose and so on). When this argument is set to 1, this behavior is disabled and no second stream is captured. Send-Fatal ---------- .Synopsis Sends the specified ErrorRecord through a named pipe from the Administrator process to the host process such that it is thrown as a terminating error. .Description The Send-Fatal function declares an error and then sends it through a named pipe from the Administrator process to the host process such that it can be thrown as a terminating error. .Parameter ErrorRecord An ErrorRecord such as the value of $_ inside of a catch block. .Outputs None. PRIVATE VARIABLES The following variables are exposed inside of the Administrator process scope but are not intended to be accessed by the user: - $Formatter - An instance of BinaryFormatter, used to serialize output objects - $PipeName - The name of our named pipe - $Location - The location used on the host - $Command - The command being ran by our process, either a string or a script block - $ArgumentList - The argument list passed to the command if it's a script block - $CapturedStream - The secondary stream being captured - $OutPipe - The NamedPipeClientStream used to send output objects through the named pipe |