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

在虚拟机中创建 Windows 服务器

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

vagrant init jborean93/WindowsServer2016
vagrant up

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

创建 Ansible 清单

以下 Ansible 清单文件可用于连接到新创建的 Windows 虚拟机：

[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 将自动随机使用另一个端口并在输出中显示。

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

• jborean93/WindowsServer2012

• jborean93/WindowsServer2012R2

• jborean93/WindowsServer2016

• jborean93/WindowsServer2019

• jborean93/WindowsServer2022

主机上线后，可以通过 127.0.0.1:3389 上的 RDP 访问它，但端口可能会因冲突而有所不同。要删除主机，请运行 vagrant destroy --force，Vagrant 将自动删除虚拟机和与该虚拟机关联的任何其他文件。

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

• Vagrantfile：读取 inventory.yml 的清单设置并配置所需主机的 Vagrant 文件

• inventory.yml：包含所需的主机和其他连接信息，例如 IP 地址和转发端口

• main.yml：Vagrant 调用的 Ansible playbook，用于配置域控制节点并将子主机加入域

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

• 在 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 是将用于创建虚拟机的镜像。

环境配置

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

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")，可以将 Exception 或 ErrorRecord 设置为第二个参数以获得更详细的错误消息。

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

一个稍微高级一点的模块是 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，则为 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提供的函数或类型是否存在来完成。

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

C#模块util可以通过在脚本顶部添加using Ansible.<module_util>;行以及所有其他using语句来引用其他C# util。

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中定义的命名空间命名。

下面的示例是一个角色结构，其中包含两个PowerShell自定义module_util，名为Ansible.ModuleUtils.ModuleUtil1、Ansible.ModuleUtils.ModuleUtil2，以及一个包含命名空间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函数，该函数输出模块的通用规范

  • 强烈建议使此函数名称对于模块唯一，以避免与可以加载的其他util发生冲突

  • 输出规范的格式是哈希表，其格式与普通模块使用的$spec相同

• 一个函数，它接收一个名为-Module参数下的AnsibleModule对象，它可以使用该对象来获取共享选项

由于这些选项可以在多个模块之间共享，强烈建议在共享规范中尽可能具体地保留模块选项名称和别名。例如，不要使用名为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 规范中相同键下的任何列表值都将附加到该相同键的模块规范中。字典值将添加模块规范中缺少的任何键，并合并任何值为列表或字典的值。这类似于文档片段插件在扩展模块文档时的工作方式。

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

Windows playbook 模块测试

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

• 在任何目录中创建一个 playbook touch testmodule.yml。

• 在同一目录中创建一个清单文件 touch hosts。

• 使用连接到 Windows 主机所需的变量填充清单文件。

• 将以下内容添加到新的 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 脚本，其中最流行的两个是：

• PowerShell ISE

• Visual Studio Code

要能够查看 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]下的条目，并设置连接到主机所需的变量。

• 安装所需的 Python 模块以支持 WinRM 和已配置的身份验证方法。

• 要执行集成测试，请运行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 开发。