diff --git a/CHANGELOG.md b/CHANGELOG.md index 5134aab..485d8e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Tasks for automating documentation for the GitHub repository wiki ([issue #110](https://github.com/dsccommunity/DscResource.Common/issues/110)). + ### Changed - Updated the pipelines files for resolving dependencies. +- Command documentation was moved from README to GitHub repository wiki. +- Change the word cmdlet to command throughout in the documentation, code + and localization strings. - `Get-LocalizedData` - Refactored to simplify execution and debugging. The command previously used a steppable pipeline (proxies `Import-LocalizedData`), that was diff --git a/README.md b/README.md index fcb6477..69ee4f0 100644 --- a/README.md +++ b/README.md @@ -24,1299 +24,18 @@ full release to [PowerShell Gallery](https://www.powershellgallery.com/). Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing). -## How to implement +## Change log -See the article [DscResource.Common functions in a DSC module](https://dsccommunity.org/blog/use-dscresource-common-functions-in-module/) -describing how to convert a DSC resource module to use DscResource.Common. - -## Cmdlets - - -Refer to the comment-based help for more information about these helper -functions. - -### `Assert-BoundParameter` - -This command asserts passed parameters. It takes a hashtable, normally -`$PSBoundParameters`. There are two parameter sets for this command. - -#### Mutually exclusive parameters are not set - -Asserts that a specified set of parameters are not passed together with -another set of parameters. - ->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. - -#### Required parameter is set - -Assert that required parameters has been specified, and throws an exception if not. - -#### Syntax - - -```plaintext -Assert-BoundParameter -BoundParameterList -MutuallyExclusiveList1 -MutuallyExclusiveList2 [] - -Assert-BoundParameter -BoundParameterList -RequiredParameter [-IfParameterPresent ] [] -``` - - -#### Outputs - -None. - -#### Example - -```powershell -$assertBoundParameterParameters = @{ - BoundParameterList = $PSBoundParameters - MutuallyExclusiveList1 = @( - 'Parameter1' - ) - MutuallyExclusiveList2 = @( - 'Parameter2' - ) -} - -Assert-BoundParameter @assertBoundParameterParameters -``` - -This example throws an exception if `$PSBoundParameters` contains both -the parameters `Parameter1` and `Parameter2`. - - -```powershell -Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange') -``` - - -Throws an exception if either of the two parameters are not specified. - - -```powershell -Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('Property2', 'Property3') -IfParameterPresent @('Property1') -``` - - -Throws an exception if the parameter 'Property1' is specified and either -of the required parameters are not. - -### `Assert-ElevatedUser` - -Assert that the user has elevated the PowerShell session. - -`Assert-ElevatedUser` will throw a statement-terminating error if the -script is not run from an elevated session. - -#### Syntax - - -```plaintext -Assert-ElevatedUser [] -``` - - -#### Outputs - -None. - -#### Example - -```powershell -`Assert-ElevatedUser -ErrorAction 'Stop'` -``` - -This example stops the entire script if it is not run from an -elevated PowerShell session. - -### `Assert-IPAddress` - -Asserts if the IP Address is valid and optionally validates -the IP Address against an Address Family - -#### Syntax - -```plaintext -Assert-IPAddress [-Address] [[-AddressFamily] ] [] -``` - -#### Outputs - -None. - -#### Example - -```powershell -Assert-IPAddress -Address '127.0.0.1' -``` - -This will assert that the supplied address is a valid IPv4 address. -If it is not an exception will be thrown. - -```powershell -Assert-IPAddress -Address 'fe80:ab04:30F5:002b::1' -``` - -This will assert that the supplied address is a valid IPv6 address. -If it is not an exception will be thrown. - -```powershell -Assert-IPAddress -Address 'fe80:ab04:30F5:002b::1' -AddressFamily 'IPv6' -``` - -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. - -### `Assert-Module` - -Assert if the specific module is available to be imported and optionally -import the module. - -#### Syntax - -```plaintext -Assert-Module [-ModuleName] [-ImportModule] [-Force] [] -``` - -#### Outputs - -None. - -#### Example - -```powershell -Assert-Module -ModuleName 'DhcpServer' -``` - -This will assert that the module DhcpServer is available. If it is not -an exception will be thrown. - -```powershell -Assert-Module -ModuleName 'DhcpServer' -ImportModule -``` - -This will assert that the module DhcpServer is available and that it has -been imported into the session. If the module is not available an exception -will be thrown. - -```powershell -Assert-Module -ModuleName 'DhcpServer' -ImportModule -Force -``` - -This will assert that the module DhcpServer is available 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. - -### `Compare-DscParameterState` - -Compare current against desired property state for any DSC resource and return -a collection psobject with the metadata from the comparison. - -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. - -#### Syntax - -```plaintext -Compare-DscParameterState [-CurrentValues] [-DesiredValues] -[[-Properties] ] [[-ExcludeProperties] ] [-TurnOffTypeChecking] - [-ReverseCheck] [-SortArrayValues] [-IncludeInDesiredState] [-IncludeValue] [] -``` - -#### Outputs - -Returns an array containing a PSObject with metadata for each property -that was evaluated. - -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. - -#### Example - -##### Example 1 - -```powershell -$currentValues = @{ - String = 'This is a string' - Int = 1 - Bool = $true -} - -$desiredValues = @{ - String = 'This is a string' - Int = 99 -} - -Compare-DscParameterState -CurrentValues $currentValues -DesiredValues $desiredValues -#result -Name Value ----- ----- -Property Int -InDesiredState False -ExpectedType System.Int32 -ActualType System.Int32 -``` - -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. - -##### Example 2 - -```powershell -$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 -#result -Name Value ----- ----- -Property Int -InDesiredState False -ExpectedType System.Int32 -ActualType System.Int32 -``` - -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. - -##### Example 3 - -```powershell -$serviceParameters = @{ - Name = $Name -} - -$returnValue = Compare-DscParameterState ` - -CurrentValues (Get-Service @serviceParameters) ` - -DesiredValues $PSBoundParameters ` - -Properties @( - 'Name' - 'Status' - 'StartType' - ) -``` - -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. - -### `Compare-ResourcePropertyState` - -Compare current and desired property state for any DSC resource and return -a hashtable with the metadata from the comparison. - -This introduces a new design pattern that is used to evaluate current and -desired state in a DSC resource. This cmdlet 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 cmdlet `Invoke-DscResource` is called -with the method `Set`, which with this design pattern will evaluate the -properties correctly. - -See the other design pattern that uses the cmdlet [`Test-DscParameterState`](#test-dscparameterstate) - -#### Syntax - -```plaintext -Compare-ResourcePropertyState [-CurrentValues] [-DesiredValues] - [[-Properties] ] [[-IgnoreProperties] ] - [[-CimInstanceKeyProperties] ] [] -``` - -#### Outputs - -Returns an array containing a hashtable with metadata for each property -that was evaluated. - -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. - -#### Example - -##### Example 1 - -```powershell -$compareTargetResourceStateParameters = @{ - CurrentValues = (Get-TargetResource $PSBoundParameters) - DesiredValues = $PSBoundParameters -} - -$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters - -$propertiesNotInDesiredState = $propertyState.Where({ -not $_.InDesiredState }) -``` - -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. - -##### Example 2 - -```powershell -$compareTargetResourceStateParameters = @{ - CurrentValues = (Get-TargetResource $PSBoundParameters) - DesiredValues = $PSBoundParameters - Properties = @( - 'Property1' - ) -} - -$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters - -$false -in $propertyState.InDesiredState -``` - -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`. - -##### Example 3 - -```powershell -$compareTargetResourceStateParameters = @{ - CurrentValues = (Get-TargetResource $PSBoundParameters) - DesiredValues = $PSBoundParameters - IgnoreProperties = @( - 'Property1' - ) -} - -$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters -``` - -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`. - -##### Example 4 - -```powershell -$compareTargetResourceStateParameters = @{ - CurrentValues = (Get-TargetResource $PSBoundParameters) - DesiredValues = $PSBoundParameters - CimInstanceKeyProperties = @{ - ResourceProperty1 = @( - 'CimProperty1' - ) - } -} - -$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters -``` - -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. - -### `ConvertTo-CimInstance` - -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. - -#### Syntax - -```plaintext -ConvertTo-CimInstance -Hashtable [] -``` - -### Outputs - -**System.Object[]** - -### Example - -```powershell -ConvertTo-CimInstance -Hashtable @{ - String = 'a string' - Bool = $true - Int = 99 - Array = 'a, b, c' -} -``` - -This example returns an CimInstance with the provided hashtable values. - -### `ConvertTo-HashTable` - -This function is used to convert a CimInstance array containing -MSFT_KeyValuePair objects into a hashtable. - -#### Syntax - -```plaintext -ConvertTo-HashTable -CimInstance - [] -``` - -### Outputs - -**System.Collections.Hashtable** - -### Example - -```powershell -$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 -``` - -This creates a array om CimInstances of the class name MSFT_KeyValuePair -and passes it to ConvertTo-HashTable which returns a hashtable. - -### `Find-Certificate` - -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. - -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. - -#### Syntax - -```plaintext -Find-Certificate [[-Thumbprint] ] [[-FriendlyName] ] -[[-Subject] ] [[-DNSName] ] [[-Issuer] ] -[[-KeyUsage] ] [[-EnhancedKeyUsage] ] [[-Store] ] -[[-AllowExpired] ] [] -``` - -### Outputs - -**System.Security.Cryptography.X509Certificates.X509Certificate2** - -### Example - -```PowerShell -Find-Certificate -Thumbprint '1111111111111111111111111111111111111111' -``` - -Return certificate that matches thumbprint. - -```PowerShell -Find-Certificate -KeyUsage 'DataEncipherment', 'DigitalSignature' -``` - -Return certificate(s) that have specific key usage. - -```PowerShell -Find-Certificate -DNSName 'www.fabrikam.com', 'www.contoso.com' -``` - -Return certificate(s) filtered on specific DNS Names. - -```PowerShell -find-certificate -Subject 'CN=contoso, DC=com' -``` - -Return certificate(s) with specific subject. - -```PowerShell -find-certificate -Issuer 'CN=contoso-ca, DC=com' -AllowExpired $true -``` - -Return all certificates from specific issuer, including expired certificates. - -```PowerShell -$findCertSplat = @{ - EnhancedKeyUsage = @('Client authentication','Server Authentication') - AllowExpired = $true -} - -Find-Certificate @findCertSplat -``` - -Return all certificates that can be used for server or client authentication, -including expired certificates. - -```PowerShell -Find-Certificate -FriendlyName 'My SSL Cert' -``` - -Return certificate based on FriendlyName. - - -### `Get-ComputerName` - -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 cmdlet can be used to get the computer name -cross-plattform. - -#### Syntax - - -```plaintext -Get-ComputerName [] -``` - - -#### Outputs - -**System.String** - -#### Notes - -None. - -#### Example - -```powershell -$computerName = Get-ComputerName -``` - -### `Get-DscProperty` - -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. - -#### Syntax - - -```plaintext -Get-DscProperty [-InputObject] [[-Name] ] [[-ExcludeName] ] [[-Attribute] ] [-HasValue] [] -``` - - -#### Outputs - -**System.Collections.Hashtable** - -#### Notes - -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]]`. - -#### Example - -```powershell -Get-DscProperty -InputObject $this -``` - -Returns all DSC resource properties of the DSC resource. - -```powershell -$this | Get-DscProperty -``` - -Returns all DSC resource properties of the DSC resource. - -```powershell -Get-DscProperty -InputObject $this -Name @('MyProperty1', 'MyProperty2') -``` - -Returns the DSC resource properties with the specified names. - -```powershell -Get-DscProperty -InputObject $this -Attribute @('Mandatory', 'Optional') -``` - -Returns the DSC resource properties that has the specified attributes. - -```powershell -Get-DscProperty -InputObject $this -Attribute @('Optional') -HasValue -``` - -Returns the DSC resource properties that has the specified attributes and -has a non-null value assigned. - -### `Get-EnvironmentVariable` - -Returns the value from an environment variable from a specified target. - -#### Syntax - - -```plaintext -Get-EnvironmentVariable [-Name] [[-FromTarget] ] [] -``` - - -#### Outputs - -**System.String** - -#### Notes - -This command returns `$null` if the environment variable does not exist. - -#### Example +A full list of changes in each version can be found in the [change log](CHANGELOG.md). -```powershell -Get-EnvironmentVariable -Name 'PSModulePath' -``` +## Documentation -Returns the value for the environment variable PSModulePath. +### How to implement -```powershell -Get-EnvironmentVariable -Name 'PSModulePath' -FromTarget 'Machine' -``` - -Returns the value for the environment variable PSModulePath from the -Machine target. - -### `Get-PSModulePath` - -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. - -#### Syntax - - -```plaintext -Get-PSModulePath [-FromTarget] [] -``` - - -#### Outputs - -**System.String** - -#### Notes - -If there are no paths to return the command will return an empty string. - -#### Example - -```powershell -Get-PSModulePath -FromTarget 'Session' -``` - -Returns the paths from the Session target. - -```powershell -Get-PSModulePath -FromTarget 'Session', 'User', 'Machine' -``` - -Returns the unique paths from the all targets. - -### `Get-LocalizedData` - -Gets language-specific data into scripts and functions based on the UI culture -that is selected for the operating system. Similar to Import-LocalizedData, with -extra parameter 'DefaultUICulture'. - -#### Syntax - - -```plaintext -Get-LocalizedData [[-BindingVariable] ] [[-DefaultUICulture] ] [-BaseDirectory ] - [-FileName ] [-SupportedCommand ] [] - -Get-LocalizedData [[-BindingVariable] ] [[-UICulture] ] [-BaseDirectory ] - [-FileName ] [-SupportedCommand ] [] -``` - - -#### Outputs - -**System.Collections.Hashtable** - -Optionally the `Get-LocalizedData` saves the hash table in the variable -that is specified by the value of the `BindingVariable` parameter. - -#### Notes - -This should preferably be used at the top of each resource PowerShell module -script file (.psm1). - -It will automatically look for a file in the folder for the current UI -culture, or default to the UI culture folder 'en-US'. - -The localized strings file can be named either `.psd1`, -e.g. `DSC_MyResource.psd1`, or suffixed with `strings`, e.g. -`DSC_MyResource.strings.psd1`. - -Read more about localization in the section [Localization](https://dsccommunity.org/styleguidelines/localization/) -in the DSC Community style guideline. - -#### Example - -```powershell -$script:resourceHelperModulePath = Join-Path -Path $PSScriptRoot -ChildPath '..\..\Modules\DscResource.Common' - -Import-Module -Name $script:resourceHelperModulePath - -$script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US' -``` - -### `Get-TemporaryFolder` - -Returns the path of the current user's temporary folder. - -#### Syntax - -```plaintext -Get-TemporaryFolder [] -``` - -#### Outputs - -**System.String** - -#### Notes - -Examples of what the cmdlet returns: - -- Windows: C:\Users\username\AppData\Local\Temp\ -- macOS: /var/folders/6x/thq2xce46bc84lr66fih2p5h0000gn/T/ -- Linux: /tmp/ - -#### Example - -```powershell -Join-Path -Path (Get-TemporaryFolder) -ChildPath 'MyTempFile` -``` - -### `New-InvalidArgumentException` - -Creates and throws an invalid argument exception. - -#### Syntax - -```plaintext -New-InvalidArgumentException [-Message] [-ArgumentName] [] -``` - -### Outputs - -None. - -### Example - -```powershell -if ( -not $resultOfEvaluation ) -{ - $errorMessage = ` - $script:localizedData.ActionCannotBeUsedInThisContextMessage ` - -f $Action, $Parameter - - New-InvalidArgumentException -ArgumentName 'Action' -Message $errorMessage -} -``` - -### `New-InvalidDataException` - -Creates and throws an invalid data exception. - -#### Syntax - -```plaintext -New-InvalidDataException [-ErrorId] [-ErrorMessage] [] -``` - -### Outputs - -None. - -### Example - -```powershell -if ( -not $resultOfEvaluation ) -{ - $errorMessage = $script:localizedData.InvalidData -f $Action - - New-InvalidDataException -ErrorId 'InvalidDataError' -ErrorMessage $errorMessage -} -``` - -### `New-InvalidOperationException` - -Creates and throws an invalid operation exception. - -#### Syntax - - -```plaintext -New-InvalidOperationException [-Message] [[-ErrorRecord] ] [] -``` - - -### Outputs - -None. - -### Example - -```powershell -try -{ - Start-Process @startProcessArguments -} -catch -{ - $errorMessage = $script:localizedData.InstallationFailedMessage -f $Path, $processId - New-InvalidOperationException -Message $errorMessage -ErrorRecord $_ -} -``` - -### `New-InvalidResultException` - -Creates and throws an invalid result exception. - -#### Syntax - -```plaintext -New-InvalidResultException [-Message] [[-ErrorRecord] ] [] -``` - -### Outputs - -None. - -### Example - -```powershell -try -{ - $numberOfObjects = Get-ChildItem -Path $path - if ($numberOfObjects -eq 0) - { - throw 'To few files.' - } -} -catch -{ - $errorMessage = $script:localizedData.TooFewFilesMessage -f $path - New-InvalidResultException -Message $errorMessage -ErrorRecord $_ -} - -``` - -### `New-NotImplementedException` - -Creates and throws an not implemented exception. - -#### Syntax - -```plaintext -New-NotImplementedException [-Message] [[-ErrorRecord] ] [] -``` - -### Outputs - -None. - -### Example - -```powershell -if ($runFeature) -{ - $errorMessage = $script:localizedData.FeatureMissing -f $path - New-NotImplementedException -Message $errorMessage -ErrorRecord $_ -} -``` - -### `New-ObjectNotFoundException` - -Creates and throws an object not found exception. - -#### Syntax - -```plaintext -New-ObjectNotFoundException [-Message] [[-ErrorRecord] ] [] -``` - -### Outputs - -None. - -### Example - -```powershell -try -{ - Get-ChildItem -Path $path -} -catch -{ - $errorMessage = $script:localizedData.PathNotFoundMessage -f $path - New-ObjectNotFoundException -Message $errorMessage -ErrorRecord $_ -} -``` - -### `Remove-CommonParameter` - -This function serves the purpose of removing common parameters and option -common parameters from a parameter hashtable. - -#### Syntax - -```plaintext -Remove-CommonParameter [-Hashtable] [] -``` - -### Outputs - -**System.Collections.Hashtable** - -### Example - -```powershell -Remove-CommonParameter -Hashtable $PSBoundParameters -``` - -Returns a new hashtable without the common and optional common parameters. - -### `Set-DscMachineRebootRequired` - -Set the DSC reboot required status variable. - -#### Syntax - -```plaintext -Set-DscMachineRebootRequired [] -``` - -### Outputs - -None. - -### Example - -```powershell -Set-DscMachineRebootRequired -``` - -Sets the $global:DSCMachineStatus variable to 1. - -### `Set-PSModulePath` - -This is a wrapper to set environment variable PSModulePath in the current -session or machine wide. - -#### Syntax - -```plaintext -Set-PSModulePath [-Path] [-Machine] [] -``` - -### Outputs - -None. - -### Example - -```powershell -Set-PSModulePath -Path ';' -``` - -Sets the session environment variable `PSModulePath` to the specified path -or paths (separated with semi-colons). - -```powershell -Set-PSModulePath -Path ';' -Machine -``` - -Sets the machine environment variable `PSModulePath` to the specified path -or paths (separated with semi-colons). - -### `Test-AccountRequirePassword` - -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. - -#### Syntax - - -```plaintext -Test-AccountRequirePassword [-Name] [] -``` - - -#### Outputs - -**System.Boolean** - -#### Example - -```powershell -Test-AccountRequirePassword -Name 'DOMAIN\MySqlUser' -``` - -Returns $true as a user account need a password. - -```powershell -Test-AccountRequirePassword -Name 'DOMAIN\MyMSA$' -``` - -Returns $false as a manged service account does not need a password. - -```powershell -Test-AccountRequirePassword -Name 'NT SERVICE\MSSQL$PAYROLL' -``` - -Returns $false as a virtual account does not need a password. - -### `Test-DscParameterState` - -This function is used to compare the values in the current state against -the desired values for any DSC resource. - -This cmdlet was designed to be used in a DSC resource from only _Test_. -The design pattern that uses the cmdlet `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_. - -A new design pattern was introduces that uses the cmdlet [`Compare-ResourcePropertyState`](#compare-resourcepropertystate) - -#### Syntax - - -```plaintext -Test-DscParameterState [-CurrentValues] [-DesiredValues] - [-Properties] [[-ExcludeProperties] ] - [-TurnOffTypeChecking] [-ReverseCheck] [-SortArrayValues] - [] -``` - - -#### Outputs - -**System.Boolean** - -#### Example - -##### Example 1 - - -```powershell -$currentState = Get-TargetResource @PSBoundParameters - -$returnValue = Test-DscParameterState -CurrentValues $currentState -DesiredValues $PSBoundParameters -``` - - -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`. - -##### Example 2 - -```powershell -$getTargetResourceParameters = @{ - ServerName = $ServerName - InstanceName = $InstanceName - Name = $Name -} - -$returnValue = Test-DscParameterState ` - -CurrentValues (Get-TargetResource @getTargetResourceParameters) ` - -DesiredValues $PSBoundParameters ` - -ExcludeProperties @( - 'FailsafeOperator' - 'NotificationMethod' - ) -``` - -##### Example 3 - -```powershell -$getTargetResourceParameters = @{ - ServerName = $ServerName - InstanceName = $InstanceName - Name = $Name -} - -$returnValue = Test-DscParameterState ` - -CurrentValues (Get-TargetResource @getTargetResourceParameters) ` - -DesiredValues $PSBoundParameters ` - -Properties ServerName, Name -``` - -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. - -### `Test-DscProperty` - -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. - -#### Syntax - - -```plaintext - Test-DscProperty [-InputObject] [-Name] [[-Attribute] {Key | Mandatory | NotConfigurable | Optional}] [-HasValue] [] -``` - - -#### Outputs - -**System.Boolean** - -#### Notes - -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]]`. - -#### Example - -```powershell -Test-DscProperty -InputObject $this -Name 'MyDscProperty' -``` - -Returns `$true` or `$false` whether the property exist or not. - -```powershell -$this | Test-DscProperty -Name 'MyDscProperty' -``` - -Returns `$true` or `$false` whether the property exist or not. - -```powershell -Test-DscProperty -InputObject $this -Name 'MyDscProperty' -HasValue -``` - -Returns `$true` if the property exist and is assigned a non-null value, if not -`$false` is returned. - -```powershell -Test-DscProperty -InputObject $this -Name 'MyDscProperty' -Attribute 'Optional' -``` - -Returns `$true` if the property exist and is an optional property. - -```powershell -Test-DscProperty -InputObject $this -Name 'MyDscProperty' -Attribute 'Optional' -HasValue -``` - -Returns `$true` if the property exist, is an optional property, and is -assigned a non-null value. - -### `Test-IsNanoServer` - -This function tests if the current OS is a Nano server. - -#### Syntax - -```plaintext -Test-IsNanoServer [] -``` - -#### Outputs - -**System.Boolean** - -#### Example - -```powershell -if ((Test-IsNanoServer)) { - 'Nano server' -} -``` - -### `Test-IsNumericType` - -Returns whether the specified object is of a numeric type: - -- [System.Byte] -- [System.Int16] -- [System.Int32] -- [System.Int64] -- [System.SByte] -- [System.UInt16] -- [System.UInt32] -- [System.UInt64] -- [System.Decimal] -- [System.Double] -- [System.Single] - -#### Syntax - - -```plaintext -Test-IsNumericType [[-Object] ] [] -``` - - -#### Outputs - -**System.Boolean** - -#### Example - -```powershell -Test-IsNumericType -Object ([System.UInt32] 3) -``` - -Returns `$true` since the value is a numeric type. - -```powershell -([System.String] 'a') | Test-IsNumericType -``` - -Returns `$false` since the value is not a numeric type. +See the article [DscResource.Common functions in a DSC module](https://dsccommunity.org/blog/use-dscresource-common-functions-in-module/) +describing how to convert a DSC resource module to use DscResource.Common. -```powershell -('a', 2, 'b') | Test-IsNumericType -``` +### Commands -Returns `$true` since one of the values passed in the pipeline is of a -numeric type. - +The documentation can be found in the [DscResource.Common Wiki](https://github.com/dsccommunity/DscResource.Common/wiki). +It is updated automatically for each release that is deployed. diff --git a/RequiredModules.psd1 b/RequiredModules.psd1 index 0c5d3c0..477b6c5 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -19,5 +19,8 @@ 'DscResource.AnalyzerRules' = 'latest' xDscResourceDesigner = 'latest' 'DscResource.Test' = 'latest' - 'DscResource.DocGenerator' = 'latest' + + # Prerequisite modules for documentation. + 'DscResource.DocGenerator' = 'latest' + PlatyPS = 'latest' } diff --git a/build.yaml b/build.yaml index c954a63..325ca24 100644 --- a/build.yaml +++ b/build.yaml @@ -24,6 +24,12 @@ BuildWorkflow: - Build_NestedModules_ModuleBuilder - Create_changelog_release_output - Generate_Wiki_Content + - Generate_Conceptual_Help + - Generate_Markdown_For_Public_Commands + - Generate_External_Help_File_For_Public_Commands + - Clean_Markdown_Of_Public_Commands + - Generate_Wiki_Sidebar + - Clean_Markdown_Metadata pack: - build @@ -131,3 +137,31 @@ GitHubConfig: GitHubConfigUserName: dscbot GitHubConfigUserEmail: dsccommunity@outlook.com UpdateChangelogOnPrerelease: false + +#################################################### +# DscResource.DocGenerator Configuration # +#################################################### +DscResource.DocGenerator: + Generate_Conceptual_Help: + MarkdownCodeRegularExpression: + - '\`(.+?)\`' # Match inline code-block + - '\\(\\)' # Match escaped backslash + - '\[[^\[]+\]\((.+?)\)' # Match markdown URL + - '_(.+?)_' # Match Italic (underscore) + - '\*\*(.+?)\*\*' # Match bold + - '\*(.+?)\*' # Match Italic (asterisk) + Publish_GitHub_Wiki_Content: + Debug: false + Generate_Wiki_Content: + MofResourceMetadata: + Type: MofResource + Category: Resources + ClassResourceMetadata: + Type: ClassResource + Category: Resources + CompositeResourceMetadata: + Type: CompositeResource + Category: Resources + Generate_Wiki_Sidebar: + Debug: false + AlwaysOverwrite: true diff --git a/source/Private/Test-DscPropertyState.ps1 b/source/Private/Test-DscPropertyState.ps1 index 0f279ca..aacfaf8 100644 --- a/source/Private/Test-DscPropertyState.ps1 +++ b/source/Private/Test-DscPropertyState.ps1 @@ -23,7 +23,7 @@ } .NOTES - This function is used by the cmdlet Compare-ResourcePropertyState. + This function is used by the command Compare-ResourcePropertyState. #> function Test-DscPropertyState { diff --git a/source/Public/Assert-BoundParameter.ps1 b/source/Public/Assert-BoundParameter.ps1 index 5b7702b..05db80c 100644 --- a/source/Public/Assert-BoundParameter.ps1 +++ b/source/Public/Assert-BoundParameter.ps1 @@ -4,8 +4,24 @@ mutually exclusive lists. .DESCRIPTION - Throws an error if there is a bound parameter that exists in both the - mutually exclusive lists. + This command asserts passed parameters. It takes a hashtable, normally + `$PSBoundParameters`. There are two parameter sets for this command. + + >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. .PARAMETER BoundParameterList The parameters that should be evaluated against the mutually exclusive @@ -38,7 +54,6 @@ 'Parameter2' ) } - Assert-BoundParameter @assertBoundParameterParameters This example throws an exception if `$PSBoundParameters` contains both @@ -52,7 +67,8 @@ .EXAMPLE Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('Property2', 'Property3') -IfParameterPresent @('Property1') - Throws an exception if the parameter 'Property1' is specified and either of the required parameters are not. + Throws an exception if the parameter 'Property1' is specified and either + of the required parameters are not. #> function Assert-BoundParameter { diff --git a/source/Public/Assert-ElevatedUser.ps1 b/source/Public/Assert-ElevatedUser.ps1 index 9fb1a9c..6ae3df3 100644 --- a/source/Public/Assert-ElevatedUser.ps1 +++ b/source/Public/Assert-ElevatedUser.ps1 @@ -3,13 +3,21 @@ Assert that the user has elevated the PowerShell session. .DESCRIPTION - Assert that the user has elevated the PowerShell session. + 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. .EXAMPLE Assert-ElevatedUser Throws an exception if the user has not elevated the PowerShell session. + .EXAMPLE + `Assert-ElevatedUser -ErrorAction 'Stop'` + + This example stops the entire script if it is not run from an + elevated PowerShell session. + .OUTPUTS None. #> diff --git a/source/Public/Assert-IPAddress.ps1 b/source/Public/Assert-IPAddress.ps1 index 6c9ca96..32b8f4a 100644 --- a/source/Public/Assert-IPAddress.ps1 +++ b/source/Public/Assert-IPAddress.ps1 @@ -1,6 +1,7 @@ <# .SYNOPSIS - Asserts that the specified IP address is valid. + Asserts if the IP Address is valid and optionally validates + the IP Address against an Address Family. .DESCRIPTION Checks the IP address so that it is valid and do not conflict with address @@ -16,21 +17,21 @@ .EXAMPLE Assert-IPAddress -Address '127.0.0.1' - This will assert that the supplied address is a valid IPv4 address. - If it is not an exception will be thrown. + This will assert that the supplied address is a valid IPv4 address. If it + is not an exception will be thrown. .EXAMPLE Assert-IPAddress -Address 'fe80:ab04:30F5:002b::1' - This will assert that the supplied address is a valid IPv6 address. - If it is not an exception will be thrown. + This will assert that the supplied address is a valid IPv6 address. If it + is not an exception will be thrown. .EXAMPLE Assert-IPAddress -Address 'fe80:ab04:30F5:002b::1' -AddressFamily 'IPv6' - 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. + 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. #> function Assert-IPAddress { diff --git a/source/Public/Assert-Module.ps1 b/source/Public/Assert-Module.ps1 index 0da2a55..045e30c 100644 --- a/source/Public/Assert-Module.ps1 +++ b/source/Public/Assert-Module.ps1 @@ -1,9 +1,11 @@ <# .SYNOPSIS - Assert if the specific module is available to be imported. + Assert if the specific module is available to be imported and optionally + import the module. .DESCRIPTION - Assert if the specific module is available to be imported. + Assert if the specific module is available to be imported and optionally + import the module. .PARAMETER ModuleName Specifies the name of the module to assert. @@ -19,19 +21,21 @@ .EXAMPLE Assert-Module -ModuleName 'DhcpServer' - This asserts that the module DhcpServer is available on the system. + This asserts that the module DhcpServer is available on the system. If it + is not an exception will be thrown. .EXAMPLE Assert-Module -ModuleName 'DhcpServer' -ImportModule This asserts that the module DhcpServer is available on the system and - imports it. + imports it. If the module is not available an exception will be thrown. .EXAMPLE Assert-Module -ModuleName 'DhcpServer' -ImportModule -Force - This asserts that the module DhcpServer is available on the system and - forcibly imports it. + 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. #> function Assert-Module { diff --git a/source/Public/Compare-DscParameterState.ps1 b/source/Public/Compare-DscParameterState.ps1 index 57ae442..0fc7889 100644 --- a/source/Public/Compare-DscParameterState.ps1 +++ b/source/Public/Compare-DscParameterState.ps1 @@ -7,6 +7,11 @@ the current values present on the system, and return a hashtable with the metadata from the comparison. + >[!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. + .PARAMETER CurrentValues A hashtable with the current values on the system, obtained by e.g. Get-TargetResource. @@ -39,7 +44,23 @@ By default, this command returns only the properties not in desired state. .PARAMETER IncludeValue - Indicates that result contains the ActualValue and ExcpectedValue properties. + Indicates that result contains the ActualValue and ExpectedValue properties. + + .OUTPUTS + System.Object[] + + .NOTES + Returns an array containing a PSCustomObject with metadata for each property + that was evaluated. + + 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. .EXAMPLE $currentValues = @{ @@ -47,22 +68,12 @@ Int = 1 Bool = $true } - $desiredValues = @{ String = 'This is a string' Int = 99 } - Compare-DscParameterState -CurrentValues $currentValues -DesiredValues $desiredValues - Name Value - ---- ----- - Property Int - InDesiredState False - ExpectedType System.Int32 - ActualType System.Int32 - ``` - 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. @@ -74,28 +85,17 @@ Int = 1 Bool = $true } - $desiredValues = @{ String = 'This is a string' Int = 99 Bool = $false } - $excludeProperties = @('Bool') - Compare-DscParameterState ` -CurrentValues $currentValues ` -DesiredValues $desiredValues ` -ExcludeProperties $ExcludeProperties - Name Value - ---- ----- - Property Int - InDesiredState False - ExpectedType System.Int32 - ActualType System.Int32 - ``` - 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. @@ -105,7 +105,6 @@ $serviceParameters = @{ Name = $Name } - $returnValue = Compare-DscParameterState ` -CurrentValues (Get-Service @serviceParameters) ` -DesiredValues $PSBoundParameters ` diff --git a/source/Public/Compare-ResourcePropertyState.ps1 b/source/Public/Compare-ResourcePropertyState.ps1 index 9862b8b..0e6f24c 100644 --- a/source/Public/Compare-ResourcePropertyState.ps1 +++ b/source/Public/Compare-ResourcePropertyState.ps1 @@ -1,11 +1,30 @@ <# .SYNOPSIS - Compare current and desired property values for any DSC resource. + Compare current and desired property values for any DSC resource and return + a hashtable with the metadata from the comparison. .DESCRIPTION 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. + 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. + + >[!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). + + See the other design patterns that uses the command [`Compare-DscParameterState`](Compare-DscParameterState) + or [`Test-DscParameterState`](Test-DscParameterState). + .PARAMETER CurrentValues The current values that should be compared to to desired values. Normally the values returned from Get-TargetResource. @@ -33,17 +52,82 @@ Permission = @('State') } + .OUTPUTS + System.Collections.Hashtable[] + + .NOTES + Returns an array containing a hashtable with metadata for each property + that was evaluated. + + 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. + .EXAMPLE $compareTargetResourceStateParameters = @{ CurrentValues = (Get-TargetResource $PSBoundParameters) DesiredValues = $PSBoundParameters } - $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters + $propertiesNotInDesiredState = $propertyState.Where({ -not $_.InDesiredState }) - This examples call Compare-ResourcePropertyState with the current state + 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. + + .EXAMPLE + $compareTargetResourceStateParameters = @{ + CurrentValues = (Get-TargetResource $PSBoundParameters) + DesiredValues = $PSBoundParameters + Properties = @( + 'Property1' + ) + } + $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters + $false -in $propertyState.InDesiredState + + 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`. + + .EXAMPLE + $compareTargetResourceStateParameters = @{ + CurrentValues = (Get-TargetResource $PSBoundParameters) + DesiredValues = $PSBoundParameters + IgnoreProperties = @( + 'Property1' + ) + } + $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters + + 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`. + + .EXAMPLE + $compareTargetResourceStateParameters = @{ + CurrentValues = (Get-TargetResource $PSBoundParameters) + DesiredValues = $PSBoundParameters + CimInstanceKeyProperties = @{ + ResourceProperty1 = @( + 'CimProperty1' + ) + } + } + $propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters + + 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. #> function Compare-ResourcePropertyState { diff --git a/source/Public/ConvertFrom-DscResourceInstance.ps1 b/source/Public/ConvertFrom-DscResourceInstance.ps1 index 02f4bb7..7c8ea0b 100644 --- a/source/Public/ConvertFrom-DscResourceInstance.ps1 +++ b/source/Public/ConvertFrom-DscResourceInstance.ps1 @@ -1,50 +1,47 @@ - <# .SYNOPSIS Convert any object to hashtable. .DESCRIPTION - This function is used to convert a psobject into a hashtable. + This function is used to convert a PSObject into a hashtable. .PARAMETER InputObject The object that should be convert to hashtable. - .PARAMETER OutPutFormat + .PARAMETER OutputFormat Set the format you do want to convert the object. The default value is HashTable. It's the only value accepted at this time. .OUTPUTS - Hashtable + System.Collections.Hashtable .EXAMPLE + $object = [PSCustomObject] = @{ + FirstName = 'John' + LastName = 'Smith' + } + ConvertFrom-DscResourceInstance -InputObject $object - $Object = [pscustomobject]=@{ - FirstName = 'John' - LastName = 'Smith' - } - - ConvertFrom-DscResourceInstance -InputObject $Object - - This creates a pscustomobject and converts its properties/values to Hashtable Key/Value. + This creates a PSCustomObject and converts its properties and values to + key/value pairs in a hashtable. .EXAMPLE + $objectArray = [PSCustomObject] = @{ + FirstName = 'John' + LastName = 'Smith' + }, [PSCustomObject] = @{ + FirstName = 'Peter' + LastName = 'Smith' + } + $objectArray | ConvertFrom-DscResourceInstance - $ObjectArray = [pscustomobject]=@{ - FirstName = 'John' - LastName = 'Smith' - },[pscustomobject]=@{ - FirstName = 'Peter' - LastName = 'Smith' - } - - $ObjectArray | ConvertFrom-DscResourceInstance - - This creates pscustomobjects and converts there properties/values to Hashtable Keys/Values through the pipeline. + This creates an array of PSCustomObject and converts their properties and + values to key/value pairs in a hashtable. #> function ConvertFrom-DscResourceInstance { [CmdletBinding()] - [OutputType([Hashtable])] + [OutputType([System.Collections.Hashtable])] param ( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] @@ -54,25 +51,27 @@ function ConvertFrom-DscResourceInstance [Parameter()] [ValidateSet('HashTable')] [String] - $OutPutFormat = 'HashTable' + $OutputFormat = 'HashTable' ) - process { - switch ($OutPutFormat) + process + { + switch ($OutputFormat) { 'HashTable' { - $Result = @{} + $result = @{} + foreach ($obj in $InputObject) { - $obj.psobject.Properties | Foreach-Object { - $Result[$_.Name] = $_.Value + $obj.PSObject.Properties | Foreach-Object { + $result[$_.Name] = $_.Value } } } } - return $Result + return $result } } diff --git a/source/Public/ConvertTo-CimInstance.ps1 b/source/Public/ConvertTo-CimInstance.ps1 index 7189853..9ff4372 100644 --- a/source/Public/ConvertTo-CimInstance.ps1 +++ b/source/Public/ConvertTo-CimInstance.ps1 @@ -11,7 +11,7 @@ A hashtable with the values to convert. .OUTPUTS - An object array with CimInstance objects. + System.Object[] .EXAMPLE ConvertTo-CimInstance -Hashtable @{ diff --git a/source/Public/ConvertTo-HashTable.ps1 b/source/Public/ConvertTo-HashTable.ps1 index e456947..a671670 100644 --- a/source/Public/ConvertTo-HashTable.ps1 +++ b/source/Public/ConvertTo-HashTable.ps1 @@ -10,7 +10,7 @@ An array of CimInstances or a single CimInstance object to convert. .OUTPUTS - Hashtable + System.Collections.Hashtable .EXAMPLE $newInstanceParameters = @{ @@ -18,22 +18,19 @@ 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 - This creates a array om CimInstances of the class name MSFT_KeyValuePair + This creates a array of CimInstances using the class name MSFT_KeyValuePair and passes it to ConvertTo-HashTable which returns a hashtable. #> function ConvertTo-HashTable diff --git a/source/Public/Find-Certificate.ps1 b/source/Public/Find-Certificate.ps1 index 58523b4..136207d 100644 --- a/source/Public/Find-Certificate.ps1 +++ b/source/Public/Find-Certificate.ps1 @@ -2,13 +2,14 @@ .SYNOPSIS 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. - .DESCRIPTION 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. + 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. + .PARAMETER Thumbprint The thumbprint of the certificate to find. @@ -37,6 +38,9 @@ .PARAMETER AllowExpired Allows expired certificates to be returned. + .OUTPUTS + System.Security.Cryptography.X509Certificates.X509Certificate2 + .EXAMPLE Find-Certificate -Thumbprint '1111111111111111111111111111111111111111' @@ -53,25 +57,25 @@ Return certificate(s) filtered on specific DNS Names. .EXAMPLE - find-certificate -Subject 'CN=contoso, DC=com' + Find-Certificate -Subject 'CN=contoso, DC=com' Return certificate(s) with specific subject. .EXAMPLE - find-certificate -Issuer 'CN=contoso-ca, DC=com' -AllowExpired $true + Find-Certificate -Issuer 'CN=contoso-ca, DC=com' -AllowExpired $true Return all certificates from specific issuer, including expired certificates. .EXAMPLE - Find-Certificate -EnhancedKeyUsage 'Server Authentication' -AllowExpired $true + Find-Certificate -EnhancedKeyUsage @('Client authentication','Server Authentication') -AllowExpired $true - Return all certificates that can be used for "Server Authentication", including expired certificates. + Return all certificates that can be used for server or client authentication, + including expired certificates. .EXAMPLE Find-Certificate -FriendlyName 'My IIS Site SSL Cert' Return certificate based on FriendlyName. - #> function Find-Certificate { diff --git a/source/Public/Get-ComputerName.ps1 b/source/Public/Get-ComputerName.ps1 index 343a84e..6c6a02d 100644 --- a/source/Public/Get-ComputerName.ps1 +++ b/source/Public/Get-ComputerName.ps1 @@ -3,14 +3,18 @@ Returns the computer name cross-plattform. .DESCRIPTION - The variable `$env:COMPUTERNAME` does not exist cross-platform which - hinders development and testing on macOS and Linux. Instead this cmdlet - can be used to get the computer name cross-plattform. + 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. + + .OUTPUTS + System.String .EXAMPLE Get-ComputerName - This example returns the computer name cross-plattform. + Returns the computer name regardless of platform. #> function Get-ComputerName { diff --git a/source/Public/Get-DscProperty.ps1 b/source/Public/Get-DscProperty.ps1 index 34c88c1..d9693f4 100644 --- a/source/Public/Get-DscProperty.ps1 +++ b/source/Public/Get-DscProperty.ps1 @@ -1,4 +1,3 @@ - <# .SYNOPSIS Returns DSC resource properties that is part of a class-based DSC resource. @@ -6,7 +5,7 @@ .DESCRIPTION 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 value. + assigned a non-null value. .PARAMETER InputObject The object that contain one or more key properties. @@ -27,6 +26,9 @@ If left out all properties are returned regardless if there is a value assigned or not. + .OUTPUTS + System.Collections.Hashtable + .EXAMPLE Get-DscProperty -InputObject $this diff --git a/source/Public/Get-EnvironmentVariable.ps1 b/source/Public/Get-EnvironmentVariable.ps1 index 20eec1d..073e02c 100644 --- a/source/Public/Get-EnvironmentVariable.ps1 +++ b/source/Public/Get-EnvironmentVariable.ps1 @@ -1,10 +1,10 @@ - <# .SYNOPSIS Returns the value from an environment variable from a specified target. .DESCRIPTION Returns the value from an environment variable from a specified target. + This command returns `$null` if the environment variable does not exist. .PARAMETER Name Specifies the environment variable name. @@ -12,6 +12,9 @@ .PARAMETER FromTarget Specifies the target to return the value from. Defaults to 'Session'. + .OUTPUTS + System.String + .EXAMPLE Get-EnvironmentVariable -Name 'PSModulePath' diff --git a/source/Public/Get-LocalizedData.ps1 b/source/Public/Get-LocalizedData.ps1 index 94adab6..e186e02 100644 --- a/source/Public/Get-LocalizedData.ps1 +++ b/source/Public/Get-LocalizedData.ps1 @@ -1,19 +1,20 @@ - <# .SYNOPSIS Gets language-specific data into scripts and functions based on the UI culture - that is selected for the operating system. - Similar to Import-LocalizedData, with extra parameter 'DefaultUICulture'. + that is specified or that is selected for the operating system. .DESCRIPTION - The Get-LocalizedData cmdlet dynamically retrieves strings from a subdirectory + 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. + Optionally the `Get-LocalizedData` saves the hash table in the variable + that is specified by the value of the `BindingVariable` parameter. + 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 cmdlet selects the subdirectory and file based on the value of 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. @@ -21,7 +22,7 @@ path, and file name, to add supported commands, and to suppress the error message that appears if the .psd1 files are not found. - The G-LocalizedData cmdlet supports the script internationalization + 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 @@ -69,6 +70,10 @@ imported data will replace the default text strings. If you are not specifying default text strings, you can select any variable name. + 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. + .PARAMETER UICulture Specifies an alternate UI culture. The default is the value of the $PsUICulture automatic variable. Enter a UI culture in - format, such as @@ -78,7 +83,7 @@ (within the base directory) from which Import-LocalizedData gets the .psd1 file for the script. - The cmdlet searches for a subdirectory with the same name as the value of the + 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 @@ -157,6 +162,22 @@ For more information, see about_Script_Internationalization. + This command should preferably be used at the top of each resource PowerShell + module script file (.psm1). + + It will automatically look for a file in the folder for the current UI + culture, or default to the UI culture folder 'en-US'. + + The localized strings file can be named either `.psd1`, + e.g. `DSC_MyResource.psd1`, or suffixed with `strings`, e.g. + `DSC_MyResource.strings.psd1`. + + Read more about localization in the section [Localization](https://dsccommunity.org/styleguidelines/localization/) + in the DSC Community style guideline. + + .OUTPUTS + System.Collections.Hashtable + .EXAMPLE $script:localizedData = Get-LocalizedData diff --git a/source/Public/Get-LocalizedDataForInvariantCulture.ps1 b/source/Public/Get-LocalizedDataForInvariantCulture.ps1 index 8c4d98d..162db08 100644 --- a/source/Public/Get-LocalizedDataForInvariantCulture.ps1 +++ b/source/Public/Get-LocalizedDataForInvariantCulture.ps1 @@ -1,4 +1,3 @@ - <# .SYNOPSIS Gets language-specific data when the culture is invariant. diff --git a/source/Public/Get-PSModulePath.ps1 b/source/Public/Get-PSModulePath.ps1 index a85f820..3373c75 100644 --- a/source/Public/Get-PSModulePath.ps1 +++ b/source/Public/Get-PSModulePath.ps1 @@ -1,4 +1,3 @@ - <# .SYNOPSIS Returns the environment variable PSModulePath from the specified target. @@ -6,11 +5,15 @@ .DESCRIPTION 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. + concatenation of all unique paths from the targets. If there are no paths + to return the command will return an empty string. .PARAMETER FromTarget Specifies the target to get the PSModulePath from. + .OUTPUTS + System.String + .EXAMPLE Get-PSModulePath -FromTarget 'Session' diff --git a/source/Public/Get-TemporaryFolder.ps1 b/source/Public/Get-TemporaryFolder.ps1 index 5c22822..b27415f 100644 --- a/source/Public/Get-TemporaryFolder.ps1 +++ b/source/Public/Get-TemporaryFolder.ps1 @@ -5,12 +5,21 @@ .DESCRIPTION Returns the path of the current user's temporary folder. + .OUTPUTS + System.String + .NOTES This is the same as doing the following - Windows: $env:TEMP - macOS: $env:TMPDIR - Linux: /tmp/ + Examples of what the command returns: + + - Windows: C:\Users\username\AppData\Local\Temp\ + - macOS: /var/folders/6x/thq2xce46bc84lr66fih2p5h0000gn/T/ + - Linux: /tmp/ + .EXAMPLE Get-TemporaryFolder diff --git a/source/Public/New-InvalidArgumentException.ps1 b/source/Public/New-InvalidArgumentException.ps1 index ff73fa9..75d507e 100644 --- a/source/Public/New-InvalidArgumentException.ps1 +++ b/source/Public/New-InvalidArgumentException.ps1 @@ -11,11 +11,14 @@ .PARAMETER ArgumentName The name of the invalid argument that is causing this error to be thrown. + .OUTPUTS + None + .EXAMPLE - $errorMessage = $script:localizedData.ActionCannotBeUsedInThisContextMessage ` - -f $Action, $Parameter + New-InvalidArgumentException -ArgumentName 'Action' -Message 'My error message' - New-InvalidArgumentException -ArgumentName 'Action' -Message $errorMessage + Creates and throws an invalid argument exception for (parameter) 'Action' + with the message 'My error message'. #> function New-InvalidArgumentException { diff --git a/source/Public/New-InvalidDataException.ps1 b/source/Public/New-InvalidDataException.ps1 index 17229ce..35e31d5 100644 --- a/source/Public/New-InvalidDataException.ps1 +++ b/source/Public/New-InvalidDataException.ps1 @@ -5,6 +5,9 @@ .DESCRIPTION Creates and throws an invalid data exception. + .OUTPUTS + None + .PARAMETER ErrorId The error Id to assign to the exception. @@ -12,12 +15,10 @@ The error message to assign to the exception. .EXAMPLE - if ( -not $resultOfEvaluation ) - { - $errorMessage = $script:localizedData.InvalidData -f $Action + New-InvalidDataException -ErrorId 'InvalidDataError' -ErrorMessage 'My error message' - New-InvalidDataException -ErrorId 'InvalidDataError' -ErrorMessage $errorMessage - } + Creates and throws an invalid data exception with the error id 'InvalidDataError' + and with the message 'My error message'. #> function New-InvalidDataException { diff --git a/source/Public/New-InvalidOperationException.ps1 b/source/Public/New-InvalidOperationException.ps1 index 189dc9c..90ba5f8 100644 --- a/source/Public/New-InvalidOperationException.ps1 +++ b/source/Public/New-InvalidOperationException.ps1 @@ -5,6 +5,9 @@ .DESCRIPTION Creates and throws an invalid operation exception. + .OUTPUTS + None + .PARAMETER Message The message explaining why this error is being thrown. @@ -18,9 +21,11 @@ } catch { - $errorMessage = $script:localizedData.InstallationFailedMessage -f $Path, $processId - New-InvalidOperationException -Message $errorMessage -ErrorRecord $_ + New-InvalidOperationException -Message 'My error message' -ErrorRecord $_ } + + Creates and throws an invalid operation exception with the message 'My error message' + and includes the exception that caused this terminating error. #> function New-InvalidOperationException { diff --git a/source/Public/New-InvalidResultException.ps1 b/source/Public/New-InvalidResultException.ps1 index 4e8d27b..3dec5ed 100644 --- a/source/Public/New-InvalidResultException.ps1 +++ b/source/Public/New-InvalidResultException.ps1 @@ -11,20 +11,30 @@ .PARAMETER ErrorRecord The error record containing the exception that is causing this terminating error. + .OUTPUTS + None + + .EXAMPLE + $numberOfObjects = Get-ChildItem -Path $path + if ($numberOfObjects -eq 0) + { + New-InvalidResultException -Message 'To few files' + } + + Creates and throws an invalid result exception with the message 'To few files' + .EXAMPLE try { $numberOfObjects = Get-ChildItem -Path $path - if ($numberOfObjects -eq 0) - { - throw 'To few files.' - } } catch { - $errorMessage = $script:localizedData.TooFewFilesMessage -f $path - New-InvalidResultException -Message $errorMessage -ErrorRecord $_ + New-InvalidResultException -Message 'Missing files' -ErrorRecord $_ } + + Creates and throws an invalid result exception with the message 'Missing files' + and includes the exception that caused this terminating error. #> function New-InvalidResultException { diff --git a/source/Public/New-NotImplementedException.ps1 b/source/Public/New-NotImplementedException.ps1 index aa3e6b6..855819c 100644 --- a/source/Public/New-NotImplementedException.ps1 +++ b/source/Public/New-NotImplementedException.ps1 @@ -11,15 +11,17 @@ .PARAMETER ErrorRecord The error record containing the exception that is causing this terminating error. + .OUTPUTS + None + .EXAMPLE - if ($runFeature) + if ($notImplementedFeature) { - $errorMessage = $script:localizedData.FeatureMissing -f $path - New-NotImplementedException -Message $errorMessage -ErrorRecord $_ + New-NotImplementedException -Message 'This feature is not implemented yet' } - Throws an not implemented exception if the variable $runFeature contains - a value. + Creates and throws an not implemented exception with the message 'This feature + is not implemented yet' #> function New-NotImplementedException { diff --git a/source/Public/New-ObjectNotFoundException.ps1 b/source/Public/New-ObjectNotFoundException.ps1 index d85254d..2eec32c 100644 --- a/source/Public/New-ObjectNotFoundException.ps1 +++ b/source/Public/New-ObjectNotFoundException.ps1 @@ -1,4 +1,3 @@ - <# .SYNOPSIS Creates and throws an object not found exception. @@ -6,12 +5,18 @@ .DESCRIPTION Creates and throws an object not found exception. + .OUTPUTS + None + .PARAMETER Message The message explaining why this error is being thrown. .PARAMETER ErrorRecord The error record containing the exception that is causing this terminating error. + .OUTPUTS + None + .EXAMPLE try { @@ -19,9 +24,11 @@ } catch { - $errorMessage = $script:localizedData.PathNotFoundMessage -f $path - New-ObjectNotFoundException -Message $errorMessage -ErrorRecord $_ + New-ObjectNotFoundException -Message 'COuld not get files' -ErrorRecord $_ } + + Creates and throws an object not found exception with the message 'Could not + get files' and includes the exception that caused this terminating error. #> function New-ObjectNotFoundException { diff --git a/source/Public/Remove-CommonParameter.ps1 b/source/Public/Remove-CommonParameter.ps1 index 48a9829..36b8d3d 100644 --- a/source/Public/Remove-CommonParameter.ps1 +++ b/source/Public/Remove-CommonParameter.ps1 @@ -6,6 +6,9 @@ This function serves the purpose of removing common parameters and option common parameters from a parameter hashtable. + .OUTPUTS + System.Collections.Hashtable + .PARAMETER Hashtable The parameter hashtable that should be pruned. diff --git a/source/Public/Set-DscMachineRebootRequired.ps1 b/source/Public/Set-DscMachineRebootRequired.ps1 index 281453f..0771dc7 100644 --- a/source/Public/Set-DscMachineRebootRequired.ps1 +++ b/source/Public/Set-DscMachineRebootRequired.ps1 @@ -7,10 +7,13 @@ This function is used to set the global variable that indicates to the LCM that a reboot of the node is required. + .OUTPUTS + None + .EXAMPLE - PS C:\> Set-DscMachineRebootRequired + Set-DscMachineRebootRequired - Sets the $global:DSCMachineStatus variable to 1. + Sets the `$global:DSCMachineStatus` variable to 1. .NOTES This function is implemented so that individual resource modules diff --git a/source/Public/Set-PSModulePath.ps1 b/source/Public/Set-PSModulePath.ps1 index 8bb04cc..82f7e58 100644 --- a/source/Public/Set-PSModulePath.ps1 +++ b/source/Public/Set-PSModulePath.ps1 @@ -1,13 +1,15 @@ - <# .SYNOPSIS Set environment variable PSModulePath in the current session or machine wide. .DESCRIPTION - This is a wrapper to set environment variable PSModulePath in current + This is a command to set environment variable PSModulePath in current session or machine wide. + .OUTPUTS + None + .PARAMETER Path A string with all the paths separated by semi-colons. @@ -18,8 +20,14 @@ .EXAMPLE Set-PSModulePath -Path ';' + Sets the session environment variable `PSModulePath` to the specified path + or paths (separated with semi-colons). + .EXAMPLE Set-PSModulePath -Path ';' -Machine + + Sets the machine environment variable `PSModulePath` to the specified path + or paths (separated with semi-colons). #> function Set-PSModulePath { diff --git a/source/Public/Test-AccountRequirePassword.ps1 b/source/Public/Test-AccountRequirePassword.ps1 index 986c86a..792a491 100644 --- a/source/Public/Test-AccountRequirePassword.ps1 +++ b/source/Public/Test-AccountRequirePassword.ps1 @@ -13,17 +13,17 @@ .EXAMPLE Test-AccountRequirePassword -Name 'DOMAIN\MyMSA$' - Returns $false as a manged service account does not need a password. + Returns `$false` as a manged service account does not need a password. .EXAMPLE Test-AccountRequirePassword -Name 'DOMAIN\MySqlUser' - Returns $true as a user account need a password. + Returns `$true` as a user account need a password. .EXAMPLE Test-AccountRequirePassword -Name 'NT SERVICE\MSSQL$PAYROLL' - Returns $false as a virtual account does not need a password. + Returns `$false`as a virtual account does not need a password. .OUTPUTS [System.Boolean] diff --git a/source/Public/Test-DscParameterState.ps1 b/source/Public/Test-DscParameterState.ps1 index 1ae7944..b727254 100644 --- a/source/Public/Test-DscParameterState.ps1 +++ b/source/Public/Test-DscParameterState.ps1 @@ -1,11 +1,16 @@ <# .SYNOPSIS - This method is used to test current and desired values for any DSC resource. + This command is used to test current and desired values for any DSC resource. .DESCRIPTION This function tests the parameter status of DSC resource parameters against the current values present on the system. + 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_. + .PARAMETER CurrentValues A hashtable with the current values on the system, obtained by e.g. Get-TargetResource. @@ -33,14 +38,18 @@ If the sorting of array values does not matter, values are sorted internally before doing the comparison. + .OUTPUTS + [System.Boolean] + .EXAMPLE $currentState = Get-TargetResource @PSBoundParameters - $returnValue = Test-DscParameterState -CurrentValues $currentState -DesiredValues $PSBoundParameters 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`. + desired state by calling `Test-DscParameterState`. The result is either + `$true` or `$false`, `$false` if one or more properties are not in desired + state. .EXAMPLE $getTargetResourceParameters = @{ @@ -48,7 +57,6 @@ InstanceName = $InstanceName Name = $Name } - $returnValue = Test-DscParameterState ` -CurrentValues (Get-TargetResource @getTargetResourceParameters) ` -DesiredValues $PSBoundParameters ` @@ -60,8 +68,9 @@ 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. + 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. .EXAMPLE $getTargetResourceParameters = @{ @@ -69,7 +78,6 @@ InstanceName = $InstanceName Name = $Name } - $returnValue = Test-DscParameterState ` -CurrentValues (Get-TargetResource @getTargetResourceParameters) ` -DesiredValues $PSBoundParameters ` diff --git a/source/Public/Test-DscProperty.ps1 b/source/Public/Test-DscProperty.ps1 index 08432ec..5464edb 100644 --- a/source/Public/Test-DscProperty.ps1 +++ b/source/Public/Test-DscProperty.ps1 @@ -3,7 +3,9 @@ Tests whether the class-based resource has the specified property. .DESCRIPTION - Tests whether the class-based resource has the specified property. + 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. .PARAMETER InputObject Specifies the object that should be tested for existens of the specified @@ -21,21 +23,24 @@ If the property exist but is not the specific attribute the command returns `$false`. + .OUTPUTS + [System.Boolean] + .EXAMPLE Test-DscProperty -InputObject $this -Name 'MyDscProperty' - Returns $true or $false whether the property exist or not. + Returns `$true` or `$false` whether the property exist or not. .EXAMPLE $this | Test-DscProperty -Name 'MyDscProperty' - Returns $true or $false whether the property exist or not. + Returns `$true` or `$false` whether the property exist or not. .EXAMPLE Test-DscProperty -InputObject $this -Name 'MyDscProperty' -HasValue - Returns $true if the property exist and is assigned a non-null value, if not - $false is returned. + Returns `$true` if the property exist and is assigned a non-null value, + if not `$false` is returned. .EXAMPLE Test-DscProperty -InputObject $this -Name 'MyDscProperty' -Attribute 'Optional' diff --git a/source/Public/Test-IsNanoServer.ps1 b/source/Public/Test-IsNanoServer.ps1 index 1efcc83..0991d47 100644 --- a/source/Public/Test-IsNanoServer.ps1 +++ b/source/Public/Test-IsNanoServer.ps1 @@ -5,10 +5,13 @@ .DESCRIPTION Tests if the current OS is a Nano server. + .OUTPUTS + [System.Boolean] + .EXAMPLE Test-IsNanoServer - Returns $true if the current operating system is Nano Server, if not $false + Returns `$true` if the current operating system is Nano Server, if not `$false` is returned. #> function Test-IsNanoServer diff --git a/source/Public/Test-IsNumericType.ps1 b/source/Public/Test-IsNumericType.ps1 index 68793c2..ea7639b 100644 --- a/source/Public/Test-IsNumericType.ps1 +++ b/source/Public/Test-IsNumericType.ps1 @@ -3,7 +3,19 @@ Returns whether the specified object is of a numeric type. .DESCRIPTION - Returns whether the specified object is of a numeric type. + Returns whether the specified object is of a numeric type: + + - [System.Byte] + - [System.Int16] + - [System.Int32] + - [System.Int64] + - [System.SByte] + - [System.UInt16] + - [System.UInt32] + - [System.UInt64] + - [System.Decimal] + - [System.Double] + - [System.Single] .PARAMETER Object The object to test if it is a numeric type. @@ -11,12 +23,17 @@ .EXAMPLE Test-IsNumericType -Object ([System.UInt32] 1) - Returns $true since the object passed is of a numeric type. + Returns `$true` since the object passed is of a numeric type. + + .EXAMPLE + ([System.String] 'a') | Test-IsNumericType + + Returns `$false` since the value is not a numeric type. .EXAMPLE ('a', 2, 'b') | Test-IsNumericType - Returns $true since one of the values in the array is of a numeric type. + Returns `$true` since one of the values in the array is of a numeric type. .OUTPUTS [System.Boolean] diff --git a/source/en-US/DscResource.Common.strings.psd1 b/source/en-US/DscResource.Common.strings.psd1 index c49bff2..016a47f 100644 --- a/source/en-US/DscResource.Common.strings.psd1 +++ b/source/en-US/DscResource.Common.strings.psd1 @@ -30,7 +30,7 @@ ConvertFrom-StringData @' KeyPropertiesMissing = The hashtable passed to function Test-DscPropertyState is missing the key 'KeyProperties'. This must be set to the property names that makes each instance in the CIM instance collection unique. (DRC0034) ArrayDoesNotMatch = One or more values in an array does not match the desired state. Details of the changes are below. (DRC0035) PropertyValueOfTypeDoesNotMatch = {0} value does not match. Current value is '{1}', but expected the value '{2}'. (DRC0036) - UnableToCompareType = Unable to compare the type {0} as it is not handled by the Test-DscPropertyState cmdlet. (DRC0037) + UnableToCompareType = Unable to compare the type {0} as it is not handled by the Test-DscPropertyState command. (DRC0037) EvaluatePropertyState = Evaluating the state of the property '{0}'. (DRC0038) PropertyInDesiredState = The parameter '{0}' is in desired state. (DRC0039) PropertyNotInDesiredState = The parameter '{0}' is not in desired state. (DRC0040) diff --git a/tests/Unit/Private/Test-DscObjectHasProperty.Tests.ps1 b/tests/Unit/Private/Test-DscObjectHasProperty.Tests.ps1 index 2a965ba..bbaed7d 100644 --- a/tests/Unit/Private/Test-DscObjectHasProperty.Tests.ps1 +++ b/tests/Unit/Private/Test-DscObjectHasProperty.Tests.ps1 @@ -48,7 +48,7 @@ AfterAll { Describe 'Test-DscObjectHasProperty' { Context 'When the object contains the expected property' { BeforeAll { - # Use the Get-Verb cmdlet to just get a simple object fast + # Use the Get-Verb command to just get a simple object fast InModuleScope -ScriptBlock { $script:testDscObject = (Get-Verb)[0] } @@ -71,7 +71,7 @@ Describe 'Test-DscObjectHasProperty' { Context 'When the object does not contain the expected property' { BeforeAll { - # Use the Get-Verb cmdlet to just get a simple object fast + # Use the Get-Verb command to just get a simple object fast InModuleScope -ScriptBlock { $script:testDscObject = (Get-Verb)[0] } diff --git a/tests/Unit/Public/Test-IsNanoServer.Tests.ps1 b/tests/Unit/Public/Test-IsNanoServer.Tests.ps1 index b81a5a7..f7447c3 100644 --- a/tests/Unit/Public/Test-IsNanoServer.Tests.ps1 +++ b/tests/Unit/Public/Test-IsNanoServer.Tests.ps1 @@ -37,7 +37,7 @@ BeforeAll { $PSDefaultParameterValues['Should:ModuleName'] = $script:moduleName <# - This mocks the Get-CimInstance on platforms where the cmdlet does not + This mocks the Get-CimInstance on platforms where the command does not exist, like Linux anc macOS. #> $stubModuleName = 'DscResource.Common.Stubs'