CHANGELOG.md

Changelog for DscResource.Common

All notable changes to this project will be documented in this file.

The format is based on and uses the types of changes according to Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Fixed

• New-*Exception
  • Use ThrowTerminatingError instead of throw. Fixes #177.

[0.24.2] - 2025-08-27

Changed

• DscResource.Common
  • Removed use of New-Object and used ::new().
  • Minimum PowerShell version is now 5.0.
• Compare-DscParameterState
  • Changed detailed diagnostic messages from Write-Verbose to Write-Debug for variable values, type comparisons, and internal diagnostics.
  • Comparison result still uses Write-Verbose to provide user-actionable information about parameter state differences.
  • Use ArrayList and not fixed size array.
  • Remove some ForEach-Object usage.
  • Move non error Verbose messages to Debug. #157.
• Test-ModuleExist
  • Changed module filtering messages from Write-Verbose to Write-Debug for internal implementation details.
  • Localized hardcoded Write-Debug messages to use localized strings (#168).
• Test-IsNanoServer
  • Changed operating system SKU diagnostic message from Write-Verbose to Write-Debug.
• Find-Certificate
  • Changed certificate filter diagnostic message from Write-Verbose to Write-Debug.
  • Use ArrayList and not fixed size array.
• Get-LocalizedDataForInvariantCulture
  • Changed file processing message from Write-Verbose to Write-Debug for internal diagnostic information.
  • Localized hardcoded Write-Debug messages to use localized strings (#169).
• Clear-ZeroedEnumPropertyValue
  • Add begin, end blocks.
• Test-DscPropertyState
  • Use ArrayList and not fixed size array.
• Assert-BoundParameter
  • Fix PSSA warning.
• ConvertFrom-DscResourceInstance
  • Fix PSSA warning.
• Get-DscProperty
  • Use ArrayList and not fixed size array.
  • Fix PSSA warning.
• Remove-CommonParameter
  • Remove use of Where-Object and ForEach-Object.

Fixed

• GitVersion feature branch regex now only match branches starting with f/ or feature/ to prevent conflicts with GitHub Copilot Agent branches (issue #173).

[0.24.1] - 2025-08-27

Added

• Assert-BoundParameter
  • Added parameter set NotAllowed with parameter NotAllowedList to validate that none of the specified parameters are bound, throwing an exception if any are present.

Changed

• Assert-BoundParameter
  • Enhanced parameter IfParameterPresent to support both string arrays and hashtables for conditional assertion logic.
  • Added alias IfEqualParameterList to parameter IfParameterPresent for backward compatibility.

[0.24.0] - 2025-08-26

Added

• Assert-BoundParameter
  • Added parameter set AtLeastOne with parameter AtLeastOneList to validate that at least one parameter from a specified list is bound #161.
  • Added parameter IfEqualParameterList to conditionally perform assertions only when specified parameters have exact values #160.
• Format-Path
  • Added parameter ExpandEnvironmentVariable (issue #147).
• Compare-DscParameterState
  • Added support for comparing large hashtables that contain lists of elements.

Changed

• Get-ComputerName
  • Replaced platform-specific logic with cross-platform implementation using [System.Environment]::MachineName for consistent short name behavior.
  • Enhanced FQDN functionality to use [System.Net.Dns]::GetHostEntry() for proper domain name resolution on Windows, Linux, and macOS.
  • Improved error handling to gracefully fallback to short name when DNS resolution fails.

[0.22.0] - 2025-04-25

Removed

• Remove the patch workaround in the pipeline for the ModuleBuilder bug.

Added

• DscResource.Common
  • Public command:
    • Get-FileProductVersion - Get the product version of a file.
    • Test-PendingRestart - Test if a pending restart is required.
  • Private command
    • Clear-ZeroedEnumPropertyValue from DscResource.Base.
• Get-DscProperty
  • Add optional parameter IgnoreZeroEnumValue.

Fixed

• Updated multiple test scripts to redirect standard output using file descriptor 3 instead of 2, ensuring that error streams remain unaffected while suppressing other output.

[0.21.0] - 2025-03-16

Added

• DscResource.Common
  • Public command:
    • Format-Path - Format a file system path based on the operating system and specified parameters.

[0.20.1] - 2025-03-10

Fixed

• Get-RegistryPropertyValue
  • Current implementation was not safe and could throw an exception if the property did not exist, even if -ErrorAction 'SilentlyContinue was passed. This was fixed by using Get-ItemProperty instead of Get-ItemPropertyValue (issue #139.

[0.20.0] - 2025-03-09

Added

• DscResource.Common
  • Added GitHub issue template for new command proposals.
  • Patch ModuleBuilder to workaround issue #135.
  • Public command:
    • Get-RegistryPropertyValue - Get a registry property value.
    • Format-Path - Format a file system path based on the operating system and specified parameters.

Changed

• Compare-DscParameterState
  • Updated comment-based help example.

[0.19.1] - 2025-02-08

Added

• Added Indented.AnalyzerRules and config
• Use prerelease DscResource.ScriptAnalyzer
• BoundParameterBehavior Enum.

Changed

• Move docs generation to separate task.
• Remove build.yml config not required.
• Assert-BoundParameter
  • Add additional parameter RequiredBehavior, defaults to the current implementation
• Assert-RequiredCommandParameter
  • Add additional functionality to to either match all required parameters or one or more. Fixes #136.

Fixed

• Fixed HQRM script analyzer errors

Removed

• codecov.yml

[0.19.0] - 2024-10-15

Changed

• Unit Tests
  • Updated path to build.ps1 in BeforeDiscovery block.
• Assert-Module
  • Added SkipEditionCheck for PS6+. Fixes #131.

[0.17.2] - 2024-07-20

Added

• Public command:
  • Get-UserName - get current user name cross platform.

Changed

• Assert-ElevatedUser
  • Add new parameter ErrorMessage to allow custom error messages.
• ConvertTo-CimInstance
  • Add parameters for ClassName and Namespace for custom values. Fixes #128

Fixed

• Get-PSModulePath
  • Throws an exception if the My Documents folder cannot be found when calling the command with the scope CurrentUser (issue #122).
• Update build process to pin GitVersion to 5.* to resolve errors (gaelcolas/Sampler#477).

[0.17.1] - 2024-04-23

Added

• Get-PSModulePath
  • Can now return the individual module path for different scopes when using the parameter -Scope. If no parameter is specified the command return the path for the scope CurrentUser.
• Test-ModuleExist
  • Checks if a PowerShell module with a specified name is available in a PSModulePath.

Fixed

• Get-PSModulePath
  • Was using the wrong path separator on Linux and macOS.
• Get-LocalizedData
  • Wrongly returned one or more boolean values in addition to the localized string array. This was because the return value was not handled when calling Add() and Remove() methods of $PSBoundParameters so it was returned to the pipeline.

[0.17.0] - 2024-01-23

Added

• Tasks for automating documentation for the GitHub repository wiki (issue #110).
• Set-PSModulePath
  • A new parameters set takes two parameters FromTarget and ToTarget that can copy from omne target to the other (issue #102).
  • A new parameter PassThru that, if specified, returns the path that was set.
• New-Exception
  • New command that creates and returns an [System.Exception].
• New-ErrorRecord
  • New command that creates and returns an [System.Management.Automation.ErrorRecord] (issue #99).
• New-ArgumentException
  • Now takes a parameter PassThru that returns the error record that was created (and does not throw).
• New-InvalidOperationException
  • Now takes a parameter PassThru that returns the error record that was created (and does not throw) (issue #98).
• New-InvalidResultException
  • Now takes a parameter PassThru that returns the error record that was created (and does not throw).
• New-NotImplementedException
  • Now takes a parameter PassThru that returns the error record that was created (and does not throw).
• Compare-DscParameterState
  • Add support for the type [System.Collections.Specialized.OrderedDictionary] passed to parameters CurrentValues and DesiredValues (issue #57).
  • Add support for DesiredValues (and CurrentValues) to pass a value, e.g a hashtable, that includes a property with the type [System.Collections.Specialized.OrderedDictionary] or an array of [System.Collections.Specialized.OrderedDictionary] (issue #57).

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.
• A meta task now removes the built module from the session if it is imported.
• Wiki source file HOME was modified to not link to README for help after command documentation now is in the wiki.
• Get-LocalizedData
  • Refactored to simplify execution and debugging. The command previously used a steppable pipeline (proxies Import-LocalizedData), that was removed since it was not possible to use the command in a pipeline. It just made it more complex and harder to debug. There are more debug messages added to hopefully simplify solving some hard to find edge cases bugs.
• New-ArgumentException
  • Now has a command alias New-InvalidArgumentException and the command was renamed to match the exception name.
  • Now uses the new command New-ErrorRecord.
• New-InvalidDataException
  • The parameter Message has a parameter alias ErrorMessage to make the command have the same parameter names as the other New-*Exception commands.
  • Now uses the new command New-ErrorRecord.
• New-InvalidOperationException
  • Now uses the new command New-ErrorRecord.
• New-InvalidResultException
  • Now uses the new command New-ErrorRecord.
• New-NotImplementedException
  • Now uses the new command New-ErrorRecord.
• New-ObjectNotFoundException
  • Now uses the new command New-ErrorRecord.

Fixed

• Assert-BoundParameter
  • Fixed example in documentation that were referencing an invalid command name.
• Get-LocalizedData
  • One debug message was wrongly using a format operator (issue #111.
• New-ObjectNotFoundException
  • Updated typo in comment-based help.

[0.16.0] - 2023-04-10

Added

• New public commands.
  • Get-EnvironmentVariable - Get a specific environment variable from a specific environment variable target.
  • Get-PSModulePath - Get the the PSModulePath from one or more environment variable targets - Issue #103

[0.15.0] - 2023-04-06

Added

• Added public function Find-Certificate that returns one or more certificates using certificate selector parameters - Issue #100
  • Related to CertificateDsc Issue #272.

[0.14.0] - 2022-12-31

Added

• Added private function Assert-RequiredCommandParameter that throws an exception if a specified parameter is not assigned a value, and optionally throws only if a specific parameter is passed. - Issue #92
  • Related to SqlServerDsc Issue #1796.
• Added public function Test-AccountRequirePassword that returns true or false whether an account need a password to be passed - Issue #93
  • Related to SqlServerDsc Issue #1794.
• Added public command Get-DscProperty that returns a hashtable of available properties for a class-based resource. See comment-based help for more information.
• Added public command Test-DscProperty that returns a true or false whether a property exist in a class-based resource. See comment-based help for more information.
• Added private function Test-DscPropertyIsAssigned that returns a true or false whether a property in a class-based resource has a non-null value.

Changed

• DscResource.Common
  • Updated Visual Studio Code project settings to configure testing for Pester 5.
• Assert-BoundParameter
  • Now has a new parameter set that calls Assert-RequiredCommandParameter which will throw an exception if a specified parameter is not assigned a value, and optionally throws only if a specific parameter is passed.

Fixed

• Fixed unit tests for Assert-ElevatedUser and Test-IsNumericType so the public function is tested correctly using the exported function.
• Fixed unit tests to easier run test both from command line and inside Visual Studio Code.

[0.13.1] - 2022-12-18

Changed

• DscResource.Common
  • Now builds the module into a separate folder output/builtModule.

Fixed

• Test-IsNumericType
  • Now handles arrays correctly.

[0.13.0] - 2022-12-17

Added

• Added public function Test-IsNumericType that returns whether the specified object is of a numeric type - Issue #87
  • Related to SqlServerDsc Issue #1795.

Changed

• Assert-ElevatedUser
  • Renamed the localized string key name and prepared the localized string file to be able to distinguish which key belong to which command.

[0.12.0] - 2022-12-10

Added

• Added public function Assert-ElevatedUser that asserts the user has elevated the PowerShell session. Issue #82
  • Related to SqlServerDsc Issue #1797.

[0.11.1] - 2022-08-18

Changed

• DscResource.Common
  • updating the Get-LocalizedData to bypass Import-LocalizedData when in Globalization-Invariant mode. The command throws when running on an Invariant culture on Linux in the latest PS versions.

[0.11.0] - 2022-08-01

Changed

• DscResource.Common
  • Update pipeline files to the latest in Sampler.
    • Fix missing tasks module.
  • Update unit tests to import and remove the module being tested.

Fixed

• Correction to Compare-DscParameterState returning false positive when parameter with an empty hashtable or CimInstance property is passed in DesiredValues, fixes issue #65.
• Correction some problems in Compare-DscParameterState, see issue #70.
  • When you use -ReverseCheck, this value is used in recursive call of Test-DscParameterState and Compare-DscParameterState, and that called another time the function.
  • When you use -Properties and -ReverseCheck, and you have an array in member, that return a wrong value, because the properties are set in recursive calls of -ReverseCheck to test the value of array.
  • When you use -ReverseCheck and, in the function Test-DscCompareState/Compare-DscParameterState are recursively called (like to test or compare value of array), -ReverseCheck value is removed from $PSBoundParameters. And the ReverseCheck isn't done.

[0.10.3] - 2021-06-26

Added

• Added cmdlet ConvertFrom-DscResourceInstance which can be used to convert any object to in another format. It accepts objects from pipeline. issue #71.
• Now code coverage is uploaded to codecov.io.

Changed

• Unit tests are now running using Pester 5 (issue #40).
• Excludes the PowerShell module script file DscResource.Common.psm1 located in folder source from the HQRM testing.

[0.10.2] - 2021-03-24

Changed

• DscResource.Common
  • Renamed default branch to main - fixes issue #62.
  • Changed to use the new GitHub deploy tasks.
• Assert-Module
  • Now it possible to forcibly import a module using -ImportModule -Force
  • It no longer outputs verbose messages that is normally generated when using Get-Module -ListAvailable if the module that is asserted is already in the session (issue #66).
• Compare-DscParameterState
  • Fix verbose message to only show when using parameter IncludeInDesiredState. Also made the verbose message more intuitive when the value being compared was a [System.Boolean].

[0.10.1] - 2020-12-25

Added

• Added cmdlet Get-ComputerName which can be used to 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.

[0.10.0] - 2020-11-18

Added

• Added cmdlet Compare-DscParameterState - Could be used in Get-TargetResource function or Get() method in Class based Resources. It is based on the code of Test-DscParameterState function to get compliance between current and desired state of resources. The OutPut of Compare-DscParameterState is a collection of PSObject. The properties of each PSObject are Property, InDesiredState, ExpectedType, ActualType, ExpectedValue, and ActualValue. The IncludeInDesiredState parameter must be used to add ExpectedValue and ActualValue.
• Added pester test to test the PSCredential object with Compare-DscParameterState.

Changed

• Cmdlet Test-DscResourceState is now calling Compare-DscParameterState. Possible breaking change.
• IncludeInDesiredState and IncludeValue parameters of Compare-DscParameterState are removed in splatting when Test-DscCompareState is called.

Fix

• Fix git diff command in QA tests on Linux and MacOS.

[0.9.3] - 2020-07-25

Fixed

• Correction to Test-DscParameterState returning false positive when parameter with an empty array is passed in DesiredValues or CurrentValues - fixes issue #53.

[0.9.2] - 2020-07-22

Added

• Test-DscParameterState can now handle script blocks. The parameter 'ValuesToCheck' was renamed to 'Properties' but an alias was added so it is not a braking change. The parameter 'ExcludeProperties' was added.
• Added a new test for the alias 'ValuesToCheck' pointing to 'Properties'.
• Added cmdlet Compare-ResourcePropertyState that also introduces a new design pattern to evaluate properties in both Test and Set - fixes issue #47.

Fixed

• Get-LocalizedData
  • Now correctly evaluates the default UI culture on non-English operating systems (issue #50.
  • If the LCID 127 is found it will be skipped and instead use the default UI culture (which is 'en-US' unless specified) (issue #11.

[0.9.1] - 2020-07-08

Added

• Added cmdlet New-InvalidDataException - fixes Issue #42.
• Added cmdlet Set-DscMachineRebootRequired - fixes Issue #43.
• Pinned Pester module version to 4.10.1 to enable build until v5.x is ready for use.

[0.9.0] - 2020-05-18

Added

• Added cmdlet Set-PSModulePath.

[0.8.0] - 2020-05-11

• Added a default value of en-US to the DefaultUICulture parameter of the Get-LocalizedData function Issue #33.
• Fixing a problem with the latest ModuleBuild 1.7.0 that breaks the CI pipeline.

[0.7.1] - 2020-05-02

Fixed

• Add missing private function Test-DscObjectHasProperty.

[0.7.0] - 2020-05-02

Added

• Added the cmdlet Assert-IPAddress
• Added the cmdlet ConvertTo-CimInstance. This cmdlet comes from NetworkingDsc.
• Added the cmdlet ConvertTo-Hashtable. This cmdlet comes from NetworkingDsc.

Changed

• Update the README.md with new cmdlet documentation format.
• Update to use HQRM tests from the DscResource.Test module.
• Update the repository to use the latest version of ModuleBuilder.
• Update to use the latest pipeline files.
• BREAKING CHANGE: Updated the cmdlet Test-DscParameterState to match the one in the module NetworkingDsc which have been extended with for example checking credentials and types. This might be a breaking change in certain scenarios, for example the type checking if on by default. This change is required to be able to move the module NetworkingDsc to use this module.

[0.6.0] - 2020-04-23

Added

• Added the cmdlet Assert-BoundParameter. This cmdlet comes from ComputerManagementDsc.
• Added the cmdlet Get-TemporaryFolder. This cmdlet comes from SqlServerDsc.
• Added GitHub templates in the repository to help contributors.

Changed

• Only run CI pipeline on branch master when there are changes to files inside the source folder.

Fixed

• The regular expression for minor-version-bump-message in the file GitVersion.yml was changed to only raise minor version when the commit message contain the word add, adds, minor, feature, or features.
• Fixed the pipeline paths trigger.

[0.5.0] - 2020-04-18

Added

• Added ImportModule parameter to Assert-Module function.

Changed

• Updated pipeline Windows VM image to windows-2019.

Fixed

• Fixed the New-*Exception function unit tests to work correctly on PowerShell version 5, 6 and 7.

[0.4.0] - 2020-03-09

Added

• Added the function Assert-Module.

Changed

• Updated the localized strings to have the unique id according to style guideline.

[0.3.0] - 2020-02-15

Added

• Added more function documentation to the README.md.
• Fix minor style issue in functions.
• Changed the VS Code project settings to trim trailing whitespace for markdown files too.
• Changed the VS Code project setting pipelineIndentationStyle to use the correct style.
• The deploy step is no longer run on forks.
• Azure Pipelines will no longer trigger on changes to just the CHANGELOG.md.
• Add section "How to implement" in the README.md.
• Added Test-IsNanoServer function - fixes Issue #9.

[0.2.0] - 2020-01-09

Changed

• Updating pipeline files to the latest in the template.
• Updating and added section Code of conduct.
• Updating and added section contribution.
• Update README.md.
• The cmdlet Get-LocalizedData can now detect localized filenames that are using both the basename and the basename plus the suffix strings. E.g.
  • MSFT_Cluster.psd1
  • MSFT_Cluster.strings.psd1

[0.1.1] - 2019-11-27

Added

• New module based on the functions available in DscResource.Template
• Change the minimum requirement to PowerShell 4.0.

Changed

• skip tests (it ...) using New-CimInstance when OS is not Windows (see issue #1)
• updating secrets and account used