xPSDesiredStateConfiguration

The xPSDesiredStateConfiguration module is a more recent, experimental version of the PSDesiredStateConfiguration module that ships in Windows as part of PowerShell 4.0.

The supported version of this module is available as PSDscResources.

This module is automatically tested using PowerShell 5.1 on servers running Windows 2012 R2 and Windows 2016, and is expected to work on other operating systems running PowerShell 5.1. While this module may work with PowerShell versions going back to PowerShell 4, there is no automatic testing performed for these versions, and thus no guarantee that the module will work as expected.

Code of Conduct

This project has adopted this code of conduct.

Releases

For each merge to the branch main a preview release will be deployed to PowerShell Gallery. Periodically a release version tag will be pushed which will deploy a full release to PowerShell Gallery.

Contributing

Please check out common DSC Community contributing guidelines.

Change log

A full list of changes in each version can be found in the change log.

Resources

• xArchive provides a mechanism to expand an archive (.zip) file to a specific path or remove an expanded archive (.zip) file from a specific path on a target node.
• xDscWebService configures an OData endpoint for DSC service to make a node a DSC pull server.
• xEnvironment provides a mechanism to configure and manage environment variables for a machine or process.
• xFileUpload is a composite resource which ensures that local files exist on an SMB share.
• xGroup provides a mechanism to manage local groups on a target node.
• xGroupSet provides a mechanism to configure and manage multiple xGroup resources with common settings but different names.
• xMsiPackage provides a mechanism to install and uninstall .msi packages.
• xPackage manages the installation of .msi and .exe packages.
• xRegistry provides a mechanism to manage registry keys and values on a target node.
• xRemoteFile ensures the presence of remote files on a local machine.
• xScript provides a mechanism to run PowerShell script blocks on a target node.
• xService provides a mechanism to configure and manage Windows services.
• xServiceSet provides a mechanism to configure and manage multiple xService resources with common settings but different names.
• xUser provides a mechanism to manage local users on the target node.
• xWindowsFeature provides a mechanism to install or uninstall Windows roles or features on a target node.
• xWindowsFeatureSet provides a mechanism to configure and manage multiple xWindowsFeature resources on a target node.
• xWindowsOptionalFeature provides a mechanism to enable or disable optional features on a target node.
• xWindowsOptionalFeatureSet provides a mechanism to configure and manage multiple xWindowsOptionalFeature resources on a target node.
• xWindowsPackageCab provides a mechanism to install or uninstall a package from a Windows cabinet (cab) file on a target node.
• xWindowsProcess provides a mechanism to start and stop a Windows process.
• xProcessSet allows starting and stopping of a group of windows processes with no arguments.

Resources that work on Nano Server:

• xGroup
• xService
• xScript
• xUser
• xWindowsOptionalFeature
• xWindowsOptionalFeatureSet
• xWindowsPackageCab

xArchive

Provides a mechanism to expand an archive (.zip) file to a specific path or remove an expanded archive (.zip) file from a specific path on a target node.

Requirements

• The System.IO.Compression type assembly must be available on the machine.
• The System.IO.Compression.FileSystem type assembly must be available on the machine.

Parameters

• [String] Path (Key): The path to the archive file that should be expanded to or removed from the specified destination.
• [String] Destination (Key): The path where the specified archive file should be expanded to or removed from.
• [String] Ensure (Write): Specifies whether or not the expanded content of the archive file at the specified path should exist at the specified destination. To update the specified destination to have the expanded content of the archive file at the specified path, specify this property as Present. To remove the expanded content of the archive file at the specified path from the specified destination, specify this property as Absent. The default value is Present. { Present | Absent }.
• [Boolean] Validate (Write): Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the desintation cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the desintation will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the desintation will not be removed. The default Checksum method is ModifiedDate. The default value is false.
• [String] Checksum (Write): The Checksum method to use to validate whether or not a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive. An invalid argument exception will be thrown if Checksum is specified while Validate is specified as false. ModifiedDate will check that the LastWriteTime property of the file at the destination matches the LastWriteTime property of the file in the archive. CreatedDate will check that the CreationTime property of the file at the destination matches the CreationTime property of the file in the archive. SHA-1, SHA-256, and SHA-512 will check that the hash of the file at the destination by the specified SHA method matches the hash of the file in the archive by the specified SHA method. The default value is ModifiedDate. { ModifiedDate | CreatedDate | SHA-1 | SHA-256 | SHA-512 }
• [System.Management.Automation.PSCredential] Credential (Write): The credential of a user account with permissions to access the specified archive path and destination if needed.
• [Boolean] Force (Write): Specifies whether or not any existing files or directories at the destination with the same name as a file or directory in the archive should be overwritten to match the file or directory in the archive. When this property is false, an error will be thrown if an item at the destination needs to be overwritten. The default value is false.

Read-Only Properties from Get-TargetResource

None

Examples

• Expand an archive without file validation
• Expand an archive under a credential without file validation
• Expand an archive with default file validation and file overwrite allowed
• Expand an archive with SHA-256 file validation and file overwrite allowed
• Remove an archive without file validation
• Remove an archive with SHA-256 file validation

xDscWebService

• EndpointName: The desired web service name.
• CertificateThumbPrint: Certificate thumbprint for creating an HTTPS endpoint. Use "AllowUnencryptedTraffic" for setting up a non SSL based endpoint.
• Port: Port for web service.
• ApplicationPoolName: The name of IIS ApplicationPool to use for the Pull Server. If not specified a pool with name 'PSWS' will be created and bound to the Pull Server instance. Preferably the new application pool is created by using the xWebAppPool resource from the xWebAdministration DSC module.
• PhysicalPath: Folder location where the content of the web service resides.
• Ensure: Ensures that the web service is Present or Absent
• State: State of the web service: { Started | Stopped }
• ModulePath: Folder location where DSC resources are stored.
• ConfigurationPath: Folder location where DSC configurations are stored.
• RegistrationKeyPath: Folder location where DSC pull server registration key file is stored.
• AcceptSelfSignedCertificates: Whether self signed certificate can be used to setup pull server.
• UseSecurityBestPractices: Whether to use best practice security settings for the node where pull server resides on. Caution: Setting this property to $true will reset registry values under "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL". This environment change enforces the use of stronger encryption cypher and may affect legacy applications. More information can be found at https://support.microsoft.com/en-us/kb/245030 and https://technet.microsoft.com/en-us/library/dn786418(v=ws.11).aspx.
• DisableSecurityBestPractices: The items that are excepted from following best practice security settings.
• Enable32BitAppOnWin64: When this property is set to true, Pull Server will run on a 32 bit process on a 64 bit machine.
• ConfigureFirewall: When this property is set to true, a Windows Firewall rule will be created, which allows incoming HTTP traffic for the selected Port. Default: true

Remark:

Configuring a Windows Firewall rule (exception) for a DSC Pull Server instance by using the xDscWebService resource is considered deprecated and thus will be removed in the future.

DSC will issue a warning when the ConfigureFirewall property is set to true. Currently the default value is true to maintain backwards compatibility with existing configurations. At a later time the default value will be set to false and in the last step the support to create a firewall rule using xDscWebService will be removed.

All users are requested to adjust existing configurations so that the ConfigureFirewall is set to false and a required Windows Firewall rule is created by using the Firewall resource from the NetworkingDsc module.

Examples

Pull Server

• A Pull Server with a separately defined IIS Application Pool and firewall rule
• A Pull Server using a SQL Server as backend
• A Pull Server default configuration
• A Pull Server with an enhanced security configuration and a firewall rule
• A Pull Server using the security best practice configuration
• Removing a Pull Server instance

Client

• Common Client (Server) Configuration

xGroup

Provides a mechanism to manage local groups on the target node. This resource works on Nano Server.

Requirements

None

Parameters

• [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.

Read-Only Properties from Get-TargetResource

None

Examples

• Remove members from a group
• Set the members of a group

xGroupSet

Provides a mechanism to configure and manage multiple xGroup resources with common settings but different names

Requirements

None

Parameters

• [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.

Read-Only Properties from Get-TargetResource

None

Examples

• Add members to multiple groups

xWindowsProcess

Provides a mechanism to start and stop a Windows process.

Requirements

None

Parameters

• [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 process. This property cannot be specified at the same time as Credential when running the process as a local user.

Read-Only Properties from Get-TargetResource

• [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.

Examples

• Start a process
• Stop a process
• Start a process under a user
• Stop a process under a user

xProcessSet

Provides a mechanism to configure and manage multiple xWindowsProcess resources on a target node.

Requirements

None

Parameters

• [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.

Read-Only Properties from Get-TargetResource

• [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.

Examples

• Start multiple processes
• Stop multiple processes

xService

Provides a mechanism to configure and manage Windows services. This resource works on Nano Server.

Requirements

None

Parameters

• [String] Name (Key): Indicates the service name. 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.
• [String] Ensure (Write): Indicates whether the service is present or absent. { Present | Absent }.
• [String] Path (Write): The path to the service executable file. Required when creating a service. The user account specified by BuiltInAccount or Credential must have access to this path in order to start the service.
• [String] DisplayName (Write): The display name of the service.
• [String] Description (Write): The description of the service.
• [String[]] Dependencies (Write): The names of the dependencies of the service.
• [String] BuiltInAccount (Write): The built-in account the service should start under. Cannot be specified at the same time as Credential or GroupManagedServiceAccount. The user account specified by this property must have access to the service executable path defined by Path in order to start the service. { LocalService | LocalSystem | NetworkService }.
• [String] GroupManagedServiceAccount (Write): The Group Managed Service Account the service should start under. Cannot be specified at the same time as Credential or BuiltinAccount. The user account specified by this property must have access to the service executable path defined by Path in order to start the service. When specified in a DOMAIN\User$ form, remember to also input the trailing dollar sign. Get-TargetResource outputs the name of the user to the BuiltinAccount property.
• [PSCredential] Credential (Write): The credential of the user account the service should start under. Cannot be specified at the same time as BuiltInAccount or GroupManagedServiceAccount. 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 path defined by Path in order to start the service. Get-TargetResource outputs the name of the user to the BuiltinAccount property.
• [Boolean] DesktopInteract (Write): Indicates whether or not the service should be able to communicate with a window on the desktop. Must be false for services not running as LocalSystem. The default value is False.
• [String] StartupType (Write): The startup type of the service. { Automatic | Disabled | Manual }. If StartupType is "Disabled" and Service is not installed the resource will complete as being DSC compliant.
• [String] State (Write): The state of the service. { Running | Stopped | Ignore }.
• [Uint32] StartupTimeout (Write): The time to wait for the service to start in milliseconds. Defaults to 30000 (30 seconds).
• [Uint32] TerminateTimeout (Write): The time to wait for the service to stop in milliseconds. Defaults to 30000 (30 seconds).

Read-Only Properties from Get-TargetResource

None

Examples

• Create a service
• Delete a service
• Change the state of a service to started or stopped
• Update startup type for a service, and ignoring the current state

xServiceSet

Provides a mechanism to configure and manage multiple xService resources with common settings but different names. This resource can only modify or delete existing services. It cannot create services.

Requirements

None

Parameters

• [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 }.

Read-Only Properties from Get-TargetResource

None

Examples

• Ensure that multiple services are running
• Set multiple services to run under the built-in account LocalService

xRemoteFile

• DestinationPath: Path where the remote file should be downloaded. Required.
• Uri: URI of the file which should be downloaded. It must be a HTTP, HTTPS or FILE resource. Required.
• UserAgent: User agent for the web request. Optional.
• Headers: Headers of the web request. Optional.
• Credential: Specifies credential of a user which has permissions to send the request. Optional.
• MatchSource: Determines whether the remote file should be re-downloaded if file in the DestinationPath was modified locally. The default value is true. Optional.
• TimeoutSec: Specifies how long the request can be pending before it times out. Optional.
• Proxy: Uses a proxy server for the request, rather than connecting directly to the Internet resource. Should be the URI of a network proxy server (e.g 'http://10.20.30.1'). Optional.
• ProxyCredential: Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. Optional.
• Ensure: Says whether DestinationPath exists on the machine. It's a read only property.
• ChecksumType: Specifies the algorithm used to calculate the checksum of the file. Optional. { None | SHA1 | SHA256 | SHA384 | SHA512 | MACTripleDES | MD5 | RIPEMD160 }.
• Checksum: Specifies the expected checksum value of downloaded file. Optional.

Examples

• Download a file
• Download a file using proxy
• Download a file with checksum

xPackage

• Ensure: Ensures that the package is Present or Absent.
• Name: The name of the package.
• Path: The source path of the package.
• ProductId: The product ID of the package (usually a GUID).
• Arguments: Command line arguments passed on the installation command line.
  • When installing MSI packages, the /quiet and /norestart arguments are automatically applied.
• IgnoreReboot: Ignore a pending reboot if requested by package installation. By default is $false and DSC will try to reboot the system.
• Credential: PSCredential needed to access Path.
• ReturnCode: An array of return codes that are returned after a successful installation.
• LogPath: The destination path of the log.
• FileHash: The hash that should match the hash of the package file.
• HashAlgorithm: The algorithm to use to get the hash of the package file.
  • Supported values: SHA1, SHA256, SHA384, SHA512, MD5, RIPEMD160
• SignerSubject: The certificate subject that should match that of the package file's signing certificate.
• SignerThumbprint: The certificate thumbprint that should match that of the package file's signing certificate.
• ServerCertificateValidationCallback: A callback function to validate the server certificate.
• RunAsCredential: Credential used to install the package on the local system.
• CreateCheckRegValue: If a registry value should be created.
• InstalledCheckRegHive: The hive in which to create the registry key. Defaults to 'LocalMachine'. { LocalMachine | CurrentUser }
• InstalledCheckRegKey: That path in the registry where the value should be created.
• InstalledCheckRegValueName: The name of the registry value to create.
• InstalledCheckRegValueData: The data that should be set to the registry value.

Read-Only Properties from Get-TargetResource

• PackageDescription: A text description of the package being installed.
• Publisher: Publisher's name.
• InstalledOn: Date of installation.
• Size: Size of the installation.
• Version: Version of the package.
• Installed: Is the package installed?

Examples

• Install an .exe using credentials
• Install an .exe using credentials and using custom registry data to discover the package
• Simple installer for an msi package that matches via the Name
• Simple installer for an msi package and matches based on the product id

xPSEndpoint (xPSSessionConfiguration)

Creates and registers a new session configuration endpoint.

• Ensure: Indicates if the session configuration is Present or Absent.
• Name: Specifies the name of the session configuration.
• StartupScript: Specifies the startup script for the configuration. Enter the fully qualified path of a Windows PowerShell script.
• RunAsCredential: Specifies the credential for commands of this session configuration. By default, commands run with the permissions of the current user.
• SecurityDescriptorSDDL: Specifies the Security Descriptor Definition Language (SDDL) string for the configuration. This string determines the permissions that are required to use the new session configuration. To use a session configuration in a session, users must have at least Execute(Invoke) permission for the configuration.
• AccessMode: Enables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. The default value is "Remote". { Local | Remote | Disabled }

Read-Only Properties from Get-TargetResource

None.

Examples

• Register a new session configuration endpoint with optional access mode
• Register a new session configuration endpoint with default values
• Register a new session configuration endpoint with custom values
• Removes an existing session configuration endpoint

xMsiPackage

Provides a mechanism to install and uninstall .msi packages.

Requirements

None

Parameters

• [String] ProductId (Key): The identifying number used to find the package, usually a GUID.
• [String] Path (Required): The path to the MSI file that should be installed or uninstalled.
• [String] Ensure (Write): Specifies whether or not the MSI file should be installed or not. To install the MSI file, specify this property as Present. To uninstall the .msi file, specify this property as Absent. The default value is Present. { Present | Absent }.
• [String] Arguments (Write): The arguments to be passed to the MSI package during installation or uninstallation if needed.
• [Boolean] IgnoreReboot _(Write): Ignore a pending reboot if requested by package installation. By default is $false and DSC will try to reboot the system.
• [System.Management.Automation.PSCredential] Credential (Write): The credential of a user account to be used to mount a UNC path if needed.
• [String] LogPath (Write): The path to the log file to log the output from the MSI execution.
• [String] FileHash (Write): The expected hash value of the MSI file at the given path.
• [String] HashAlgorithm (Write): The algorithm used to generate the given hash value.
• [String] SignerSubject (Write): The subject that should match the signer certificate of the digital signature of the MSI file.
• [String] SignerThumbprint (Write): The certificate thumbprint that should match the signer certificate of the digital signature of the MSI file.
• [String] ServerCertificateValidationCallback (Write): PowerShell code that should be used to validate SSL certificates for paths using HTTPS.
• [System.Management.Automation.PSCredential] RunAsCredential (Write): The credential of a user account under which to run the installation or uninstallation of the MSI package.

Read-Only Properties from Get-TargetResource

• [String] Name (Read): The display name of the MSI package.
• [String] InstallSource (Read): The path to the MSI package.
• [String] InstalledOn (Read): The date that the MSI package was installed on or serviced on, whichever is later.
• [UInt32] Size (Read): The size of the MSI package in MB.
• [String] Version (Read): The version number of the MSI package.
• [String] PackageDescription (Read): The description of the MSI package.
• [String] Publisher (Read): The publisher of the MSI package.

Examples

• Install the MSI file with the given ID at the given file path or HTTP URL
• Uninstall the MSI file with the given ID at the given Path
• Uninstall the MSI file with the given ID at the given HTTPS URL

xFileUpload

• DestinationPath: Path where the local file should be uploaded.
• SourcePath: Path to the local file which should be uploaded.
• Credential: PSCredential for the user with access to DestinationPath.
• CertificateThumbprint: Thumbprint of the certificate which should be used for encryption/decryption.

Examples

• Upload file or folder to a SMB share

xEnvironment

Provides a mechanism to configure and manage environment variables for a machine or process.

Requirements

None

Parameters

• [String] Name (Key): The name of the environment variable to create, modify, or remove.
• [String] Value (Write): The desired value for the environment variable. The default value is an empty string which either indicates that the variable should be removed entirely or that the value does not matter when testing its existence. Multiple entries can be entered and separated by semicolons (see Examples).
• [String] Ensure (Write): Specifies if the environment varaible should exist. { Present | Absent }.
• [Boolean] Path (Write): Indicates whether or not the environment variable is a path variable. If the variable being configured is a path variable, the value provided will be appended to or removed from the existing value, otherwise the existing value will be replaced by the new value. When configured as a Path variable, multiple entries separated by semicolons are ensured to be either present or absent without affecting other Path entries (see Examples). The default value is False.
• [String[]] Target (Write): Indicates the target where the environment variable should be set. { Process | Machine | Process, Machine }.

Read-Only Properties from Get-TargetResource

None

Examples

• Create a regular (non-path) environment variable
• Create or update a path environment variable
• Remove paths from a path environment variable
• Remove an environment variable

xEnvironment_AddMultiplePaths

xScript

Provides a mechanism to run PowerShell script blocks on a target node. This resource works on Nano Server.

Requirements

None

Parameters

• [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.

Read-Only Properties from Get-TargetResource

• [String] Result (Read): The result from the GetScript script block.

Examples

• Create a file with content through xScript

xRegistry

Provides a mechanism to manage registry keys and values on a target node.

Requirements

None

Parameters

• [String] Key (Key): The path of the registry key to add, modify, or remove. This path must include the registry hive/drive (e.g. HKEY_LOCAL_MACHINE, HKLM:).
• [String] ValueName (Key): The name of the registry value. To add or remove a registry key, specify this property as an empty string without specifying ValueType or ValueData. To modify or remove the default value of a registry key, specify this property as an empty string while also specifying ValueType or ValueData.
• [String] Ensure (Write): Specifies whether or not the registry key or value should exist. To add or modify a registry key or value, set this property to Present. To remove a registry key or value, set this property to Absent. { Present | Absent }.
• [String] ValueData (Write): The data the specified registry key value should have as a string or an array of strings (MultiString only).
• [String] ValueType (Write): The type the specified registry key value should have. { String | Binary | DWord | QWord | MultiString | ExpandString }
• [Boolean] Hex (Write): Specifies whether or not the specified DWord or QWord registry key data is provided in a hexadecimal format. Not valid for types other than DWord and QWord. The default value is $false.
• [Boolean] Force (Write): Specifies whether or not to overwrite the specified registry key value if it already has a value or whether or not to delete a registry key that has subkeys. The default value is $false.

Read-Only Properties from Get-TargetResource

None

Examples

• Add a registry key
• Add or modify a registry key value
• Remove a registry key value
• Remove a registry key

xUser

Provides a mechanism to manage local users on a target node.

Requirements

None

Parameters

• [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 enabled. Set this property to $true to ensure that this account is disabled, and set it to $false to ensure that it is enabled.
  • Suported values: $true, $false
  • Default value: $false
• [String] Ensure (Write): Ensures that the feature is present or absent.
  • Supported values: Present, Absent
  • Default Value: Present
• [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.
  • Suported values: $true, $false
  • Default value: $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 the password.
  • Suported values: $true, $false
  • Default value: $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, and set it to $false if the password will expire.
  • Suported values: $true, $false
  • Default value: $false

Examples

• Create a new local user account
• Remove a local user account
• Create a new detailed local user account

xWindowsFeature

Provides a mechanism to install or uninstall Windows roles or features on a target node.

Requirements

• 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.

Parameters

• [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): Set this property to $true to ensure the state of all required subfeatures with the state of the feature you specify with the Name property. The default value is $false.
• [String] LogPath (Write): Indicates the path to a log file to log the operation.

Read-Only Properties from Get-TargetResource

• [String] DisplayName (Read): The display name of the retrieved role or feature.

Examples

• Install a Windows feature
• Uninstall a Windows feature
• Install a Windows feature using credentials
• Install a Windows feature, output the log to file

xWindowsFeatureSet

Provides a mechanism to configure and manage multiple xWindowsFeature resources on a target node.

Requirements

• 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.

Parameters

• [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).

Read-Only Properties from Get-TargetResource

• [String] DisplayName (Read): The display names of the retrieved roles or features.

Examples

• Install multiple Windows features
• Uninstall multiple Windows features

xWindowsOptionalFeature

Provides a mechanism to enable or disable optional features on a target node. This resource works on Nano Server.

Requirements

• 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.

Parameters

• [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 }.

Read-Only Properties from Get-TargetResource

• [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.

Examples

• Enable the specified windows optional feature and output logs to the specified path
• Disables the specified windows optional feature and output logs to the specified path

xWindowsOptionalFeatureSet

Provides a mechanism to configure and manage multiple xWindowsOptionalFeature resources on a target node. This resource works on Nano Server.

Requirements

• 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.

Parameters

• [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 }.

Read-Only Properties from Get-TargetResource

None

Examples

• Enable multiple features
• Disable multiple features

xWindowsPackageCab

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.

Requirements

• Target machine must have access to the DISM PowerShell module

Parameters

• [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.

Read-Only Properties from Get-TargetResource

None

Examples

• Install a cab file with the given name from the given path

Functions

Publish-ModuleToPullServer

Publishes a 'ModuleInfo' object(s) to the pullserver module repository or user provided path. It accepts its input from a pipeline so it can be used in conjunction with Get-Module as in 'Get-Module -Name ModuleName' | Publish-Module

Publish-MOFToPullServer

Publishes a 'FileInfo' object(s) to the pullserver configuration repository. It accepts FileInfo input from a pipeline so it can be used in conjunction with Get-ChildItem .*.mof | Publish-MOFToPullServer

Examples

Change the name and the workgroup name

This configuration will set a machine name and change its workgroup.

Switch from a workgroup to a domain

This configuration sets the machine name and joins a domain. Note: this requires a credential.

Change the name while staying on the domain

This example will change the machines name while remaining on the domain. Note: this requires a credential.

Change the name while staying on the workgroup

This example will change a machine's name while remaining on the workgroup.

Switch from a domain to a workgroup

This example switches the computer from a domain to a workgroup. Note: this requires a credential.

Download file from URI, specifying headers and user agent

This configuration will download a file from a specific URI to DestinationPath. The web request will contain specific headers and will be sent using a specified user agent.

Upload file to an SMB share

This configuration will upload a file from SourcePath to the remote DestinationPath. Username and password will be used to access the DestinationPath.

Sample1.ps1 installs a package that uses an .exe file

This configuration will install a .exe package, verifying the package using the package name.

Sample1.ps2 installs a package that uses an .exe file

This configuration will install a .exe package and verify the package using the product ID and package name.

Sample1.ps3 installs a package that uses an .msi file

This configuration will install a .msi package and verify the package using the product ID and package name and requires credentials to read the share and install the package.

Sample1.ps4 installs a package that uses an .exe file

This configuration will install a .exe package and verify the package using the product ID and package name and requires credentials to read the share and install the package. It also uses custom registry values to check for the package presence.

Validate pullserver deployment

If Sample_xDscWebService.ps1 is used to setup a DSC pull and reporting endpoint, the service endpoint can be validated by performing Invoke-WebRequest -URI http://localhost:8080/PSDSCPullServer.svc/$metadata in PowerShell or http://localhost:8080/PSDSCPullServer.svc/ when using InternetExplorer.

Pullserver Validation Pester Tests