{"id":6221,"date":"2015-05-11T00:01:00","date_gmt":"2015-05-11T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2015\/05\/11\/anatomy-of-a-powershell-dsc-resource\/"},"modified":"2019-02-18T10:29:38","modified_gmt":"2019-02-18T17:29:38","slug":"anatomy-of-a-powershell-dsc-resource","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/anatomy-of-a-powershell-dsc-resource\/","title":{"rendered":"Anatomy of a PowerShell DSC Resource"},"content":{"rendered":"

Summary<\/b>: Guest blogger and Microsoft PFE, Jason Walker, talks about the anatomy of a Windows PowerShell DSC resource.<\/span><\/p>\n

Microsoft Scripting Guy, Ed Wilson, is here. Today is Part 1 of a two-part series written by Microsoft PFE and Honorary Scripting Guy, Jason Walker<\/a>.<\/p>\n

The majority of my "PowerShelling" lately has been around Desired State Configuration (DSC). However, the gotcha with DSC is if there isn’t a resource for the configuration area that you want to configure, you can’t use DSC for that task.<\/p>\n

Now let’s not jump to conclusions and eliminate DSC as a solution. If you can write a Windows PowerShell script, you can write a DSC resource. A DSC resource is a Windows PowerShell module with one addition. A DSC resource has a MOF file that defines each of the configurable properties. It’s that simple.<\/p>\n

When designing a resource (see Writing a custom DSC resource with MOF<\/a>), it should be written to configure one thing—and one thing only. In most cases, a resource should correlate to a cmdlet noun. For example, if you run Get-Command *ADUser<\/b> you will find the following cmdlets:<\/p>\n

PS C:\\Windows\\system32> Get-Command *ADUser<\/p>\n

CommandType   Name<\/p>\n

———–   —-<\/p>\n

Cmdlet     Get-ADUser<\/p>\n

Cmdlet     New-ADUser<\/p>\n

Cmdlet     Remove-ADUser<\/p>\n

Cmdlet     Set-ADUser<\/p>\n

These cmdlets enable you to create a user (New-ADUser<\/b>), modify the attributes of a user (Set-ADUser<\/b>), delete a user (Remove-ADUser<\/b>), and find a user and return information about that user (Get-ADUser<\/b>). Now if I wanted to put that user in a specific group, I would have to use a cmdlet that has a different noun (Add-ADGroupMember<\/b>). Therefore, if I was going to use DSC to create a user and place that user in a specific group, I would need two resources (xADUser<\/b> and xADGroupMember<\/b>).<\/p>\n

To demonstrate the ease of writing a resource, I will walk you through creating a resource to create a file or a folder. I will call the resource xItem<\/b> because I will be using the New-Item<\/b> and Get-Item<\/b> cmdlets in my resource. In addition, this resource will live in the xFileFolder<\/b> module.<\/p>\n

By reviewing the examples in the New-Item<\/b> Help file, we can determine that the resource will need the following properties: Name<\/b>, ItemType<\/b>, and Path<\/b>. (I recommend that when you use native cmdlets in your resources, you make the resource parameter names match the parameter names of the cmdlets that are used in your resource. I will expand on this later.) Because I want the resource to be able to remove a file or folder if needed, I will also need the Ensure<\/b> property.<\/p>\n

Now I have everything I need to create the schema (MOF file) for the resource. I will use the xDscResourceDesigner<\/b> module for this. The xDscResourceDesigner<\/b> module simplifies creating the foundation for a DSC resource. The module will create the folder structure for the resource, the MOF file, and a template of the psm1 file. For more instructions about using the xDscResourceDesigner<\/b> module and the details on the MOF file, see the following blog by the Windows PowerShell team: Resource Designer Tool – A walkthrough writing a DSC resource<\/a>. Here is my code:<\/p>\n

\"Image<\/a><\/p>\n

In my example, I defined each property by using the New-xDscResourceProperty<\/b> function. First, I have to define a property that will have the Key<\/b> attribute. The key must be unique among like resources. Because I can’t have two files with the same name and the same path, I’m going to use the path as the key.<\/p>\n

You can also use multiple properties for the key when needed. For example, a resource to create DNS A records would need to have the host name and IP address as key properties because you can have two DNS A records with the same host name (such as in a DNS round-robin scenario), but the IP addresses must be different.<\/p>\n

When each property is defined, I pass them to the New-xDscResource<\/b> function. When the New-xDscResource<\/b> function is called, I also specify the module name, resource name, and where I want the resource to live. I left out giving the properties a description so the code would fit on one page. The description is optional, but it’s nice if it’s there, and I recommend you always include it.<\/p>\n

Now back to the code. When running my example, the xDscResourceDesigner<\/b> creates the needed folder structure, schema.mof, and MSFT_xItem.psm1 file (which is where the Windows PowerShell lives). This is shown here:<\/p>\n

\"Image<\/a><\/p>\n

That is enough instruction for one day. Tomorrow I will explain how to write the Get<\/b>, Set<\/b>, and Test-Target<\/b> resource functions.<\/p>\n

~Jason<\/p>\n

Thank you, Jason. This is great information.<\/p>\n

I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Guest blogger and Microsoft PFE, Jason Walker, talks about the anatomy of a Windows PowerShell DSC resource. Microsoft Scripting Guy, Ed Wilson, is here. Today is Part 1 of a two-part series written by Microsoft PFE and Honorary Scripting Guy, Jason Walker. The majority of my "PowerShelling" lately has been around Desired State Configuration […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[56,338,414,3,4,45],"class_list":["post-6221","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-guest-blogger","tag-jason-walker","tag-providers","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Guest blogger and Microsoft PFE, Jason Walker, talks about the anatomy of a Windows PowerShell DSC resource. Microsoft Scripting Guy, Ed Wilson, is here. Today is Part 1 of a two-part series written by Microsoft PFE and Honorary Scripting Guy, Jason Walker. The majority of my "PowerShelling" lately has been around Desired State Configuration […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/6221","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=6221"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/6221\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=6221"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=6221"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=6221"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}