Documentation for PowerShell Desired State Configuration
Home Page: https://learn.microsoft.com/powershell/dsc/overview
License: Creative Commons Attribution 4.0 International
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
![microsoft-github-policy-service[bot] avatar](https://avatars.githubusercontent.com/in/95686?v=4 "microsoft-github-policy-service[bot]")
Code doesn't work
Example given here is not working, import module statement is missing
ca05709b-35cf-fc59-997b-d653ad723994
Typo
The topmost heading in this page says "Supported Windows operation system versions". It should probably read "Supported Windows operating system versions" or maybe just "Supported Windows versions".
https://learn.microsoft.com/en-us/powershell/dsc/getting-started/wingettingstarted?view=dsc-1.1
60157828-986c-43e3-a151-9ed69ebdddd7
[Enter feedback here]
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Get-Foo cmdlet" instead of "Typo."v3.0
https://learn.microsoft.com/en-us/powershell/dsc/getting-started/getting-started?view=dsc-3.0
Examples of dsc-3.0 configurations are outdated, they are the same as dsc-2.0 examples.
For example, the following code does not work on DSC 3.0:
Invoke-DscResource @{
Name = 'Environment'
ModuleName = 'PSDscResources'
Property = @{
Name = 'TestEnvironmentVariable'
Value = 'TestValue'
Ensure = 'Present'
Path = $false
Target = @('Process', 'Machine')
}
Method = Test
}No response
Get-Foo cmdlet" instead of "Typo."v1.1
No links to a particular page
Update-Help -Force -Module PSDesiredStateConfiguration does not work on Windows PowerShell when referencing DSC 1.1. As directory browsing is not enabled, I was unable to verify if there are indeed no help files. As far as Update-Help is concerned, there are none. People are still using DSC 1.1, it would be nice to get help content still, even if it might not be updated any longer. Help for PSDesiredStateConfiguration 2.0.5 and 3 is available.
No response
No response
This issue copied from MicrosoftDocs/PowerShell-Docs#7689
Need some sort of document that will describe:
This looks like a suitable location for this information (or have another new about side-document):
psdesiredstateconfiguration/about/about_classes_and_dsc
Typo
At "Folder structure for a MOF resource" part below folder structure is missing MyDscResources.psd1 file which is a required file to work this.
$env:ProgramFiles\WindowsPowerShell\Modules (folder)
|- MyDscResources (folder)
|- DSCResources (folder)
|- Demo_IISWebsite (folder)
|- Demo_IISWebsite.psd1 (file, optional)
|- Demo_IISWebsite.psm1 (file, required)
|- Demo_IISWebsite.schema.mof (file, required)
The correct one should be like below
$env: psmodulepath
|- MyDscResources
|- MyDscResources.psd1
|- DSCResources
|- xVirtualMachine
|- xVirtualMachine.psd1
|- xVirtualMachine.schema.psm1
https://learn.microsoft.com/en-us/powershell/dsc/resources/authoringresourcemof?view=dsc-1.1
sdwheeler
5c5afac2-e1a7-b27d-98e4-44ecdb2a92cd
Typo
In 1.1 document for composite resources
https://learn.microsoft.com/en-us/powershell/dsc/resources/authoringresourcecomposite?view=dsc-1.1
Should be
Import-DscResource -Module or Import-DscResource -ModuleName ?
when we try writing it is giving below options only
https://learn.microsoft.com/en-us/powershell/dsc/resources/authoringresourcecomposite?view=dsc-1.1
3b881d76-ee94-94bd-4719-440c698d8856
The script in the section #my-resources-wont-update-how-to-reset-the-cache is specifying the WMI Provider to be dsccore, but in later versions of Windows it is called dsctimer.
⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.
Hi!
The last line from the HelloWorld script is missing.
You should append for the last line: HelloWorld
⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.
As a user, I need a document to tell me how I can import PowerShell module to the DSC script.
Details:
I'm trying to create a guest configuration to monitor if the VM enabled Windows defender realtimeMonitoring.
Here is my code:
Configuration EnableRealtimeMonitoring
{
Import-DscResource -ModuleName 'PSDscResources'
Node localhost
{
Script EnableRealtimeMonitoring
{
GetScript = {
$RealtimeMonitoringEnabled = Get-MpComputerStatus | select -expandproperty RealTimeProtectionEnabled
return @{ 'Result' = "$RealtimeMonitoringEnabled" }
}
TestScript = {
# Create and invoke a scriptblock using the $GetScript automatic variable, which contains a string representation of the GetScript.
$state = [scriptblock]::Create($GetScript).Invoke()
if( $state.Result -eq 1 )
{
Write-Verbose -Message ('Current state of RealtimeMonitoringEnabled is {0}' -f $state.Result)
return $true
}
Write-Verbose -Message ('Current state of RealtimeMonitoringEnabled is {0}' -f $state.Result)
return $false
}
SetScript = {
Set-MpPreference -DisableRealtimeMonitoring $false
}
}
}
}
However, while evaluating the compliance status the Get-GuestConfigurationPackageComplianceStatus command return following error:
Error Message: PowerShell DSC resource
| MSFT_ScriptResource failed to execute Test-TargetResource functionality with error message:
| System.InvalidOperationException: The test script threw an error. --->
| System.Management.Automation.MethodInvocationException: Exception calling "Invoke" with "0"
| argument(s): "The term 'Get-MpComputerStatus' is not recognized as a name of a cmdlet, function,
| script file, or executable program. Check the spelling of the name, or if a path was included, verify
| that the path is correct and try again." ---> System.Management.Automation.CommandNotFoundException:
| The term 'Get-MpComputerStatus' is not recognized as a name of a cmdlet, function, script file, or
| executable program. Check the spelling of the name, or if a path was included, verify that the path is
| correct and try again. at
| System.Management.Automation.ExceptionHandlingOps.CheckActionPreference(FunctionContext funcContext,
| Exception exception) at System
So I tried to import Defender module since Get-MpComputerStatus is a command from Defender module.
However, either of the following ways solved this issue:
Import-DscResource -ModuleName 'Defender'
Import-DscResource -Name 'Defender'
Import-Module -Name 'Defender'
Could anyone tell me how can I import a PowerShell module to the DSC script?
Thanks
Import Powershell module to the DSC script
No response
2.0
The title line says it all; the DSC/Configuration page lists nothing but the single line of code and the parameters; all other details appear to be placeholders.
Fill in documentation outside of the placeholder values used for new pages prior to editing.
1.1
You can force a Node to update its resources by changing the version number in the archive's name, or by creating a new checksum. The Pull Client will check for newer versions of required resources, as well as updated checksums, when its LCM refreshes.
If changing the resource code and creating a new checksum is not working fine, please remove it.
if I am wrong please kindly reply to me and explain why then ignore my suggestion.
1.1
In the "Syntax" section the "Ensure" option is listed with possible values "Enable" and "Disable", but these values should be "Present" and "Absent"
The same mistake is also on https://docs.microsoft.com/en-us/powershell/dsc/reference/resources/windows/windowsoptionalfeaturesetresource?view=dsc-1.1
This most probably applies to all DSC versions (1.1, 2.0, 3.0)
Change the following:
Ensure = [string] { Enable | Disable }
To:
Ensure = [string] { Present | Absent }
Get-Foo cmdlet" instead of "New cmdlet."v2.0.6 has mostly bug fixes with 2 notable exceptions:
Other details are in v2 changelog.
No response
About Topic
No response
PowerShell/PSDesiredStateConfiguration#52
N/A
Get-Foo cmdlet" instead of "Typo."v2.0
If a class or enum is defined with the same name in more than one module, compiling configurations that use both of those modules fails due to the name collision.
We already partially cover this problem for defining the Reasons property for machine configuration:
We should generalize this note and advice and surface it wherever it makes sense.
We should document this behavior, suggest that authors prefix their enums and classes with their module name, and add name prefixing to the best practices section for the Class-based DSC Resources article.
We may want to add an include that we can use throughout the documentation wherever we're talking about naming classes and enums for use as DSC Resource property types.
Get-Foo cmdlet" instead of "Typo."v1.1
When a user wants to invoke a DSC Resource that has complex properties in PSDSCv1.1, they need to convert the complex property into a CimInstance or the invocation errors confusingly.
With the example resource definition:
[DscResource()]
class InvocableExample {
[DscProperty(Key)] [string] $Path
[DscProperty()] [Complex] $Info
[DscProperty()] [VeryComplex] $Options
[InvocableExample] Get() { return $this }
[bool] Test() { return $true }
[void] Set() { }
}
class Complex {
[DscProperty()] [string] $Version
[DscProperty()] [bool] $StartOnBoot
}
class VeryComplex {
[DscProperty()] [string] $Name
[DscProperty()] [Nested[]] $Settings
}
class Nested {
[DscProperty()] [bool] $Enabled
[DscProperty()] [string] $Name
}You can use New-CimInstance with the ClientOnly parameter to create the complex property inline for the DSC Resource's property hash:
Invoke-DscResource -Name InvocableExample -Method Get -ModuleName ExampleResources -Property @{
Path = 'C:\dsc\example.json'
Info = New-CimInstance -ClientOnly -ClassName Complex -Property @{
Version = '1.1.0'
}
}When the property's type is an array, like [Nested[]], you need to cast the inline array to [CimInstance[]]:
$Options = New-CimInstance -ClientOnly -ClassName VeryComplex -Property @{
Name = 'Nested Options'
Settings = New-CimInstance -ClientOnly Nested -Property [CimInstance[]]@(
@{ Name = 'First' ; Enabled = $true }
@{ Name = 'Second' ; Enabled = $false }
)
}You need to convert every complex property, including nested ones, with New-CimInstance.
Extend the documentation for invoking DSC Resources in v1.1 to document this requirement.
The example should include Example(configuration name) at the end of the configuration example.
Current:
Configuration Example {
# Import the module that contains the Registry DSC Resource.
Import-DscResource -ModuleName PSDscResources
# The Registry DSC Resource can ensure the state of registry keys
Registry DscTest {
Key = 'HKEY_CURRENT_USER\DscTest'
ValueName = 'Example'
Ensure = 'Present'
ValueData = 'Test Value'
ValueType = 'String'
}
}
Proposed:
Configuration Example {
# Import the module that contains the Registry DSC Resource.
Import-DscResource -ModuleName PSDscResources
# The Registry DSC Resource can ensure the state of registry keys
Registry DscTest {
Key = 'HKEY_CURRENT_USER\DscTest'
ValueName = 'Example'
Ensure = 'Present'
ValueData = 'Test Value'
ValueType = 'String'
}
}
Example
Without the configuration name at the end, the configuration won't be compiled when you call the script.
Also I'm not sure if the doc should clarify that you can define multiple configurations in one file and just include names of all configuration at the end and calling the script will result in all configurations to be compiled at once.
⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.
1.1
https://docs.microsoft.com/en-us/powershell/dsc/resources/authoringresourcemof?view=dsc-1.1
Hi there,
I just followed the guide of Writing a custom DSC resource with MOF and it was very clear and helpful. However, I didn't find the description to teach how to test the custom DSC resource with MOF.
There is a testing description in another document here: https://docs.microsoft.com/en-us/powershell/dsc/resources/authoringresourceclass?view=dsc-1.1, but it didn't helpful.
Could you please provide more information?
Thanks,
Ethan
Add more details on how to test the custom DSC resource with MOF.
Get-Foo cmdlet" instead of "Typo."We should provide guidance when the script resource is appropriate to use. In general, before considering using the script resource, the user should consider if they can just turn the script they were going to use into a script-based resource. Use of scripts within config breaks the declarative model and makes idempotency much harder.
No response
No response
The listed command for installing the 3.0 module only pulls the 2.0.7 version from the gallery.
Using Install-Module PSDesiredStateConfiguration -AllowPreRelease -Force -RequiredVersion 3.0.0-beta1 pulls a version 3 module.
⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.
The example works - you can use it, the value will appear in "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" and SystemPropertiesAdvanced.exe will show the environment value is present/absent [as per the DSC policy], but if you check for the environment variable by opening a new command prompt window or starting a new PowerShell process, the change will not apply (if you removed it via DSC, it's still there; if you added it via DSC, it's not there). It does appear in those locations after a restart.
This is the most stupid idiotic implementation ever.
SETX.EXE works fine. Whatever method PowerShell is using isn't doing what SETX does. you must tell your readers that if they try your examples, then don't work the way any IT professional would expect them to work.
This applies to both modules that have the 'ENVIRONMENT' provider.
[Enter feedback here]
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.
Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.
2.0, 3.0
All labels in the article are displaying Placeholder data, like '{{ Fill in the Synopsis }}'. This makes the article less useful.
Please replace the placeholders with the actual information.
Should the article be updated to add this OS?
According to https://docs.microsoft.com/en-us/windows-server/get-started/editions-comparison-windows-server-2022, DSC seems to be supported.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Typo
[Enter feedback here]
https://learn.microsoft.com/en-us/powershell/dsc/overview?view=dsc-2.0
sdwheeler
7befffa4-ef78-f531-1a36-ecce7355978c
Get-Foo cmdlet" instead of "Typo."v3.0
There's a conflict of ideas between what the PS Team call DSCv3 and what other teams call DSCv3 such as this doc.
Someone came to the PS Discord asking for info about DSCv3 on Linux, and referring both to this doc and the last presentation from Steve about what he calls DSCv3.
Which is it? Those are 2 different things.
Feel free to ask me any question.
Refer to the module as PSDSCv3, and the project Steve is working on as DSCv3 Utility, or even DSCv3 engine or something...
DSC (good old one) is:
Each and every DSC documentation should at least link to an explanation and definition of this, and how the DSC ecosystem relate to each of them (i.e. Machine Config).
Hi,
I have tested the code provided using:
and I get errors that PSDscResources\WindowsFeature is not recognized.
When I try with:
the code is compiled.
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.
Copied from MicrosoftDocs/PowerShell-Docs#7373
Together with PSDesiredStateConfiguration v3 module allows Get-DscResource, Invoke-DscResource and DSC configuration compilation on all platforms, supported by PowerShell (using class-based DSC resources).
At this point this PR is not a breaking change: existing (MOF/MMI-based) DSC code will continue to work as it was and will continue to be the default mechanism for DSC operations (for now).
Cross-platform DSC updates of this PR are done as an alternative mechanism for DSC operations; to use them:
1.1
Configuration documents (MOF files) can be applied to the machineusing the Start-DscConfiguration cmdlet.
Should become
Configuration documents (MOF files) can be applied to the machine using the Start-DscConfiguration cmdlet.
Configuration documents (MOF files) can be applied to the machineusing the Start-DscConfiguration cmdlet.
Should become
Configuration documents (MOF files) can be applied to the machine using the Start-DscConfiguration cmdlet.
Missing information
The chapter that should have described DSCv3 installation is missing from this page https://learn.microsoft.com/en-us/powershell/dsc/overview?view=dsc-3.0&preserve-view=true
https://learn.microsoft.com/en-us/powershell/dsc/overview?view=dsc-3.0&preserve-view=true
7befffa4-ef78-f531-1a36-ecce7355978c
3.0
Hi,
I met the following problems while running the provided script in the doc:
After module was imported:
I'm using PS7.2, both PSDscResources and Environment are installed and imported.
Could you please tell me how to fix this issue?
Thanks
No response
Get-Foo cmdlet" instead of "Typo."v1.1, v2.0, v3.0
The documentation suggests adding a class called Reasons for the Reasons property used by machine configuration. However, if two or more modules define a Reasons class, loading those modules raises an exception when the second module loads because the class is already defined.
No response
The documentation should warn DSC Resource authors about this problem and suggest prefixing the class name with the module's name, like SqlServerDscReasons for the SqlServerDsc module and noting that the property can use a hash table, as well as the tradeoffs.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.