win_timezone - Upgrade to Ansible.Basic style #705
Conversation
Upgrades the win_timzone module to the Ansible.Basic style module. This cleans up the older legacy module_util code and aligns it with the newer standards we try to write new modules in.
| @@ -3,71 +3,75 @@ | |||
| # Copyright: (c) 2015, Phil Schwartz <[email protected]> | |||
| # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) | |||
|
|
|||
| #Requires -Module Ansible.ModuleUtils.Legacy | |||
| #AnsibleRequires -CSharpUtil Ansible.Basic | |||
There was a problem hiding this comment.
This newer requires statement is used by Ansible to load in the Ansible.Basic C# module util.
| $spec = @{ | ||
| options = @{ | ||
| timezone = @{ | ||
| required = $true | ||
| type = "str" | ||
| } | ||
| } | ||
| supports_check_mode = $true | ||
| } | ||
|
|
||
| $timezone = Get-AnsibleParam -obj $params -name "timezone" -type "str" -failifempty $true | ||
| $module = [Ansible.Basic.AnsibleModule]::Create($args, $spec) | ||
|
|
||
| $result = @{ | ||
| changed = $false | ||
| previous_timezone = $timezone | ||
| timezone = $timezone | ||
| } | ||
| $timezone = $module.Params.timezone |
There was a problem hiding this comment.
Instead of using Parse-Args and Get-AnsibleParam we define the argument spec inside a hashtable, create the module object, then retrieve the module options through $module.Params.x. The $spec is the module option specification and this module only has 1 option called timezone that is required and is typed as a string.
We also explicitly have to opt into saying we support check mode with supports_check_mode = $true in the root of the spec hashtable. Without this the module will be skipped when running under check mode.
| $module.Result.previous_timezone = $null | ||
| $module.Result.timezone = $timezone |
There was a problem hiding this comment.
The module result is located under $module.Result. We assign the return values accordingly.
| } | ||
|
|
||
| # Get the current timezone set | ||
| $previousTz = Invoke-TzUtil /g -Module $module -Action "getting the current machine's timezone setting" |
There was a problem hiding this comment.
The Invoke-TzUtil is merely a helper function and isn't strictly related to using the Ansible.Basic style. I just saw this module called tzutil.exe multiple times and was checking the result before failing if it wasn't 0. So instead of duplicating those checks I put it in one function and have that handle all the error handling.
| $Module.Result.stdout = $stdout -join "`n" | ||
| $Module.Result.stderr = $stderr -join "`n" | ||
| $Module.Result.rc = $LASTEXITCODE | ||
| $Module.FailJson("An error occurred when $Action.") |
There was a problem hiding this comment.
Instead of Fail-Json $result "msg" we now do $module.FailJson("msg"). The result is already stored in the module object so we just need to supply the error message to fail with.
$module.FailJson() will automatically exit the module and set it as failed.
| $previousTz = Invoke-TzUtil /g -Module $module -Action "getting the current machine's timezone setting" | ||
| $module.Result.previous_timezone = $previousTz | ||
|
|
||
| if ($module.DiffMode) { |
There was a problem hiding this comment.
We use $module.DiffMode to check if --diff is enabled for the task. This isn't strictly necessary but it avoids sending extra data back to Ansible.
| $module.Diff.before = "$previousTz`n" | ||
| $module.Diff.after = "$timezone`n" |
There was a problem hiding this comment.
Instead of diff being part of the result, it's stored under a specific property $module.Diff. The structure is the same as before where we typically return a before and after with the changes involved.
| $module.FailJson("The specified timezone: $timezone isn't supported on the machine.") | ||
| } | ||
|
|
||
| if (-not $module.CheckMode) { |
There was a problem hiding this comment.
$module.CheckMode is a boolean that is true when we are running in check mode. Basically we want to avoid making any actual changes while in check mode.
| } | ||
|
|
||
| Exit-Json $result | ||
| $module.ExitJson() |
There was a problem hiding this comment.
Instead of Exit-Json $result we just do $module.ExitJson(). The result is already stored on the $module object so we don't have to provide it separately. This will stop the module and return the data in the result.
SUMMARY
Upgrades the win_timzone module to the Ansible.Basic style module. This cleans up the older legacy module_util code and aligns it with the newer standards we try to write new modules in.
ISSUE TYPE
COMPONENT NAME
win_timezone
ADDITIONAL INFORMATION
Typically I would have to create a changelog fragment for this change but as this is a new module that has not been released yet there are no public facing changes for users so it does not need one.