Modules/DscResource.Common/0.17.0/en-US/DscResource.Common-help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Assert-BoundParameter</command:name> <command:verb>Assert</command:verb> <command:noun>BoundParameter</command:noun> <maml:description> <maml:para>Throws an error if there is a bound parameter that exists in both the mutually exclusive lists.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This command asserts passed parameters. It takes a hashtable, normally `$PSBoundParameters`. There are two parameter sets for this command.</maml:para> <maml:para>>There is no built in logic to validate against parameters sets for DSC >so this can be used instead to validate the parameters that were set in >the configuration. MutuallyExclusiveParameters This parameter set takes two mutually exclusive lists of parameters. If any of the parameters in the first list are specified, none of the parameters in the second list can be specified. RequiredParameter Assert that required parameters has been specified, and throws an exception if not. Optionally it can be specified that parameters are only required if a specific parameter has been passed.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Assert-BoundParameter</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BoundParameterList</maml:name> <maml:description> <maml:para>The parameters that should be evaluated against the mutually exclusive lists MutuallyExclusiveList1 and MutuallyExclusiveList2. This parameter is normally set to the $PSBoundParameters variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IfParameterPresent</maml:name> <maml:description> <maml:para>One or more parameter names that if specified will trigger the evaluation. If neither of the parameter names has been specified the evaluation of required parameters are not made.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RequiredParameter</maml:name> <maml:description> <maml:para>One or more parameter names that is required to have been specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Assert-BoundParameter</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BoundParameterList</maml:name> <maml:description> <maml:para>The parameters that should be evaluated against the mutually exclusive lists MutuallyExclusiveList1 and MutuallyExclusiveList2. This parameter is normally set to the $PSBoundParameters variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MutuallyExclusiveList1</maml:name> <maml:description> <maml:para>An array of parameter names that are not allowed to be bound at the same time as those in MutuallyExclusiveList2.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MutuallyExclusiveList2</maml:name> <maml:description> <maml:para>An array of parameter names that are not allowed to be bound at the same time as those in MutuallyExclusiveList1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BoundParameterList</maml:name> <maml:description> <maml:para>The parameters that should be evaluated against the mutually exclusive lists MutuallyExclusiveList1 and MutuallyExclusiveList2. This parameter is normally set to the $PSBoundParameters variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IfParameterPresent</maml:name> <maml:description> <maml:para>One or more parameter names that if specified will trigger the evaluation. If neither of the parameter names has been specified the evaluation of required parameters are not made.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MutuallyExclusiveList1</maml:name> <maml:description> <maml:para>An array of parameter names that are not allowed to be bound at the same time as those in MutuallyExclusiveList2.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MutuallyExclusiveList2</maml:name> <maml:description> <maml:para>An array of parameter names that are not allowed to be bound at the same time as those in MutuallyExclusiveList1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RequiredParameter</maml:name> <maml:description> <maml:para>One or more parameter names that is required to have been specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$assertBoundParameterParameters = @{ BoundParameterList = $PSBoundParameters MutuallyExclusiveList1 = @( 'Parameter1' ) MutuallyExclusiveList2 = @( 'Parameter2' ) } Assert-BoundParameter @assertBoundParameterParameters</dev:code> <dev:remarks> <maml:para>This example throws an exception if `$PSBoundParameters` contains both the parameters `Parameter1` and `Parameter2`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange')</dev:code> <dev:remarks> <maml:para>Throws an exception if either of the two parameters are not specified.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('Property2', 'Property3') -IfParameterPresent @('Property1')</dev:code> <dev:remarks> <maml:para>Throws an exception if the parameter 'Property1' is specified and either of the required parameters are not.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Assert-ElevatedUser</command:name> <command:verb>Assert</command:verb> <command:noun>ElevatedUser</command:noun> <maml:description> <maml:para>Assert that the user has elevated the PowerShell session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Assert that the user has elevated the PowerShell session. The command will throw a statement-terminating error if the script is not run from an elevated session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Assert-ElevatedUser</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Assert-ElevatedUser</dev:code> <dev:remarks> <maml:para>Throws an exception if the user has not elevated the PowerShell session.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>`Assert-ElevatedUser -ErrorAction 'Stop'`</dev:code> <dev:remarks> <maml:para>This example stops the entire script if it is not run from an elevated PowerShell session.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Assert-IPAddress</command:name> <command:verb>Assert</command:verb> <command:noun>IPAddress</command:noun> <maml:description> <maml:para>Asserts if the IP Address is valid and optionally validates the IP Address against an Address Family.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Checks the IP address so that it is valid and do not conflict with address family. If any problems are detected an exception will be thrown.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Assert-IPAddress</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>AddressFamily</maml:name> <maml:description> <maml:para>IP address family that the supplied Address should be in. Valid values are 'IPv4' or 'IPv6'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Address</maml:name> <maml:description> <maml:para>Specifies an IPv4 or IPv6 address.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Address</maml:name> <maml:description> <maml:para>Specifies an IPv4 or IPv6 address.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>AddressFamily</maml:name> <maml:description> <maml:para>IP address family that the supplied Address should be in. Valid values are 'IPv4' or 'IPv6'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Assert-IPAddress -Address '127.0.0.1'</dev:code> <dev:remarks> <maml:para>This will assert that the supplied address is a valid IPv4 address. If it is not an exception will be thrown.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Assert-IPAddress -Address 'fe80:ab04:30F5:002b::1'</dev:code> <dev:remarks> <maml:para>This will assert that the supplied address is a valid IPv6 address. If it is not an exception will be thrown.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Assert-IPAddress -Address 'fe80:ab04:30F5:002b::1' -AddressFamily 'IPv6'</dev:code> <dev:remarks> <maml:para>This will assert that address is valid and that it matches the supplied address family. If the supplied address family does not match the address an exception will be thrown.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Assert-Module</command:name> <command:verb>Assert</command:verb> <command:noun>Module</command:noun> <maml:description> <maml:para>Assert if the specific module is available to be imported and optionally import the module.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Assert if the specific module is available to be imported and optionally import the module.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Assert-Module</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ModuleName</maml:name> <maml:description> <maml:para>Specifies the name of the module to assert.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Specifies to forcibly import the module even if it is already in the session. This parameter is ignored unless parameter `ImportModule` is also used.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ImportModule</maml:name> <maml:description> <maml:para>Specifies to import the module if it is asserted.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Specifies to forcibly import the module even if it is already in the session. This parameter is ignored unless parameter `ImportModule` is also used.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ImportModule</maml:name> <maml:description> <maml:para>Specifies to import the module if it is asserted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ModuleName</maml:name> <maml:description> <maml:para>Specifies the name of the module to assert.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Assert-Module -ModuleName 'DhcpServer'</dev:code> <dev:remarks> <maml:para>This asserts that the module DhcpServer is available on the system. If it is not an exception will be thrown.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Assert-Module -ModuleName 'DhcpServer' -ImportModule</dev:code> <dev:remarks> <maml:para>This asserts that the module DhcpServer is available on the system and imports it. If the module is not available an exception will be thrown.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Assert-Module -ModuleName 'DhcpServer' -ImportModule -Force</dev:code> <dev:remarks> <maml:para>This asserts that the module DhcpServer is available on the system and it will be forcibly imported into the session (even if it was already in the session). If the module is not available an exception will be thrown.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Compare-DscParameterState</command:name> <command:verb>Compare</command:verb> <command:noun>DscParameterState</command:noun> <maml:description> <maml:para>This method is used to compare current and desired values for any DSC resource.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function compare the parameter status of DSC resource parameters against the current values present on the system, and return a hashtable with the metadata from the comparison.</maml:para> <maml:para>>[!NOTE] >The content of the function `Test-DscParameterState` has been extracted and now >`Test-DscParameterState` is just calling `Compare-DscParameterState`. >This function can be used in a DSC resource from the Get function/method.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Compare-DscParameterState</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>CurrentValues</maml:name> <maml:description> <maml:para>A hashtable with the current values on the system, obtained by e.g. Get-TargetResource.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DesiredValues</maml:name> <maml:description> <maml:para>The hashtable of desired values. For example $PSBoundParameters with the desired values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="ValuesToCheck"> <maml:name>Properties</maml:name> <maml:description> <maml:para>This is a list of properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>ExcludeProperties</maml:name> <maml:description> <maml:para>This is a list of which properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeInDesiredState</maml:name> <maml:description> <maml:para>Indicates that result adds the properties in the desired state. By default, this command returns only the properties not in desired state.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeValue</maml:name> <maml:description> <maml:para>Indicates that result contains the ActualValue and ExpectedValue properties.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ReverseCheck</maml:name> <maml:description> <maml:para>Indicates that a reverse check should be done. The current and desired state are swapped for another test.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SortArrayValues</maml:name> <maml:description> <maml:para>If the sorting of array values does not matter, values are sorted internally before doing the comparison.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TurnOffTypeChecking</maml:name> <maml:description> <maml:para>Indicates that the type of the parameter should not be checked.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>CurrentValues</maml:name> <maml:description> <maml:para>A hashtable with the current values on the system, obtained by e.g. Get-TargetResource.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DesiredValues</maml:name> <maml:description> <maml:para>The hashtable of desired values. For example $PSBoundParameters with the desired values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>ExcludeProperties</maml:name> <maml:description> <maml:para>This is a list of which properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeInDesiredState</maml:name> <maml:description> <maml:para>Indicates that result adds the properties in the desired state. By default, this command returns only the properties not in desired state.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeValue</maml:name> <maml:description> <maml:para>Indicates that result contains the ActualValue and ExpectedValue properties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="ValuesToCheck"> <maml:name>Properties</maml:name> <maml:description> <maml:para>This is a list of properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ReverseCheck</maml:name> <maml:description> <maml:para>Indicates that a reverse check should be done. The current and desired state are swapped for another test.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SortArrayValues</maml:name> <maml:description> <maml:para>If the sorting of array values does not matter, values are sorted internally before doing the comparison.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TurnOffTypeChecking</maml:name> <maml:description> <maml:para>Indicates that the type of the parameter should not be checked.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object[]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Returns an array containing a PSCustomObject with metadata for each property that was evaluated.</maml:para> <maml:para>Metadata Name | Type | Description --- | --- | --- Property | `[System.String]` | The name of the property that was evaluated InDesiredState | `[System.Boolean]` | Returns `$true` if the expected and actual value was equal. ExpectedType | `[System.String]` | Return the type of desired object. ActualType | `[System.String]` | Return the type of current object. ExpectedValue | `[System.PsObject]` | Return the value of expected object. ActualValue | `[System.PsObject]` | Return the value of current object.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$currentValues = @{ String = 'This is a string' Int = 1 Bool = $true } $desiredValues = @{ String = 'This is a string' Int = 99 } Compare-DscParameterState -CurrentValues $currentValues -DesiredValues $desiredValues</dev:code> <dev:remarks> <maml:para>The function Compare-DscParameterState compare the value of each hashtable based on the keys present in $desiredValues hashtable. The result indicates that Int property is not in the desired state. No information about Bool property, because it is not in $desiredValues hashtable.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$currentValues = @{ String = 'This is a string' Int = 1 Bool = $true } $desiredValues = @{ String = 'This is a string' Int = 99 Bool = $false } $excludeProperties = @('Bool') Compare-DscParameterState ` -CurrentValues $currentValues ` -DesiredValues $desiredValues ` -ExcludeProperties $ExcludeProperties</dev:code> <dev:remarks> <maml:para>The function Compare-DscParameterState compare the value of each hashtable based on the keys present in $desiredValues hashtable and without those in $excludeProperties. The result indicates that Int property is not in the desired state. No information about Bool property, because it is in $excludeProperties.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>$serviceParameters = @{ Name = $Name } $returnValue = Compare-DscParameterState ` -CurrentValues (Get-Service @serviceParameters) ` -DesiredValues $PSBoundParameters ` -Properties @( 'Name' 'Status' 'StartType' )</dev:code> <dev:remarks> <maml:para>This compares the values in the current state against the desires state. The command Get-Service is called using just the required parameters to get the values in the current state. The parameter 'Properties' is used to specify the properties 'Name','Status' and 'StartType' for the comparison.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Compare-ResourcePropertyState</command:name> <command:verb>Compare</command:verb> <command:noun>ResourcePropertyState</command:noun> <maml:description> <maml:para>Compare current and desired property values for any DSC resource and return a hashtable with the metadata from the comparison.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function is used to compare current and desired property values for any DSC resource, and return a hashtable with the metadata from the comparison.</maml:para> <maml:para>This introduces another design pattern that is used to evaluate current and desired state in a DSC resource. This command is meant to be used in a DSC resource from both Test and Set . The evaluation is made in Set to make sure to only change the properties that are not in the desired state. Properties that are in the desired state should not be changed again. This design pattern also handles when the command `Invoke-DscResource` is called with the method `Set`, which with this design pattern will evaluate the properties correctly.</maml:para> <maml:para>>[!NOTE] >This design pattern is not widely used in the DSC resource modules in the >DSC Community, the only known use is in SqlServerDsc. This design pattern >can be viewed as deprecated, and should be replaced with the design pattern >that uses the command \ \`Compare-DscParameterState\`\ (Compare-DscParameterState).</maml:para> <maml:para>See the other design patterns that uses the command \ \`Compare-DscParameterState\`\ (Compare-DscParameterState)or \ \`Test-DscParameterState\`\ (Test-DscParameterState).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Compare-ResourcePropertyState</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>CurrentValues</maml:name> <maml:description> <maml:para>The current values that should be compared to to desired values. Normally the values returned from Get-TargetResource.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DesiredValues</maml:name> <maml:description> <maml:para>The values set in the configuration and is provided in the call to the functions *-TargetResource, and that will be compared against current values. Normally set to $PSBoundParameters.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Properties</maml:name> <maml:description> <maml:para>An array of property names, from the keys provided in DesiredValues, that will be compared. If this parameter is left out, all the keys in the DesiredValues will be compared.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>IgnoreProperties</maml:name> <maml:description> <maml:para>An array of property names, from the keys provided in DesiredValues, that will be ignored in the comparison. If this parameter is left out, all the keys in the DesiredValues will be compared.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>CimInstanceKeyProperties</maml:name> <maml:description> <maml:para>A hashtable containing a key for each property that contain a collection of CimInstances and the value is an array of strings of the CimInstance key properties. @{ Permission = @('State') }</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>@{}</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>CimInstanceKeyProperties</maml:name> <maml:description> <maml:para>A hashtable containing a key for each property that contain a collection of CimInstances and the value is an array of strings of the CimInstance key properties. @{ Permission = @('State') }</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>@{}</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>CurrentValues</maml:name> <maml:description> <maml:para>The current values that should be compared to to desired values. Normally the values returned from Get-TargetResource.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DesiredValues</maml:name> <maml:description> <maml:para>The values set in the configuration and is provided in the call to the functions *-TargetResource, and that will be compared against current values. Normally set to $PSBoundParameters.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>IgnoreProperties</maml:name> <maml:description> <maml:para>An array of property names, from the keys provided in DesiredValues, that will be ignored in the comparison. If this parameter is left out, all the keys in the DesiredValues will be compared.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Properties</maml:name> <maml:description> <maml:para>An array of property names, from the keys provided in DesiredValues, that will be compared. If this parameter is left out, all the keys in the DesiredValues will be compared.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable[]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Returns an array containing a hashtable with metadata for each property that was evaluated.</maml:para> <maml:para>Metadata Name | Type | Description --- | --- | --- ParameterName | `[System.String]` | The name of the property that was evaluated Expected | The type of the property | The desired value for the property Actual | The type of the property | The actual current value for the property InDesiredState | `[System.Boolean]` | Returns `$true` if the expected and actual value was equal.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$compareTargetResourceStateParameters = @{ CurrentValues = (Get-TargetResource $PSBoundParameters) DesiredValues = $PSBoundParameters } $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters $propertiesNotInDesiredState = $propertyState.Where({ -not $_.InDesiredState })</dev:code> <dev:remarks> <maml:para>This example calls Compare-ResourcePropertyState with the current state and the desired state and returns a hashtable array of all the properties that was evaluated based on the properties pass in the parameter DesiredValues. Finally it sets a parameter `$propertiesNotInDesiredState` that contain an array with all properties not in desired state.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$compareTargetResourceStateParameters = @{ CurrentValues = (Get-TargetResource $PSBoundParameters) DesiredValues = $PSBoundParameters Properties = @( 'Property1' ) } $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters $false -in $propertyState.InDesiredState</dev:code> <dev:remarks> <maml:para>This example calls Compare-ResourcePropertyState with the current state and the desired state and returns a hashtable array with just the property `Property1` as that was the only property that was to be evaluated. Finally it checks if `$false` is present in the array property `InDesiredState`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>$compareTargetResourceStateParameters = @{ CurrentValues = (Get-TargetResource $PSBoundParameters) DesiredValues = $PSBoundParameters IgnoreProperties = @( 'Property1' ) } $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters</dev:code> <dev:remarks> <maml:para>This example calls Compare-ResourcePropertyState with the current state and the desired state and returns a hashtable array of all the properties except the property `Property1`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>$compareTargetResourceStateParameters = @{ CurrentValues = (Get-TargetResource $PSBoundParameters) DesiredValues = $PSBoundParameters CimInstanceKeyProperties = @{ ResourceProperty1 = @( 'CimProperty1' ) } } $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters</dev:code> <dev:remarks> <maml:para>This example calls Compare-ResourcePropertyState with the current state and the desired state and have a property `ResourceProperty1` who's value is an array of embedded CIM instances. The key property for the CIM instances are `CimProperty1`. The CIM instance key property `CimProperty1` is used to get the unique CIM instance object to compare against from both the current state and the desired state.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-DscResourceInstance</command:name> <command:verb>ConvertFrom</command:verb> <command:noun>DscResourceInstance</command:noun> <maml:description> <maml:para>Convert any object to hashtable.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function is used to convert a PSObject into a hashtable.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-DscResourceInstance</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that should be convert to hashtable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>OutputFormat</maml:name> <maml:description> <maml:para>Set the format you do want to convert the object. The default value is HashTable. It's the only value accepted at this time.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>HashTable</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that should be convert to hashtable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>OutputFormat</maml:name> <maml:description> <maml:para>Set the format you do want to convert the object. The default value is HashTable. It's the only value accepted at this time.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>HashTable</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$object = [PSCustomObject] = @{ FirstName = 'John' LastName = 'Smith' } ConvertFrom-DscResourceInstance -InputObject $object</dev:code> <dev:remarks> <maml:para>This creates a PSCustomObject and converts its properties and values to key/value pairs in a hashtable.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$objectArray = [PSCustomObject] = @{ FirstName = 'John' LastName = 'Smith' }, [PSCustomObject] = @{ FirstName = 'Peter' LastName = 'Smith' } $objectArray | ConvertFrom-DscResourceInstance</dev:code> <dev:remarks> <maml:para>This creates an array of PSCustomObject and converts their properties and values to key/value pairs in a hashtable.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-CimInstance</command:name> <command:verb>ConvertTo</command:verb> <command:noun>CimInstance</command:noun> <maml:description> <maml:para>Converts a hashtable into a CimInstance array.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function is used to convert a hashtable into MSFT_KeyValuePair objects. These are stored as an CimInstance array. DSC cannot handle hashtables but CimInstances arrays storing MSFT_KeyValuePair.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-CimInstance</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Hashtable</maml:name> <maml:description> <maml:para>A hashtable with the values to convert.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Hashtable</maml:name> <maml:description> <maml:para>A hashtable with the values to convert.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object[]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>ConvertTo-CimInstance -Hashtable @{ String = 'a string' Bool = $true Int = 99 Array = 'a, b, c' }</dev:code> <dev:remarks> <maml:para>This example returns an CimInstance with the provided hashtable values.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-HashTable</command:name> <command:verb>ConvertTo</command:verb> <command:noun>HashTable</command:noun> <maml:description> <maml:para>Converts CimInstances into a hashtable.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function is used to convert a CimInstance array containing MSFT_KeyValuePair objects into a hashtable.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-HashTable</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>CimInstance</maml:name> <maml:description> <maml:para>An array of CimInstances or a single CimInstance object to convert.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CimInstance[]</command:parameterValue> <dev:type> <maml:name>CimInstance[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>CimInstance</maml:name> <maml:description> <maml:para>An array of CimInstances or a single CimInstance object to convert.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CimInstance[]</command:parameterValue> <dev:type> <maml:name>CimInstance[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$newInstanceParameters = @{ ClassName = 'MSFT_KeyValuePair' Namespace = 'root/microsoft/Windows/DesiredStateConfiguration' ClientOnly = $true } $cimInstance = [Microsoft.Management.Infrastructure.CimInstance[]] ( (New-CimInstance @newInstanceParameters -Property @{ Key = 'FirstName' Value = 'John' }), (New-CimInstance @newInstanceParameters -Property @{ Key = 'LastName' Value = 'Smith' }) ) ConvertTo-HashTable -CimInstance $cimInstance</dev:code> <dev:remarks> <maml:para>This creates a array of CimInstances using the class name MSFT_KeyValuePair and passes it to ConvertTo-HashTable which returns a hashtable.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Find-Certificate</command:name> <command:verb>Find</command:verb> <command:noun>Certificate</command:noun> <maml:description> <maml:para>Locates one or more certificates using the passed certificate selector parameters.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>A common function to find certificates based on multiple search filters, including, but not limited to: Thumbprint, Friendly Name, DNS Names, Key Usage, Issuers, etc.</maml:para> <maml:para>Locates one or more certificates using the passed certificate selector parameters. If more than one certificate is found matching the selector criteria, they will be returned in order of descending expiration date.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Find-Certificate</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Thumbprint</maml:name> <maml:description> <maml:para>The thumbprint of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>FriendlyName</maml:name> <maml:description> <maml:para>The friendly name of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Subject</maml:name> <maml:description> <maml:para>The subject of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>DNSName</maml:name> <maml:description> <maml:para>The subject alternative name of the certificate to export must contain these values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>Issuer</maml:name> <maml:description> <maml:para>The issuer of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="6" aliases="none"> <maml:name>KeyUsage</maml:name> <maml:description> <maml:para>The key usage of the certificate to find must contain these values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="7" aliases="none"> <maml:name>EnhancedKeyUsage</maml:name> <maml:description> <maml:para>The enhanced key usage of the certificate to find must contain these values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="8" aliases="none"> <maml:name>Store</maml:name> <maml:description> <maml:para>The Windows Certificate Store Name to search for the certificate in. Defaults to 'My'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>My</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="9" aliases="none"> <maml:name>AllowExpired</maml:name> <maml:description> <maml:para>Allows expired certificates to be returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue> <dev:type> <maml:name>Boolean</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="9" aliases="none"> <maml:name>AllowExpired</maml:name> <maml:description> <maml:para>Allows expired certificates to be returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Boolean</command:parameterValue> <dev:type> <maml:name>Boolean</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>DNSName</maml:name> <maml:description> <maml:para>The subject alternative name of the certificate to export must contain these values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="7" aliases="none"> <maml:name>EnhancedKeyUsage</maml:name> <maml:description> <maml:para>The enhanced key usage of the certificate to find must contain these values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>FriendlyName</maml:name> <maml:description> <maml:para>The friendly name of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>Issuer</maml:name> <maml:description> <maml:para>The issuer of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="6" aliases="none"> <maml:name>KeyUsage</maml:name> <maml:description> <maml:para>The key usage of the certificate to find must contain these values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="8" aliases="none"> <maml:name>Store</maml:name> <maml:description> <maml:para>The Windows Certificate Store Name to search for the certificate in. Defaults to 'My'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>My</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Subject</maml:name> <maml:description> <maml:para>The subject of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Thumbprint</maml:name> <maml:description> <maml:para>The thumbprint of the certificate to find.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.Cryptography.X509Certificates.X509Certificate2</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Find-Certificate -Thumbprint '1111111111111111111111111111111111111111'</dev:code> <dev:remarks> <maml:para>Return certificate that matches thumbprint.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Find-Certificate -KeyUsage 'DataEncipherment', 'DigitalSignature'</dev:code> <dev:remarks> <maml:para>Return certificate(s) that have specific key usage.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Find-Certificate -DNSName 'www.fabrikam.com', 'www.contoso.com'</dev:code> <dev:remarks> <maml:para>Return certificate(s) filtered on specific DNS Names.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Find-Certificate -Subject 'CN=contoso, DC=com'</dev:code> <dev:remarks> <maml:para>Return certificate(s) with specific subject.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Find-Certificate -Issuer 'CN=contoso-ca, DC=com' -AllowExpired $true</dev:code> <dev:remarks> <maml:para>Return all certificates from specific issuer, including expired certificates.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 6 --------------------------</maml:title> <dev:code>Find-Certificate -EnhancedKeyUsage @('Client authentication','Server Authentication') -AllowExpired $true</dev:code> <dev:remarks> <maml:para>Return all certificates that can be used for server or client authentication, including expired certificates.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 7 --------------------------</maml:title> <dev:code>Find-Certificate -FriendlyName 'My IIS Site SSL Cert'</dev:code> <dev:remarks> <maml:para>Return certificate based on FriendlyName.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-ComputerName</command:name> <command:verb>Get</command:verb> <command:noun>ComputerName</command:noun> <maml:description> <maml:para>Returns the computer name cross-plattform.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns the computer name cross-plattform. The variable `$env:COMPUTERNAME` does not exist cross-platform which hinders development and testing on macOS and Linux. Instead this command can be used to get the computer name cross-plattform.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-ComputerName</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-ComputerName</dev:code> <dev:remarks> <maml:para>Returns the computer name regardless of platform.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-DscProperty</command:name> <command:verb>Get</command:verb> <command:noun>DscProperty</command:noun> <maml:description> <maml:para>Returns DSC resource properties that is part of a class-based DSC resource.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns DSC resource properties that is part of a class-based DSC resource. The properties can be filtered using name, attribute, or if it has been assigned a non-null value.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-DscProperty</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that contain one or more key properties.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies one or more property names to return. If left out all properties are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>ExcludeName</maml:name> <maml:description> <maml:para>Specifies one or more property names to exclude.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="Type"> <maml:name>Attribute</maml:name> <maml:description> <maml:para>Specifies one or more property attributes to return. If left out all property types are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HasValue</maml:name> <maml:description> <maml:para>Specifies to return only properties that has been assigned a non-null value. If left out all properties are returned regardless if there is a value assigned or not.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="Type"> <maml:name>Attribute</maml:name> <maml:description> <maml:para>Specifies one or more property attributes to return. If left out all property types are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>ExcludeName</maml:name> <maml:description> <maml:para>Specifies one or more property names to exclude.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HasValue</maml:name> <maml:description> <maml:para>Specifies to return only properties that has been assigned a non-null value. If left out all properties are returned regardless if there is a value assigned or not.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that contain one or more key properties.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies one or more property names to return. If left out all properties are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>[System.Collections.Hashtable]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This command only works with nullable data types, if using a non-nullable type make sure to make it nullable, e.g. [Nullable[System.Int32]].</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-DscProperty -InputObject $this</dev:code> <dev:remarks> <maml:para>Returns all DSC resource properties of the DSC resource.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$this | Get-DscProperty</dev:code> <dev:remarks> <maml:para>Returns all DSC resource properties of the DSC resource.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-DscProperty -InputObject $this -Name @('MyProperty1', 'MyProperty2')</dev:code> <dev:remarks> <maml:para>Returns the DSC resource properties with the specified names.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Get-DscProperty -InputObject $this -Attribute @('Mandatory', 'Optional')</dev:code> <dev:remarks> <maml:para>Returns the DSC resource properties that has the specified attributes.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Get-DscProperty -InputObject $this -Attribute @('Optional') -HasValue</dev:code> <dev:remarks> <maml:para>Returns the DSC resource properties that has the specified attributes and has a non-null value assigned.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-EnvironmentVariable</command:name> <command:verb>Get</command:verb> <command:noun>EnvironmentVariable</command:noun> <maml:description> <maml:para>Returns the value from an environment variable from a specified target.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns the value from an environment variable from a specified target. This command returns `$null` if the environment variable does not exist.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-EnvironmentVariable</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the environment variable name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>FromTarget</maml:name> <maml:description> <maml:para>Specifies the target to return the value from. Defaults to 'Session'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Session</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>FromTarget</maml:name> <maml:description> <maml:para>Specifies the target to return the value from. Defaults to 'Session'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Session</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the environment variable name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>[System.String]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-EnvironmentVariable -Name 'PSModulePath'</dev:code> <dev:remarks> <maml:para>Returns the value for the environment variable PSModulePath.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'Machine'</dev:code> <dev:remarks> <maml:para>Returns the value for the environment variable PSModulePath from the Machine target.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-LocalizedData</command:name> <command:verb>Get</command:verb> <command:noun>LocalizedData</command:noun> <maml:description> <maml:para>Gets language-specific data into scripts and functions based on the UI culture that is specified or that is selected for the operating system.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The Get-LocalizedData command dynamically retrieves strings from a subdirectory whose name matches the UI language set for the current user of the operating system. It is designed to enable scripts to display user messages in the UI language selected by the current user.</maml:para> <maml:para>Optionally the `Get-LocalizedData` saves the hash table in the variable that is specified by the value of the `BindingVariable` parameter.</maml:para> <maml:para>Get-LocalizedData imports data from .psd1 files in language-specific subdirectories of the script directory and saves them in a local variable that is specified in the command. The command selects the subdirectory and file based on the value of the $PSUICulture automatic variable. When you use the local variable in the script to display a user message, the message appears in the user's UI language.</maml:para> <maml:para>You can use the parameters of G-LocalizedData to specify an alternate UI culture, path, and file name, to add supported commands, and to suppress the error message that appears if the .psd1 files are not found.</maml:para> <maml:para>The G-LocalizedData command supports the script internationalization initiative that was introduced in Windows PowerShell 2.0. This initiative aims to better serve users worldwide by making it easy for scripts to display user messages in the UI language of the current user. For more information about this and about the format of the .psd1 files, see about_Script_Internationalization.</maml:para> <maml:para>```mermaid graph LR</maml:para> <maml:para>Argument{Parameter set?} -->|"Only UICulture (DefaultUICulture = en-US)"| UseUIC Argument -->|"Only DefaultUICulture"| GetUIC[[Get OS Culture]] GetUIC --> LCID127{"Is LCID = 127?<br>(in variant culture)"} Argument -->|"Both UICulture and DefaultUICulture"| UseUIC UseUIC[Use UICulture] --> LCID127 LCID127 -->|"No"| SetUIC[[Set UICulture]] LCID127 -->|"Yes"| UseDC[Use default culture] UseDC --> SetUIC SetUIC --> SearchFile[[Find UICulture<br>localization file]] SearchFile --> FileExist FileExist{localization<br>file exist?} -->|"No"| ParentCulture{Parent culture<br>exist?} ParentCulture -->|"Yes"| UseParentC[Use parent culture] UseParentC --> SetUIC ParentCulture -->|"No"| EvalDefaultC{Evaluate<br>default>br>culture?} EvalDefaultC -->|"Yes"| UseDC EvalDefaultC -->|"No"| EvalStillLCID127{Still invariant?} FileExist -->|"Yes"| EvalStillLCID127 EvalStillLCID127 -->|"Yes, Use Get-LocalizedDataForInvariantCulture"| GetFile[[Get localization strings]] EvalStillLCID127 -->|"No, Use Import-LocalizedData"| GetFile ```</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-LocalizedData</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="Variable"> <maml:name>BindingVariable</maml:name> <maml:description> <maml:para>Specifies the variable into which the text strings are imported. Enter a variable name without a dollar sign ($).</maml:para> <maml:para>In Windows PowerShell 2.0, this parameter is required. In Windows PowerShell 3.0, this parameter is optional. If you omit this parameter, Import-LocalizedData returns a hash table of the text strings. The hash table is passed down the pipeline or displayed at the command line.</maml:para> <maml:para>When using Import-LocalizedData to replace default text strings specified in the DATA section of a script, assign the DATA section to a variable and enter the name of the DATA section variable in the value of the BindingVariable parameter. Then, when Import-LocalizedData saves the imported content in the BindingVariable, the imported data will replace the default text strings. If you are not specifying default text strings, you can select any variable name.</maml:para> <maml:para>If the BindingVariable parameter is not specified, Import-LocalizedData returns a hashtable of the text strings. The hash table is passed down the pipeline or displayed at the command line.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>UICulture</maml:name> <maml:description> <maml:para>Specifies an alternate UI culture. The default is the value of the $PsUICulture automatic variable. Enter a UI culture in <language>-<region> format, such as en-US, de-DE, or ar-SA.</maml:para> <maml:para>The value of the UICulture parameter determines the language-specific subdirectory (within the base directory) from which Import-LocalizedData gets the .psd1 file for the script.</maml:para> <maml:para>The command searches for a subdirectory with the same name as the value of the UICulture parameter or the $PsUICulture automatic variable, such as de-DE or ar-SA. If it cannot find the directory, or the directory does not contain a .psd1 file for the script, it searches for a subdirectory with the name of the language code, such as de or ar. If it cannot find the subdirectory or .psd1 file, the command fails and the data is displayed in the default language specified in the script.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>DefaultUICulture</maml:name> <maml:description> <maml:para>Specifies which UICulture to default to if current UI culture or its parents culture don't have matching data file.</maml:para> <maml:para>For example, if you have a data file in 'en-US' but not in 'en' or 'en-GB' and your current culture is 'en-GB', you can default back to 'en-US'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>En-US</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BaseDirectory</maml:name> <maml:description> <maml:para>Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileName</maml:name> <maml:description> <maml:para>Specifies the name of the data file (.psd1) to be imported. Enter a file name. You can specify a file name that does not include its .psd1 file name extension, or you can specify the file name including the .psd1 file name extension.</maml:para> <maml:para>The FileName parameter is required when Import-LocalizedData is not used in a script. Otherwise, the parameter is optional and the default value is the base name of the script. You can use this parameter to direct Import-LocalizedData to search for a different .psd1 file.</maml:para> <maml:para>For example, if the FileName is omitted and the script name is FindFiles.ps1, Import-LocalizedData searches for the FindFiles.psd1 data file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportedCommand</maml:name> <maml:description> <maml:para>Specifies cmdlets and functions that generate only data.</maml:para> <maml:para>Use this parameter to include cmdlets and functions that you have written or tested. For more information, see about_Script_Internationalization.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BaseDirectory</maml:name> <maml:description> <maml:para>Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="Variable"> <maml:name>BindingVariable</maml:name> <maml:description> <maml:para>Specifies the variable into which the text strings are imported. Enter a variable name without a dollar sign ($).</maml:para> <maml:para>In Windows PowerShell 2.0, this parameter is required. In Windows PowerShell 3.0, this parameter is optional. If you omit this parameter, Import-LocalizedData returns a hash table of the text strings. The hash table is passed down the pipeline or displayed at the command line.</maml:para> <maml:para>When using Import-LocalizedData to replace default text strings specified in the DATA section of a script, assign the DATA section to a variable and enter the name of the DATA section variable in the value of the BindingVariable parameter. Then, when Import-LocalizedData saves the imported content in the BindingVariable, the imported data will replace the default text strings. If you are not specifying default text strings, you can select any variable name.</maml:para> <maml:para>If the BindingVariable parameter is not specified, Import-LocalizedData returns a hashtable of the text strings. The hash table is passed down the pipeline or displayed at the command line.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>DefaultUICulture</maml:name> <maml:description> <maml:para>Specifies which UICulture to default to if current UI culture or its parents culture don't have matching data file.</maml:para> <maml:para>For example, if you have a data file in 'en-US' but not in 'en' or 'en-GB' and your current culture is 'en-GB', you can default back to 'en-US'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>En-US</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FileName</maml:name> <maml:description> <maml:para>Specifies the name of the data file (.psd1) to be imported. Enter a file name. You can specify a file name that does not include its .psd1 file name extension, or you can specify the file name including the .psd1 file name extension.</maml:para> <maml:para>The FileName parameter is required when Import-LocalizedData is not used in a script. Otherwise, the parameter is optional and the default value is the base name of the script. You can use this parameter to direct Import-LocalizedData to search for a different .psd1 file.</maml:para> <maml:para>For example, if the FileName is omitted and the script name is FindFiles.ps1, Import-LocalizedData searches for the FindFiles.psd1 data file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportedCommand</maml:name> <maml:description> <maml:para>Specifies cmdlets and functions that generate only data.</maml:para> <maml:para>Use this parameter to include cmdlets and functions that you have written or tested. For more information, see about_Script_Internationalization.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>UICulture</maml:name> <maml:description> <maml:para>Specifies an alternate UI culture. The default is the value of the $PsUICulture automatic variable. Enter a UI culture in <language>-<region> format, such as en-US, de-DE, or ar-SA.</maml:para> <maml:para>The value of the UICulture parameter determines the language-specific subdirectory (within the base directory) from which Import-LocalizedData gets the .psd1 file for the script.</maml:para> <maml:para>The command searches for a subdirectory with the same name as the value of the UICulture parameter or the $PsUICulture automatic variable, such as de-DE or ar-SA. If it cannot find the directory, or the directory does not contain a .psd1 file for the script, it searches for a subdirectory with the name of the language code, such as de or ar. If it cannot find the subdirectory or .psd1 file, the command fails and the data is displayed in the default language specified in the script.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Before using Import-LocalizedData, localize your user messages. Format the messages for each locale (UI culture) in a hash table of key/value pairs, and save the hash table in a file with the same name as the script and a .psd1 file name extension. Create a directory under the script directory for each supported UI culture, and then save the .psd1 file for each UI culture in the directory with the UI culture name.</maml:para> <maml:para>For example, localize your user messages for the de-DE locale and format them in a hash table. Save the hash table in a <ScriptName>.psd1 file. Then create a de-DE subdirectory under the script directory, and save the de-DE <ScriptName>.psd1 file in the de-DE subdirectory. Repeat this method for each locale that you support.</maml:para> <maml:para>Import-LocalizedData performs a structured search for the localized user messages for a script.</maml:para> <maml:para>Import-LocalizedData begins the search in the directory where the script file is located (or the value of the BaseDirectory parameter). It then searches within the base directory for a subdirectory with the same name as the value of the $PsUICulture variable (or the value of the UICulture parameter), such as de-DE or ar-SA. Then, it searches in that subdirectory for a .psd1 file with the same name as the script (or the value of the FileName parameter).</maml:para> <maml:para>If Import-LocalizedData cannot find a subdirectory with the name of the UI culture, or the subdirectory does not contain a .psd1 file for the script, it searches for a .psd1 file for the script in a subdirectory with the name of the language code, such as de or ar. If it cannot find the subdirectory or .psd1 file, the command fails, the data is displayed in the default language in the script, and an error message is displayed explaining that the data could not be imported. To suppress the message and fail gracefully, use the ErrorAction common parameter with a value of SilentlyContinue.</maml:para> <maml:para>If Import-LocalizedData finds the subdirectory and the .psd1 file, it imports the hash table of user messages into the value of the BindingVariable parameter in the command. Then, when you display a message from the hash table in the variable, the localized message is displayed.</maml:para> <maml:para>For more information, see about_Script_Internationalization.</maml:para> <maml:para>This command should preferably be used at the top of each resource PowerShell module script file (.psm1).</maml:para> <maml:para>It will automatically look for a file in the folder for the current UI culture, or default to the UI culture folder 'en-US'.</maml:para> <maml:para>The localized strings file can be named either `<ScriptFileName>.psd1`, e.g. `DSC_MyResource.psd1`, or suffixed with `strings`, e.g. `DSC_MyResource.strings.psd1`.</maml:para> <maml:para>Read more about localization in the section \ Localization\ (https://dsccommunity.org/styleguidelines/localization/)in the DSC Community style guideline.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$script:localizedData = Get-LocalizedData</dev:code> <dev:remarks> <maml:para>Imports the localized strings for the current OS UI culture. If the localized folder does not exist then the localized strings for the default UI culture 'en-US' is returned.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$script:localizedData = Get-LocalizedData -DefaultUICulture 'de-DE'</dev:code> <dev:remarks> <maml:para>Imports the localized strings for the current OS UI culture. If the localized folder does not exist then the localized strings for the default UI culture 'de-DE' is returned.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>$script:localizedData = Get-LocalizedData -UICulture 'de-DE'</dev:code> <dev:remarks> <maml:para>Imports the localized strings for UI culture 'de-DE'. If the localized folder does not exist then the localized strings for the default UI culture 'en-US' is returned.</maml:para> <maml:para>$script:localizedData = Get-LocalizedData -UICulture 'de-DE' -DefaultUICulture 'en-GB'</maml:para> <maml:para>Imports the localized strings for UI culture 'de-DE'. If the localized folder does not exist then the localized strings for the default UI culture 'en-GB' is returned.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-LocalizedDataForInvariantCulture</command:name> <command:verb>Get</command:verb> <command:noun>LocalizedDataForInvariantCulture</command:noun> <maml:description> <maml:para>Gets language-specific data when the culture is invariant. This directly gets the data from the DefaultUICulture, but without calling "Import-LocalizedData" which throws when the pwsh session is configured to be of invariant culture (as in the Guest Config agent).</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The Get-LocalizedDataForInvariantCulture grabs the data from a localized string data psd1 file, without calling Import-LocalizedData which errors when called in a powershell session with the Globalization-Invariant mode enabled (https://docs.microsoft.com/en-us/dotnet/core/compatibility/globalization/6.0/culture-creation-invariant-mode).</maml:para> <maml:para>Instead, this function reads and executes the content of a psd1 file in a constrained language mode that only allows basic ConvertFrom-stringData.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-LocalizedDataForInvariantCulture</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>BaseDirectory</maml:name> <maml:description> <maml:para>Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none"> <maml:name>FileName</maml:name> <maml:description> <maml:para>Specifies the base name of the data file (.psd1) to be imported. Enter a file name. You can specify a file name that does not include its .psd1 file name extension, or you can specify the file name including the .psd1 file name extension.</maml:para> <maml:para>The FileName parameter is required when Get-LocalizedDataForInvariantCulture is not used in a script. Otherwise, the parameter is optional and the default value is the base name of the calling script. You can use this parameter to directly search for a specific .psd1 file.</maml:para> <maml:para>For example, if the FileName is omitted and the script name is FindFiles.ps1, Get-LocalizedDataForInvariantCulture searches for the FindFiles.psd1 or FindFiles.strings.psd1 data file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>DefaultUICulture</maml:name> <maml:description> <maml:para>Specifies which UICulture to default to if current UI culture or its parents culture don't have matching data file.</maml:para> <maml:para>For example, if you have a data file in 'en-US' but not in 'en' or 'en-GB' and your current culture is 'en-GB', you can default back to 'en-US'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>En-US</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>BaseDirectory</maml:name> <maml:description> <maml:para>Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>DefaultUICulture</maml:name> <maml:description> <maml:para>Specifies which UICulture to default to if current UI culture or its parents culture don't have matching data file.</maml:para> <maml:para>For example, if you have a data file in 'en-US' but not in 'en' or 'en-GB' and your current culture is 'en-GB', you can default back to 'en-US'.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>En-US</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="2" aliases="none"> <maml:name>FileName</maml:name> <maml:description> <maml:para>Specifies the base name of the data file (.psd1) to be imported. Enter a file name. You can specify a file name that does not include its .psd1 file name extension, or you can specify the file name including the .psd1 file name extension.</maml:para> <maml:para>The FileName parameter is required when Get-LocalizedDataForInvariantCulture is not used in a script. Otherwise, the parameter is optional and the default value is the base name of the calling script. You can use this parameter to directly search for a specific .psd1 file.</maml:para> <maml:para>For example, if the FileName is omitted and the script name is FindFiles.ps1, Get-LocalizedDataForInvariantCulture searches for the FindFiles.psd1 or FindFiles.strings.psd1 data file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para>The Get-LocalizedDataForInvariantCulture should only be used when we want to avoid using Import-LocalizedData, such as when doing so will fail because the powershell session is in Globalization-Invariant mode: https://docs.microsoft.com/en-us/dotnet/core/compatibility/globalization/6.0/culture-creation-invariant-mode</maml:para> <maml:para>Before using Get-LocalizedDataForInvariantCulture, localize your user messages to the desired default locale (UI culture, usually en-US) in a hash table of key/value pairs, and save the hash table in a file with the same name as the script or module with a .psd1 file name extension. Create a directory under the module base or script's parent directory for each supported UI culture, and then save the .psd1 file for each UI culture in the directory with the UI culture name.</maml:para> <maml:para>For example, localize your user messages for the de-DE locale and format them in a hash table. Save the hash table in a <ScriptName>.psd1 file. Then create a de-DE subdirectory under the script directory, and save the de-DE <ScriptName>.psd1 file in the de-DE subdirectory. Repeat this method for each locale that you support.</maml:para> <maml:para>Import-LocalizedData performs a structured search for the localized user messages for a script.</maml:para> <maml:para>Get-LocalizedDataForInvariantCulture only search in the BaseDirectory specified. It then searches within the base directory for a subdirectory with the same name as the value of the $DefaultUICulture variable (specified or default to en-US), such as de-DE or ar-SA. Then, it searches in that subdirectory for a .psd1 file with the same name as provided FileName such as FileName.psd1 or FileName.strings.psd1.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-LocalizedDataForInvariantCulture -BaseDirectory .\source\ -FileName DscResource.Common -DefaultUICulture en-US</dev:code> <dev:remarks> <maml:para>This is an example, usually it is only used by Get-LocalizedData in DSC resources to import the localized strings when the Culture is Invariant (id 127).</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-PSModulePath</command:name> <command:verb>Get</command:verb> <command:noun>PSModulePath</command:noun> <maml:description> <maml:para>Returns the environment variable PSModulePath from the specified target.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns the environment variable PSModulePath from the specified target. If more than one target is provided the return will contain all the concatenation of all unique paths from the targets. If there are no paths to return the command will return an empty string.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-PSModulePath</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>FromTarget</maml:name> <maml:description> <maml:para>Specifies the target to get the PSModulePath from.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>FromTarget</maml:name> <maml:description> <maml:para>Specifies the target to get the PSModulePath from.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>[System.String]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>If there are no paths to return the command will return an empty string.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-PSModulePath -FromTarget 'Session'</dev:code> <dev:remarks> <maml:para>Returns the paths from the Session target.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-PSModulePath -FromTarget 'Session', 'User', 'Machine'</dev:code> <dev:remarks> <maml:para>Returns the unique paths from the all targets.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-TemporaryFolder</command:name> <command:verb>Get</command:verb> <command:noun>TemporaryFolder</command:noun> <maml:description> <maml:para>Returns the path of the current user's temporary folder.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns the path of the current user's temporary folder.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-TemporaryFolder</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This is the same as doing the following - Windows: $env:TEMP</maml:para> <maml:para>- macOS: $env:TMPDIR</maml:para> <maml:para>- Linux: /tmp/</maml:para> <maml:para></maml:para> <maml:para>Examples of what the command returns:</maml:para> <maml:para>- Windows: C:\Users\username\AppData\Local\Temp\</maml:para> <maml:para>- macOS: /var/folders/6x/thq2xce46bc84lr66fih2p5h0000gn/T/</maml:para> <maml:para>- Linux: /tmp/</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-TemporaryFolder</dev:code> <dev:remarks> <maml:para>Returns the current user temporary folder on the current operating system.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-ArgumentException</command:name> <command:verb>New</command:verb> <command:noun>ArgumentException</command:noun> <maml:description> <maml:para>Creates and throws or returns an invalid argument exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates and throws or returns an invalid argument exception.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-ArgumentException</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ArgumentName</maml:name> <maml:description> <maml:para>The name of the invalid argument that is causing this error to be thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the error record instead of throwing it.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ArgumentName</maml:name> <maml:description> <maml:para>The name of the invalid argument that is causing this error to be thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the error record instead of throwing it.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.ArgumentException</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>New-ArgumentException -ArgumentName 'Action' -Message 'My error message'</dev:code> <dev:remarks> <maml:para>Creates and throws an invalid argument exception for (parameter) 'Action' with the message 'My error message'.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$errorRecord = New-ArgumentException -ArgumentName 'Action' -Message 'My error message' -PassThru</dev:code> <dev:remarks> <maml:para>Creates an invalid argument exception for (parameter) 'Action' with the message 'My error message' and returns the exception.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-ErrorRecord</command:name> <command:verb>New</command:verb> <command:noun>ErrorRecord</command:noun> <maml:description> <maml:para>Creates a new ErrorRecord.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The New-ErrorRecord function creates a new ErrorRecord with the specified parameters.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-ErrorRecord</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ErrorCategory</maml:name> <maml:description> <maml:para>Specifies the category of the error.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">NotSpecified</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OpenError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">CloseError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DeviceError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DeadlockDetected</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InvalidArgument</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InvalidData</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InvalidOperation</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InvalidResult</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InvalidType</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">MetadataError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NotImplemented</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NotInstalled</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ObjectNotFound</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OperationStopped</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">OperationTimeout</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SyntaxError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ParserError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PermissionDenied</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ResourceBusy</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ResourceExists</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ResourceUnavailable</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ReadError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WriteError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">FromStdErr</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecurityError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtocolError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ConnectionError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AuthenticationError</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">LimitsExceeded</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">QuotaExceeded</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NotEnabled</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">ErrorCategory</command:parameterValue> <dev:type> <maml:name>ErrorCategory</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>Specifies a string that uniquely identifies the error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Exception</maml:name> <maml:description> <maml:para>Specifies the exception that caused the error.</maml:para> <maml:para>If an error record is passed to parameter ErrorRecord and if the wrapped exception in the error record contains a `[System.Management.Automation.ParentContainsErrorRecordException]`, the new ErrorRecord should have this exception as its Exception instead.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Exception</command:parameterValue> <dev:type> <maml:name>Exception</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TargetObject</maml:name> <maml:description> <maml:para>Specifies the object that was being manipulated when the error occurred.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>New-ErrorRecord</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>Specifies an existing ErrorRecord.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Exception</maml:name> <maml:description> <maml:para>Specifies the exception that caused the error.</maml:para> <maml:para>If an error record is passed to parameter ErrorRecord and if the wrapped exception in the error record contains a `[System.Management.Automation.ParentContainsErrorRecordException]`, the new ErrorRecord should have this exception as its Exception instead.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Exception</command:parameterValue> <dev:type> <maml:name>Exception</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ErrorCategory</maml:name> <maml:description> <maml:para>Specifies the category of the error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorCategory</command:parameterValue> <dev:type> <maml:name>ErrorCategory</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>Specifies a string that uniquely identifies the error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>Specifies an existing ErrorRecord.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Exception</maml:name> <maml:description> <maml:para>Specifies the exception that caused the error.</maml:para> <maml:para>If an error record is passed to parameter ErrorRecord and if the wrapped exception in the error record contains a `[System.Management.Automation.ParentContainsErrorRecordException]`, the new ErrorRecord should have this exception as its Exception instead.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Exception</command:parameterValue> <dev:type> <maml:name>Exception</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TargetObject</maml:name> <maml:description> <maml:para>Specifies the object that was being manipulated when the error occurred.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.ErrorRecord, System.Exception, System.Management.Automation.ErrorCategory, System.Object, System.String</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.ErrorRecord</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>The function supports two parameter sets: 'ErrorRecord' and 'Exception'. If the 'ErrorRecord' parameter set is used, the function creates a new ErrorRecord based on an existing one and an exception. If the 'Exception' parameter set is used, the function creates a new ErrorRecord based on an exception, an error category, a target object, and an error ID.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$ex = New-Exception -Message 'An error occurred.' $errorRecord = New-ErrorRecord -Exception $ex -ErrorCategory 'InvalidOperation'</dev:code> <dev:remarks> <maml:para>This example creates a new ErrorRecord with the specified parameters. Passing 'InvalidOperation' which is one available value of the enum `[System.Management.Automation.ErrorCategory]`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$ex = New-Exception -Message 'An error occurred.' $errorRecord = New-ErrorRecord -Exception $ex -ErrorCategory 'InvalidOperation' -TargetObject $myObject</dev:code> <dev:remarks> <maml:para>This example creates a new ErrorRecord with the specified parameters. TargetObject is set to the object that was being manipulated when the error occurred.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>$ex = New-Exception -Message 'An error occurred.' $errorRecord = New-ErrorRecord -Exception $ex -ErrorCategory 'InvalidOperation' -ErrorId 'MyErrorId'</dev:code> <dev:remarks> <maml:para>This example creates a new ErrorRecord with the specified parameters. Passing ErrorId that will be set as the FullyQualifiedErrorId in the error record.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>$existingErrorRecord = [System.Management.Automation.ErrorRecord]::new( [System.Management.Automation.ParentContainsErrorRecordException]::new('Existing error'), 'ExistingErrorId', [System.Management.Automation.ErrorCategory]::InvalidOperation, $null ) $newException = [System.Exception]::new('New error') $newErrorRecord = New-ErrorRecord -ErrorRecord $existingErrorRecord -Exception $newException $newErrorRecord.Exception.Message</dev:code> <dev:remarks> <maml:para>This example first creates an emulated ErrorRecord that contain a `ParentContainsErrorRecordException` which will be replaced by the new exception passed to New-ErrorRecord. The result of `$newErrorRecord.Exception.Message` will be 'New error'.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-Exception</command:name> <command:verb>New</command:verb> <command:noun>Exception</command:noun> <maml:description> <maml:para>Creates and returns an exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates an exception that will be returned.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-Exception</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.Exception</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$errorRecord = New-Exception -Message 'An error occurred'</dev:code> <dev:remarks> <maml:para>Creates and returns an exception with the message 'An error occurred'.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>try { Get-ChildItem -Path $path -ErrorAction 'Stop' } catch { $exception = New-Exception -Message 'Could not get files' -ErrorRecord $_ }</dev:code> <dev:remarks> <maml:para>Returns an exception with the message 'Could not get files' and includes the exception that caused this terminating error.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-InvalidDataException</command:name> <command:verb>New</command:verb> <command:noun>InvalidDataException</command:noun> <maml:description> <maml:para>Creates and throws an invalid data exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates and throws an invalid data exception.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-InvalidDataException</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>The error Id to assign to the exception.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="ErrorMessage"> <maml:name>Message</maml:name> <maml:description> <maml:para>The error message to assign to the exception.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>The error Id to assign to the exception.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="ErrorMessage"> <maml:name>Message</maml:name> <maml:description> <maml:para>The error message to assign to the exception.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>New-InvalidDataException -ErrorId 'InvalidDataError' -Message 'My error message'</dev:code> <dev:remarks> <maml:para>Creates and throws an invalid data exception with the error id 'InvalidDataError' and with the message 'My error message'.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-InvalidOperationException</command:name> <command:verb>New</command:verb> <command:noun>InvalidOperationException</command:noun> <maml:description> <maml:para>Creates and throws or returns an invalid operation exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates and throws or returns an invalid operation exception.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-InvalidOperationException</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the error record instead of throwing it.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the error record instead of throwing it.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None. If the PassThru parameter is not specified the command throws an error record.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.InvalidOperationException. If the PassThru parameter is specified the command returns an error record.</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>try { Start-Process @startProcessArguments } catch { New-InvalidOperationException -Message 'My error message' -ErrorRecord $_ }</dev:code> <dev:remarks> <maml:para>Creates and throws an invalid operation exception with the message 'My error message' and includes the exception that caused this terminating error.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$errorRecord = New-InvalidOperationException -Message 'My error message' -PassThru</dev:code> <dev:remarks> <maml:para>Creates and returns an invalid operation exception with the message 'My error message'.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-InvalidResultException</command:name> <command:verb>New</command:verb> <command:noun>InvalidResultException</command:noun> <maml:description> <maml:para>Creates and throws an invalid result exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates and throws an invalid result exception.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-InvalidResultException</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$numberOfObjects = Get-ChildItem -Path $path if ($numberOfObjects -eq 0) { New-InvalidResultException -Message 'To few files' }</dev:code> <dev:remarks> <maml:para>Creates and throws an invalid result exception with the message 'To few files'</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>try { $numberOfObjects = Get-ChildItem -Path $path } catch { New-InvalidResultException -Message 'Missing files' -ErrorRecord $_ }</dev:code> <dev:remarks> <maml:para>Creates and throws an invalid result exception with the message 'Missing files' and includes the exception that caused this terminating error.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-NotImplementedException</command:name> <command:verb>New</command:verb> <command:noun>NotImplementedException</command:noun> <maml:description> <maml:para>Creates and throws or returns an not implemented exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates and throws or returns an not implemented exception.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-NotImplementedException</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the error record instead of throwing it.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the error record instead of throwing it.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.NotImplementedException</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>if ($notImplementedFeature) { New-NotImplementedException -Message 'This feature is not implemented yet' }</dev:code> <dev:remarks> <maml:para>Creates and throws an not implemented exception with the message 'This feature is not implemented yet'.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$errorRecord = New-NotImplementedException -Message 'This feature is not implemented yet' -PassThru</dev:code> <dev:remarks> <maml:para>Creates and returns an not implemented exception with the message 'This feature is not implemented yet'.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-ObjectNotFoundException</command:name> <command:verb>New</command:verb> <command:noun>ObjectNotFoundException</command:noun> <maml:description> <maml:para>Creates and throws an object not found exception.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates and throws an object not found exception.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-ObjectNotFoundException</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>The error record containing the exception that is causing this terminating error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message explaining why this error is being thrown.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>try { Get-ChildItem -Path $path } catch { New-ObjectNotFoundException -Message 'Could not get files' -ErrorRecord $_ }</dev:code> <dev:remarks> <maml:para>Creates and throws an object not found exception with the message 'Could not get files' and includes the exception that caused this terminating error.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-CommonParameter</command:name> <command:verb>Remove</command:verb> <command:noun>CommonParameter</command:noun> <maml:description> <maml:para>Removes common parameters from a hashtable.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function serves the purpose of removing common parameters and option common parameters from a parameter hashtable.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-CommonParameter</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Hashtable</maml:name> <maml:description> <maml:para>The parameter hashtable that should be pruned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Hashtable</maml:name> <maml:description> <maml:para>The parameter hashtable that should be pruned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Remove-CommonParameter -Hashtable $PSBoundParameters</dev:code> <dev:remarks> <maml:para>Returns a new hashtable without the common and optional common parameters.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-DscMachineRebootRequired</command:name> <command:verb>Set</command:verb> <command:noun>DscMachineRebootRequired</command:noun> <maml:description> <maml:para>Set the DSC reboot required status variable.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Sets the global DSCMachineStatus variable to a value of 1. This function is used to set the global variable that indicates to the LCM that a reboot of the node is required.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-DscMachineRebootRequired</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This function is implemented so that individual resource modules do not need to use and therefore suppress Global variables directly. It also enables mocking to increase testability of consumers.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Set-DscMachineRebootRequired</dev:code> <dev:remarks> <maml:para>Sets the `$global:DSCMachineStatus` variable to 1.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-PSModulePath</command:name> <command:verb>Set</command:verb> <command:noun>PSModulePath</command:noun> <maml:description> <maml:para>Set environment variable PSModulePath in the current session or machine wide.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This is a command to set environment variable PSModulePath in current session or machine wide.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-PSModulePath</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FromTarget</maml:name> <maml:description> <maml:para>The target environment variable to copy the value from.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the set value.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ToTarget</maml:name> <maml:description> <maml:para>The target environment variable to set the value to.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-PSModulePath</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Machine</maml:name> <maml:description> <maml:para>If set the PSModulePath will be changed machine wide. If not set, only the current session will be changed.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the set value.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>A string with all the paths separated by semi-colons.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FromTarget</maml:name> <maml:description> <maml:para>The target environment variable to copy the value from.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Machine</maml:name> <maml:description> <maml:para>If set the PSModulePath will be changed machine wide. If not set, only the current session will be changed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>If specified, returns the set value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>A string with all the paths separated by semi-colons.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ToTarget</maml:name> <maml:description> <maml:para>The target environment variable to set the value to.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>;<Path 2>'</dev:code> <dev:remarks> <maml:para>Sets the session environment variable `PSModulePath` to the specified path or paths (separated with semi-colons).</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>;<Path 2>' -Machine</dev:code> <dev:remarks> <maml:para>Sets the machine environment variable `PSModulePath` to the specified path or paths (separated with semi-colons).</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Set-PSModulePath -FromTarget 'MAchine' -ToTarget 'User'</dev:code> <dev:remarks> <maml:para>Copies the value of the machine environment variable `PSModulePath` to the user environment variable `PSModulePath`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-AccountRequirePassword</command:name> <command:verb>Test</command:verb> <command:noun>AccountRequirePassword</command:noun> <maml:description> <maml:para>Returns whether the specified account require a password to be provided.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns whether the specified account require a password to be provided. If the account is a (global) managed service account, virtual account, or a built-in account then there is no need to provide a password.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-AccountRequirePassword</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Credential name for the account.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Credential name for the account.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>[System.Boolean]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Test-AccountRequirePassword -Name 'DOMAIN\MyMSA$'</dev:code> <dev:remarks> <maml:para>Returns `$false` as a manged service account does not need a password.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Test-AccountRequirePassword -Name 'DOMAIN\MySqlUser'</dev:code> <dev:remarks> <maml:para>Returns `$true` as a user account need a password.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Test-AccountRequirePassword -Name 'NT SERVICE\MSSQL$PAYROLL'</dev:code> <dev:remarks> <maml:para>Returns `$false`as a virtual account does not need a password.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-DscParameterState</command:name> <command:verb>Test</command:verb> <command:noun>DscParameterState</command:noun> <maml:description> <maml:para>This command is used to test current and desired values for any DSC resource.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This function tests the parameter status of DSC resource parameters against the current values present on the system.</maml:para> <maml:para>This command was designed to be used in a DSC resource from only Test . The design pattern that uses the command `Test-DscParameterState` assumes that LCM is used which always calls Test before Set , or that there never is a need to evaluate the state in Set .</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-DscParameterState</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>CurrentValues</maml:name> <maml:description> <maml:para>A hashtable with the current values on the system, obtained by e.g. Get-TargetResource.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DesiredValues</maml:name> <maml:description> <maml:para>The hashtable of desired values. For example $PSBoundParameters with the desired values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="ValuesToCheck"> <maml:name>Properties</maml:name> <maml:description> <maml:para>This is a list of properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>ExcludeProperties</maml:name> <maml:description> <maml:para>This is a list of which properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ReverseCheck</maml:name> <maml:description> <maml:para>Indicates that a reverse check should be done. The current and desired state are swapped for another test.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SortArrayValues</maml:name> <maml:description> <maml:para>If the sorting of array values does not matter, values are sorted internally before doing the comparison.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TurnOffTypeChecking</maml:name> <maml:description> <maml:para>Indicates that the type of the parameter should not be checked.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>CurrentValues</maml:name> <maml:description> <maml:para>A hashtable with the current values on the system, obtained by e.g. Get-TargetResource.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DesiredValues</maml:name> <maml:description> <maml:para>The hashtable of desired values. For example $PSBoundParameters with the desired values.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>ExcludeProperties</maml:name> <maml:description> <maml:para>This is a list of which properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="ValuesToCheck"> <maml:name>Properties</maml:name> <maml:description> <maml:para>This is a list of properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ReverseCheck</maml:name> <maml:description> <maml:para>Indicates that a reverse check should be done. The current and desired state are swapped for another test.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SortArrayValues</maml:name> <maml:description> <maml:para>If the sorting of array values does not matter, values are sorted internally before doing the comparison.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TurnOffTypeChecking</maml:name> <maml:description> <maml:para>Indicates that the type of the parameter should not be checked.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>[System.Boolean]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$currentState = Get-TargetResource @PSBoundParameters $returnValue = Test-DscParameterState -CurrentValues $currentState -DesiredValues $PSBoundParameters</dev:code> <dev:remarks> <maml:para>The function Get-TargetResource is called first using all bound parameters to get the values in the current state. The result is then compared to the desired state by calling `Test-DscParameterState`. The result is either `$true` or `$false`, `$false` if one or more properties are not in desired state.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$getTargetResourceParameters = @{ ServerName = $ServerName InstanceName = $InstanceName Name = $Name } $returnValue = Test-DscParameterState ` -CurrentValues (Get-TargetResource @getTargetResourceParameters) ` -DesiredValues $PSBoundParameters ` -ExcludeProperties @( 'FailsafeOperator' 'NotificationMethod' )</dev:code> <dev:remarks> <maml:para>This compares the values in the current state against the desires state. The function Get-TargetResource is called using just the required parameters to get the values in the current state. The parameter 'ExcludeProperties' is used to exclude the properties 'FailsafeOperator' and 'NotificationMethod' from the comparison. The result is either `$true` or `$false`, `$false` if one or more properties are not in desired state.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>$getTargetResourceParameters = @{ ServerName = $ServerName InstanceName = $InstanceName Name = $Name } $returnValue = Test-DscParameterState ` -CurrentValues (Get-TargetResource @getTargetResourceParameters) ` -DesiredValues $PSBoundParameters ` -Properties ServerName, Name</dev:code> <dev:remarks> <maml:para>This compares the values in the current state against the desires state. The function Get-TargetResource is called using just the required parameters to get the values in the current state. The 'Properties' parameter is used to to only compare the properties 'ServerName' and 'Name'.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-DscProperty</command:name> <command:verb>Test</command:verb> <command:noun>DscProperty</command:noun> <maml:description> <maml:para>Tests whether the class-based resource has the specified property.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Tests whether the class-based resource has the specified property, and can optionally tests if the property has a certain attribute or whether it is assigned a non-null value.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-DscProperty</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object that should be tested for existens of the specified property.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the property.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Attribute</maml:name> <maml:description> <maml:para>Specifies if the property should be evaluated to have a specific attribute. If the property exist but is not the specific attribute the command returns `$false`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HasValue</maml:name> <maml:description> <maml:para>Specifies if the property should be evaluated to have a non-value. If the property exist but is assigned `$null` the command returns `$false`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Attribute</maml:name> <maml:description> <maml:para>Specifies if the property should be evaluated to have a specific attribute. If the property exist but is not the specific attribute the command returns `$false`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HasValue</maml:name> <maml:description> <maml:para>Specifies if the property should be evaluated to have a non-value. If the property exist but is assigned `$null` the command returns `$false`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object that should be tested for existens of the specified property.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the property.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>[System.Boolean]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>[System.Boolean]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This command only works with nullable data types, if using a non-nullable type make sure to make it nullable, e.g. [Nullable[System.Int32]].</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Test-DscProperty -InputObject $this -Name 'MyDscProperty'</dev:code> <dev:remarks> <maml:para>Returns `$true` or `$false` whether the property exist or not.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>$this | Test-DscProperty -Name 'MyDscProperty'</dev:code> <dev:remarks> <maml:para>Returns `$true` or `$false` whether the property exist or not.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Test-DscProperty -InputObject $this -Name 'MyDscProperty' -HasValue</dev:code> <dev:remarks> <maml:para>Returns `$true` if the property exist and is assigned a non-null value, if not `$false` is returned.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Test-DscProperty -InputObject $this -Name 'MyDscProperty' -Attribute 'Optional'</dev:code> <dev:remarks> <maml:para>Returns `$true` if the property exist and is an optional property.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Test-DscProperty -InputObject $this -Name 'MyDscProperty' -Attribute 'Optional' -HasValue</dev:code> <dev:remarks> <maml:para>Returns `$true` if the property exist, is an optional property, and is assigned a non-null value.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-IsNanoServer</command:name> <command:verb>Test</command:verb> <command:noun>IsNanoServer</command:noun> <maml:description> <maml:para>Tests if the current OS is a Nano server.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Tests if the current OS is a Nano server.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-IsNanoServer</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>[System.Boolean]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Test-IsNanoServer</dev:code> <dev:remarks> <maml:para>Returns `$true` if the current operating system is Nano Server, if not `$false` is returned.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-IsNumericType</command:name> <command:verb>Test</command:verb> <command:noun>IsNumericType</command:noun> <maml:description> <maml:para>Returns whether the specified object is of a numeric type.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Returns whether the specified object is of a numeric type:</maml:para> <maml:para>- [System.Byte]</maml:para> <maml:para>- [System.Int16]</maml:para> <maml:para>- [System.Int32]</maml:para> <maml:para>- [System.Int64]</maml:para> <maml:para>- [System.SByte]</maml:para> <maml:para>- [System.UInt16]</maml:para> <maml:para>- [System.UInt32]</maml:para> <maml:para>- [System.UInt64]</maml:para> <maml:para>- [System.Decimal]</maml:para> <maml:para>- [System.Double]</maml:para> <maml:para>- [System.Single]</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-IsNumericType</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Object</maml:name> <maml:description> <maml:para>The object to test if it is a numeric type.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Object</maml:name> <maml:description> <maml:para>The object to test if it is a numeric type.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>[System.Boolean]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>When passing in an array of values from the pipeline, the command will return $true if any of the values in the array is numeric.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Test-IsNumericType -Object ([System.UInt32] 1)</dev:code> <dev:remarks> <maml:para>Returns `$true` since the object passed is of a numeric type.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>([System.String] 'a') | Test-IsNumericType</dev:code> <dev:remarks> <maml:para>Returns `$false` since the value is not a numeric type.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>('a', 2, 'b') | Test-IsNumericType</dev:code> <dev:remarks> <maml:para>Returns `$true` since one of the values in the array is of a numeric type.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |