ansible.windows.win_powershell – Run PowerShell scripts¶
Note
This plugin is part of the ansible.windows collection (version 1.5.0).
To install it use: ansible-galaxy collection install ansible.windows.
To use it in a playbook, specify: ansible.windows.win_powershell.
New in version 1.5.0: of ansible.windows
Synopsis¶
Runs a PowerShell script and outputs the data in a structured format.
Use ansible.windows.win_command or ansible.windows.win_shell to run a tranditional PowerShell process with stdout, stderr, and rc results.
Parameters¶
Notes¶
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.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]).
See Also¶
See also
- ansible.windows.win_command
The official documentation on the ansible.windows.win_command module.
- ansible.windows.win_shell
The official documentation on the ansible.windows.win_shell module.
Examples¶
- 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
}
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Jordan Borean (@jborean93)