Try SpotterRun PowerShell scripts
| "added in version" 1.5.0 of ansible.windows"
Authors: Jordan Borean (@jborean93)
Install with ansible-galaxy collection install ansible.windows:==2.3.0
collections:
- name: ansible.windows
version: 2.3.0Runs a PowerShell script and outputs the data in a structured format.
Use M(ansible.windows.win_command) or M(ansible.windows.win_shell) to run a traditional PowerShell process with stdout, stderr, and rc results.
- 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 Directory -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!"
chdir:
description:
- The PowerShell location to set when starting the script.
- This can be a location in any of the PowerShell providers.
- The default location is dependent on many factors, if relative paths are used then
set this option.
type: str
depth:
default: 2
description:
- How deep the return values are serialized for C(result), C(output), and C(information[x].message_data).
- This also controls the depth of the diff output set by C($Ansible.Diff).
- Setting this to a higher value can dramatically increase the amount of data that
needs to be returned.
type: int
script:
description:
- The PowerShell script to run.
required: true
type: str
creates:
description:
- A path or path filter pattern; when the referenced path exists on the target host,
the task will be skipped.
type: str
removes:
description:
- A path or path filter pattern; when the referenced path B(does not) exist on the
target host, the task will be skipped.
type: str
arguments:
description:
- A list of arguments to pass to I(executable) when running a script in another PowerShell
process.
- These are not arguments to pass to I(script), use I(parameters) for that purpose.
elements: str
type: list
executable:
description:
- A custom PowerShell executable to run the script in.
- When not defined the script will run in the current module PowerShell interpreter.
- Both the remote PowerShell and the one specified by I(executable) must be running
on PowerShell v5.1 or newer.
- Setting this value may change the values returned in the C(output) return value
depending on the underlying .NET type.
type: str
parameters:
description:
- Parameters to pass into the script as key value pairs.
- The key corresponds to the parameter name and the value is the value for that parameter.
type: dict
error_action:
choices:
- silently_continue
- continue
- stop
default: continue
description:
- The C($ErrorActionPreference) to set before executing I(script).
- C(silently_continue) will ignore any errors and exceptions raised.
- C(continue) is the default behaviour in PowerShell, errors are present in the I(error)
return value but only terminating exceptions will stop the script from continuing
and set it as failed.
- C(stop) will treat errors like exceptions, will stop the script and set it as failed.
type: str
debug:
description:
- A list of warning messages created by the script.
- Debug messages only appear when C($DebugPreference = 'Continue').
elements: str
returned: always
sample:
- debug record
type: list
error:
contains:
category_info:
contains:
activity:
description:
- Description of the operation which encountered the error.
returned: always
sample: Write-Error
type: str
category:
description:
- The category name of the error record.
returned: always
sample: NotSpecified
type: str
category_id:
description:
- The integer representation of the category.
returned: always
sample: 0
type: int
reason:
description:
- Description of the error.
returned: always
sample: WriteErrorException
type: str
target_name:
description:
- Description of the target object.
- Can be an empty string if no target was specified.
returned: always
sample: C:\Windows
type: str
target_type:
description:
- Description of the type of the target object.
- Can be an empty string if no target object was specified.
returned: always
sample: String
type: str
description:
- More information about the error record.
type: dict
error_details:
contains:
message:
description:
- Message for the error record.
returned: always
sample: Specific error message
type: str
recommended_action:
description:
- Recommended action in the even that this error occurs.
- This is empty unless the code which generates the error adds this explicitly.
returned: always
sample: Delete file
type: str
description:
- Additional details about an ErrorRecord.
- Can be null if there are not additional details.
type: dict
exception:
contains:
help_link:
description:
- A link to the help details for the exception.
- May not be set as it's dependent on whether the .NET exception class provides
this info.
returned: always
sample: http://docs.ansible.com/
type: str
hresult:
description:
- The signed integer assigned to this exception.
- May not be set as it's dependent on whether the .NET exception class provides
this info.
returned: always
sample: -1
type: int
inner_exception:
description:
- The inner exception details if there is one present.
- The dict contains the same keys as a normal exception.
returned: always
type: dict
message:
description:
- The exception message.
returned: always
sample: The method ran into an error
type: str
source:
description:
- Name of the application or object that causes the error.
- This may be an empty string as it's dependent on the code that raises
the exception.
returned: always
sample: C:\Windows
type: str
type:
description:
- The full .NET type of the Exception class.
returned: always
sample: System.Exception
type: str
description:
- Details about the exception behind the error record.
type: dict
fully_qualified_error_id:
description:
- The unique identifier for the error condition
- May be null if no id was specified when the record was created.
returned: always
sample: ParameterBindingFailed
type: str
output:
description:
- The formatted error record message as typically seen in a PowerShell console.
returned: always
sample: "Write-Error \"error\" : error\n + CategoryInfo : NotSpecified:\
\ (:) [Write-Error], WriteErrorException\n + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException\n"
type: str
pipeline_iteration_info:
description:
- The status of the pipeline when this record was created.
- The values are 0 index based.
- Each element entry represents the command index in a pipeline statement.
- The value of each element represents the pipeline input idx in that command.
- For Example C('C:\Windows', 'C:\temp' | Get-ChildItem | Get-Item), C([1, 2,
9]) represents an error occured with the 2nd output, 3rd, and 9th output of
the 1st, 2nd, and 3rd command in that pipeline respectively.
elements: int
returned: always
sample:
- 0
- 0
type: list
script_stack_trace:
description:
- The script stack trace for the error record.
returned: always
sample: 'at <ScriptBlock>, <No file>: line 1'
type: str
target_object:
description:
- The object which the error occured.
- May be null if no object was specified when the record was created.
- Type type of this object depends on the error record itself.
- If the value is a complex type, it will follow the C(depth) limit specified.
returned: always
sample: C:\Windows
type: raw
description:
- A list of error records created by the script.
elements: dict
returned: always
type: list
host_err:
description:
- The strings written to the host error output, typically the stderr.
- This is not the same as objects sent to the error stream in PowerShell.
returned: always
sample: 'Error 1
Error 2'
type: str
host_out:
description:
- The strings written to the host output, typically the stdout.
- This is not the same as objects sent to the output stream in PowerShell.
returned: always
sample: 'Line 1
Line 2'
type: str
information:
contains:
message_data:
contains: {}
description:
- Message data associated with the record.
- The value here can be of any type.
returned: always
sample: information record
type: complex
source:
description:
- The source of the record.
returned: always
sample: Write-Information
type: str
tags:
description:
- A list of tags associated with the record.
elements: str
returned: always
sample:
- Host
type: list
time_generated:
description:
- The time the record was generated.
- This is the time in UTC as an ISO 8601 formatted string.
returned: always
sample: '2021-02-11T04:46:00.4694240Z'
type: str
description:
- A list of information records created by the script.
- The information stream was only added in PowerShell v5, older versions will always
have an empty list as a value.
elements: dict
returned: always
type: list
output:
description:
- A list containing all the objects outputted by the script.
- The list elements can be anything as it is based on what was ran.
returned: always
sample:
- output 1
- 2
- - inner list
- key: value
- None
type: list
result:
contains: {}
description:
- The values that were set by C($Ansible.Result) in the script.
- Defaults to an empty dict but can be set to anything by the script.
returned: always
sample:
key: value
other key: 1
type: complex
verbose:
description:
- A list of warning messages created by the script.
- Verbose messages only appear when C($VerbosePreference = 'Continue').
elements: str
returned: always
sample:
- verbose record
type: list
warning:
description:
- A list of warning messages created by the script.
- Warning messages only appear when C($WarningPreference = 'Continue').
elements: str
returned: always
sample:
- warning record
type: list