win_uri: module cleanup and added check-mode support (#20511)

The following changes have been made:
- Added check-mode support
- Added parameter type support
- Replace PSObject by a normal dictionary
- Improve idempotency (only when $dest is provided it is not idempotent (yet)

lib/ansible/modules/windows/win_uri.ps1

@@ -19,43 +19,44 @@
 # WANT_JSON
 # POWERSHELL_COMMON
 
-$params = Parse-Args $args;
-
-$result = New-Object psobject @{
-    win_uri = New-Object psobject
-}
+$ErrorActionPreference = "Stop"
 
 # Functions ###############################################
 
 Function ConvertTo-SnakeCase($input_string) {
     $snake_case = $input_string -csplit "(?<!^)(?=[A-Z])" -join "_"
-    $snake_case = $snake_case.ToLower()
-
-    return $snake_case
+    return $snake_case.ToLower()
 }
 
 # Build Arguments
-$webrequest_opts = @{}
-
-$url = Get-AnsibleParam -obj $params -name "url" -failifempty $true
-$method = Get-AnsibleParam -obj $params "method" -default "GET"
-$content_type = Get-AnsibleParam -obj $params -name "content_type"
-$headers = Get-AnsibleParam -obj $params -name "headers"
-$body = Get-AnsibleParam -obj $params -name "body"
-$dest = Get-AnsibleParam -obj $params -name "dest" -type "path" -default $null
-$use_basic_parsing = ConvertTo-Bool (Get-AnsibleParam -obj $params -name "use_basic_parsing" -default $true)
-
-$webrequest_opts.Uri = $url
-Set-Attr $result.win_uri "url" $url
-
-$webrequest_opts.Method = $method
-Set-Attr $result.win_uri "method" $method
-
-$webrequest_opts.ContentType = $content_type
-Set-Attr $result.win_uri "content_type" $content_type
+$params = Parse-Args $args -supports_check_mode $true
+
+$url = Get-AnsibleParam -obj $params -name "url" -type "string" -failifempty $true
+$method = Get-AnsibleParam -obj $params "method" -type "string" -default "GET" -validateset "GET","POST","PUT","HEAD","DELETE","OPTIONS","PATCH","TRACE","CONNECT","REFRESH"
+$content_type = Get-AnsibleParam -obj $params -name "content_type" -type "string"
+# TODO: Why is this not a normal dictionary ?
+$headers = Get-AnsibleParam -obj $params -name "headers" -type "string"
+# TODO: Why is this not a normal dictionary ?
+$body = Get-AnsibleParam -obj $params -name "body" -type "string"
+$dest = Get-AnsibleParam -obj $params -name "dest" -type "path"
+$use_basic_parsing = Get-AnsibleParam -obj $params -name "use_basic_parsing" -type "bool" -default $true
+
+$result = @{
+    changed = $false
+    win_uri = @{
+        content_type = $content_type
+        method = $method
+        url = $url
+        use_basic_parsing = $use_basic_parsing
+    }
+}
 
-$webrequest_opts.UseBasicParsing = $use_basic_parsing
-Set-Attr $result.win_uri "use_basic_parsing" $use_basic_parsing
+$webrequest_opts = @{
+    ContentType = $content_type
+    Method = $method
+    Uri = $url
+    UseBasicParsing = $use_basic_parsing
+}
 
 if ($headers -ne $null) {
     $req_headers = @{}
@@ -68,25 +69,31 @@ if ($headers -ne $null) {
 
 if ($body -ne $null) {
     $webrequest_opts.Body = $body
-    Set-Attr $result.win_uri "body" $body
+    $result.win_uri.body = $body
 }
 
 if ($dest -ne $null) {
     $webrequest_opts.OutFile = $dest
-    Set-Attr $result.win_uri "dest" $dest
+    $result.win_uri.dest = $dest
 }
 
-try {
-    $response = Invoke-WebRequest @webrequest_opts
-} catch {
-    $ErrorMessage = $_.Exception.Message
-    Fail-Json $result $ErrorMessage
+# TODO: When writing to a file, this is not idempotent !
+if ($check_mode -ne $true -or $dest -eq $null) {
+    try {
+        $response = Invoke-WebRequest @webrequest_opts
+    } catch {
+        Fail-Json $result $_.Exception.Message
+    }
+}
+
+# Assume a change when we are writing to a file
+if ($dest -ne $null) {
+    $result.changed = $true
 }
 
 ForEach ($prop in $response.psobject.properties) {
     $result_key = ConvertTo-SnakeCase $prop.Name
-    $result_value = $prop.Value
-    Set-Attr $result $result_key $result_value
+    $result.$result_key = $prop.Value
 }
 
 Exit-Json $result

lib/ansible/modules/windows/win_uri.py

@@ -36,6 +36,7 @@ options:
   url:
     description:
       - HTTP or HTTPS URL in the form of (http|https)://host.domain:port/path
+    required: True
   method:
     description:
       - The HTTP Method of the request or response.
@@ -61,7 +62,6 @@ options:
     version_added: "2.3"
     description:
       - Output the response body to a file.
-    default: None
   headers:
     description:
       - 'Key Value pairs for headers. Example "Host: www.somesite.com"'
@@ -84,19 +84,19 @@ EXAMPLES = r'''
 # Set a HOST header to hit an internal webserver:
 - name: Hit a Specific Host on the Server
   win_uri:
-    url: http://example.com
+    url: http://example.com/
     method: GET
     headers:
       host: www.somesite.com
 
 - name: Perform a HEAD on an Endpoint
   win_uri:
-    url: http://www.example.com
+    url: http://www.example.com/
     method: HEAD
 
 - name: POST a Body to an Endpoint
   win_uri:
-    url: http://www.somesite.com
+    url: http://www.somesite.com/
     method: POST
     body: "{ 'some': 'json' }"
 '''
@@ -106,17 +106,17 @@ url:
   description: The Target URL
   returned: always
   type: string
-  sample: "https://www.ansible.com"
+  sample: https://www.ansible.com
 method:
   description: The HTTP method used.
   returned: always
   type: string
-  sample: "GET"
+  sample: GET
 content_type:
   description: The "content-type" header used.
   returned: always
   type: string
-  sample: "application/json"
+  sample: application/json
 use_basic_parsing:
   description: The state of the "use_basic_parsing" flag.
   returned: always
@@ -137,7 +137,7 @@ status_description:
   description: A summery of the status.
   returned: success
   type: string
-  stample: "OK"
+  sample: OK
 raw_content:
   description: The raw content of the HTTP response.
   returned: success