ansible / ansible.windows / 2.3.0 / module / win_powershell Run PowerShell scripts | "added in version" 1.5.0 of ansible.windows" Authors: Jordan Borean (@jborean93)ansible.windows.win_powershell (2.3.0) — module
Install with ansible-galaxy collection install ansible.windows:==2.3.0
collections: - name: ansible.windows version: 2.3.0
Runs 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