ansible.windows.win_package 模块 – 安装/卸载可安装包

注意

此模块是 ansible.windows 集合 (版本 2.5.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install ansible.windows。

要在 playbook 中使用它，请指定：ansible.windows.win_package。

概要

• 安装或卸载 Windows 软件包。

• 支持 .exe、.msi、.msp、.appx、.appxbundle、.msix 和 .msixbundle。

• 这些包可以来自本地文件系统、网络文件共享或 URL。

• 有关支持的每种包类型的更多信息，请参见 *provider*。

参数

参数	注释
arguments 任意	安装程序需要安装或卸载包的任何参数。 如果包是 MSI，请不要提供 /qn、/log 或 /norestart 参数。 这仅用于 msi、msp 和 registry 提供程序。 可以是参数列表，模块将根据需要转义参数，建议在处理 MSI 包时使用字符串，因为 msiexec 存在独特的转义问题。 使用参数列表时，列表中的每个项目都被视为单个参数。因此，如果列表中的参数包含空格，则 Ansible 将对此进行引用，以确保 Windows 将其视为单个参数。如果不需要此行为，则应将参数拆分为两个单独的列表项。有关更多详细信息，请参见示例部分。
chdir 路径	在安装或卸载包之前，将指定路径设置为当前工作目录。 这仅用于 msi、msp 和 registry 提供程序。
client_cert 字符串	用于 X509 身份验证的客户端证书（.pfx）的路径。此路径可以是文件系统上 pfx 的路径，也可以是 PowerShell 证书路径 Cert:\CurrentUser\My\<thumbprint>。 如果未对证书文件进行密码保护，则 WinRM 连接必须使用 CredSSP 进行身份验证，或者在任务上使用 become。 如果证书受密码保护，其他身份验证类型可以在证书受密码保护时设置 *client_cert_password*。
client_cert_password 字符串	如果证书受密码保护，则为 *client_cert* 的密码。
creates_path 路径	将检查指定路径的存在，并使用结果来确定包是否已安装。 您可以将其与 product_id 和其他 creates_* 结合使用。
creates_service 字符串	将检查指定服务的现有情况，并使用结果来确定包是否已安装。 您可以将其与 product_id 和其他 creates_* 结合使用。
creates_version 字符串	将检查 creates_path 处文件的“文件版本”属性，并使用结果来确定包是否已安装。 creates_path 必须设置且为文件。 您可以将其与 product_id 和其他 creates_* 结合使用。
expected_return_code 列表 / 元素=整数	一个或多个来自包安装的返回代码，指示成功。 返回代码被读取为有符号整数，任何大于 2147483647 的值都需要表示为有符号等价物，即 4294967295 是 -1。 要将无符号数转换为有符号等价物，您可以运行“[Int32](“0x{0:X}” -f ([UInt32]3221225477))”。 返回代码 3010 通常表示需要重新启动，如果返回代码为 3010，则设置 reboot_required 返回值。 这仅用于 msi、msp 和 registry 提供程序。 默认值： [0, 3010]
follow_redirects 字符串	模块是否应该遵循重定向。 all 将遵循所有重定向。 none 将不遵循任何重定向。 safe 只会遵循“安全”重定向，“安全”意味着客户端仅对重定向到的 URI 执行 GET 或 HEAD 请求。 遵循重定向 URL 时，将丢弃 Authorization 头部和任何已设置的凭据，不会进行重定向。 选项 "all" "none" "safe" ← (默认)
force_basic_auth 布尔值	默认情况下，只有当 Web 服务对初始请求以 401 状态响应时，才会发送身份验证头部。由于某些基本身份验证服务不会正确发送 401，因此登录将失败。 此选项强制在原始请求上发送基本身份验证头部。 选项 false ← (默认) true
headers 字典	要在请求上设置的额外头部。 这应该是一个字典，其中键是头部名称，值是该头部的值。
http_agent 字符串	用于识别的头部，通常显示在 Web 服务器日志中。 这被设置为 HTTP 请求上的 User-Agent 头部。 默认值： "ansible-httpget"
log_path 路径	指定安装或卸载包后持久保存的日志文件的路径。 这仅用于 msi 或 msp 提供程序。 省略此选项时，将改为使用临时日志文件。 这只对 MSI 文件有效，对 registry 提供程序使用 arguments。
maximum_redirection 整数	指定模块在连接失败之前将连接重定向到备用 URI 的次数。 如果设置为 0 或 follow_redirects 设置为 none，或者在不执行 GET 或 HEAD 请求时设置为 safe，则会阻止所有重定向。 默认值： 50
路径 字符串	要安装或卸载的包的位置。 此包可以位于本地文件系统、网络共享或 URL 上。 当 state=present 时，product_id 未设置且路径为 URL，此文件将始终下载到临时目录以进行幂等性检查，否则只有在基于 product_id 检查未安装包的情况下才会下载文件。 如果 state=present，则必须设置此值。 如果 state=absent，则如果设置了 product_id，则无需设置此值。
product_id 字符串	已安装包的产品 ID。 这用于检查产品是否已安装，以及如果 state=absent 则获取卸载信息。 对于 msi 包，这是包的 ProductCode (GUID)。可以在与 registry 提供程序相同的注册表路径下找到它。 对于 msp 包，这是包的 PatchCode (GUID)，可以在文件的属性中的 Details -> Revision number 下找到。 对于 msix 包，这是在 Get-AppxPackage cmdlet 下找到的包的 Name 或 PackageFullName。 对于注册表 (exe) 包，这是在 provider 中指定的注册表路径下的注册表键名称。 如果 path 设置为本地可访问的文件路径且包不是 exe，则忽略此值。 当包是 exe，或者路径是 URL 或网络共享且未使用凭据委派时，应该设置此值。可以使用 creates_* 选项，但不推荐。
provider 字符串	设置搜索包时要使用的包提供程序。 auto 提供程序将选择正确的提供程序（如果设置了 path），否则它将根据 product_id 扫描所有其他提供程序。 msi 提供程序扫描基于 MSI 的 ProductCode 在机器范围和当前用户上下文中安装的 MSI 包。 msix 提供程序用于安装 .appx、.msix、.appxbundle 或 .msixbundle 包。这些包仅安装或删除在当前用户上。主机必须设置为允许侧载应用程序或处于开发人员模式。请参阅示例以了解如何启用此功能。如果包已安装，但 path 指向更新的包，则将安装在现有包之上。 msp 提供程序扫描基于 MSP 的 PatchCode 在机器范围和当前用户上下文中安装的所有 MSP 修补程序。msp 将应用于或从所有应用并已安装的 msi 产品中删除。如果修补程序已过期或被取代，则不会执行任何操作。 registry 提供程序用于传统的 exe 安装程序，并使用以下注册表路径来确定产品是否已安装；HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall、HKLM:\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall、HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall 和 HKCU:\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall。 选项 "auto" ← (默认) "msi" "msix" "msp" "registry"
proxy_password 字符串	proxy_username 的密码。
proxy_url 字符串	要用于请求的显式代理。 默认情况下，除非 use_proxy 设置为 no，否则请求将使用 IE 定义的代理。
proxy_use_default_credential 布尔值	使用当前用户的凭据通过 NTLM、Kerberos 或 Negotiate 身份验证对受保护的代理主机进行身份验证。 使用 Basic 身份验证的代理仍然需要通过 proxy_username 和 proxy_password 选项显式提供凭据。 只有在使用带有密码的 become、使用密码连接 SSH 或使用 CredSSP 或 Kerberos with delegation 连接 WinRM 时，模块才能访问用户的凭据。 如果不使用 become 或上述不同的身份验证方法，则没有可用的默认凭据，也不会发生代理身份验证。 选项 false ← (默认) true
proxy_username 字符串	用于代理身份验证的用户名。
state 字符串	是否安装或卸载包。 模块使用 product_id 来确定包是否已安装。 对于除 auto 之外的所有提供程序，如果 path 是本地可访问的文件系统路径，则可用于幂等性检查。 选项 "absent" "present" ← (默认)
url_method 字符串	请求的 HTTP 方法。
url_password 字符串	url_username 的密码。
url_timeout 整数	指定请求在超时之前可以挂起的时长（以秒为单位）。 设置为 0 表示无限超时。 默认值： 30
url_username 字符串	用于身份验证的用户名。
use_default_credential 布尔值	使用当前用户的凭据，对使用NTLM、Kerberos或Negotiate身份验证保护的服务器进行身份验证。 使用Basic身份验证的站点仍然需要通过url_username和url_password选项显式提供凭据。 只有在使用带有密码的 become、使用密码连接 SSH 或使用 CredSSP 或 Kerberos with delegation 连接 WinRM 时，模块才能访问用户的凭据。 如果不使用become或上述不同的身份验证方法，则不会有默认凭据可用，也不会进行身份验证。 选项 false ← (默认) true
use_proxy 布尔值	如果为no，则不会使用IE中为当前用户定义的代理。 选项 false true ← (默认)
validate_certs 布尔值	如果为no，则不会验证SSL证书。 这仅应在使用自签名证书的个人控制站点上使用。 选项 false true ← (默认)
wait_for_children 布尔值 在 ansible.windows 1.3.0 中添加	模块将等待其生成的进程完成，但忽略在该子进程中生成的任何进程。 设置为true，以便在模块返回之前等待所有后代进程完成。 如果安装/卸载程序只是一个包装器，然后将其自身的子进程调用实际的安装程序，则此功能非常有用。当此选项为true时，模块将等待两个进程都完成之后再返回。 对于大多数安装程序，这不需要，设置为true可能会导致模块不返回，直到手动停止正在等待的进程。 需要 Windows Server 2012 或 Windows 8 或更高版本才能使用。 选项 false ← (默认) true

注释

注意

• 当state=absent并且产品是exe文件时，路径可能与最初用于安装软件包的路径不同。如果未设置路径，则使用的路径将是该product_id在注册表中QuietUninstallString或UninstallString下设置的路径。

• 默认情况下，所有 msi 安装和卸载都将使用参数/log, /qn, /norestart运行。

• 在product_id和creates_*下所有安装检查加在一起，如果一个失败，则程序被认为不存在。

另请参阅

另请参阅

chocolatey.chocolatey.win_chocolatey

使用chocolatey管理软件包。

community.windows.win_hotfix

安装和卸载 Windows 修补程序。

ansible.windows.win_updates

下载并安装 Windows 更新。

community.windows.win_inet_proxy

管理 WinINet 和 Internet Explorer 的代理设置。

示例

- name: Install the Visual C thingy
  ansible.windows.win_package:
    path: http://download.microsoft.com/download/1/6/B/16B06F60-3B20-4FF2-B699-5E9B7962F9AE/VSU_4/vcredist_x64.exe
    product_id: '{CF2BEA3C-26EA-32F8-AA9B-331F7E34BA97}'
    arguments: /install /passive /norestart

- name: Install Visual C thingy with list of arguments instead of a string
  ansible.windows.win_package:
    path: http://download.microsoft.com/download/1/6/B/16B06F60-3B20-4FF2-B699-5E9B7962F9AE/VSU_4/vcredist_x64.exe
    product_id: '{CF2BEA3C-26EA-32F8-AA9B-331F7E34BA97}'
    arguments:
      - /install
      - /passive
      - /norestart

- name: Install MSBuild thingy with arguments split to prevent quotes
  ansible.windows.win_package:
    path: https://download.visualstudio.microsoft.com/download/pr/9665567e-f580-4acd-85f2-bc94a1db745f/vs_BuildTools.exe
    product_id: '{D1437F51-786A-4F57-A99C-F8E94FBA1BD8}'
    arguments:
      - --norestart
      - --passive
      - --wait
      - --add
      - Microsoft.Net.Component.4.6.1.TargetingPack
      - --add
      - Microsoft.Net.Component.4.6.TargetingPack

- name: Install Remote Desktop Connection Manager from msi with a permanent log
  ansible.windows.win_package:
    path: https://download.microsoft.com/download/A/F/0/AF0071F3-B198-4A35-AA90-C68D103BDCCF/rdcman.msi
    product_id: '{0240359E-6A4C-4884-9E94-B397A02D893C}'
    state: present
    log_path: D:\logs\vcredist_x64-exe-{{lookup('pipe', 'date +%Y%m%dT%H%M%S')}}.log

- name: Install Application from msi with multiple properties for installer
  ansible.windows.win_package:
    path: C:\temp\Application.msi
    state: present
    arguments: >-
      SERVICE=1
      DBNAME=ApplicationDB
      DBSERVER=.\SQLEXPRESS
      INSTALLDIR="C:\Program Files (x86)\App lication\App Server"

- name: Install Microsoft® SQL Server® 2019 Express (DPAPI example)
  ansible.windows.win_package:
    path: C:\temp\SQLEXPR_x64_ENU\SETUP.EXE
    product_id: Microsoft SQL Server SQL2019
    arguments:
      - SAPWD=VeryHardPassword
      - /ConfigurationFile=C:\temp\configuration.ini
  become: true
  vars:
    ansible_become_method: runas
    ansible_become_user: "{{ user }}"
    ansible_become_pass: "{{ password }}"

- name: Uninstall Remote Desktop Connection Manager
  ansible.windows.win_package:
    product_id: '{0240359E-6A4C-4884-9E94-B397A02D893C}'
    state: absent

- name: Install Remote Desktop Connection Manager locally omitting the product_id
  ansible.windows.win_package:
    path: C:\temp\rdcman.msi
    state: present

- name: Uninstall Remote Desktop Connection Manager from local MSI omitting the product_id
  ansible.windows.win_package:
    path: C:\temp\rdcman.msi
    state: absent

# 7-Zip exe doesn't use a guid for the Product ID
- name: Install 7zip from a network share with specific credentials
  ansible.windows.win_package:
    path: \\domain\programs\7z.exe
    product_id: 7-Zip
    arguments: /S
    state: present
  become: true
  become_method: runas
  become_flags: logon_type=new_credential logon_flags=netcredentials_only
  vars:
    ansible_become_user: DOMAIN\User
    ansible_become_password: Password

- name: Install 7zip and use a file version for the installation check
  ansible.windows.win_package:
    path: C:\temp\7z.exe
    creates_path: C:\Program Files\7-Zip\7z.exe
    creates_version: 16.04
    state: present

- name: Uninstall 7zip from the exe
  ansible.windows.win_package:
    path: C:\Program Files\7-Zip\Uninstall.exe
    product_id: 7-Zip
    arguments: /S
    state: absent

- name: Uninstall 7zip without specifying the path
  ansible.windows.win_package:
    product_id: 7-Zip
    arguments: /S
    state: absent

- name: Install application and override expected return codes
  ansible.windows.win_package:
    path: https://download.microsoft.com/download/1/6/7/167F0D79-9317-48AE-AEDB-17120579F8E2/NDP451-KB2858728-x86-x64-AllOS-ENU.exe
    product_id: '{7DEBE4EB-6B40-3766-BB35-5CBBC385DA37}'
    arguments: '/q /norestart'
    state: present
    expected_return_code: [0, 666, 3010]

- name: Install a .msp patch
  ansible.windows.win_package:
    path: C:\Patches\Product.msp
    state: present

- name: Remove a .msp patch
  ansible.windows.win_package:
    product_id: '{AC76BA86-A440-FFFF-A440-0C13154E5D00}'
    state: absent

- name: Enable installation of 3rd party MSIX packages
  ansible.windows.win_regedit:
    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock
    name: AllowAllTrustedApps
    data: 1
    type: dword
    state: present

- name: Install an MSIX package for the current user
  ansible.windows.win_package:
    path: C:\Installers\Calculator.msix  # Can be .appx, .msixbundle, or .appxbundle
    state: present

- name: Uninstall an MSIX package using the product_id
  ansible.windows.win_package:
    product_id: InputApp
    state: absent

返回值

常用返回值已在此处记录，以下是此模块特有的字段

键	描述
log 字符串	MSI 或 MSP 日志的内容。 返回：MSI 或 MSP 包的安装/卸载失败 示例： "Installation completed successfully"
rc 整数	包进程的返回代码。 返回：发生更改 示例： 0
reboot_required 布尔值	是否需要重新启动才能完成软件包。如果可执行文件的返回代码为 3010，则将其设置为 true。 返回：始终 示例： true
stderr 字符串	包进程的 stderr 流。 返回：安装或卸载期间发生故障 示例： "Failed to install program"
stdout 字符串	包进程的 stdout 流。 返回：安装或卸载期间发生故障 示例： "Installing program"

作者

• Trond Hindenes (@trondhindenes)

• Jordan Borean (@jborean93)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信