Windows 模块开发流程

在本节中，我们将逐步介绍如何开发、测试和调试 Ansible Windows 模块。

由于 Windows 模块是用 Powershell 编写的，并且需要在 Windows 主机上运行，因此本指南与通常的开发流程指南有所不同。

本节内容

Windows 环境设置 

与可以在运行 Ansible 的主机上运行的 Python 模块开发不同，Windows 模块需要为 Windows 主机编写和测试。虽然可以从 Microsoft 下载 Windows 的评估版本，但这些映像通常需要进一步修改才能被 Ansible 使用。设置 Windows 主机以使其可以被 Ansible 使用的最简单方法是使用 Vagrant 设置虚拟机。Vagrant 可以用来下载称为“盒子”的现有操作系统映像，然后部署到像 VirtualBox 这样的虚拟机管理程序。这些盒子可以离线创建和存储，也可以从名为 Vagrant Cloud 的中央存储库下载。

本指南将使用 packer-windoze 存储库创建的 Vagrant 盒子，这些盒子也已上传到 Vagrant Cloud。要了解更多有关这些映像是如何创建的信息，请转到 GitHub 存储库，查看 README 文件。

在开始之前，必须安装以下程序（有关安装说明，请参阅 Vagrant 和 VirtualBox 文档）

Vagrant
VirtualBox

在 VM 中创建 Windows 服务器 

要创建单个 Windows Server 2016 实例，请运行以下命令

vagrant init jborean93/WindowsServer2016
vagrant up

这将从 Vagrant Cloud 下载 Vagrant 盒子，并将其添加到主机上的本地盒子中，然后在 VirtualBox 中启动该实例。第一次启动时，Windows VM 将运行 sysprep 过程，然后自动创建一个 HTTP 和 HTTPS WinRM 监听器。Vagrant 将在监听器上线后完成其过程，之后 Ansible 可以使用该 VM。

创建 Ansible 清单 

以下 Ansible 清单文件可用于连接到新创建的 Windows VM

[windows]
WindowsServer  ansible_host=127.0.0.1

[windows:vars]
ansible_user=vagrant
ansible_password=vagrant
ansible_port=55986
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore

注意

端口 55986 由 Vagrant 自动转发到创建的 Windows 主机，如果与现有的本地端口冲突，则 Vagrant 会自动随机使用另一个端口并在输出中显示出来。

创建的操作系统基于映像集。可以使用以下映像

主机上线后，可以通过 127.0.0.1:3389 上的 RDP 访问它，但端口可能会有所不同，具体取决于是否存在冲突。要删除主机，请运行 vagrant destroy --force，Vagrant 将自动删除 VM 和与该 VM 关联的任何其他文件。

虽然这在单个 Windows 实例上测试模块时很有用，但这些主机在没有修改的情况下无法与基于域的模块一起使用。位于 ansible-windows 的 Vagrantfile 可用于创建测试域环境，供 Ansible 使用。该存储库包含三个文件，Ansible 和 Vagrant 都使用这些文件来在域环境中创建多个 Windows 主机。这些文件是

Vagrantfile：Vagrant 文件，它读取 inventory.yml 的清单设置，并配置所需的主机
inventory.yml：包含所需的主机以及其他连接信息，例如 IP 地址和转发端口
main.yml：Vagrant 调用的 Ansible 剧本，用于配置域控制节点，并将子主机加入域

默认情况下，这些文件将创建以下环境

运行在 Windows Server 2016 上的单个 AD 域控制器
五个子主机，分别代表每个主要 Windows Server 版本，并加入该域
DNS 名称是 domain.local 的域
每个主机上的本地管理员帐户，用户名为 vagrant，密码为 vagrant
域管理员帐户 [email protected]，密码为 VagrantPass1

如果需要，可以通过更改 inventory.yml 文件中的变量 domain_* 来修改域名称和帐户。还可以通过更改 domain_children 键下定义的主机来修改清单文件，以配置更多或更少的服务器。主机变量 ansible_host 是将分配给 VirtualBox 主机专用网络适配器的私有 IP，而 vagrant_box 是将用来创建 VM 的盒子。

配置环境 

要按照原样配置环境，请运行以下命令

git clone https://github.com/jborean93/ansible-windows.git
cd vagrant
vagrant up

注意

Vagrant 依次配置每个主机，因此这可能需要一些时间才能完成。如果在设置域的 Ansible 阶段出现任何错误，请运行 vagrant provision 重新运行该步骤。

与使用 Vagrant 设置单个 Windows 实例不同，这些主机也可以使用 IP 地址直接访问，也可以通过转发端口访问。使用主机专用网络适配器访问它更容易，因为使用的是正常的协议端口，例如 RDP 仍然通过 3389 访问。如果无法使用主机专用网络 IP 解析主机，则可以使用以下端口通过 127.0.0.1 访问这些协议

RDP：295xx
SSH：296xx
WinRM HTTP：297xx
WinRM HTTPS：298xx
SMB：299xx

将 xx 替换为清单文件中域控制器开始的条目号，从 00 开始递增。例如，在默认的 inventory.yml 文件中，SERVER2012R2 的 WinRM over HTTPS 通过端口 29804 转发，因为它是在 domain_children 中的第四个条目。

Windows 新模块开发 

创建新模块时，需要注意以下几点

模块代码位于 Powershell (.ps1) 文件中，而文档包含在同名 Python (.py) 文件中
避免在模块中使用 Write-Host/Debug/Verbose/Error，并将需要返回的内容添加到 $module.Result 变量中
要使模块失败，请调用 $module.FailJson("failure message here")，可以将 Exception 或 ErrorRecord 设置为第二个参数，以获得更详细的错误消息
可以将异常或 ErrorRecord 作为第二个参数传递给 FailJson("failure", $_) 以获取更详细的输出
大多数新模块需要在合并到 Ansible 主代码库之前进行检查模式和集成测试
避免在大型代码块上使用 try/catch 语句，而是针对单个调用使用它们，这样可以使错误消息更具描述性
在使用 try/catch 语句时，尝试捕获特定的异常
避免使用 PSCustomObjects，除非必要
查找 ./lib/ansible/module_utils/powershell/ 中的通用功能，并使用该代码，而不是重复工作。可以通过添加 #Requires -Module * 行（其中 * 是要导入的文件名）来导入这些功能，并且在通过 Ansible 运行时，它们会自动包含在发送到 Windows 目标的模块代码中。
除了 PowerShell 模块工具之外，C# 模块工具存储在 ./lib/ansible/module_utils/csharp/ 中，如果存在 #AnsibleRequires -CSharpUtil * 行，则会在模块执行期间自动导入。
C# 和 PowerShell 模块工具实现相同目标，但 C# 允许开发人员实现低级任务（例如调用 Win32 API），并且在某些情况下可能更快。
确保代码在 Windows Server 2016 及更高版本上运行于 Powershell v5.1 及更高版本；如果需要更高的最低 Powershell 或操作系统版本，请确保文档清楚地反映这一点。
Ansible 在 strictmode 版本 2.0 下运行模块。确保通过在开发脚本顶部添加 Set-StrictMode -Version 2.0 来启用此功能进行测试。
如果可能，优先使用原生 Powershell cmdlet 而不是可执行文件调用。
使用完整的 cmdlet 名称，而不是别名，例如使用 Remove-Item 而不是 rm。
使用 cmdlet 的命名参数，例如使用 Remove-Item -Path C:\temp 而不是 Remove-Item C:\temp。

一个非常基本的 Powershell 模块 win_environment 体现了 Powershell 模块的最佳实践。它演示了如何实现 check-mode 和 diff-support，并且还显示了在满足特定条件时对用户的警告。

一个稍微高级的模块是 win_uri，它还展示了如何使用不同的参数类型（bool、str、int、list、dict、path）以及参数的选择，如何使模块失败以及如何处理异常。

作为新 AnsibleModule 包装器的一部分，输入参数是根据参数规范定义和验证的。以下选项可以在参数规范的根级别设置。

mutually_exclusive：一个列表列表，其中内部列表包含不能一起设置的模块选项。
no_log：阻止模块将任何日志输出到 Windows 事件日志。
options：一个字典，其中键是模块选项，值是该选项的规范。
required_by：一个字典，其中如果设置了键指定的选项，则必须设置值指定的选项。
required_if：一个列表列表，其中内部列表包含 3 或 4 个元素；
- 第一个元素是用来检查值的模块选项。
- 第二个元素是第一个元素指定的选项的值，如果匹配，则运行 required if 检查。
- 第三个元素是在上面匹配时所需的模块选项列表。
- 可选的第四个元素是一个布尔值，它声明第三个元素中的所有模块选项是否都必需（默认值：$false）还是只有一个（$true）。
required_one_of：一个列表列表，其中内部列表包含模块选项，其中至少要设置一个。
required_together：一个列表列表，其中内部列表包含必须一起设置的模块选项。
supports_check_mode：模块是否支持 check mode，默认情况下，此值为 $false。

模块的实际输入选项是在 options 值中作为字典设置的。此字典的键是模块选项名称，而值是该模块选项的规范。每个规范都可以设置以下选项。

aliases：模块选项的别名列表。
choices：模块选项的有效值列表，如果 type=list，则每个列表值都针对 choices 进行验证，而不是列表本身。
default：如果未设置，则为模块选项的默认值。
deprecated_aliases：一个哈希表列表，定义了已弃用的别名及其将被删除的版本。每个条目必须包含 name 和 collection_name 键，以及 version 或 date。
elements：当 type=list 时，这将设置每个列表值的类型，这些值与 type 相同。
no_log：将在 module_invocation 返回值中返回之前对输入值进行清理。
removed_in_version：声明已弃用的模块选项将被删除的时间，如果设置，则会向最终用户显示警告。
removed_at_date：声明已弃用的模块选项将被删除的日期 (YYYY-MM-DD)，如果设置，则会向最终用户显示警告。
removed_from_collection：声明已弃用的模块选项将从哪个集合中删除；如果指定了 removed_in_version 和 removed_at_date 之一，则必须指定此选项。
required：如果未设置模块选项，将失败。
type：模块选项的类型，如果未设置，则默认为 str。有效类型包括：
- bool：布尔值。
- dict：字典值，如果输入是 JSON 或 key=value 字符串，则将其转换为字典。
- float：浮点数或 Single 值。
- int：Int32 值。
- json：一个字符串，如果输入是字典，则将该值转换为 JSON 字符串。
- list：一个值列表，如果设置了 elements=<type>，则可以转换单个列表值类型。如果 elements=dict，则定义 options，这些值将根据参数规范进行验证。当输入是字符串时，字符串将按 , 分割，并且任何空格都将被修剪。
- path：一个字符串，其中像 %TEMP% 这样的值将根据环境值进行扩展。如果输入值以 \\?\ 开头，则不会运行扩展。
- raw：对 Ansible 传入的值不进行任何转换。
- sid：将 Windows 安全标识符值或 Windows 帐户名称转换为 SecurityIdentifier 值。
- str：该值将转换为字符串。

当 type=dict 或 type=list 且 elements=dict 时，还可以为该模块选项设置以下键。

apply_defaults：如果 True，则该值基于该键的 options 规范默认值，如果 False，则该值为 null。仅在用户未定义模块选项且 type=dict 时有效。
mutually_exclusive：与根级别的 mutually_exclusive 相同，但针对子字典中的值进行验证。
options：与根级别的 options 相同，但包含子选项的有效选项。
required_if：与根级别的 required_if 相同，但针对子字典中的值进行验证。
required_by：与根级别的 required_by 相同，但针对子字典中的值进行验证。
required_together：与根级别的 required_together 相同，但针对子字典中的值进行验证。
required_one_of：与根级别的 required_one_of 相同，但针对子字典中的值进行验证。

模块类型也可以是一个委托函数，将值转换为模块选项所需的任何类型。例如，以下代码片段展示了如何创建自定义类型来创建一个 UInt64 值

$spec = @{
    uint64_type = @{ type = [Func[[Object], [UInt64]]]{ [System.UInt64]::Parse($args[0]) } }
}
$uint64_type = $module.Params.uint64_type

如有疑问，请查看其他核心模块并了解它们是如何实现的。

有时，Windows 提供多种方法来完成一项任务；在编写模块时，应优先考虑以下顺序

原生 PowerShell cmdlet，例如 Remove-Item -Path C:\temp -Recurse
.NET 类，例如 [System.IO.Path]::GetRandomFileName()
通过 New-CimInstance cmdlet 使用 WMI 对象
通过 New-Object -ComObject cmdlet 使用 COM 对象
调用原生可执行文件，例如 Secedit.exe

PowerShell 模块支持 PowerShell 内置的 #Requires 选项的子集，以及 #AnsibleRequires 指定的某些 Ansible 特定要求。这些语句可以放置在脚本中的任何位置，但最常见的是在脚本的开头。它们用于更轻松地声明模块的要求，而无需编写任何检查。每个 requires 语句都必须单独占一行，但一个脚本中可以有多个 requires 语句。

以下是 Ansible 模块中可使用的检查

#Requires -Module Ansible.ModuleUtils.<module_util>：在 Ansible 2.4 中添加，指定要在模块执行时加载的 module_util。
#Requires -Version x.y：在 Ansible 2.5 中添加，指定模块所需的 PowerShell 版本。如果未满足此要求，模块将失败。
#AnsibleRequires -PowerShell <module_util>：在 Ansible 2.8 中添加，类似于 #Requires -Module，它指定要在模块执行时加载的 module_util。
#AnsibleRequires -CSharpUtil <module_util>：在 Ansible 2.8 中添加，指定要在模块执行时加载的 C# module_util。
#AnsibleRequires -OSVersion x.y：在 Ansible 2.5 中添加，指定模块所需的 OS 构建版本，如果未满足此要求，模块将失败。实际的 OS 版本是从 [Environment]::OSVersion.Version 导出的。
#AnsibleRequires -Become：在 Ansible 2.5 中添加，强制 exec 运行程序使用 become 运行模块，这主要用于绕过 WinRM 限制。如果未指定 ansible_become_user，则使用 SYSTEM 帐户。

#AnsibleRequires -PowerShell 和 #AnsibleRequires -CSharpUtil 支持更多功能，例如

导入集合中包含的 util（在 Ansible 2.9 中添加）
通过相对名称导入 util（在 Ansible 2.10 中添加）
通过向导入声明添加 -Optional 指定 util 是可选的（在 Ansible 2.12 中添加）。

有关更多详细信息，请参阅以下示例

# Imports the PowerShell Ansible.ModuleUtils.Legacy provided by Ansible itself
#AnsibleRequires -PowerShell Ansible.ModuleUtils.Legacy

# Imports the PowerShell my_util in the my_namesapce.my_name collection
#AnsibleRequires -PowerShell ansible_collections.my_namespace.my_name.plugins.module_utils.my_util

# Imports the PowerShell my_util that exists in the same collection as the current module
#AnsibleRequires -PowerShell ..module_utils.my_util

# Imports the PowerShell Ansible.ModuleUtils.Optional provided by Ansible if it exists.
# If it does not exist then it will do nothing.
#AnsibleRequires -PowerShell Ansible.ModuleUtils.Optional -Optional

# Imports the C# Ansible.Process provided by Ansible itself
#AnsibleRequires -CSharpUtil Ansible.Process

# Imports the C# my_util in the my_namespace.my_name collection
#AnsibleRequires -CSharpUtil ansible_collections.my_namespace.my_name.plugins.module_utils.my_util

# Imports the C# my_util that exists in the same collection as the current module
#AnsibleRequires -CSharpUtil ..module_utils.my_util

# Imports the C# Ansible.Optional provided by Ansible if it exists.
# If it does not exist then it will do nothing.
#AnsibleRequires -CSharpUtil Ansible.Optional -Optional

对于可选的 require 语句，模块代码需要在尝试使用 util 之前验证是否已导入 util。这可以通过检查 util 提供的函数或类型是否存在来完成。

虽然 #Requires -Module 和 #AnsibleRequires -PowerShell 都可用于加载 PowerShell 模块，但建议使用 #AnsibleRequires。这是因为 #AnsibleRequires 支持集合模块 util、通过相对 util 名称导入以及可选 util 导入。

C# 模块 util 可以通过在脚本的开头添加一行 using Ansible.<module_util>; 来引用其他 C# util，该行与所有其他 using 语句位于同一位置。

Windows 模块实用程序 

与 Python 模块类似，PowerShell 模块还提供许多模块实用程序，这些实用程序在 PowerShell 中提供辅助函数。可以通过向 PowerShell 模块添加以下行来导入这些 module_utils

#Requires -Module Ansible.ModuleUtils.Legacy

这将导入位于 ./lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 的 module_util，并允许调用其所有函数。从 Ansible 2.8 开始，Windows 模块 util 也可使用 C# 编写，并存储在 lib/ansible/module_utils/csharp 中。可以通过向 PowerShell 模块添加以下行来导入这些 module_utils

#AnsibleRequires -CSharpUtil Ansible.Basic

这将导入位于 ./lib/ansible/module_utils/csharp/Ansible.Basic.cs 的 module_util，并在执行进程中自动加载类型。C# 模块 util 可以相互引用，并通过在 util 开头的 using 语句中添加以下行来一起加载

using Ansible.Become;

在 C# 文件中可以设置特殊注释来控制编译参数。可以在脚本中添加以下注释；

//AssemblyReference -Name <assembly dll> [-CLR [Core|Framework]]：编译期间要引用的程序集 DLL，可选的 -CLR 标志也可用于指定在 .NET Core、Framework 或两者（如果省略）下运行时要引用的程序集。
//NoWarn -Name <error id> [-CLR [Core|Framework]]：编译代码时要忽略的编译器警告 ID，可选的 -CLR 的工作方式与上述相同。可以在编译器错误中找到警告列表。

此外，还定义了以下预处理器符号；

CORECLR：当 PowerShell 通过 .NET Core 运行时，此符号存在。
WINDOWS：当 PowerShell 在 Windows 上运行时，此符号存在。
UNIX：当 PowerShell 在 Unix 上运行时，此符号存在。

这些标志的组合有助于使模块 util 在 .NET Framework 和 .NET Core 上都可互操作，以下是在实际操作中的示例

#if CORECLR
using Newtonsoft.Json;
#else
using System.Web.Script.Serialization;
#endif

//AssemblyReference -Name Newtonsoft.Json.dll -CLR Core
//AssemblyReference -Name System.Web.Extensions.dll -CLR Framework

// Ignore error CS1702 for all .NET types
//NoWarn -Name CS1702

// Ignore error CS1956 only for .NET Framework
//NoWarn -Name CS1956 -CLR Framework

以下列出了与 Ansible 一起打包的 module_utils，以及它们的功能概述

ArgvParser：用于将参数列表转换为符合 Windows 参数解析规则的转义字符串的实用程序。
CamelConversion：用于将 camelCase 字符串/列表/字典转换为 snake_case 的实用程序。
CommandUtil：用于执行 Windows 进程并将 stdout/stderr 和 rc 作为单独的对象返回的实用程序。
FileUtil：扩展 Get-ChildItem 和 Test-Path 以处理特殊文件（例如 C:\pagefile.sys）的实用程序。
Legacy：Ansible 模块的通用定义和辅助实用程序。
LinkUtil：用于创建、删除和获取有关符号链接、联接点和硬链接信息的实用程序。
SID：用于将用户或组转换为 Windows SID，反之亦然的实用程序。

有关任何特定模块实用程序及其要求的更多详细信息，请参阅 Ansible 模块实用程序源代码。

PowerShell 模块实用程序可以存储在标准 Ansible 分发版之外，用于与自定义模块一起使用。自定义 module_utils 放在 playbook 或角色目录的根目录中的名为 module_utils 的文件夹中。

C# 模块实用程序也可以存储在标准 Ansible 分发版之外，用于与自定义模块一起使用。与 PowerShell util 类似，这些实用程序存储在名为 module_utils 的文件夹中，文件名必须以扩展名 .cs 结尾，以 Ansible. 开头，并以 util 中定义的命名空间命名。

以下示例是一个角色结构，其中包含两个名为 Ansible.ModuleUtils.ModuleUtil1、Ansible.ModuleUtils.ModuleUtil2 的 PowerShell 自定义 module_utils，以及一个包含命名空间 Ansible.CustomUtil 的 C# util

meta/
  main.yml
defaults/
  main.yml
module_utils/
  Ansible.ModuleUtils.ModuleUtil1.psm1
  Ansible.ModuleUtils.ModuleUtil2.psm1
  Ansible.CustomUtil.cs
tasks/
  main.yml

每个 PowerShell module_util 必须至少包含一个函数，该函数已在文件末尾使用 Export-ModuleMember 导出。例如

Export-ModuleMember -Function Invoke-CustomUtil, Get-CustomInfo

公开共享模块选项 

PowerShell 模块 util 可以轻松公开模块在构建其参数规范时可以使用的通用模块选项。这允许将通用功能存储和维护在一个位置，并让多个模块以最小的工作量使用这些功能。添加到其中一个 util 的任何新功能或错误修复将自动用于调用该 util 的各种模块。

例如，有一个模块 util 处理对 API 的身份验证和通信。多个模块可以使用此 util 公开一组通用模块选项，例如 API 端点、用户名、密码、超时、证书验证等等，而无需将这些选项添加到每个模块规范中。

具有共享参数规范的模块 util 的标准约定是

一个 Get-<namespace.name.util name>Spec 函数，它输出模块的通用规范
- 强烈建议将此函数名设置为模块内唯一，以避免与可能加载的其他工具发生冲突。
- 输出规范的格式与用于普通模块的 $spec 相同，是一个哈希表。
该函数接受一个名为 AnsibleModule 的对象，作为 -Module 参数传递，它可以使用该对象获取共享选项。

由于这些选项可以在多个模块之间共享，因此强烈建议将共享规范中的模块选项名称和别名设置为尽可能具体。例如，不要使用名为 password 的工具选项，而应使用唯一名称作为前缀，例如 acme_password。

警告

如果选项名称或别名不唯一，则可能会阻止工具被使用这些名称或别名作为其自身选项的模块使用。

以下是一个名为 ServiceAuth.psm1 的模块工具示例，该工具位于一个集合中，实现了模块与服务进行身份验证的通用方式。

Invoke-MyServiceResource {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ValidateScript({ $_.GetType().FullName -eq 'Ansible.Basic.AnsibleModule' })]
        $Module,

        [Parameter(Mandatory=$true)]
        [String]
        $ResourceId,

        [String]
        $State = 'present'
    )

    # Process the common module options known to the util
    $params = @{
        ServerUri = $Module.Params.my_service_url
    }
    if ($Module.Params.my_service_username) {
        $params.Credential = Get-MyServiceCredential
    }

    if ($State -eq 'absent') {
        Remove-MyService @params -ResourceId $ResourceId
    } else {
        New-MyService @params -ResourceId $ResourceId
    }
}

Get-MyNamespaceMyCollectionServiceAuthSpec {
    # Output the util spec
    @{
        options = @{
            my_service_url = @{ type = 'str'; required = $true }
            my_service_username = @{ type = 'str' }
            my_service_password = @{ type = 'str'; no_log = $true }
        }

        required_together = @(
            ,@('my_service_username', 'my_service_password')
        )
    }
}

$exportMembers = @{
    Function = 'Get-MyNamespaceMyCollectionServiceAuthSpec', 'Invoke-MyServiceResource'
}
Export-ModuleMember @exportMembers

要使模块利用此通用参数规范，可以将其设置为以下方式。

#!powershell

# Include the module util ServiceAuth.psm1 from the my_namespace.my_collection collection
#AnsibleRequires -PowerShell ansible_collections.my_namespace.my_collection.plugins.module_utils.ServiceAuth

# Create the module spec like normal
$spec = @{
    options = @{
        resource_id = @{ type = 'str'; required = $true }
        state = @{ type = 'str'; choices = 'absent', 'present' }
    }
}

# Create the module from the module spec but also include the util spec to merge into our own.
$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec, @(Get-MyNamespaceMyCollectionServiceAuthSpec))

# Call the ServiceAuth module util and pass in the module object so it can access the module options.
Invoke-MyServiceResource -Module $module -ResourceId $module.Params.resource_id -State $module.params.state

$module.ExitJson()

注意

在模块规范中定义的选项始终优先于工具规范。工具规范中相同键下的任何列表值都将附加到该键的模块规范中。字典值将添加模块规范中缺少的任何键，并合并任何值为列表或字典的值。这与文档片段插件扩展模块文档的方式类似。

要为模块记录这些共享的工具选项，请创建一个文档片段插件，记录模块工具实现的选项，并为实现该工具的每个模块扩展模块文档，使其文档中包含该片段。

Windows playbook 模块测试 

可以使用 Ansible playbook 测试模块。例如

在任何目录中创建一个 playbook：touch testmodule.yml。
在同一目录中创建一个清单文件：touch hosts。
使用连接到 Windows 主机(s)所需的变量填充清单文件。
将以下内容添加到新的 playbook 文件中

---
- name: test out windows module
  hosts: windows
  tasks:
  - name: test out module
    win_module:
      name: test name

运行 playbook：ansible-playbook -i hosts testmodule.yml。

这对于查看 Ansible 如何使用新模块端到端运行非常有用。下面展示了其他可能用于测试模块的方法。

Windows 调试 

目前只能在 Windows 主机上调试模块。这在开发新模块或实施错误修复时非常有用。以下是设置此操作需要遵循的一些步骤。

将模块脚本复制到 Windows 服务器。
将文件夹 ./lib/ansible/module_utils/powershell 和 ./lib/ansible/module_utils/csharp 复制到与上述脚本相同的目录。
在模块代码中以 #Requires -Module 开头的任何行的开头添加一个额外的 #，这仅对于以 #Requires -Module 开头的任何行有效。
将以下内容添加到已复制到服务器上的模块脚本开头。

# Set $ErrorActionPreference to what's set during Ansible execution
$ErrorActionPreference = "Stop"

# Set the first argument as the path to a JSON file that contains the module args
$args = @("$($pwd.Path)\args.json")

# Or instead of an args file, set $complex_args to the pre-processed module args
$complex_args = @{
    _ansible_check_mode = $false
    _ansible_diff = $false
    path = "C:\temp"
    state = "present"
}

# Import any C# utils referenced with '#AnsibleRequires -CSharpUtil' or 'using Ansible.;
# The $_csharp_utils entries should be the context of the C# util files and not the path
Import-Module -Name "$($pwd.Path)\powershell\Ansible.ModuleUtils.AddType.psm1"
$_csharp_utils = @(
    [System.IO.File]::ReadAllText("$($pwd.Path)\csharp\Ansible.Basic.cs")
)
Add-CSharpType -References $_csharp_utils -IncludeDebugInfo

# Import any PowerShell modules referenced with '#Requires -Module`
Import-Module -Name "$($pwd.Path)\powershell\Ansible.ModuleUtils.Legacy.psm1"

# End of the setup code and start of the module code
#!powershell

可以根据模块需要向 $complex_args 添加更多参数，或者使用以下结构的 JSON 文件定义模块选项。

{
    "ANSIBLE_MODULE_ARGS": {
        "_ansible_check_mode": false,
        "_ansible_diff": false,
        "path": "C:\\temp",
        "state": "present"
    }
}

可以使用多种 IDE 来调试 Powershell 脚本，其中最流行的两个是

要查看 Ansible 传递给模块的参数，请执行以下步骤。

在 Ansible 命令之前添加 ANSIBLE_KEEP_REMOTE_FILES=1，以指定 Ansible 应该保留服务器上的 exec 文件。
使用 Ansible 用于执行模块的同一用户帐户登录 Windows 服务器。
导航到 %TEMP%\..。它应该包含一个以 ansible-tmp- 开头的文件夹。
在此文件夹中，打开模块的 PowerShell 脚本。
在此脚本中，有一个名为 $json_raw 的原始 JSON 脚本，其中包含 module_args 下的模块参数。这些参数可以手动分配给调试脚本中定义的 $complex_args 变量，或者放入 args.json 文件中。

Windows 单元测试 

目前，没有机制可以在 Ansible CI 下为 Powershell 模块运行单元测试。

Windows 集成测试 

Ansible 模块的集成测试通常以 Ansible 角色的形式编写。这些测试角色位于 ./test/integration/targets 中。您必须首先设置测试环境，并为 Ansible 连接配置测试清单。

在本例中，我们将设置一个测试清单，以连接到两个主机并运行 win_stat 的集成测试。

运行命令 source ./hacking/env-setup 来准备环境。
创建 ./test/integration/inventory.winrm.template 的副本，并将其命名为 inventory.winrm。
填充 [windows] 下的条目，并设置连接到主机所需的变量。
安装支持 WinRM 的必要 Python 模块以及配置的身份验证方法。
要执行集成测试，请运行 ansible-test windows-integration win_stat；可以使用 win_stat 替换要测试的角色。

这将执行当前为此角色定义的所有测试。可以使用 -v 参数设置详细程度，就像使用 ansible-playbook 一样。

在为新模块开发测试时，建议在检查模式下测试一个场景，并在非检查模式下测试两次。这确保检查模式不进行任何更改，但会报告更改，以及第二次运行是幂等的，并且不会报告更改。例如

- name: remove a file (check mode)
  win_file:
    path: C:\temp
    state: absent
  register: remove_file_check
  check_mode: true

- name: get result of remove a file (check mode)
  win_command: powershell.exe "if (Test-Path -Path 'C:\temp') { 'true' } else { 'false' }"
  register: remove_file_actual_check

- name: assert remove a file (check mode)
  assert:
    that:
    - remove_file_check is changed
    - remove_file_actual_check.stdout == 'true\r\n'

- name: remove a file
  win_file:
    path: C:\temp
    state: absent
  register: remove_file

- name: get result of remove a file
  win_command: powershell.exe "if (Test-Path -Path 'C:\temp') { 'true' } else { 'false' }"
  register: remove_file_actual

- name: assert remove a file
  assert:
    that:
    - remove_file is changed
    - remove_file_actual.stdout == 'false\r\n'

- name: remove a file (idempotent)
  win_file:
    path: C:\temp
    state: absent
  register: remove_file_again

- name: assert remove a file (idempotent)
  assert:
    that:
    - not remove_file_again is changed

Windows 通信和开发支持 

加入 Ansible 论坛，并使用 windows 标记来讨论关于 Windows 的 Ansible 开发。