DSC Resource Kit Release August 2017

DSC Resource Kit Release

We just released the DSC Resource Kit!

This release includes updates to 10 DSC resource modules. In these past 6 weeks, 91 pull requests have been merged and 74 issues have been closed, all thanks to our amazing community!

The modules updated in this release are:

  • SecurityPolicyDsc
  • xCertificate
  • xComputerManagement
  • xDhcpServer
  • xDnsServer
  • xExchange
  • xFailOverCluster
  • xNetworking
  • xPSDesiredStateConfiguration
  • xSqlServer

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 August 16. A recording of our updates as well as summarizing notes are available. Join us for the next call at 12PM (Pacific time) on September 27 to ask questions and give feedback about your experience with the DSC Resource Kit. You can download a calendar event for the next call here.

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
SecurityPolicyDsc 1.5.0.0
  • Refactored user rights assignment to read and test easier.
xCertificate 3.0.0.0
  • Add CodeCov.io code coverage reporting.
  • Opted into “Common Tests – Validate Example Files”.
  • Fixed bugs in examples.
  • Updated License and Manifest Copyright info to be 2017 Microsoft Corporation.
  • xCertReq:
  • Added .github support files:
    • CONTRIBUTING.md
    • ISSUE_TEMPLATE.md
    • PULL_REQUEST_TEMPLATE.md
  • Opted into Common Tests “Validate Module Files” and “Validate Script Files”.
  • Converted files with UTF8 with BOM over to UTF8 – fixes Issue 87.
  • Converted to use auto-documentation/wiki format – fixes Issue 84.
xComputerManagement 2.1.0.0
  • xComputer: Changed comparison that validates if we are in the correct AD Domain to work correctly if FQDN wasn”t used.
  • Updated AppVeyor.yml to use AppVeyor.psm1 module in DSCResource.Tests.
  • Removed Markdown.md errors.
  • Added CodeCov.io support.
  • xScheduledTask
    • Fixed incorrect TaskPath handling – Issue 45
  • Change examples to meet HQRM standards and optin to Example validation tests.
  • Replaced examples in README.MD to links to Example files.
  • Added the VS Code PowerShell extension formatting settings that cause PowerShell files to be formatted as per the DSC Resource kit style guidelines – Issue #91.
  • Opted into Common Tests “Validate Module Files” and “Validate Script Files”.
  • Converted files with UTF8 with BOM over to UTF8 – fixes Issue 90.
  • Updated Year to 2017 in License and Manifest – fixes Issue 87.
  • Added .github support files – fixes Issue 88:
    • CONTRIBUTING.md
    • ISSUE_TEMPLATE.md
    • PULL_REQUEST_TEMPLATE.md
  • Resolved all PSScriptAnalyzer warnings and style guide warnings.
  • xOfflineDomainJoin:
    • Changed to use CommonResourceHelper to load localization strings.
    • Renamed en-US to be correct case so that localization strings can be loaded.
    • Suppress PSScriptAnalyzer rule PSAvoidGlobalVars for $global:DSCMachineStatus = 1.
  • xComputer:
    • Suppress PSScriptAnalyzer rule PSAvoidGlobalVars for $global:DSCMachineStatus = 1.
  • xVirtualMemory:
    • Suppress PSScriptAnalyzer rule PSAvoidGlobalVars for $global:DSCMachineStatus = 1.
xDhcpServer 1.6.0.0
  • Added xDhcpServerClass
xDnsServer 1.8.0.0
  • Converted AppVeyor.yml to pull Pester from PSGallery instead of Chocolatey
  • Fixed bug in xDnsServerADZone causing Get-TargetResource to fail with an extra property.
xExchange 1.16.0.0
  • Add missing parameters to xExchClientAccessServer
xFailOverCluster 1.8.0.0
  • Changes to xFailOverCluster
    • Added a common resource helper module with helper functions for localization.
      • Added helper functions; Get-LocalizedData, New-InvalidResultException, New-ObjectNotFoundException, New-InvalidOperationException and New-InvalidArgumentException.
    • Fixed lint error MD034 and fixed typos in README.md.
    • Opt-in for module files common tests (issue 119).
      • Removed Byte Order Mark (BOM) from the files; CommonResourceHelper.psm1 and FailoverClusters.stubs.psm1.
    • Opt-in for script files common tests (issue 121).
      • Removed Byte Order Mark (BOM) from the files; CommonResourceHelper.Tests.ps1, MSFT_xCluster.Tests.ps1, MSFT_xClusterDisk.Tests.ps1, MSFT_xClusterPreferredOwner.Tests.ps1, MSFT_xWaitForCluster.Tests.ps1.
    • Added common test helper functions to help test the throwing of localized error strings.
      • Get-InvalidArgumentRecord
      • Get-InvalidOperationRecord
      • Get-ObjectNotFoundException
      • Get-InvalidResultException.
    • Updated year to 2017 in license file and module manifest (issue 131).
  • Changes to xClusterDisk
    • Enabled localization for all strings (issue 84).
    • Fixed the OutputType data type that was not fully qualified.
    • Minor style changes.
    • Fixed Script Analyzer warnings for Write-Verbose.
  • Changes to xClusterNetwork
    • Replaced the URL for the parameter Role in README.md. The new URL is a more generic description of the possible settings for the Role parameter. The previous URL was still correct but focused on Hyper-V in particular.
    • Fixed typos in parameter descriptions in README.md, comment-based help and schema.mof.
    • Enabled localization for all strings (issue 85).
    • Minor style changes.
    • Fixed Script Analyzer warnings for Write-Verbose.
  • Changes to xCluster
    • Resolved Script Analyzer rule warnings by changing Get-WmiObject to Get-CimInstance (issue 49).
    • Minor style change in tests. Removed “-” in front of “-Be”, “-Not”, “-Throw”, etc.
    • Enabled localization for all strings (issue 83).
    • Added tests to improve code coverage.
      • Fixed random problem with tests failing with error “Invalid token for impersonation – it cannot be duplicated.” (issue 133).
    • Minor style changes.
    • Fixed Script Analyzer warnings for Write-Verbose.
  • Changes to xWaitForCluster
    • Refactored the unit test for this resource to use stubs and increase coverage (issue 78).
    • Now the Test-TargetResource correctly returns false if the domain name cannot be evaluated (issue 107).
    • Changed the code to be more aligned with the style guideline.
    • Updated parameter description in the schema.mof.
    • Resolved Script Analyzer warnings (issue 54).
    • Enabled localization for all strings (issue 88).
    • Minor style changes.
  • Changes to xClusterQuorum
    • Refactored the unit test for this resource to use stubs and increase coverage (issue 77).
    • Changed the code to be more aligned with the style guideline.
    • Updated parameter description in the schema.mof.
    • Added example (issue 47)
      • 1-SetQuorumToNodeMajority.ps1
      • 2-SetQuorumToNodeAndDiskMajority.ps1
      • 3-SetQuorumToNodeAndFileShareMajority.ps1
      • 4-SetQuorumToDiskOnly.ps1
    • Added links to examples from README.md.
    • Minor style changes.
    • Enabled localization for all strings (issue 87).
  • Changes to xClusterPreferredOwner
    • Enabled localization for all strings (issue 86).
    • Fixed typo in the returned hash table from Get-TargetResource.
    • Minor style changes.
xNetworking 5.1.0.0
  • MSFT_xDhcpClient:
    • Corrected style and formatting to meet HQRM guidelines.
    • Converted exceptions to use ResourceHelper functions.
  • README.MD:
    • Cleaned up badges by putting them into a table.
  • MSFT_xDnsConnectionSuffix:
    • Corrected style and formatting to meet HQRM guidelines.
    • Converted exceptions to use ResourceHelper functions.
  • README.MD:
    • Converted badges to use branch header as used in xSQLServer.
  • Added standard .markdownlint.json to configure rules to run on Markdown files.
  • MSFT_xDnsClientGlobalSetting:
    • Corrected style and formatting to meet HQRM guidelines.
    • Converted exceptions to use ResourceHelper functions.
  • Updated year to 2017 in LICENSE and module manifest.
  • MSFT_xDnsServerAddress:
    • Fix error when setting address on adapter where NameServer Property does not exist in registry for interface – see issue 237.
    • Corrected style and formatting to meet HQRM guidelines.
  • MSFT_xIPAddress:
    • Improved examples to clarify how to set IP Address prefix – see issue 239.
  • MSFT_xFirewall:
    • Fixed bug with DisplayName not being set correctly in some situations – see issue 234.
    • Corrected style and formatting to meet HQRM guidelines.
    • Converted exceptions to use ResourceHelper functions.
  • Added .github support files:
    • CONTRIBUTING.md
    • ISSUE_TEMPLATE.md
    • PULL_REQUEST_TEMPLATE.md
  • Opted into Common Tests “Validate Module Files” and “Validate Script Files”.
  • Converted files with UTF8 with BOM over to UTF8 – fixes Issue 250.
  • MSFT_xFirewallProfile:
    • Created new resource configuring firewall profiles.
  • MSFT_xNetConnectionProfile:
    • Corrected style and formatting to meet HQRM guidelines.
    • Added validation for provided parameters.
    • Prevent testing parameter values of connection that aren”t set in resource – fixes Issue 254.
    • Improved unit test coverage for this resource.
xPSDesiredStateConfiguration 7.0.0.0
  • xService
    • BREAKING CHANGE: The service will now return as compliant if the service is not installed and the StartupType is set to Disabled regardless of the value of the Ensure property.
  • Fixed misnamed certificate thumbprint variable in example Sample_xDscWebServiceRegistrationWithSecurityBestPractices
xSQLServer 8.1.0.0
  • Changes to xSQLServer
    • Added back .markdownlint.json so that lint rule MD013 is enforced.
    • Change the module to use the image “Visual Studio 2017” as the build worker image for AppVeyor (issue 685).
    • Minor style change in CommonResourceHelper. Added missing [Parameter()] on three parameters.
    • Minor style changes to the unit tests for CommonResourceHelper.
    • Changes to xSQLServerHelper
    • Opt-in for module files common tests (issue 702).
      • Removed Byte Order Mark (BOM) from the files; CommonResourceHelper.psm1, MSFT_xSQLServerAvailabilityGroupListener.psm1, MSFT_xSQLServerConfiguration.psm1, MSFT_xSQLServerEndpointPermission.psm1, MSFT_xSQLServerEndpointState.psm1, MSFT_xSQLServerNetwork.psm1, MSFT_xSQLServerPermission.psm1, MSFT_xSQLServerReplication.psm1, MSFT_xSQLServerScript.psm1, SQLPSStub.psm1, SQLServerStub.psm1.
    • Opt-in for script files common tests (issue 707).
      • Removed Byte Order Mark (BOM) from the files; DSCClusterSqlBuild.ps1, DSCFCISqlBuild.ps1, DSCSqlBuild.ps1, DSCSQLBuildEncrypted.ps1, SQLPush_SingleServer.ps1, 1-AddAvailabilityGroupListenerWithSameNameAsVCO.ps1, 2-AddAvailabilityGroupListenerWithDifferentNameAsVCO.ps1, 3-RemoveAvailabilityGroupListenerWithSameNameAsVCO.ps1, 4-RemoveAvailabilityGroupListenerWithDifferentNameAsVCO.ps1, 5-AddAvailabilityGroupListenerUsingDHCPWithDefaultServerSubnet.ps1, 6-AddAvailabilityGroupListenerUsingDHCPWithSpecificSubnet.ps1, 2-ConfigureInstanceToEnablePriorityBoost.ps1, 1-CreateEndpointWithDefaultValues.ps1, 2-CreateEndpointWithSpecificPortAndIPAddress.ps1, 3-RemoveEndpoint.ps1, 1-AddConnectPermission.ps1, 2-RemoveConnectPermission.ps1, 3-AddConnectPermissionToAlwaysOnPrimaryAndSecondaryReplicaEachWithDifferentSqlServiceAccounts.ps1, 4-RemoveConnectPermissionToAlwaysOnPrimaryAndSecondaryReplicaEachWithDifferentSqlServiceAccounts.ps1, 1-MakeSureEndpointIsStarted.ps1, 2-MakeSureEndpointIsStopped.ps1, 1-EnableTcpIpWithStaticPort.ps1, 2-EnableTcpIpWithDynamicPort.ps1, 1-AddServerPermissionForLogin.ps1, 2-RemoveServerPermissionForLogin.ps1, 1-ConfigureInstanceAsDistributor.ps1, 2-ConfigureInstanceAsPublisher.ps1, 1-WaitForASingleClusterGroup.ps1, 2-WaitForMultipleClusterGroups.ps1.
    • Updated year to 2017 in license file (issue 711).
    • Code style clean-up throughout the module to align against the Style Guideline.
    • Fixed typos and the use of wrong parameters in unit tests which was found after release of new version of Pester (issue 773).
  • Changes to xSQLServerAlwaysOnService
    • Added resource description in README.md.
    • Updated parameters descriptions in comment-based help, schema.mof and README.md.
    • Changed the datatype of the parameter to Uint32 so the same datatype is used in both the Get-/Test-/Set-TargetResource functions as in the schema.mof (issue 688).
    • Added read-only property IsHadrEnabled to schema.mof and the README.md (issue 687).
    • Minor cleanup of code.
    • Added examples (issue 633)
      • 1-EnableAlwaysOn.ps1
      • 2-DisableAlwaysOn.ps1
    • Fixed PS Script Analyzer errors (issue 724)
    • Casting the result of the property IsHadrEnabled to [System.Boolean] so that $null is never returned, which resulted in an exception (issue 763).
  • Changes to xSQLServerDatabasePermission
    • Fixed PS Script Analyzer errors (issue 725)
  • Changes to xSQLServerScript
    • Fixed PS Script Analyzer errors (issue 728)
  • Changes to xSQLServerSetup
    • Added Swedish localization (issue 695).
    • Now Get-TargetResource correctly returns an array for property ASSysAdminAccounts, and no longer throws an error when there is just one Analysis Services administrator (issue 691).
    • Added a simple integration test (issue 709).
    • Fixed PS Script Analyzer errors (issue 729)

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 DSC Team
@katiedsc (Twitter)
@kwirkykat (GitHub)