en-US/about_PSeudo_Administrator_Scope.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
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:
 
    Write-Output -> Send-Output
    Write-Error -> Send-Error
    Write-Debug -> Send-Debug
    Write-Verbose -> Send-Verbose
    Write-Warning -> Send-Warning
    Write-Information -> Send-Information
    Write-Host -> Send-Host
    Write-Progress -> Send-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