1014 lines
48 KiB
ReStructuredText
1014 lines
48 KiB
ReStructuredText
.. _ansible.windows.win_powershell_module:
|
|
|
|
|
|
******************************
|
|
ansible.windows.win_powershell
|
|
******************************
|
|
|
|
**Run PowerShell scripts**
|
|
|
|
|
|
Version added: 1.5.0
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
|
|
Synopsis
|
|
--------
|
|
- Runs a PowerShell script and outputs the data in a structured format.
|
|
- Use :ref:`ansible.windows.win_command <ansible.windows.win_command_module>` or :ref:`ansible.windows.win_shell <ansible.windows.win_shell_module>` to run a tranditional PowerShell process with stdout, stderr, and rc results.
|
|
|
|
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="1">Parameter</th>
|
|
<th>Choices/<font color="blue">Defaults</font></th>
|
|
<th width="100%">Comments</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>arguments</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>A list of arguments to pass to <em>executable</em> when running a script in another PowerShell process.</div>
|
|
<div>These are not arguments to pass to <em>script</em>, use <em>parameters</em> for that purpose.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>chdir</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>The PowerShell location to set when starting the script.</div>
|
|
<div>This can be a location in any of the PowerShell providers.</div>
|
|
<div>The default location is dependent on many factors, if relative paths are used then set this option.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>creates</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>depth</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">integer</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<b>Default:</b><br/><div style="color: blue">2</div>
|
|
</td>
|
|
<td>
|
|
<div>How deep the return values are serialized for <code>result</code>, <code>output</code>, and <code>information[x].message_data</code>.</div>
|
|
<div>Setting this to a higher value can dramatically increase the amount of data that needs to be returned.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>error_action</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
<ul style="margin: 0; padding: 0"><b>Choices:</b>
|
|
<li>silently_continue</li>
|
|
<li><div style="color: blue"><b>continue</b> ←</div></li>
|
|
<li>stop</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<div>The <code>$ErrorActionPreference</code> to set before executing <em>script</em>.</div>
|
|
<div><code>silently_continue</code> will ignore any errors and exceptions raised.</div>
|
|
<div><code>continue</code> is the default behaviour in PowerShell, errors are present in the <em>error</em> return value but only terminating exceptions will stop the script from continuing and set it as failed.</div>
|
|
<div><code>stop</code> will treat errors like exceptions, will stop the script and set it as failed.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>executable</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>A custom PowerShell executable to run the script in.</div>
|
|
<div>When not defined the script will run in the current module PowerShell interpreter.</div>
|
|
<div>Both the remote PowerShell and the one specified by <em>executable</em> must be running on PowerShell v5.1 or newer.</div>
|
|
<div>Setting this value may change the values returned in the <code>output</code> return value depending on the underlying .NET type.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>parameters</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>Parameters to pass into the script as key value pairs.</div>
|
|
<div>The key corresponds to the parameter name and the value is the value for that parameter.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>removes</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>A path or path filter pattern; when the referenced path <b>does not</b> exist on the target host, the task will be skipped.</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="parameter-"></div>
|
|
<b>script</b>
|
|
<a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
/ <span style="color: red">required</span>
|
|
</div>
|
|
</td>
|
|
<td>
|
|
</td>
|
|
<td>
|
|
<div>The PowerShell script to run.</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/>
|
|
|
|
|
|
Notes
|
|
-----
|
|
|
|
.. note::
|
|
- The module is set as failed when a terminating exception is throw, or ``error_action=stop`` and a normal error record is raised.
|
|
- The output values are processed using a custom filter and while it mostly matches the ``ConvertTo-Json`` result the following value types are different.
|
|
- ``DateTime`` will be an ISO 8601 string in UTC, ``DateTimeOffset`` will have the offset as specified by the value.
|
|
- ``Enum`` will contain a dictionary with ``Type``, ``String``, ``Value`` being the type name, string representation and raw integer value respectively.
|
|
- ``Type`` will contain a dictionary with ``Name``, ``FullName``, ``AssemblyQualifiedName``, ``BaseType`` being the type name, the type name including the namespace, the full assembly name the type was defined in and the base type it derives from.
|
|
- The script has access to the ``$Ansible`` variable where it can set ``Result``, ``Changed``, ``Failed``, or access ``Tmpdir``.
|
|
- ``$Ansible.Result`` is a value that is returned back to the controller as is.
|
|
- ``$Ansible.Changed`` can be set to ``true`` or ``false`` to reflect whether the module made a change or not. By default this is set to ``true``.
|
|
- ``$Ansible.Failed`` can be set to ``true`` if the script wants to return the failure back to the controller.
|
|
- ``$Ansible.Tmpdir`` is the path to a temporary directory to use as a scratch location that is cleaned up after the module has finished.
|
|
- ``$Ansible.Verbosity`` reveals Ansible's verbosity level for this play. Allows the script to set VerbosePreference/DebugPreference based on verbosity. Added in ``1.9.0``.
|
|
- Any host/console output like ``Write-Host`` or ``[Console]::WriteLine`` is not considered an output object, they are returned as a string in *host_out* and *host_err*.
|
|
- The module will skip running the script when in check mode unless the script defines ``[CmdletBinding(SupportsShouldProcess``]).
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
.. seealso::
|
|
|
|
:ref:`ansible.windows.win_command_module`
|
|
The official documentation on the **ansible.windows.win_command** module.
|
|
:ref:`ansible.windows.win_shell_module`
|
|
The official documentation on the **ansible.windows.win_shell** module.
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
- name: Run basic PowerShell script
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
echo "Hello World"
|
|
|
|
- name: Run PowerShell script with parameters
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
[CmdletBinding()]
|
|
param (
|
|
[String]
|
|
$Path,
|
|
|
|
[Switch]
|
|
$Force
|
|
)
|
|
|
|
New-Item -Path $Path -ItemType Direcotry -Force:$Force
|
|
parameters:
|
|
Path: C:\temp
|
|
Force: true
|
|
|
|
- name: Run PowerShell script that modifies the module changed result
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
if (Get-Service -Name test -ErrorAction SilentlyContinue) {
|
|
Remove-Service -Name test
|
|
}
|
|
else {
|
|
$Ansible.Changed = $false
|
|
}
|
|
|
|
- name: Run PowerShell script in PowerShell 7
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
$PSVersionTable.PSVersion.Major
|
|
executable: pwsh.exe
|
|
arguments:
|
|
- -ExecutionPolicy
|
|
- ByPass
|
|
register: pwsh_output
|
|
failed_when:
|
|
- pwsh_output.output[0] != 7
|
|
|
|
- name: Run code in check mode
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
[CmdletBinding(SupportsShouldProcess)]
|
|
param ()
|
|
|
|
# Use $Ansible to detect check mode
|
|
if ($Ansible.CheckMode) {
|
|
echo 'running in check mode'
|
|
}
|
|
else {
|
|
echo 'running in normal mode'
|
|
}
|
|
|
|
# Use builtin ShouldProcess (-WhatIf)
|
|
if ($PSCmdlet.ShouldProcess('target')) {
|
|
echo 'also running in normal mode'
|
|
}
|
|
else {
|
|
echo 'also running in check mode'
|
|
}
|
|
check_mode: yes
|
|
|
|
- name: Return a failure back to Ansible
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
if (Test-Path C:\bad.file) {
|
|
$Ansible.Failed = $true
|
|
}
|
|
|
|
- name: Define when the script made a change or not
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
if ((Get-Item WSMan:\localhost\Service\Auth\Basic).Value -eq 'true') {
|
|
Set-Item WSMan:\localhost\Service\Auth\Basic -Value false
|
|
}
|
|
else {
|
|
$Ansible.Changed = $true
|
|
}
|
|
|
|
- name: Define when to enable Verbose/Debug output
|
|
ansible.windows.win_powershell:
|
|
script: |
|
|
if ($Ansible.Verbosity -ge 3) {
|
|
$VerbosePreference = "Continue"
|
|
}
|
|
if ($Ansible.Verbosity -eq 5) {
|
|
$DebugPreference = "Continue"
|
|
}
|
|
Write-Output "Hello World!"
|
|
Write-Verbose "Hello World!"
|
|
Write-Debug "Hello World!"
|
|
|
|
|
|
|
|
Return Values
|
|
-------------
|
|
Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module:
|
|
|
|
.. raw:: html
|
|
|
|
<table border=0 cellpadding=0 class="documentation-table">
|
|
<tr>
|
|
<th colspan="3">Key</th>
|
|
<th>Returned</th>
|
|
<th width="100%">Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>debug</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list of warning messages created by the script.</div>
|
|
<div>Debug messages only appear when <code>$DebugPreference = 'Continue'</code>.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['debug record']</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>error</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list of error records created by the script.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>category_info</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td></td>
|
|
<td>
|
|
<div>More information about the error record.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>activity</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Description of the operation which encountered the error.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Write-Error</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>category</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The category name of the error record.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">NotSpecified</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>category_id</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">integer</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The integer representation of the category.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>reason</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Description of the error.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">WriteErrorException</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>target_name</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Description of the target object.</div>
|
|
<div>Can be an empty string if no target was specified.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">C:\Windows</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>target_type</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Description of the type of the target object.</div>
|
|
<div>Can be an empty string if no target object was specified.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">String</div>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>error_details</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td></td>
|
|
<td>
|
|
<div>Additional details about an ErrorRecord.</div>
|
|
<div>Can be null if there are not additional details.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>message</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Message for the error record.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Specific error message</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>recommended_action</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Recommended action in the even that this error occurs.</div>
|
|
<div>This is empty unless the code which generates the error adds this explicitly.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Delete file</div>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>exception</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td></td>
|
|
<td>
|
|
<div>Details about the exception behind the error record.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>help_link</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A link to the help details for the exception.</div>
|
|
<div>May not be set as it's dependent on whether the .NET exception class provides this info.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">http://docs.ansible.com/</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>hresult</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">integer</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The signed integer assigned to this exception.</div>
|
|
<div>May not be set as it's dependent on whether the .NET exception class provides this info.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">-1</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>inner_exception</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The inner exception details if there is one present.</div>
|
|
<div>The dict contains the same keys as a normal exception.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>message</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The exception message.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">The method ran into an error</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>source</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Name of the application or object that causes the error.</div>
|
|
<div>This may be an empty string as it's dependent on the code that raises the exception.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">C:\Windows</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="1">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>type</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The full .NET type of the Exception class.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">System.Exception</div>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>fully_qualified_error_id</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The unique identifier for the error condition</div>
|
|
<div>May be null if no id was specified when the record was created.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">ParameterBindingFailed</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>output</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The formatted error record message as typically seen in a PowerShell console.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Write-Error "error" : error
|
|
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
|
|
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>pipeline_iteration_info</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=integer</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The status of the pipeline when this record was created.</div>
|
|
<div>The values are 0 index based.</div>
|
|
<div>Each element entry represents the command index in a pipeline statement.</div>
|
|
<div>The value of each element represents the pipeline input idx in that command.</div>
|
|
<div>For Example <code>'C:\Windows', 'C:\temp' | Get-ChildItem | Get-Item</code>, <code>[1, 2, 9]</code> represents an error occured with the 2nd output, 3rd, and 9th output of the 1st, 2nd, and 3rd command in that pipeline respectively.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">[0, 0]</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>script_stack_trace</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The script stack trace for the error record.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">at <ScriptBlock>, <No file>: line 1</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>target_object</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The object which the error occured.</div>
|
|
<div>May be null if no object was specified when the record was created.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">C:\Windows</div>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>host_err</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The strings written to the host error output, typically the stderr.</div>
|
|
<div>This is not the same as objects sent to the error stream in PowerShell.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Error 1
|
|
Error 2</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>host_out</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The strings written to the host output, typically the stdout.</div>
|
|
<div>This is not the same as objects sent to the output stream in PowerShell.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Line 1
|
|
Line 2</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>information</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=dictionary</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list of information records created by the script.</div>
|
|
<div>The information stream was only added in PowerShell v5, older versions will always have an empty list as a value.</div>
|
|
<br/>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>message_data</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">complex</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>Message data associated with the record.</div>
|
|
<div>The value here can be of any type.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">information record</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>source</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The source of the record.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">Write-Information</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>tags</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list of tags associated with the record.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['Host']</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="elbow-placeholder"> </td>
|
|
<td colspan="2">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>time_generated</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The time the record was generated.</div>
|
|
<div>This is the time in UTC as an ISO 8601 formatted string.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">2021-02-11T04:46:00.4694240Z</div>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>output</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list containing all the objects outputted by the script.</div>
|
|
<div>The list elements can be anything as it is based on what was ran.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['output 1', 2, ['inner list'], {'key': 'value'}, 'None']</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>result</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">complex</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>The values that were set by <code>$Ansible.Result</code> in the script.</div>
|
|
<div>Defaults to an empty dict but can be set to anything by the script.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'key': 'value', 'other key': 1}</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>verbose</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list of warning messages created by the script.</div>
|
|
<div>Verbose messages only appear when <code>$VerbosePreference = 'Continue'</code>.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['verbose record']</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="3">
|
|
<div class="ansibleOptionAnchor" id="return-"></div>
|
|
<b>warning</b>
|
|
<a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">list</span>
|
|
/ <span style="color: purple">elements=string</span>
|
|
</div>
|
|
</td>
|
|
<td>always</td>
|
|
<td>
|
|
<div>A list of warning messages created by the script.</div>
|
|
<div>Warning messages only appear when <code>$WarningPreference = 'Continue'</code>.</div>
|
|
<br/>
|
|
<div style="font-size: smaller"><b>Sample:</b></div>
|
|
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['warning record']</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br/><br/>
|
|
|
|
|
|
Status
|
|
------
|
|
|
|
|
|
Authors
|
|
~~~~~~~
|
|
|
|
- Jordan Borean (@jborean93)
|