master:
dev:
PSDscResources is the new home of the in-box resources from PSDesiredStateConfiguration.
These resources are a combination of those in the in-box PSDesiredStateConfiguration module as well as community contributions from our experimental xPSDesiredStateConfiguration module on GitHub. These resources have also recently been updated to meet the DSC Resource Kit High Quality Resource Module (HQRM) guidelines.
In-box resources not currently included in this module should not be affected and can still load from the in-box PSDesiredStateConfiguration module.
Because PSDscResources overwrites in-box resources, it is only available for WMF 5.1. Many of the resource updates provided here are also included in the xPSDesiredStateConfiguration module which is still compatible with WMF 4 and WMF 5 (though this module is not supported and may be removed in the future).
To update your in-box resources to the newest versions provided by PSDscResources, first install PSDscResources from the PowerShell Gallery:
Install-Module PSDscResourcesThen, simply add this line to your DSC configuration:
Import-DscResource -ModuleName PSDscResourcesThis project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This module does not accept breaking changes.
Please check out the common DSC Resources contributing guidelines.
- Group: Provides a mechanism to manage local groups on a target node.
- GroupSet: Provides a mechanism to configure and manage multiple Group resources with common settings but different names.
- Script: Provides a mechanism to run PowerShell script blocks on a target node.
- Service: Provides a mechanism to configure and manage Windows services on a target node.
- ServiceSet: Provides a mechanism to configure and manage multiple Service resources with common settings but different names.
- User: Provides a mechanism to manage local users on a target node.
- WindowsFeature: Provides a mechanism to install or uninstall Windows roles or features on a target node.
- WindowsFeatureSet: Provides a mechanism to configure and manage multiple WindowsFeature resources on a target node.
- WindowsOptionalFeature: Provides a mechanism to enable or disable optional features on a target node.
- WindowsOptionalFeatureSet: Provides a mechanism to configure and manage multiple WindowsOptionalFeature resources on a target node.
- WindowsPackageCab: Provides a mechanism to install or uninstall a package from a Windows cabinet (cab) file on a target node.
- WindowsProcess: Provides a mechanism to start and stop a Windows process.
- ProcessSet: Provides a mechanism to configure and manage multiple WindowsProcess resources on a target node.
Provides a mechanism to manage local groups on a target node. This resource works on Nano Server.
None
- [String] GroupName (Key): The name of the group to create, modify, or remove.
- [String] Ensure (Write): Indicates if the group should exist or not. To add a group or modify an existing group, set this property to Present. To remove a group, set this property to Absent. The default value is Present. { Present | Absent }.
- [String] Description (Write): The description the group should have.
- [String[]] Members (Write): The members the group should have. This property will replace all the current group members with the specified members. Members should be specified as strings in the format of their domain qualified name (domain\username), their UPN (username@domainname), their distinguished name (CN=username,DC=...), or their username (for local machine accounts). Using either the MembersToExclude or MembersToInclude properties in the same configuration as this property will generate an error.
- [String[]] MembersToInclude (Write): The members the group should include. This property will only add members to a group. Members should be specified as strings in the format of their domain qualified name (domain\username), their UPN (username@domainname), their distinguished name (CN=username,DC=...), or their username (for local machine accounts). Using the Members property in the same configuration as this property will generate an error.
- [String[]] MembersToExclude (Write): The members the group should exclude. This property will only remove members from a group. Members should be specified as strings in the format of their domain qualified name (domain\username), their UPN (username@domainname), their distinguished name (CN=username,DC=...), or their username (for local machine accounts). Using the Members property in the same configuration as this property will generate an error.
- [System.Management.Automation.PSCredential] Credential (Write): A credential to resolve non-local group members.
None
Provides a mechanism to configure and manage multiple Group resources with common settings but different names
None
- [String] GroupName (Key): The names of the groups to create, modify, or remove.
The following parameters will be the same for each group in the set:
- [String] Ensure (Write): Indicates if the groups should exist or not. To add groups or modify existing groups, set this property to Present. To remove groups, set this property to Absent. { Present | Absent }.
- [String[]] MembersToInclude (Write): The members the groups should include. This property will only add members to groups. Members should be specified as strings in the format of their domain qualified name (domain\username), their UPN (username@domainname), their distinguished name (CN=username,DC=...), or their username (for local machine accounts).
- [String[]] MembersToExclude (Write): The members the groups should exclude. This property will only remove members groups. Members should be specified as strings in the format of their domain qualified name (domain\username), their UPN (username@domainname), their distinguished name (CN=username,DC=...), or their username (for local machine accounts).
- [System.Management.Automation.PSCredential] Credential (Write): A credential to resolve non-local group members.
None
Provides a mechanism to run PowerShell script blocks on a target node. This resource works on Nano Server.
None
- [String] GetScript (Key): A string that can be used to create a PowerShell script block that retrieves the current state of the resource. This script block runs when the Get-DscConfiguration cmdlet is called. This script block should return a hash table containing one key named Result with a string value.
- [String] SetScript (Key): A string that can be used to create a PowerShell script block that sets the resource to the desired state. This script block runs conditionally when the Start-DscConfiguration cmdlet is called. The TestScript script block will run first. If the TestScript block returns False, this script block will run. If the TestScript block returns True, this script block will not run. This script block should not return.
- [String] TestScript (Key): A string that can be used to create a PowerShell script block that validates whether or not the resource is in the desired state. This script block runs when the Start-DscConfiguration cmdlet is called or when the Test-DscConfiguration cmdlet is called. This script block should return a boolean with True meaning that the resource is in the desired state and False meaning that the resource is not in the desired state.
- [PSCredential] Credential (Write): The credential of the user account to run the script under if needed.
- [String] Result (Read): The result from the GetScript script block.
Provides a mechanism to configure and manage Windows services on a target node. This resource works on Nano Server.
None
- [String] Name (Key): Indicates the service name. Note that sometimes this is different from the display name. You can get a list of the services and their current state with the Get-Service cmdlet.
- [String] Ensure (Write): Indicates whether the service is present or absent. Defaults to Present. { Present | Absent }.
- [String] Path (Write): The path to the service executable file.
- [String] StartupType (Write): Indicates the startup type for the service. { Automatic | Disabled | Manual }.
- [String] BuiltInAccount (Write): Indicates the sign-in account to use for the service. { LocalService | LocalSystem | NetworkService }.
- [PSCredential] Credential (Write): The credential to run the service under.
- [Boolean] DesktopInteract (Write): Indicates whether the service can create or communicate with a window on the desktop. Must be false for services not running as LocalSystem. Defaults to False.
- [String] State (Write): Indicates the state you want to ensure for the service. Defaults to Running. { Running | Stopped | Ignore }.
- [String] DisplayName (Write): The display name of the service.
- [String] Description (Write): The description of the service.
- [String[]] Dependencies (Write): An array of strings indicating the names of the dependencies of the service.
- [Uint32] StartupTimeout (Write): The time to wait for the service to start in milliseconds. Defaults to 30000.
- [Uint32] TerminateTimeout (Write): The time to wait for the service to stop in milliseconds. Defaults to 30000.
None
Provides a mechanism to configure and manage multiple Service resources with common settings but different names. This resource can only modify or delete existing services. It cannot create services.
None
- [String[]] Name (Key): The names of the services to modify or delete. This may be different from the service's display name. To retrieve a list of all services with their names and current states, use the Get-Service cmdlet.
The following parameters will be the same for each service in the set:
- [String] Ensure (Write): Indicates whether the services are present or absent. { Present | Absent }.
- [String] BuiltInAccount (Write): The built-in account the services should start under. Cannot be specified at the same time as Credential. The user account specified by this property must have access to the service executable paths in order to start the services. { LocalService | LocalSystem | NetworkService }.
- [PSCredential] Credential (Write): The credential of the user account the services should start under. Cannot be specified at the same time as BuiltInAccount. The user specified by this credential will automatically be granted the Log on as a Service right. The user account specified by this property must have access to the service executable paths in order to start the services.
- [String] StartupType (Write): The startup type of the services. { Automatic | Disabled | Manual }.
- [String] State (Write): The state the services. { Running | Stopped | Ignore }.
None
- Ensure that multiple services are running
- Set multiple services to run under the built-in account LocalService
Provides a mechanism to manage local users on a target node. This resource works on Nano Server.
None
- [String] UserName (Key): Indicates the account name for which you want to ensure a specific state.
- [String] Description (Write): Indicates the description you want to use for the user account.
- [Boolean] Disabled (Write): Indicates if the account is disabled. Set this property to true to ensure that this account is disabled, and set it to false to ensure that it is enabled. The default value is false.
- [String] Ensure (Write): Ensures that the feature is present or absent { Present | Absent }.
- [String] FullName (Write): Represents a string with the full name you want to use for the user account.
- [PSCredential] Password (Write): Indicates the password you want to use for this account.
- [Boolean] PasswordChangeNotAllowed (Write): Indicates if the user can change the password. Set this property to true to ensure that the user cannot change the password, and set it to false to allow the user to change the password. The default value is false.
- [Boolean] PasswordChangeRequired (Write): Indicates if the user must change the password at the next sign in. Set this property to true if the user must change their password. The default value is true.
- [Boolean] PasswordNeverExpires (Write): Indicates if the password will expire. To ensure that the password for this account will never expire, set this property to true. The default value is false.
None
Provides a mechanism to install or uninstall Windows roles or features on a target node. This resource is not supported on Nano Server.
- Target machine must be running Windows Server 2008 or later.
- Target machine must have access to the DISM PowerShell module.
- Target machine must have access to the ServerManager module (provided by default on Windows Server).
- [String] Name (Key): Indicates the name of the role or feature that you want to ensure is added or removed. This is the same as the Name property from the Get-WindowsFeature cmdlet, and not the display name of the role or feature.
- [PSCredential] Credential (Write): Indicates the credential to use to add or remove the role or feature if needed.
- [String] Ensure (Write): Specifies whether the feature should be installed (Present) or uninstalled (Absent) { Present | Absent }.
- [Boolean] IncludeAllSubFeature (Write): Specifies whether or not all subfeatures should be installed with the specified role or feature. The default value is false.
- [String] LogPath (Write): Indicates the path to a log file to log the operation.
- [String] DisplayName (Read): The display name of the retrieved role or feature.
Provides a mechanism to configure and manage multiple WindowsFeature resources on a target node.
- Target machine must be running Windows Server 2008 or later.
- Target machine must have access to the DISM PowerShell module.
- Target machine must have access to the ServerManager module.
- [String] Name (Key): The names of the roles or features to install or uninstall. This may be different from the display name of the feature/role. To retrieve the names of features/roles on a machine use the Get-WindowsFeature cmdlet.
- [String] Ensure (Write): Specifies whether the feature should be installed or uninstalled. To install features, set this property to Present. To uninstall features, set this property to Absent. { Present | Absent }.
- [Boolean] IncludeAllSubFeature (Write): Specifies whether or not all subfeatures should be installed or uninstalled alongside the specified roles or features. If this property is true and Ensure is set to Present, all subfeatures will be installed. If this property is false and Ensure is set to Present, subfeatures will not be installed or uninstalled. If Ensure is set to Absent, all subfeatures will be uninstalled.
- [PSCredential] Credential (Write): The credential of the user account under which to install or uninstall the roles or features.
- [String] LogPath (Write): The custom file path to which to log this operation. If not passed in, the default log path will be used (%windir%\logs\ServerManager.log).
- [String] DisplayName (Read): The display names of the retrieved roles or features.
Provides a mechanism to enable or disable optional features on a target node. This resource works on Nano Server.
- Target machine must be running a Windows client operating system, Windows Server 2012 or later, or Nano Server.
- Target machine must have access to the DISM PowerShell module
- [String] Name (Key): The name of the Windows optional feature to enable or disable.
- [String] Ensure (Write): Specifies whether the feature should be enabled or disabled. To enable the feature, set this property to Present. To disable the feature, set the property to Absent. The default value is Present. { Present | Absent }.
- [Boolean] RemoveFilesOnDisable (Write): Specifies that all files associated with the feature should be removed if the feature is being disabled.
- [Boolean] NoWindowsUpdateCheck (Write): Specifies whether or not DISM contacts Windows Update (WU) when searching for the source files to enable the feature. If $true, DISM will not contact WU.
- [String] LogPath (Write): The path to the log file to log this operation. There is no default value, but if not set, the log will appear at %WINDIR%\Logs\Dism\dism.log.
- [String] LogLevel (Write): The maximum output level to show in the log. ErrorsOnly will log only errors. ErrorsAndWarning will log only errors and warnings. ErrorsAndWarningAndInformation will log errors, warnings, and debug information). The default value is "ErrorsAndWarningAndInformation". { ErrorsOnly | ErrorsAndWarning | ErrorsAndWarningAndInformation }.
- [String[]] CustomProperties (Read): The custom properties retrieved from the Windows optional feature as an array of strings.
- [String] Description (Read): The description retrieved from the Windows optional feature.
- [String] DisplayName (Read): The display name retrieved from the Windows optional feature.
Provides a mechanism to configure and manage multiple WindowsOptionalFeature resources on a target node. This resource works on Nano Server.
- Target machine must be running a Windows client operating system, Windows Server 2012 or later, or Nano Server.
- Target machine must have access to the DISM PowerShell module.
- [String[]] Name (Key): The names of the Windows optional features to enable or disable.
The following parameters will be the same for each Windows optional feature in the set:
- [String] Ensure (Write): Specifies whether the Windows optional features should be enabled or disabled. To enable the features, set this property to Present. To disable the features, set this property to Absent. { Present | Absent }.
- [Boolean] RemoveFilesOnDisable (Write): Specifies whether or not to remove the files associated with the Windows optional features when they are disabled.
- [Boolean] NoWindowsUpdateCheck (Write): Specifies whether or not DISM should contact Windows Update (WU) when searching for the source files to restore Windows optional features on an online image.
- [String] LogPath (Write): The file path to which to log the operation.
- [String] LogLevel (Write): The level of detail to include in the log. { ErrorsOnly | ErrorsAndWarning | ErrorsAndWarningAndInformation }.
None
Provides a mechanism to install or uninstall a package from a Windows cabinet (cab) file on a target node. This resource works on Nano Server.
- Target machine must have access to the DISM PowerShell module
- [String] Name (Key): The name of the package to install or uninstall.
- [String] Ensure (Required): Specifies whether the package should be installed or uninstalled. To install the package, set this property to Present. To uninstall the package, set the property to Absent. { Present | Absent }.
- [String] SourcePath (Required): The path to the cab file to install or uninstall the package from.
- [String] LogPath (Write): The path to a file to log the operation to. There is no default value, but if not set, the log will appear at %WINDIR%\Logs\Dism\dism.log.
None
Provides a mechanism to start and stop a Windows process.
None
- [String] Path (Key): The executable file of the process. This can be defined as either the full path to the file or as the name of the file if it is accessible through the environment path. Relative paths are not supported.
- [String] Arguments (Key): A single string containing all the arguments to pass to the process. Pass in an empty string if no arguments are needed.
- [PSCredential] Credential (Write): The credential of the user account to run the process under. If this user is from the local system, the StandardOutputPath, StandardInputPath, and WorkingDirectory parameters cannot be provided at the same time.
- [String] Ensure (Write): Specifies whether or not the process should be running. To start the process, specify this property as Present. To stop the process, specify this property as Absent. { Present | Absent }.
- [String] StandardOutputPath (Write): The file path to which to write the standard output from the process. Any existing file at this file path will be overwritten. This property cannot be specified at the same time as Credential when running the process as a local user.
- [String] StandardErrorPath (Write): The file path to which to write the standard error output from the process. Any existing file at this file path will be overwritten.
- [String] StandardInputPath (Write): The file path from which to receive standard input for the process. This property cannot be specified at the same time as Credential when running the process as a local user.
- [String] WorkingDirectory (Write): The file path to the working directory under which to run the file. This property cannot be specified at the same time as Credential when running the process as a local user.
- [UInt64] PagedMemorySize (Read): The amount of paged memory, in bytes, allocated for the process.
- [UInt64] NonPagedMemorySize (Read): The amount of nonpaged memory, in bytes, allocated for the process.
- [UInt64] VirtualMemorySize (Read): The amount of virtual memory, in bytes, allocated for the process.
- [SInt32] HandleCount (Read): The number of handles opened by the process.
- [SInt32] ProcessId (Read): The unique identifier of the process.
- [SInt32] ProcessCount (Read): The number of instances of the given process that are currently running.
Provides a mechanism to configure and manage multiple WindowsProcess resources on a target node.
None
- [String[]] Path (Key): The file paths to the executables of the processes to start or stop. Only the names of the files may be specified if they are all accessible through the environment path. Relative paths are not supported.
The following parameters will be the same for each process in the set:
- [PSCredential] Credential (Write): The credential of the user account to run the processes under. If this user is from the local system, the StandardOutputPath, StandardInputPath, and WorkingDirectory parameters cannot be provided at the same time.
- [String] Ensure (Write): Specifies whether or not the processes should be running. To start the processes, specify this property as Present. To stop the processes, specify this property as Absent. { Present | Absent }.
- [String] StandardOutputPath (Write): The file path to which to write the standard output from the processes. Any existing file at this file path will be overwritten. This property cannot be specified at the same time as Credential when running the processes as a local user.
- [String] StandardErrorPath (Write): The file path to which to write the standard error output from the processes. Any existing file at this file path will be overwritten.
- [String] StandardInputPath (Write): The file path from which to receive standard input for the processes. This property cannot be specified at the same time as Credential when running the processes as a local user.
- [String] WorkingDirectory (Write): The file path to the working directory under which to run the process. This property cannot be specified at the same time as Credential when running the processes as a local user.
- [UInt64] PagedMemorySize (Read): The amount of paged memory, in bytes, allocated for the processes.
- [UInt64] NonPagedMemorySize (Read): The amount of nonpaged memory, in bytes, allocated for the processes.
- [UInt64] VirtualMemorySize (Read): The amount of virtual memory, in bytes, allocated for the processes.
- [SInt32] HandleCount (Read): The number of handles opened by the processes.
- [SInt32] ProcessId (Read): The unique identifier of the processes.
- [SInt32] ProcessCount (Read): The number of instances of the given processes that are currently running.
- WindowsFeature:
- Added Catch to ignore RuntimeException when importing ServerManager module. This solves the issue described here.
- Updated unit tests.
- Added WindowsProcess
- CommonTestHelper:
- Added Get-AppVeyorAdministratorCredential.
- Added Set-StrictMode -'Latest' and $errorActionPreference -'Stop'.
- Service:
- Updated resource module, unit tests, integration tests, and examples to reflect the changes made in xPSDesiredStateConfiguration.
- Group:
- Updated resource module, examples, and integration tests to reflect the changes made in xPSDesiredStateConfiguration.
- Added Script
- Added GroupSet, ServiceSet, WindowsFeatureSet, WindowsOptionalFeatureSet, and ProcessSet.
- Added Set-StrictMode -'Latest' and $errorActionPreference -'Stop' to Group, Service, User, WindowsFeature, WindowsOptionalFeature, WindowsPackageCab.
- Fixed bug in WindowsFeature in which is was checking the 'Count' property of an object that was not always an array.
- Cleaned Group and Service resources and tests.
- Added WindowsFeature.
- Initial release of PSDscResources.