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 将在侦听器上线后完成其过程，之后 VM 可以被 Ansible 使用。

创建 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 上的 HTTPS WinRM 通过端口 29804 转发，因为它是在 domain_children 中的第四个条目。

Windows 新模块开发 

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

模块代码位于 Powershell (.ps1) 文件中，而文档包含在同名 Python (.py) 文件中
避免在模块中使用 Write-Host/Debug/Verbose/Error，并将需要返回的内容添加到 $module.Result 变量
要使模块失败，请调用 $module.FailJson("failure message here")，可以将异常或 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 模块的最佳实践。它演示了如何实现检查模式和差异支持，以及在满足特定条件时向用户显示警告。

一个稍微高级的模块是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：模块是否支持检查模式，默认情况下为$false。

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

aliases：模块选项的别名列表。
choices：模块选项的有效值列表，如果type=list，则每个列表值都根据选择进行验证，而不是列表本身。
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 中提供辅助函数。这些 module_utils 可以通过在 PowerShell 模块中添加以下行来导入。

#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 中。这些 module_utils 可以通过在 PowerShell 模块中添加以下行来导入。

#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 放在名为 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 的函数，用于输出模块的通用规范。
- 强烈建议使该函数名称在模块中保持唯一，以避免与其他可能加载的 util 发生冲突。
- 输出规范的格式是一个哈希表，与普通模块使用的 $spec 格式相同。
一个函数，接收一个名为 AnsibleModule 的对象，在 -Module 参数下调用，用于获取共享选项。

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

警告

如果选项名称或别名不唯一，可能会导致该 util 无法被也使用这些名称或别名的模块使用。

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

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()

注意

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

为了为模块记录这些共享的 util 选项，请创建一个 doc 片段插件，它记录模块 util 实现的选项，并扩展实现该 util 的每个模块的模块文档，以将其包含在文档中。

Windows playbook 模块测试 

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

在任意目录中创建一个 playbook touch testmodule.yml。
在同一个目录中创建一个 inventory 文件 touch hosts。
用连接到 Windows 主机所需的变量填充 inventory 文件。
将以下内容添加到新的 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_KEEP_REMOTE_FILES=1 作为 Ansible 命令的前缀，以指定 Ansible 应该保留服务器上的执行文件。
使用 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 配置一个测试 inventory 以连接到它。

在这个例子中，我们将设置一个测试 inventory 来连接到两个主机并运行 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 标签来讨论 Ansible 对 Windows 的开发。