The xPSDesiredStateConfiguration module is a more recent, experimental version of the PSDesiredStateConfiguration module that ships in Windows as part of PowerShell 4.0. The module contains the xDscWebService, xWindowsProcess, xService, xPackage, xRemoteFile, xWindowsOptionalFeature and xGroup DSC resources, as well as the xFileUpload composite DSC resource.
Please check out common DSC Resources contributing guidelines.
- xArchive creates or expands (extracts) ZIP archives.
- xDscWebService configures an OData endpoint for DSC service to make a node a DSC pull server.
- xWindowsProcess configures and manages Windows processes.
- xService configures and manages Windows services.
- xRemoteFile ensures the presence of remote files on a local machine.
- xPackage manages the installation of .msi and .exe packages.
- xGroup configures and manages local Windows groups
- xFileUpload is a composite resource which ensures that local files exist on an SMB share.
- xWindowsOptionalFeature configures optional Windows features.
- xRegistry is a copy of the built-in Registry resource, with some small bug fixes.
The xArchive DSC Resource enables the creation or extraction of ZIP archives from / onto the local filesystem. The DSC Resource has two modes: extraction or compression. The DestinationType property controls the behavior of the DSC Resource.
If the DestinationType is set to Directory (default), then the ZIP file specified in the Path property will be extracted to the path in Destination. If the DestinationType is set to File, then the directory specified in the Path property will be compressed into a new ZIP file at the path specified in the Destination property.
- Path: The path of the ZIP archive, if extracting, or the source directory to compress, if compressing.
- Destination: The destination of the extracted files or the new ZIP archive.
- DestinationType: The destination can be either
FileorDirectory. - CompressionLevel: The amount of compression that should be applied to the new ZIP archive. The value can be one of the following:
Optimal,Fastest,NoCompression
- 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.
- PhysicalPath: Folder location where the content of the web service resides.
- State: State of the web service: { Started | Stopped }
- ModulePath: Folder location where DSC resources are stored.
- ConfigurationPath: Folder location where DSC configurations are stored.
- Ensure: Ensures that the web service is Present or Absent
For a complete list of properties, please use Get-DscResource
- Path: The full path or the process executable
- Arguments: This is a mandatory parameter for passing arguments to the process executable. Specify an empty string if you don't want to pass any arguments.
- Credential: The credentials of the user under whose context you want to run the process.
- Ensure: Ensures that the process is running or stopped: { Present | Absent }
For a complete list of properties, please use Get-DscResource
- Name: The name for the service.
- Ensure: An enumeration which stating whether the service needs to be created (when set to 'Present') or deleted (when set to 'Absent')
- Path: The path to the service executable file. This is a requied parameter if Ensure is set to true
- DestinationPath: Path where the remote file should be downloaded.
- Uri: URI of the file which should be downloaded.
- UserAgent: User agent for the web request.
- Headers: Headers of the web request.
- Credential: Specifies credential of a user which has permissions to send the request.
- MatchSource: Determines whether the remote file should be re-downloaded if file in the DestinationPath was modified locally.
- Ensure: Says whether DestinationPath exists on the machine. It's a read only property.
For a complete list, please use Get-DscResource.
- 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.
- 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.
- 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?
- RunAsCredential: Credentials to use when installing the package.
- InstalledCheckRegKey: Registry key to open to check for package installation status.
- InstalledCheckRegValueName: Registry value name to check for package installation status.
- InstalledCheckRegValueData: Value to compare against the retrieved value to check for package installation.
- CreateCheckRegValue: Creates the InstallCheckRegValueName registry value/data after successful package installation.
This resource extends PowerShell 4.0 Group resource by supporting cross-domain account lookup where a valid trust relationship exists. In addition, limited support for UPN-formatted names are supported for identifying user, computer, and group domain-based accounts.
- GroupName: The name of the group.
- Ensure: Ensures that the group is Present or Absent.
- Description: Description of the group.
- Members: The members that form the group. Note: If the group already exists, the listed items in this property replaces what is in the group.
- MembersToInclude: List of users to add to the group. Note: This property is ignored if 'Members' is specified.
- MembersToExclude: List of users you want to ensure are not members of the group. Note: This property is ignored if 'Members' is specified.
- Credential: Indicates the credentials required to access remote resources. Note: This account must have the appropriate Active Directory permissions to add all non-local accounts to the group or an error will occur.
Local accounts may be specified in one of the following ways:
- The simple name of the account of the group or local user.
- The account name scoped to the explicit machine name (eg. myserver\users or myserver\username).
- The account name scoped using the explicit local machine qualifier (eg. .\users or .\username).
Domain members may be specified using domain\name or User Principal Name (UPN) formatting. The following illustrates the various formats
- Domain joined machines: mydomain\myserver or [email protected]
- Domain user accounts: mydomain\username or [email protected]
- Domain group accounts: mydomain\groupname or [email protected]
- 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.
This is a copy of the built-in Registry resource from the PSDesiredStateConfiguration module, with one small change: it now supports registry keys whose names contain forward slashes.
Note: the xWindowsOptionalFeature is only supported on Windows client or Windows Server 2012 (and later) SKUs.
- Name: Name of the optional Windows feature.
- Source: Specifies the location of the files that are required to restore a feature that has been removed from the image.
- You can specify the Windows directory of a mounted image or a running Windows installation that is shared on the network.
- If you specify multiple Source arguments, the files are gathered from the first location where they are found and the rest of the locations are ignored.
- RemoveFilesOnDisable: Removes the files for an optional feature without removing the feature's manifest from the image.
- Suported values: $true, $false.
- Default value: $false.
- LogPath: Specifies the full path and file name to log to.
- If not set, the default is %WINDIR%\Logs\Dism\dism.log.
- Ensure: Ensures that the feature is present or absent.
- Supported values: Present, Absent.
- Default Value: Present.
- NoWindowsUpdateCheck: Prevents DISM from contacting Windows Update (WU) when searching for the source files to restore a feature on an online image.
- Suported values: $true, $false.
- Default value: $false.
- LogLevel: Specifies the maximum output level shown in the logs.
- Suported values: ErrorsOnly, ErrorsAndWarning, ErrorsAndWarningAndInformation.
- Default value: ErrorsOnly.
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 Get-Module <ModuleName> | Publish-Module
Publishes a 'FileInfo' object(s) to the pullserver configuration repository. Its accepts FileInfo input from a pipeline so it can be used in conjunction with Get-ChildItem .*.mof | Publish-MOFToPullServer
- Publish-ModuleToPullServer
- Publish-MOFToPullServer
- Replaced New-NetFirewallRule cmdlets with netsh as this cmdlet is not available by default on some downlevel OS such as Windows 2012 R2 Core.
- Added more information how to use Publish-DSCModuleAndMof cmdlet and samples
- Removed compliance server samples
- Added Pester tests to validate pullserver deployement.
- Removed Compliance Server deployment from xWebservice resource. Fixed database provider selection issue depending on OS flavor
- Added Publish-DSCModuleAndMof cmdlet to package DSC modules and mof and publish them on DSC enterprise pull server
- xRemoteFile resource: Added size verification in cache
- xService:
- Fixed a bug where 'Dependencies' property was not picked up and caused exception when set.
- xWindowsOptionalFeature:
- Fixed bug where Test-TargetResource method always failed.
- Added support for Windows Server 2012 (and later) SKUs.
- Added xRegistry resource
- Added CreateCheckRegValue parameter to xPackage resource
- Added MatchSource parameter to xRemoteFile resource
- MSFT_xPackageResource: Added ValidateSet to Get/Set/Test-TargetResource to match MSFT_xPackageResource.schema.mof
- Fixed bug causing xService to throw error when service already exists
- Added StartupTimeout to xService resource
- Removed UTF8 BOM
- Added code for pull server removal
- Added logging inner exception messages in xArchive and xPackage resources
- Fixed hash calculation in Get-CacheEntry
- Fixed issue with PSDSCComplianceServer returning HTTP Error 401.2
- Add support to xPackage resource for checking different registry hives
- Added support for new registration properties in xDscWebService resource
- xArchive:
- Fix problems with file names containing square brackets.
- xDSCWebService:
- Fix default culture issue.
- xPackage:
- Security enhancements.
- Multiple issues addressed
- Corrected output type for Set- and Test-TargetResource functions in xWebSite, xPackage, xArchive, xGroup, xProcess, xService
- xRemoteFile modified to support creating a directory that does not exist when specified, ensuring idempotency. Also improved error messages.
- xDSCWebService updated so that Get-TargetResource returns the OData Endpoint URL correctly.
- In xWindowsOptionalFeature, fixed Test-TargetResource issue requiring Ensure = True.
- Note: this change requires the previous Ensure values of Enable and Disable to change to Present and Absent
- Adding following resources:
- xGroup
- Adding following resources:
- xFileUpload
- Adding following resources:
- xWindowsProcess
- xService
- xRemoteFile
- xPackage
- Fix to remove and recreate the SSL bindings when performing a new HTTPS IIS Endpoint setup.
- Fix in the resource module to consume WebSite Name parameter correctly
- Initial release with the following resources:
- DscWebService
This configuration will set a machine name and change its workgroup.
This configuration sets the machine name and joins a domain. Note: this requires a credential.
This example will change the machines name while remaining on the domain. Note: this requires a credential.
This example will change a machine's name while remaining on the workgroup.
This example switches the computer from a domain to a workgroup. Note: this requires a credential.
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.
This configuration will upload a file from SourcePath to the remote DestinationPath. Username and password will be used to access the DestinationPath.
This configuration will install a .exe package, verifying the package using the package name.
This configuration will install a .exe package and verify the package using the product ID and package name.
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.
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.
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 Powershll or http://localhost:8080/PSDSCPullServer.svc/ when using InternetExplorer.