DSC Resource Kit Release July 2017

We just released the DSC Resource Kit!This release includes updates to 12 DSC resource modules. In these past 6 weeks, 106 pull requests have been merged and 115 issues have been closed, all thanks to our amazing community! This is by far the most issues we have ever had closed for a single release!

The modules updated in this release are:

  • PsDscResources
  • SecurityPolicyDsc
  • SharePointDsc
  • xCertificate
  • xComputerManagement
  • xFailOverCluster
  • xHyper-V
  • xNetworking
  • xSqlServer
  • xStorage
  • xWebAdministration
  • xWindowsUpdate

For a detailed list of the resource modules and fixes in this release, see the Included in this Release section below.

Our last community call for the DSC Resource Kit was last week on July 5. A recording of our updates as well as summarizing notes are available. Join us for the next call on August 16 to ask questions and give feedback about your experience with the DSC Resource Kit. Keep an eye on the community agenda for the link to the next call.

We strongly encourage you to update to the newest version of all modules using the PowerShell Gallery, and don’t forget to give us your feedback in the comments below, on GitHub, or on Twitter (@PowerShell_Team)!

All resources with the ‘x’ prefix in their names are still experimental – this means that those resources are provided AS IS and are not supported through any Microsoft support program or service. If you find a problem with a resource, please file an issue on GitHub.

Included in this Release

You can see a detailed summary of all changes included in this release in the table below. For past release notes, go to the README.md or Changelog.md file on the GitHub repository page for a specific module (see the How to Find DSC Resource Modules on GitHub section below for details on finding the GitHub page for a specific module).

Module Name Version Release Notes
PSDscResources 2.8.0.0
  • Archive:
    • Added handling of directory archive entries that end with a foward slash
    • Removed formatting of LastWriteTime timestamp and updated comparison of timestamps to handle dates in different formats
  • WindowsProcess:
    • Fix unreliable tests
  • Updated Test-IsNanoServer to return false if Get-ComputerInfo fails
  • Registry:
    • Fixed bug when using the full registry drive name (e.g. HKEY_LOCAL_MACHINE) and using a key name that includes a drive with forward slashes (e.g. C:/)
SecurityPolicyDsc 1.4.0.0
  • Fixed bug in which friendly name translation may fail if user or group contains “S-“.
  • Fixed bug identified in issue 33 and 34 where Test-TargetResource would return false but was true
SharePointDsc 1.8.0.0
  • Fixed issue in SPServiceAppProxyGroup causing some service names to return as null
  • Added TLS and SMTP port support for SharePoint 2016
  • Fixed issue in SPWebApplication where the Get method didn’t return Classic web applications properly
  • Fixed issue in SPSubscriptionSettingsServiceApp not returning database values
  • Updated Readme of SPInstall to include SharePoint Foundation is not supported
  • Fixed issue with Access Denied in SPDesignerSettings
  • Fixed missing brackets in error message in SPExcelServiceApp
  • Removed the requirement for the ConfigWizard in SPInstallLanguagePack
  • Fixed Language Pack detection issue in SPInstallLanguagePack
  • Added support to set Windows service accounts for search related services to SPSearchServiceApp resource
  • Fixed issue in SPCreateFarm and SPJoinFarm where an exception was not handled correctly
  • Fixed issue in SPSessionStateService not returning correct database server and name
  • Fixed missing Ensure property default in SPRemoteFarmTrust
  • Fixed issue in SPWebAppGeneralSettings where -1 was returned for the TimeZone
  • Fixed incorrect UsagePoint check in SPQuotaTemplate
  • Fixed issue in SPWebAppPolicy module where verbose messages are causing errors
  • Fixed incorrect parameter naming in Get method of SPUserProfilePropery
  • Fixed issue in SPBlobCacheSettings when trying to declare same URL with different zone
  • Improve documentation on SPProductUpdate to specify the need to unblock downloaded files
  • Added check if file is blocked in SPProductUpdate to prevent endless wait
  • Enhance SPUserProfileServiceApp to allow for NoILM to be enabled
  • Fixed issue in SPUserProfileProperty where PropertyMapping was Null
xCertificate 2.8.0.0
  • xCertReq:
    • Added FriendlyName parameter to xCertReq.
    • Changed exceptions to be raised using New-InvalidOperationException from PSDscResources.
    • Changed integration tests to use Config Data instead of value in config to support additional tests.
    • Converted unit tests to use Get-InvalidOperationRecord in CommonTestHelper.
    • Improved unit test style to match standard layout.
    • Minor corrections to style to be HQRM compliant.
    • Improved Verbose logging by writing all lines of CertReq.exe output.
    • Fixed CA auto-detection to work when CA name contains a space.
  • Corrected all makrdown rule violations in README.MD.
  • Added markdownlint.json file to enable line length rule checking in VSCode with markdownlint extension installed.
  • Added the VS Code PowerShell extension formatting settings that cause PowerShell files to be formatted as per the DSC Resource kit style guidelines.
  • Fixed verbose preference not being passed to CertificateDsc.Common functions – fixes Issue 70.
  • Converted all calls to New-InvalidArgumentError function to New-InvalidArgumentException found in CertificateDsc.ResourceHelper – fixes Issue 68
  • Replaced all calls to Write-Error with calls to New-InvalidArgumentException and InvalidOperationException`
  • xWaitForCertificateServices:
    • Added new resource.
  • Cleaned up example format to meet style guidelines and changed examples to issue 2048 bit certificates.
  • Fixed spelling error in xCertificateExport Issuer parameter description.
xComputerManagement 2.0.0.0
  • Updated resources
    • BREAKING CHANGE: xScheduledTask: Added nearly all available parameters for tasks
xFailOverCluster 1.7.0.0
  • Changes to xClusterPreferredOwner
    • Script Analyzer warnings have been fixed (issue 50). This also failed the tests for the resource.
  • Changes to xClusterDisk
    • Fixed test that was failing in AppVeyor (issue 55).
  • Changes to xFailOverCluster
    • Added “Code of Conduct” text to the README.md (issue 44).
    • Added TOC for all resources in the README.md (issue 43).
    • Fixed typos and lint errors in README.md.
    • Fixed style issue in example in README.md.
    • Removed “Unreleased” “tag” from the resources xClusterQuorum and xClusterDisk (issue 36)
    • Added new sections to each resource (Requirements, Parameters and Examples) in the README.md. Some does not yet have any examples, so they are set to “None.”.
    • Added GitHub templates PULL_REQUEST_TEMPLATE, ISSUE_TEMPLATE and CONTRIBUTING.md (issue 45).
    • Split the change log from README.md to a separate file CHANGELOG.md (issue 48).
    • Added the resource xClusterPreferredOwner to README.md (issue 51).
    • Added the resource xClusterNetwork to README.md (issue 56).
    • Removed Credential parameter from parameter list for xWaitForCluster. Parameter Credential does not exist in the schema.mof of the resource (issue 62).
    • Now all parameters in the README.md list their data type and type qualifier (issue 58.)
    • Added Import-DscResource to example in README.md.
    • Added CodeCov and opt-in for all common tests (issue 41).
    • Added CodeCov badge to README.md
      • Fixed CodeCov badge links so they now can be clicked on.
    • Fixed lint rule MD013 in CHANGELOG.md.
    • Fixed lint rule MD013 in README.md.
    • Fixed lint rule MD024 in README.md.
    • Fixed lint rule MD032 in README.md.
    • Removed example from README.md (issue 42).
    • Fixed typo in filename for ISSUE_TEMPLATE. Was “ISSUE_TEMPLATE”, now it is correctly “ISSUE_TEMPLATE.md”.
    • Changed appveyor.yml to use the new default test framework in the AppVeyor module in DscResource.Tests (AppVeyor.psm1).
    • Added VS Code workspace settings file with formatting settings matching the Style Guideline (issue 67). That will make it possible inside VS Code to press SHIFT+ALT+F, or press F1 and choose “Format document” in the list. The PowerShell code will then be formatted according to the Style Guideline (although maybe not complete, but would help a long way).
    • Added new stubs for FailoverClusters module (Tests\Unit\Stubs\FailoverClusters.stubs.psm1) to be able to run unit tests on a computer that does not have or can install Failover Clustering PowerShell module.
    • Added a script file (Tests\Unit\Stubs\Write-ModuleStubFile.ps1) to be able to rebuild the stub file (FailoverClusters.stubs.psm1) whenever needed.
    • Added code block around types in README.md.
  • Changes to xCluster
    • Added examples
      • 1-CreateFirstNodeOfAFailoverCluster.ps1
      • 2-JoinAdditionalNodeToFailoverCluster.ps1
      • 3-CreateFailoverClusterWithTwoNodes.ps1 (this is the example from README.md)
    • Fixed typo in xCluster parameter description.
    • Added links to examples from README.md
    • Refactored the unit test for this resource to use stubs and increase coverage (issue 73).
      • Removed the password file (MSFT_xCluster.password.txt) which seemed unnecessary.
    • Test-TargetResource now throws and error if domain name cannot be evaluated (issue 72).
    • Set-TargetResource now correctly throws and error if domain name cannot be evaluated (issue 71).
  • Changes to xWaitForCluster
    • Added example
      • 1-WaitForFailoverClusterToBePresent.ps1
    • Added link to example from README.md
  • Changes to xClusterDisk
    • Refactored the unit test for this resource to use stubs and increase coverage (issue 74).
    • Removed an evaluation that called Test-TargetResource in Set-TargetResource and instead added logic so that Set-TargetResource evaluates if it should remove a disk (issue 90).
    • Changed the code to be more aligned with the style guideline.
    • Added examples (issue 46)
      • 1-AddClusterDisk.ps1
      • 2-RemoveClusterDisk.ps1
    • Added links to examples from README.md.
  • Changes to xClusterPreferredOwner
    • Refactored the unit test for this resource to use stubs and increase coverage (issue 76).
    • Changed the code to be more aligned with the style guideline.
    • Added examples (issue 52)
      • 1-AddPreferredOwner.ps1
      • 2-RemovePreferredOwner.ps1
    • Added links to examples from README.md.
  • Changes to xClusterNetwork
    • Refactored the unit test for this resource to use stubs and increase coverage (issue 75).
    • Changed the code to be more aligned with the style guideline.
    • Updated resource and parameter description in README.md and schema.mof.
    • Added example (issue 57)
      • 1-ChangeClusterNetwork.ps1
    • Added links to examples from README.md.
xHyper-V 3.9.0.0
  • MSFT_xVMHyperV:
    • Increased xVMHyperV StartupMemory and MinimumMemory limits from 17GB to 64GB.
    • EnableGuestService works on localized OS (language independent).
    • Adds missing Hyper-V-PowerShell feature in examples.
  • Added the following resources:
    • MSFT_xVMProcessor to manage virtual machine processor options.
    • MSFT_xVMHost to managing Hyper-V host settings.
  • MSFT_xVMSwitch:
    • Added support for Switch Embedded Teaming (SET) in Server 2016.
    • Fixed a bug where Get-TargetResource threw an error if a non External switch is used.
    • Updated unit tests to use template version 1.2.0.
    • Style fixes.
    • Added support for Localization.
  • xHyper-V module:
    • Added vs code formatting rule settings.
    • Fix Markdown rule violations in Readme.md.
    • Added .MetaTestOptIn.json for Markdown common test to be included.
    • Added Appveyor badge for Dev branch in Readme.md and moved to Branches section.
    • Added missing properties for all resources in Readme.md.
    • Added and corrected missing / wrong DataTypes and Dsc attributes in Readme.md.
    • Updated Readme to match DscResources style.
    • Created change log and linked to it from Readme.
    • Removed version info from Readme.
    • Updated appveyor.yml to use Appveyor module.
    • Examples:
      • Removed code from Readme and linked to example files instead.
      • Moved code to new example files where there was only code in Readme.
    • Codecov:
      • Updated appveyor.yml to include codecov.
      • Added .codecov.yml.
      • Added codecov badges to Readme.
  • MSFT_xVHD:
    • Support setting the disk type.
    • Added unit tests.
    • Added example Sample_xVHD_FixedVHD.ps1
    • Style fixes
xNetworking 5.0.0.0
  • Find-NetworkAdapter:
    • Fixed to return null if exception thrown.
    • Allowed passing no selection parameters.
  • MSFT_xNetAdapterName:
    • Fixed bug in Get-TargetResource when Name is the only adapter selector parameter.
    • Improved verbose logging.
    • More improvements to verbose logging.
  • Added Get-DnsClientServerStaticAddress to NetworkingDsc.Common to return statically assigned DNS server addresses to support fix for issue 113.
  • MSFT_xDNSserverAddress:
    • Added support for setting DNS Client to DHCP for issue 113.
    • Added new examples to show how to enable DHCP on DNS Client.
    • Improved integration test coverage to enable testing of multiple addresses and DHCP.
    • Converted exception creation to use common exception functions.
  • MSFT_xDhcpClient:
    • Updated example to also cover setting DNS Client to DHCP.
  • Added the VS Code PowerShell extension formatting settings that cause PowerShell files to be formatted as per the DSC Resource kit style guidelines.
  • MSFT_xDefaultGatewayAddress:
    • Corrected style and formatting to meet HQRM guidelines.
    • Converted exceptions to use ResourceHelper functions.
  • Updated badges in README.MD to match the layout from PSDscResources.
  • MSFT_xIPAddress:
    • BREAKING CHANGE: Adding support for multiple IP addresses being assigned.
xSQLServer 8.0.0.0
  • BREAKING CHANGE: The module now requires WMF 5.
    • This is required for class-based resources
  • Added new resource
    • xSQLServerAlwaysOnAvailabilityGroupDatabaseMembership
    • Added localization support for all strings.
    • Refactored as a MOF based resource due to challenges with Pester and testing in Powershell 5.
  • Changes to xSQLServer
    • BREAKING CHANGE: xSQLServer does no longer try to support WMF 4.0 (PowerShell 4.0) (issue 574). Minimum supported version of WMF is now 5.0 (PowerShell 5.0).
    • BREAKING CHANGE: Removed deprecated resource xSQLAOGroupJoin (issue 457).
    • BREAKING CHANGE: Removed deprecated resource xSQLAOGroupEnsure (issue 456).
    • BREAKING CHANGE: Removed deprecated resource xSQLServerFailoverClusterSetup (issue 336).
    • Updated PULL_REQUEST_TEMPLATE adding comment block around text. Also rearranged and updated texts (issue 572).
    • Added common helper functions for HQRM localization, and added tests for the helper functions.
      • Get-LocalizedData
      • New-InvalidResultException
      • New-ObjectNotFoundException
      • New-InvalidOperationException
      • New-InvalidArgumentException
    • Updated CONTRIBUTING.md describing the new localization helper functions.
    • Fixed typos in xSQLServer.strings.psd1
    • Fixed CodeCov badge links in README.md so that they point to the correct branch.
    • Added VS Code workspace settings file with formatting settings matching the Style Guideline (issue 645). That will make it possible inside VS Code to press SHIFT+ALT+F, or press F1 and choose “Format document” in the list. The PowerShell code will then be formatted according to the Style Guideline (although maybe not complete, but would help a long way).
      • Removed powershell.codeFormatting.alignPropertyValuePairs setting since it does not align with the style guideline.
      • Added powershell.codeFormatting.preset with a value of “Custom” so that workspace formatting settings are honored (issue 665).
    • Fixed lint error MD013 and MD036 in README.md.
    • Updated .markdownlint.json to enable rule MD013 and MD036 to enforce those lint markdown rules in the common tests.
    • Fixed lint error MD013 in CHANGELOG.md.
    • Fixed lint error MD013 in CONTRIBUTING.md.
    • Added code block around types in README.md.
    • Updated copyright information in xSQLServer.psd1.
    • Opt-in for markdown common tests (issue 668).
      • The old markdown tests has been removed.
  • Changes to xSQLServerHelper
    • Removed helper function Grant-ServerPerms because the deprecated resource that was using it was removed.
    • Removed helper function Grant-CNOPerms because the deprecated resource that was using it was removed.
    • Removed helper function New-ListenerADObject because the deprecated resource that was using it was removed.
    • Added tests for those helper functions that did not have tests.
    • Test-SQLDscParameterState helper function can now correctly pass a CimInstance as DesiredValue.
    • Test-SQLDscParameterState helper function will now output a warning message if the value type of a desired value is not supported.
    • Added localization to helper functions (issue 641).
      • Resolved the issue when using Write-Verbose in helper functions discussed in 641 where Write-Verbose wouldn”t write out verbose messages unless using parameter Verbose.
      • Moved localization strings from xSQLServer.strings.psd1 to xSQLServerHelper.strings.psd1.
  • Changes to xSQLServerSetup
    • BREAKING CHANGE: Replaced StartWin32Process helper function with the cmdlet Start-Process (issue 41, 93 and 126).
    • BREAKING CHANGE: The parameter SetupCredential has been removed since it is no longer needed. This is because the resource now support the built-in PsDscRunAsCredential.
    • BREAKING CHANGE: Now the resource supports using built-in PsDscRunAsCredential. If PsDscRunAsCredential is set, that username will be used as the first system administrator.
    • BREAKING CHANGE: If the parameter PsDscRunAsCredential are not assigned any credentials then the resource will start the setup process as the SYSTEM account. When installing as the SYSTEM account, then parameter SQLSysAdminAccounts and ASSysAdminAccounts must be specified when installing feature Database Engine and Analysis Services respectively.
    • When setup exits with the exit code 3010 a warning message is written to console telling that setup finished successfully, but a reboot is required (partly fixes issue 565).
    • When setup exits with an exit code other than 0 or 3010 a warning message is written to console telling that setup finished with an error (partly fixes issue 580).
    • Added a new parameter SetupProcessTimeout which defaults to 7200 seconds (2 hours). If the setup process has not finished before the timeout value in SetupProcessTimeout an error will be thrown (issue 566).
    • Updated all examples to match the removal of SetupCredential.
    • Updated (removed) severe known issues in README.md for resource xSQLServerSetup.
    • Now all major version uses the same identifier to evaluate InstallSharedDir and InstallSharedWOWDir (issue 420).
    • Now setup arguments that contain no value will be ignored, for example when InstallSharedDir and InstallSharedWOWDir path is already present on the target node, because of a previous installation (issue 639).
    • Updated Get-TargetResource to correctly detect BOL, Conn, BC and other tools when they are installed without SQLENGINE (issue 591).
    • Now it can detect Documentation Components correctly after the change in issue 591 (issue 628)
    • Fixed bug that prevented Get-DscConfiguration from running without error. The return hash table fails if the $clusteredSqlIpAddress variable is not used. The schema expects a string array but it is initialized as just a null string, causing it to fail on Get-DscConfiguration (issue 393).
    • Added localization support for all strings.
    • Added a test to test some error handling for cluster installations.
    • Added support for MDS feature install (issue 486)
      • Fixed localization support for MDS feature (issue 671).
  • Changes to xSQLServerRSConfig
    • BREAKING CHANGE: Removed $SQLAdminCredential parameter. Use common parameter PsDscRunAsCredential (WMF 5.0+) to run the resource under different credentials. PsDscRunAsCredential Windows account must be a sysadmin on SQL Server (issue 568).
    • In addition, the resource no longer uses Invoke-Command cmdlet that was used to impersonate the Windows user specified by $SQLAdminCredential. The call also needed CredSSP authentication to be enabled and configured on the target node, which complicated deployments in non-domain scenarios. Using PsDscRunAsCredential solves this problems for us.
    • Fixed virtual directory creation for SQL Server 2016 (issue 569).
    • Added unit tests (issue 295).
  • Changes to xSQLServerDatabase
    • Changed the readme, SQLInstance should have been SQLInstanceName.
  • Changes to xSQLServerScript
    • Fixed bug with schema and variable mismatch for the Credential/Username parameter in the return statement (issue 661).
    • Optional QueryTimeout parameter to specify sql script query execution timeout. Fixes issue 597
  • Changes to xSQLServerAlwaysOnService
    • Fixed typos in localization strings and in tests.
  • Changes to xSQLServerAlwaysOnAvailabilityGroup
    • Now it utilize the value of “FailoverMode” to set the “FailoverMode” property of the Availability Group instead of wrongly using the “AvailabilityMode” property of the Availability Group.
xStorage 3.2.0.0
  • xDisk:
    • Fix error message when new partition does not become writable before timeout.
    • Removed unneeded timeout initialization code.
  • xDiskAccessPath:
    • Fix error message when new partition does not become writable before timeout.
    • Removed unneeded timeout initialization code.
    • Fix error when used on Windows Server 2012 R2 – See Issue 102.
  • Added the VS Code PowerShell extension formatting settings that cause PowerShell files to be formatted as per the DSC Resource kit style guidelines.
  • Removed requirement on Hyper-V PowerShell module to execute integration tests.
  • xMountImage:
    • Fix error when mounting VHD on Windows Server 2012 R2 – See Issue 105
xWebAdministration 1.18.0.0
  • Added sample for xWebVirtualDirectory for creating a new virtual directory. Bugfix for 195.
  • Added integration tests for xWebVirtualDirectory. Fixes 188.
  • xWebsite:
    • Fixed bugs when setting log properties, fixes 299.
xWindowsUpdate 2.7.0.0
  • xWindowsUpdateAgent: Fix Get-TargetResource returning incorrect key

How to Find Released DSC Resource Modules

To see a list of all released DSC Resource Kit modules, go to the PowerShell Gallery and display all modules tagged as DSCResourceKit. You can also enter a module’s name in the search box in the upper right corner of the PowerShell Gallery to find a specific module.

Of course, you can also always use PowerShellGet (available in WMF 5.0) to find modules with DSC Resources:

# To list all modules that are part of the DSC Resource Kit
Find-Module -Tag DSCResourceKit 
# To list all DSC resources from all sources 
Find-DscResource

To find a specific module, go directly to its URL on the PowerShell Gallery:
http://www.powershellgallery.com/packages/< module name >
For example:
http://www.powershellgallery.com/packages/xWebAdministration

How to Install DSC Resource Modules From the PowerShell Gallery

We recommend that you use PowerShellGet to install DSC resource modules:

Install-Module -Name < module name >

For example:

Install-Module -Name xWebAdministration

To update all previously installed modules at once, open an elevated PowerShell prompt and use this command:

Update-Module

After installing modules, you can discover all DSC resources available to your local system with this command:

Get-DscResource

How to Find DSC Resource Modules on GitHub

All resource modules in the DSC Resource Kit are available open-source on GitHub.
You can see the most recent state of a resource module by visiting its GitHub page at:
https://github.com/PowerShell/< module name >
For example, for the xCertificate module, go to:
https://github.com/PowerShell/xCertificate.

All DSC modules are also listed as submodules of the DscResources repository in the xDscResources folder.

How to Contribute

You are more than welcome to contribute to the development of the DSC Resource Kit! There are several different ways you can help. You can create new DSC resources or modules, add test automation, improve documentation, fix existing issues, or open new ones.
See our contributing guide for more info on how to become a DSC Resource Kit contributor.

If you would like to help, please take a look at the list of open issues for the DscResources repository.
You can also check issues for specific resource modules by going to:
https://github.com/PowerShell/< module name >/issues
For example:
https://github.com/PowerShell/xPSDesiredStateConfiguration/issues

Your help in developing the DSC Resource Kit is invaluable to us!

Questions, comments?

If you’re looking into using PowerShell DSC, have questions or issues with a current resource, or would like a new resource, let us know in the comments below, on Twitter (@PowerShell_Team), or by creating an issue on GitHub.

Katie Keim
Software Engineer
PowerShell Team
@katiedsc (Twitter)
@kwirkykat (GitHub)