ansible.windows.win_powershell – Run PowerShell scripts

• Synopsis
• Parameters
• Notes
• See Also
• Examples
• Return Values

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

See Also

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)