Windows: Add-Warning() and Add-DeprecationWarning() (#20903)

* Windows: Add Warn() and Deprecate() mechanisms

Similar to what already exists for python modules.

* Turn deprecations from list of strings, to list of dicts

Since #20884 the internal representations of deprecation messages is
changed from a list of strings to a list of dicts.

* Rename to Add-Warning() and Add-DeprecationWarning()

Implemented as discussed.

lib/ansible/module_utils/powershell.ps1

@@ -98,6 +98,46 @@ Function Fail-Json($obj, $message = $null)
     Exit 1
 }
 
+# Helper function to add warnings, even if the warnings attribute was
+# not already set up. This is a convenience for the module developer
+# so he does not have to check for the attribute prior to adding.
+Function Add-Warning($obj, $message)
+{
+    if (Get-Member -InputObject $obj -Name "warnings") {
+        if ($obj.warnings -is [System.Array]) {
+            $obj.warnings += $message
+        } else {
+            throw "warnings attribute is not an array"
+        }
+    } else {
+        $obj.warnings = ,@( $message )
+    }
+}
+
+# Helper function to add deprecations, even if the deprecations attribute was
+# not already set up. This is a convenience for the module developer
+# so he does not have to check for the attribute prior to adding.
+Function Add-DeprecationWarning($obj, $message, $version = $null)
+{
+    if (Get-Member -InputObject $obj -Name "deprecations") {
+        if ($obj.deprecations -is [System.Array]) {
+            $obj.deprecations += @{
+                msg = $message
+                version = $version
+            }
+        } else {
+            throw "deprecations attribute is not a list"
+        }
+    } else {
+        $obj.deprecations = ,@(
+            @{
+                msg = $message
+                version = $version
+            }
+        )
+    }
+}
+
 Function Expand-Environment($value)
 {
     [System.Environment]::ExpandEnvironmentVariables($value)