win_xml – Manages XML file content on Windows hosts

New in version 2.7.

Synopsis

  • Manages XML nodes, attributes and text, using xpath to select which xml nodes need to be managed.
  • XML fragments, formatted as strings, are used to specify the desired state of a part or parts of XML files on remote Windows servers.
  • For non-Windows targets, use the xml module instead.

Parameters

Parameter Choices/Defaults Comments
attribute
string
The attribute name if the type is 'attribute'.
Required if type=attribute.
backup
boolean
    Choices:
  • no ←
  • yes
Determine whether a backup should be created.
When set to yes, create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
count
boolean
added in 2.9
    Choices:
  • no ←
  • yes
When set to yes, return the number of nodes matched by xpath.
fragment
string
The string representation of the XML fragment expected at xpath. Since ansible 2.9 not required when state=absent, or when count=yes.

aliases: xmlstring
path
path / required
Path to the file to operate on.

aliases: dest, file
state
string
added in 2.9
    Choices:
  • present ←
  • absent
Set or remove the nodes (or attributes) matched by xpath.
type
string / required
    Choices:
  • attribute
  • element ←
  • text
The type of XML node you are working with.
xpath
string / required
Xpath to select the node or nodes to operate on.

Notes

Note

  • Only supports operating on xml elements, attributes and text.
  • Namespace, processing-instruction, command and document node types cannot be modified with this module.

See Also

See also

xml – Manage bits and pieces of XML files or strings
XML manipulation for Posix hosts.
w3shools XPath tutorial
A useful tutorial on XPath

Examples

- name: Apply our filter to Tomcat web.xml
  win_xml:
   path: C:\apache-tomcat\webapps\myapp\WEB-INF\web.xml
   fragment: '<filter><filter-name>MyFilter</filter-name><filter-class>com.example.MyFilter</filter-class></filter>'
   xpath: '/*'

- name: Apply sslEnabledProtocols to Tomcat's server.xml
  win_xml:
   path: C:\Tomcat\conf\server.xml
   xpath: '//Server/Service[@name="Catalina"]/Connector[@port="9443"]'
   attribute: 'sslEnabledProtocols'
   fragment: 'TLSv1,TLSv1.1,TLSv1.2'
   type: attribute

- name: remove debug configuration nodes from nlog.conf
  win_xml:
   path: C:\IISApplication\nlog.conf
   xpath: /nlog/rules/logger[@name="debug"]/descendant::*
   state: absent

- name: count configured connectors in Tomcat's server.xml
  win_xml:
   path: C:\Tomcat\conf\server.xml
   xpath: //Server/Service/Connector
   count: yes
  register: connector_count

- name: show connector count
  debug:
    msg="Connector count is {{connector_count.count}}"

- name: ensure all lang=en attributes to lang=nl
  win_xml:
   path: C:\Data\Books.xml
   xpath: //@[lang="en"]
   attribute: lang
   fragment: nl
   type: attribute

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
backup_file
string
if backup=yes
Name of the backup file that was created.

Sample:
C:\Path\To\File.txt.11540.20150212-220915.bak
count
integer
if count=yes
Number of nodes matched by xpath.

Sample:
33
err
list
always, for type element and -vvv or more
XML comparison exceptions.

Sample:
attribute mismatch for actual=string
msg
string
always
What was done.

Sample:
xml added


Status

Authors

  • Richard Levenberg (@richardcs)
  • Jon Hawkesworth (@jhawkesworth)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.