Run PowerShell scripts
Version added: 1.5.0
- 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.
Note
- The module is set as failed when a terminating exception is throw, or
error_action=stopand a normal error record is raised. - The output values are processed using a custom filter and while it mostly matches the
ConvertTo-Jsonresult the following value types are different. DateTimewill be an ISO 8601 string in UTC,DateTimeOffsetwill have the offset as specified by the value.Enumwill contain a dictionary withType,String,Valuebeing the type name, string representation and raw integer value respectively.Typewill contain a dictionary withName,FullName,AssemblyQualifiedName,BaseTypebeing 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
$Ansiblevariable where it can setResult,Changed,Failed, or accessTmpdir. $Ansible.Resultis a value that is returned back to the controller as is.$Ansible.Changedcan be set totrueorfalseto reflect whether the module made a change or not. By default this is set totrue.$Ansible.Failedcan be set totrueif the script wants to return the failure back to the controller.$Ansible.Tmpdiris the path to a temporary directory to use as a scratch location that is cleaned up after the module has finished.$Ansible.Verbosityreveals Ansible's verbosity level for this play. Allows the script to set VerbosePreference/DebugPreference based on verbosity. Added in1.9.0.- Any host/console output like
Write-Hostor[Console]::WriteLineis 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]).
.. 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.
- 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!"Common return values are documented here, the following are the fields unique to this module:
- Jordan Borean (@jborean93)