Write TargetResource Functions for PowerShell DSC
Summary: Guest blogger and Microsoft PFE, Jason Walker, talks about writing Get, Set, and Test TargetResource functions for DSC.
Microsoft Scripting Guy, Ed Wilson, is here. Microsoft PFE and Honorary Scripting Guy, Jason Walker, is back with us today for Part 2 of his two-part series.
Yesterday in Anatomy of a PowerShell DSC Resource, I gave an overview of the anatomy of a DSC resource and explained how to use the xDscResourceDesigner module to lay down the foundation of a DSC resource. Today I will explain what is involved in writing your Get, Set, and Test TargetResource functions. I’m going to start with the Test-TargetResource function because, in most cases, it will take the longest to write.
The Test-TargetResource function needs to be able to compare every parameter that is defined in the schema.mof file to what is the reality on the server. If the server matches the configuration script, it returns $true, and if the server does not match, it returns $false. Here is how this looks in the example:
To summarize the code in the example, the Test-TargetResource function will get the current configuration and store the results in $ItemResult. It then compares $ItemResult to the configuration script. To break this down even further, if $Ensure is present, and $ItemResult exists without an error, the node must be in a desired state, so the script will return TRUE. If not, it will return FALSE, meaning the node is not in a desired state. After that, a check for the opposite condition is performed.
You will also notice the use of Write-Verbose. This is not only beneficial when manually running the configuration to monitor progress—it’s also extremely useful when troubleshooting what went wrong when you are not watching the configuration as it is applied. Let me explain…
Windows PowerShell will log the Verbose, Error, and Debug streams to the event log. If you need to troubleshoot why a configuration that ran in the past failed, you need to analyze the Operational, Analytical, and Debug logs under Microsoft-Windows-DSC. The Windows PowerShell team does an excellent job of detailing this in this post: Using Event Logs to Diagnose Errors in Desired State Configuration.
It is a best practice to use Write-Verbose. I recommend keeping the verbose messages informational, but brief. You want them to be useful, but we’ve all been through the pain of analyzing logs, so don’t get crazy and overdo it.
The Get-TargetResource function is much simpler than Test-TargetResource. This function will get the current state of the node that is being configured, but it is not used during the configuration process. The results must be returned in a hash table.
This example is straightforward. One thing to note is that I specified the ErrorAction parameter of SilentlyContinue because Get-Item will throw an error if a path isn’t found. When this resource first runs, it’s expected to not have an item’s path, and I don’t want to fill the logs with this error.
The Set-TargetResource function is the function that is responsible for “making it so.” In Part 1 of this blog series, I recommended using the same parameter names in your resource as the parameter names of the cmdlets that you used in the resource. I recommended this so you can splat the parameters. Splatting is not only fun to say, it simplifies the code, making the Test-TargetResource function easy to develop.
This example first removes the parameters that don’t exist for the cmdlets being used so I can splat $PSBoundParameters. You can see that I also add the Force parameter when $Ensure equals “present” (creating a new item) and the Recurse parameter when $Ensure is “absent” (removing an item). When you write the Test-TargetResource function, you want it to run without interactive input. This means that when the resource is running, it should NOT be waiting for a user to confirm an action.
When you have all the *-TargetResource functions developed, I recommend that you start your testing by running the functions outside of the resource to confirm they perform as expected. Then test the resource from a configuration script. When you’re ready to make your resource ready for prime-time, make sure you follow the design and testing checklist provided by the Windows PowerShell team: PowerShell DSC Resource Design and Testing Checklist.
As I said early in this series, a DSC resource is simply a Windows PowerShell module. If you want to look at more examples of DSC resources, look in the $PSModulePath located here:
C:\Windows\System32\WindowsPowerShell\v1.0\Modules\PSDesiredStateConfiguration
…and here:
C:\Program Files\WindowsPowerShell\Modules
And that’s all it takes to write your very own DSC resource.
~Jason
Thanks, Jason, for taking the time to share this series.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy
Light
Dark
0 comments