Windows 模块开发流程

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

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

本节涵盖的内容

Windows 环境设置 

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

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

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

Vagrant
VirtualBox

在虚拟机中创建 Windows 服务器 

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

vagrant init jborean93/WindowsServer2016
vagrant up

这将从 Vagrant Cloud 下载 Vagrant box 并将其添加到您主机上的本地 box 中，然后在 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 的 box。

配置环境 

要配置环境，请运行以下命令

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")，可以将异常或 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 在严格模式版本 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 模块的最佳实践。它演示了如何实现检查模式和 diff 支持，还显示了在满足特定条件时向用户显示的警告。

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

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

mutually_exclusive：一个列表的列表，其中内部列表包含不能一起设置的模块选项
no_log：阻止模块向 Windows 事件日志发出任何日志
options：一个字典，其中键是模块选项，值是该选项的规范
required_by：一个字典，其中值指定的选项必须在键指定的选项也设置的情况下设置
required_if：一个列表的列表，其中内部列表包含 3 或 4 个元素；
- 第一个元素是用来检查值的模块选项
- 第二个元素是第一个元素指定的选项的值，如果匹配，则运行必需的 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，则该值为空。仅在用户未定义模块选项且 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 模块支持 #Requires 选项的少量子集，这些选项内置于 PowerShell 中，以及由 #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 被放置在一个名为 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 的各种模块使用。

这方面的一个例子是使用一个处理对 API 的身份验证和通信的模块 util。此 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 剧本模块测试 

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

在任何目录中创建一个剧本 touch testmodule.yml。
在同一个目录中创建一个库存文件 touch hosts。
使用连接到 Windows 主机所需变量填充库存文件。
将以下内容添加到新的剧本文件中

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

运行剧本 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 应该保留服务器上的执行文件。
使用 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 开发。