Merge pull request #299 from kwirkykat/CleanRegistry

Upgrade the xRegistry resource to high quality

DSCResources/MSFT_xRegistryResource/MSFT_xRegistryResource.schema.mof

@@ -1,11 +1,11 @@
 [ClassVersion("1.0.0"), FriendlyName("xRegistry")] 
 class MSFT_xRegistryResource : OMI_BaseResource
 {
-  [Key] string Key;
-  [Key] string ValueName;
-  [Write] string ValueData[];
-  [Write,ValueMap{"String", "Binary", "DWord", "QWord", "MultiString", "ExpandString"},Values{"String", "Binary", "DWord", "QWord", "MultiString", "ExpandString"}] string ValueType;
-  [Write,ValueMap{"Present", "Absent"},Values{"Present", "Absent"}] string Ensure;
-  [Write] boolean Hex;
-  [Write] boolean Force;
+  [Key, Description("The path of the registry key to add, modify, or remove. This path must include the registry hive/drive.")] String Key;
+  [Key, Description("The name of the registry value. To add or remove a registry key, specify this property as an empty string without specifying ValueType or ValueData. To modify or remove the default value of a registry key, specify this property as an empty string while also specifying ValueType or ValueData.")] String ValueName;
+  [Write, Description("The data the specified registry key value should have as a string or an array of strings (MultiString only).")] String ValueData[];
+  [Write, Description("The type the specified registry key value should have."), ValueMap{"String", "Binary", "DWord", "QWord", "MultiString", "ExpandString"},Values{"String", "Binary", "DWord", "QWord", "MultiString", "ExpandString"}] String ValueType;
+  [Write, Description("Specifies whether or not the registry key or value should exist. To add or modify a registry key or value, set this property to Present. To remove a registry key or value, set the property to Absent."), ValueMap{"Present", "Absent"},Values{"Present", "Absent"}] String Ensure;
+  [Write, Description("Specifies whether or not the specified DWord or QWord registry key data is provided in a hexadecimal format. Not valid for types other than DWord and QWord. The default value is $false.")] Boolean Hex;
+  [Write, Description("Specifies whether or not to overwrite the specified registry key value if it already has a value or whether or not to delete a registry key that has subkeys. The default value is $false.")] Boolean Force;
 };

DSCResources/MSFT_xRegistryResource/en-US/MSFT_xRegistryResource.schema.mfl

@@ -1,16 +1,11 @@
-#pragma namespace("\\\\.\\root\\default")
-instance of __namespace{ name="MS_409";};
-#pragma namespace("\\\\.\\root\\default\\MS_409")
-
-[Description("This resource is used to perform Get, Set and Test operations on Windows Registry.") : Amended,AMENDMENT, LOCALE(0x0409)] 
+[Description("Provides a mechanism to manage registry keys and values on a target node.") : Amended,AMENDMENT, LOCALE("MS_409")] 
 class MSFT_xRegistryResource : OMI_BaseResource
 {
-  [Key,Description("Path of the registry key.\n") : Amended] string Key;
-  [Key,Description("Name of the registry key value.\n") : Amended] string ValueName;
-  [Description("Data of the registry key value.\n") : Amended] string ValueData[];
-  [Description("Type of the registry key data.\n") : Amended] string ValueType;
-  [Description("Enumerated value describing if the environment variable should exist on target machine.\nPresent {default}  \nAbsent   \n") : Amended] string Ensure;
-  [Description("Flag to identify Hex or Decimal values.\n") : Amended] boolean Hex;
-  [Description("Flag to specify forced execution.\n") : Amended] boolean Force;
+  [Key,Description("The path of the registry key to add, modify, or remove. This path must include the registry hive/drive.") : Amended] String Key;
+  [Key,Description("The name of the registry value. To add or remove a registry key, specify this property as an empty string without specifying ValueType or ValueData. To modify or remove the default value of a registry key, specify this property as an empty string while also specifying ValueType or ValueData.") : Amended] String ValueName;
+  [Description("The data the specified registry key value should have as a string or an array of strings (MultiString only).") : Amended] String ValueData[];
+  [Description("The type the specified registry key value should have.") : Amended] String ValueType;
+  [Description("Specifies whether or not the registry key or value should exist. To add or modify a registry key or value, set this property to Present. To remove a registry key or value, set the property to Absent.") : Amended] String Ensure;
+  [Description("Specifies whether or not the specified DWord or QWord registry key data is provided in a hexadecimal format. Not valid for types other than DWord and QWord. The default value is $false.") : Amended] Boolean Hex;
+  [Description("Specifies whether or not to overwrite the specified registry key value if it already has a value or whether or not to delete a registry key that has subkeys. The default value is $false.") : Amended] Boolean Force;
 };
-

DSCResources/MSFT_xRegistryResource/en-US/MSFT_xRegistryResource.strings.psd1

@@ -1,28 +1,38 @@
-# Localized    10/30/2015 03:58 AM (GMT)    303:4.80.0411     MSFT_xRegistryResource.strings.psd1
 # Localized resources for MSFT_xRegistryResource
 
 ConvertFrom-StringData @'
-###PSLOC
-ParameterValueInvalid=(ERROR) Parameter '{0}' has an invalid value '{1}' for type '{2}'
-InvalidPSDriveSpecified=(ERROR) Invalid PSDrive '{0}' specified in registry key '{1}'
-InvalidRegistryHiveSpecified=(ERROR) Invalid registry hive was specified in registry key '{0}'
-SetRegValueFailed=(ERROR) Failed to set registry key value '{0}' to value '{1}' of type '{2}'
-SetRegValueUnchanged=(UNCHANGED) No change to registry key value '{0}' containing '{1}'
-SetRegKeyUnchanged=(UNCHANGED) No change to registry key '{0}'
-SetRegValueSucceeded=(SET) Set registry key value '{0}' to '{1}' of type '{2}'
-SetRegKeySucceeded=(SET) Create registry key '{0}'
-SetRegKeyFailed=(ERROR) Failed to created registry key '{0}'
-RemoveRegKeyTreeFailed=(ERROR) Registry Key '{0}' has subkeys, cannot remove without Force flag
-RemoveRegKeySucceeded=(REMOVAL) Registry key '{0}' removed
-RemoveRegKeyFailed=(ERROR) Failed to remove registry key '{0}'
-RemoveRegValueSucceeded=(REMOVAL) Registry key value '{0}' removed
-RemoveRegValueFailed=(ERROR) Failed to remove registry key value '{0}'
-RegKeyDoesNotExist=Registry key '{0}' does not exist
-RegKeyExists=Registry key '{0}' exists
-RegValueExists=Found registry key value '{0}' with type '{1}' and data '{2}'
-RegValueDoesNotExist=Registry key value '{0}' does not exist
-RegValueTypeMismatch=Registry key value '{0}' of type '{1}' does not exist
-RegValueDataMismatch=Registry key value '{0}' of type '{1}' does not contain data '{2}'
-DefaultValueDisplayName=(Default)
-###PSLOC
+    DefaultValueDisplayName = (Default)
+
+    GetTargetResourceStartMessage = Get-TargetResource is starting for Registry resource with Key {0}
+    GetTargetResourceEndMessage = Get-TargetResource has finished for Registry resource with Key {0}
+    RegistryKeyDoesNotExist = The registry key at path {0} does not exist.
+    RegistryKeyExists = The registry key at path {0} exists.
+    RegistryKeyValueDoesNotExist = The registry key at path {0} does not have a value named {1}.
+    RegistryKeyValueExists = The registry key at path {0} has a value named {1}.
+
+    SetTargetResourceStartMessage = Set-TargetResource is starting for Registry resource with Key {0}
+    SetTargetResourceEndMessage = Set-TargetResource has finished for Registry resource with Key {0}
+    CreatingRegistryKey = Creating registry key at path {0}...
+    SettingRegistryKeyValue = Setting the value {0} under the registry key at path {1}...
+    OverwritingRegistryKeyValue = Overwriting the value {0} under the registry key at path {1}...
+    RemovingRegistryKey = Removing registry key at path {0}...
+    RegistryKeyValueAlreadySet = The value {0} under the registry key at path {1} has already been set to the specified value.
+    RemovingRegistryKeyValue = Removeing the value {0} from the registry key at path {1}...
+
+    TestTargetResourceStartMessage = Test-TargetResource is starting for Registry resource with Key {0}
+    TestTargetResourceEndMessage = Test-TargetResource has finished for Registry resource with Key {0}
+    RegistryKeyValueTypeDoesNotMatch = The type of the value {0} under the registry key at path {1} does not match the expected type. Expected {2} but was {3}.
+    RegistryKeyValueDoesNotMatch = The value {0} under the registry key at path {1} does not match the expected value. Expected {2} but was {3}.
+
+    CannotRemoveExistingRegistryKeyWithSubKeysWithoutForce = The registry key at path {0} has subkeys. To remove this registry key please specifiy the Force parameter as $true.
+    CannotOverwriteExistingRegistryKeyValueWithoutForce = The registry key at path {0} already has a value with the name {1}. To overwrite this registry key value please specifiy the Force parameter as $true.
+    CannotRemoveExistingRegistryKeyValueWithoutForce = The registry key at path {0} already has a value with the name {1}. To remove this registry key value please specifiy the Force parameter as $true.
+    RegistryDriveInvalid = The registry drive specified in the registry key path {0} is missing or invalid.
+    ArrayNotAllowedForExpectedType = The specified value data has been declared as a string array, but the registry key type {0} cannot be converted from an array. Please declare the value data as only one string or use the registry type MultiString.
+    DWordDataNotInHexFormat = The specified registry key value data {0} is not in the correct hex format to parse as an Int32 (dword).
+    QWordDataNotInHexFormat = The specified registry key value data {0} is not in the correct hex format to parse as an Int64 (qword). 
+    BinaryDataNotInHexFormat = The specified registry key value data {0} is not in the correct hex format to parse as a Byte array (Binary).
+    InvalidRegistryDrive = The registry drive {0} is invalid. Please update the Key parameter to include a valid registry drive.
+    InvalidRegistryDriveAbbreviation = The registry drive abbreviation {0} is invalid. Please update the Key parameter to include a valid registry drive.
+    RegistryDriveCouldNotBeMounted = The registry drive with the abbreviation {0} could not be mounted.
 '@

DSCResources/MSFT_xWindowsProcess/MSFT_xWindowsProcess.psm1

@@ -685,17 +685,22 @@ function Get-ProcessOwner
         $Process
     )
 
-    $owner = Get-ProcessOwnerCimInstance -Process $Process
+    $owner = Get-ProcessOwnerCimInstance -Process $Process -ErrorAction 'SilentlyContinue'
 
-    if ($null -ne $owner.Domain)
+    if ($null -ne $owner)
     {
-        return ($owner.Domain + '\' + $owner.User)
-    }
-    else
-    {
-        # return the default domain
-        return ($env:computerName + '\' + $owner.User)
+        if ($null -ne $owner.Domain)
+        {
+            return ($owner.Domain + '\' + $owner.User)
+        }
+        else
+        {
+            # return the default domain
+            return ($env:computerName + '\' + $owner.User)
+        }
     }
+
+    return ''
 }
 
 <#
@@ -721,7 +726,7 @@ function Get-ProcessOwnerCimInstance
         $Process
     )
 
-    return Invoke-CimMethod -InputObject $Process -MethodName 'GetOwner'
+    return Invoke-CimMethod -InputObject $Process -MethodName 'GetOwner' -ErrorAction 'SilentlyContinue'
 }
 
 <#

Examples/Sample_xRegistryResource_AddKey.ps1

@@ -0,0 +1,19 @@
+<#
+    .SYNOPSIS
+        Create a new registry key called MyNewKey as a subkey under the key
+        'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'.
+#>
+Configuration Sample_xRegistryResource_AddKey
+{
+    Import-DscResource -ModuleName 'xPSDesiredStateConfiguration'
+
+    Node localhost
+    {
+        xRegistry Registry1
+        {
+            Key = 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey'
+            Ensure = 'Present'
+            ValueName = ''
+        }
+    }
+}

Examples/Sample_xRegistryResource_AddOrModifyValue.ps1

@@ -0,0 +1,27 @@
+<#
+    .SYNOPSIS
+        If the registry key value MyValue under the key
+        'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment' does not exist,
+        creates it with the Binary value 0.
+
+        If the registry key value MyValue under the key
+        'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment' already exists,
+        overwrites it with the Binary value 0.
+#>
+Configuration Sample_xRegistryResource_AddOrModifyValue
+{
+    Import-DscResource -ModuleName 'xPSDesiredStateConfiguration'
+
+    Node localhost
+    {
+        xRegistry Registry1
+        {
+            Key = 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'
+            Ensure = 'Present'
+            ValueName = 'MyValue'
+            ValueType = 'Binary'
+            ValueData = '0x00'
+            Force = $true
+        }
+    }
+}

Examples/Sample_xRegistryResource_RemoveKey.ps1

@@ -0,0 +1,19 @@
+<#
+    .SYNOPSIS
+        Removes the registry key called MyNewKey under the parent key
+        'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'.
+#>
+Configuration Sample_xRegistryResource_RemoveKey
+{
+    Import-DscResource -ModuleName 'xPSDesiredStateConfiguration'
+
+    Node localhost
+    {
+        xRegistry Registry1
+        {
+            Key = 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\MyNewKey'
+            Ensure = 'Absent'
+            ValueName = ''
+        }
+    }
+}

Examples/Sample_xRegistryResource_RemoveValue.ps1

@@ -0,0 +1,19 @@
+<#
+    .SYNOPSIS
+        Removes the registry key value MyValue from the key
+        'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'.
+#>
+Configuration Sample_xRegistryResource_RemoveValue
+{
+    Import-DscResource -ModuleName 'xPSDesiredStateConfiguration'
+
+    Node localhost
+    {
+        xRegistry Registry1
+        {
+            Key = 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'
+            Ensure = 'Absent'
+            ValueName = 'MyValue'
+        }
+    }
+}